trick/docs/not_referenced/design/DesIntegrator.md

Integrators

Integration is a numerical process of accumulating change. It is commonly used to propagate simulation states from one time step to the next.

Trick's integration scheme helps a simulation developer to perform integration, using one of many well-known integration algorithms or to define his own.

To do this, Trick defines two job classes specifically for integration:

1. Derivative Class Job
2. Integration Class Job

At initialization time, the job scheduler runs all derivative jobs once. During run-time, Derivative and Integration class jobs are then alternately executed one or more times at the top of the rate group frame. The integration algorithm chosen by the user determines the number of times that they are executed per frame. For example, for Runge-Kutta 2 they will alternately be called 2 times.

Derivative Class Job

The user implements derivative class job functions which are expected to calculate derivatives (to be integrated). Derivative job functions may pass any number of arguments. They may also be written to return any value. Their return value is irrelevant to the scheduler. The unique feature of a derivative class job is how it's scheduled. It is always called right before integration class job(s) in the same sim_object.

Integrator Class Job

The user also implements integration class jobs functions which are expected to integrate the derivatives calculated by the derivative class jobs in the same sim object. Like derivative job functions, integration job functions may take any number of arguments. But, the return value of an integration function is significant.

A non-zero return value tells the job scheduler ( see exec_scheduled_modules(), in S_source.c) that integration is not yet complete, and that the derivative and integration class job functions should again be called for the current (t) frame. A zero return value means that integration is complete for the current frame.

Integrator integrate() Function Interface

To aid in the implementation of an integration job function, Trick provides the integrate() function:

int integrate() ;

The Integrator object stores the input (derivative) values to be integrated, intermediate values, and the resultant (integrated) values.

To use integrate(), the user is expected to:

1. Declare an IntegLoop in the S_define with the frequency the integration/derivative jobs.
2. Call getIntegrator(< Integration Algorithm >, <# of variables to integrate>) in the input file for each IntegLoop.
3. In the integration class job:
   
   1. Populate the Integrator object with the state-values: load_state( <state variable>, ..., NULL);
   2. and state-derivative values: load_deriv( <state deriv variable>, ..., NULL);
   3. call the Trick integrate() function: <int> = integrate();
   4. unload the results from: unload_state(<state variable, ..., NULL);
   5. and return the integer value returned from the integrate() function.

Each time integrate() is called it will make progress in its estimate of the new state.

That progress is recorded in the element Integrator->state_ws. After calling integrate(), a non-zero value in Integrator->intermediate_step, indicates that the integration is not yet complete; that integrate() needs to be called again. A zero value in Integartor->intermediate_step means that integration is done. The integration algorithms available are listed in the table below.

Integration Algorithm
Euler
Euler_Cromer
Nystrom_Lear_2
Runge_Kutta_2
Modified_Midpoint_4
Runge_Kutta_4
Runge_Kutta_Gill_4
Runge_Kutta_Fehlberg_45
Runge_Kutta_Fehlberg_78
ABM_Method

Derivative and Integration Class Job Scheduling

Derivative and Integration class jobs are scheduled/called by the IntegLoop Scheduler to which they are assigned.

A new IntegLoopScheduler class is created for each IntegLoop defined in the S_define. The sim_objects that are assigned to the IntegLoopScheduler are added to the scheduler with a call to add_sim_object(). Each IntegLoopScheduler is registered with the Executive when the default_data class jobs are run. Also, rebuild_jobs() is called to add jobs to the proper queue for each sim_object assigned to the IntegLoopScheduler during default_data class jobs. When the initialization class jobs are run, all of the derivative class jobs will be run at time equals 0. Based on the user-defined fequency, the Executive calls the appropriate IntegLoopScheduler integrate() function.

IntegLoopScheduler Integrate() Function Design

The following happens for each IntegLoopScheduler integrate() function call:

• All pre-integration class jobs are called.
• If the variable first_step_deriv is TRUE, then all derivative class jobs are called.
• Call all integration class jobs, each integration class job will be called repeatedly until the specific integration algorithm returns a zero value.
• Call all derivative class jobs.
• Call the dynamic_event class jobs.

Integration Algorithms

The specific Integrators that Trick supports are listed in the above table. Each of these integration algorithms is well known in the world of numerical methods and therefore will not be described. The implementation of the algorithms are included in Trick release packages, but are not maintained by Trick. The ER7 division maintains an er7_utils configuration that contains the integrator code that is used by Trick. @see Trick::Integrator