JEDI-Math Library Specification
The JEDI-Math library is in the process of defining its basic architecture and content. Below are listed the main points of discussion. Input is sought from any Delphi developer interested in this project, whether an established mathematician or an occasional user of mathematical routines. On the main page the mailing list and news group details are provided, from which comments and suggestions are compiled and summarized on this page. As any Open Source project this is a collaborative effort that can only thrive from the active participation of as many users as possible.
While the specification is drawn up the preparations for the first public release of the library continue. That release will follow these specifications as closely as possible, but any version 0 release is not guaranteed to be consistent with the finalized parts of the specification below. Complete compliance will be enforced from version 1.0 onwards, which will not be released until after the completion of this specification.
Where final decisions have been made contributors are asked to comply before submitting new code for inclusion into the library. This saves the library developers a huge amount of time, and it will provide for a swift release path for new code.
In the table below the current issues are summarized. This reflects the results of the ongoing discussions on the regular JEDI-Math media. As long as the status is not "Finalized" any formulation can be amended through participation in the dicussions. When an issue is finalized, it's complete text can be found in the JEDI-Math Library Specification document (which does not yet exist). If a developer is coordinating the discussion on an issue, his/her initials are in the "Lead" column, otherwise the issue is updated as new input becomes available.
|Issue open for discussion|
|Issue finalized; complete text in JEDI-Math Library Specification document|
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.
The fields of mathematics to be included in the library, and their priority for implementation in the first release, in no particular order:
This should keep us busy for now getting these into shape and tested. The following are high priority follow-ups:
The remainder of the list goes:
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.
updated: 9 March 2003.
Page maintained by Patrick Van Laake.