External Integrators

This page documents an experimental feature. You can help out by testing it and recording your experiences.

Integrators are loaded dynamically ('dlopened') from DLL/SO files at runtime. This will allow us to offer a wider range of such tools, without requiring that a new release of ASCEND be made each time a new integrator or solver is to be added.

The API for integrators is a reasonably 'narrow' one; its documentation can be seen in ascend/integrator/integrator.h (or via doxygen).

A sketch of the Integrator API as seen by external integrators

Loading of an integrator DLL can be triggered by an IMPORT statement in your model file. As with all IMPORTed files, this could be a python script, a DLL, or some other yet-to-be-implemented file-type with an import handler.

The DLL will contain a yourdllname_register method, which will do the job of registering the Integrator.

Registering an integrator is done by creating (allocated) an IntegratorInternals object and filling in its details, then passing it (as a pointer) to the function integrator_register. The IntegratorInternals struct contains pointers to various functions required for the implementation of the new Integrator. It also includes the name of the new integrator, and a ID number (whether this last has any use is yet to be seen).

The integrator_register function will then add the integrator to the list of registered integrators, and from that point on it will be available in the user interface list of interators (PyGTK GUI only). Parameters defined for the integrator will be visible via the Integrator dialog, and output from the integrator will be available in the usual way. You can provide a statistics-reporting function as well, although this has not yet been incorporated into the GUI.

If your integrator follows the protocol of the LSODE integrator, you can use integrator_analyse_ode to analyse your problem and create the standard lists of variables and equations. Otherwise you can define your own 'analyse' function that accesses the slv_system_t directly in order to define the integration problem.

The basic flow of information from your model file to the integrator is something like:

model_file --> instance_hierarchy --> prob_t --> slv_system_t --> IntegratorSystem

Your 'analyse' function takes care of just the last step.

Current external integrators

See Solvers for the full list of external solvers in ASCEND.

Currently, we offer:

• LSODE provides ODE solution using Adams-Moulton and Backwards Difference Formula techniques.
• IDA provides DAE solution using Backwards Difference Formula.
• DOPRI5 provides explicit one-step integration using Dormund-Prince equations.

We also propose to add RKSUITE for a range of explicit Runge-Kutta integrators, and perhaps RADAU5 for an implicit one-step integrator.

A blended explicit-implicit integrator might be worth looking at also, such as BIMD.

See also External Solvers and Integrator API.