Structural design of the library

1. Code model. Fundamental to the development of the library is the choice of code model. Delphi itself is an object-oriented framework, as are most applications built with it, but pure numerical code is probably better off in procedural code, due to the usually tighter integration between code and data. An object-oriented design, on the other hand, offers more opportunities for code re-use, and hierarchical dependencies of more complex code on fundamental operations (e.g. the JmMatrix and JmComplex units will be used by many other units).

The development of the library is currently driven by donations from individual developers. So far the donated code is of both kinds, and sometimes mixed in a single unit. The discussion on the JM media tends to supporting this mixed model, where a "procedural" approach underlies an object-oriented interface to the code. The JmMatrix unit is a good example of this: there is an object-oriented hierarchy of matrix forms, but the implementation of individual forms tightly couples code and data. Nevertheless, a type-based approach, such as in the JmComplex unit, is still a good option for simple types and operations.

2. Hierarchy. The preliminary list of fields of mathematics to be included in the library can be divided into functional groups of increasing complexity and diverging implementation. At the base of the hierarchy are the so-called core classes: data types and functions that support more complex operations. These core classes should be identified and implemented as soon as possible, to facilitate the development of more complex units.

Currently the core classes include the following: complex numbers, long integers, random numbers, matrices, and a full set of simple functions for trigoniometry, exponentiation, logarithmics, etc. (the current JclMath).

The following hierarchy has been suggested:

Donations and legalia

JEDI-Math tries to attract as much existing code as possible in building its library. The donated code should be eligible to be released under the MPL. Once donated the code has to be made to conform to the guidelines of this library. For formatting the JEDI VCL guidelines have been adopted.

Standardized library functionality

The root of the library will be the JmMathBasics unit (or something like that). This unit should define items and functionality that are used throughout the library. These items are:

1. Data type(s). Currently it is not feasible to develop separate libraries for different data types. Instead, the TJmFloat type is defined and set to equate one of the fundamental types, selectable by the user. This implies that any dependency on data size, range, precision, etc. should be relative to TJmFloat. There can be exceptions to this, such as in the case of random numbers, which are always 32-bit integers, or doubles.

2. Memory management. Memory allocation and disposal should preferably be organized centrally to support use of large volumes of data (streaming), cross-module memory access (DLLs, file mapping, etc), and CPU efficient alignment.

3. Error management. Mathematical evaluation often involves large volumes of data, and dealing with ill-formed data should not generate exceptions, rather the code should return the FPU special values. (Certain FPU instructions, by the way, handle input special values such as +Inf and -Inf correctly.) Higher level errors (e.g. incompatible matrix sizes) should generate exceptions through a common interface used throughout the library. Error description strings should be compiled in a single unit as resourcestrings to allow for internationalization.

Furthermore, certain conventions have to be established to simplify use of the library:

1. Function call consistency. Standard calling schemes have to be developed for use throughout the library, such that similar functions are similarly invoked. This means, for instance, that parameters should be of a common type wherever possible, and specified in a specific order.

Implementation plan

The fields of mathematics to be included in the library, and their priority for implementation in the first release, in no particular order:

• Complex Numbers
• Matrix/Vector/Similtaneous Equations
• Large Integer routines
• Symbolics
• Statistics
• Genetic Algorithms
• Existing jcl/jvcl code

This should keep us busy for now getting these into shape and tested. The following are high priority follow-ups:

• Mixed precision matrix/vector routines
• Centralized error handling

The remainder of the list goes:

• Geometric math (coordinate transformations, intersections between lines, etc)
• Interpolation and approximation
• Probability, Random numbers
• Integration of (differential) functions
• Function fitting
• Eigen systems
• FFT
• Partial differential equations
• Graphs, networks, topologies
• Sorting
• Searching
• Filtering
• Heuristic methods
• Cryptography, stegography
• Data mining
• Overdetermined equations and householder integration & differential equations
• Nonlinear systems
• Numerical solvers (Poisson, Laplace, etc.), maybe also for general PDE's
• Marcov Chains, Baysian Networks
• Graphing of results

Documentation

All code for the library should be fully documented. The documentation should not only describe individual functions, but also their proper use and context. Since the JEDI project is using Doc-o-Matic for the generation of help files, source code files should adopt the formatting instructions of Doc-o-Matic to facilitate the generation of an help file.

Quality Assurance and testing

What are the minimal standards that code has to pass in order to be eligible for release? Obviously, code has to compile cleanly on Delphi 5 through 7. Furthermore, the code has to pass a number of tests with DUnit (currently being set up). A standard reference to test for completeness of functionality and validation of code could be selected.

The nature of many mathematical algorithms make it very hard to find and correct bugs. This places an additional burden on our shoulders to certify the correctness of the library code. There are basically two scenarios that need to be tested:

1. Standard data. The code has to be tested with a set of well-behaved data. Such a data set and its reference can be generated with other, established mathematical software packages. For each module in the library such a data set has to be defined, and the code tested against the reference, preferably not by the original developer of the code.

2. Ill-formed data. The code has to be able to gracefully handle ill-formed data (such as Ln(-2.0)), and deal with pathologies such as NaNs, numerical overflow and underflow, and denormal representations.