trick/docs/documentation/simulation_capabilities/Integrator.md

Trick provides a state integration capability described by the inputs below. To use these options a developer must develop application code which interfaces the application states with the Trick integration services. The integration job class is designed to accommodate the application state to Trick integration service interface.

All integration class jobs must return an integer value which represents the current integration pass identifier. If all integration passes are complete, the job must return a zero.

The code below represents a simple integration job implementation.

/*********** TRICK HEADER **************
PURPOSE:   (State Integration Job)
...
CLASS:     (integration)
...
*/
#include "ip_state.h"
#include "sim_services/Integrator/include/integrator_c_intf.h"

int integration_test( IP_STATE* s)
{
    int ipass;

    /* LOAD THE POSITION AND VELOCITY STATES */
    load_state(
        &s->pos[0],
        &s->pos[1],
        &s->vel[0],
        &s->vel[1],
        NULL
    );

    /* LOAD THE POSITION AND VELOCITY STATE DERIVATIVES */
    load_deriv(
        &s->vel[0],
        &s->vel[1],
        &s->acc[0],
        &s->acc[1],
        NULL
    );

    /* CALL THE TRICK INTEGRATION SERVICE */
    ipass = integrate();

    /* UNLOAD THE NEW POSITION AND VELOCITY STATES */
    unload_state(
        &s->pos[0],
        &s->pos[1],
        &s->vel[0],
        &s->vel[1],
        NULL
    );

    /* RETURN */
    return(ipass);
}

The integrate() function, declared externally, is the function which physically integrates the states. This function uses the input parameters defined in Table 18 and 19 to integrate any set of states and derivatives.

First, the states must be loaded, load_state() . Notice in the example code that both position and velocity are loaded into the state array. This is because the integrators are primarily 1st order differential equation integrators, which means that velocities are integrated to positions independently from the accelerations being integrated to velocities. Hence, the velocity is a state and the acceleration is its derivative, just as the position is a state and velocity is its derivative. From the 2 degree of freedom code example, there are four states: two position and two velocity.

Next, the derivative of the position (velocity) and the derivative of the velocity (acceleration) must be loaded, load_deriv() . The integration job class is designed to be called once for each intermediate pass of a multi-pass integrator. For example the Runge_Kutta_4 integrator will make 4 separate derivative evaluations and stores the resulting state from each intermediate pass separately so that they may be combined and weighted to create a "true" state for the specified time step. The intermediate_step parameter defines the current intermediate step ID for the integrator. This parameter is initialized to zero by the executive and managed by the integrate() function.

With the states and derivatives loaded into the appropriate integrator arrays, the integrate() function must be called to integrate the states through a single intermediate step of the selected integration scheme. The integrated states must then be unloaded, unload_state() .

If a developer wishes to use their own integration scheme, then the integrate() function source code should be reviewed so that the proper interfaces can be maintained. The integrate() source code is located in the ${TRICK_HOME}/trick_source/sim_services/integ/integrate.c file.

Integrator Control Inputs

There can be any number of integration class jobs listed within the S_define file; each integration job should have an associated IntegLoop declaration. The available inputs for state integration control are listed in Table 18.

Table 18 State Integration Control Inputs

Name	Default	Description
getIntegrator(Integrator_type, unsigned int, double)	No default value	Tell Trick the Integrator scheme and the number of state variables. A call to this function is required otherwise a runtime error is generated.
set_first_step_deriv(bool)	True	True=perform derivative evaluation for the first pass of the integrator; False=use the derivative evaluation from the last pass of the previous integration cycle.
set_last_step_deriv(bool)	False	True=perform derivative evaluation for the last pass of the integrator; False=do not perform derivative evaluation for the last pass of the integrator.

• getIntegrator(Alg, State_size, Dt) : The Alg parameter is an enumerated type which currently has nine possible values. These values and information about the associated integrator is shown in Table 19. The State_size parameter is the number of states that are to be integrated. This includes position and velocity states; e.g. for a three axis translational simulation, there would be three position states and three velocity states, hence the second parameter would equal 6 states. The Dt parameter is the integration frequency; however, this parameter is ignored unless using the Integration class stand-alone. The frequency is defined in the S_define when using integration within Trick.
• set_first_step_deriv(first_step) : The first_step parameter is a boolean. If True then Trick will run the derivative jobs for the first integration step. If False then Trick will run only the integration jobs for the first integration step.
• set_last_step_deriv(last_step) : The last_step parameter is a boolean. If True then Trick will run the derivative jobs after the last integration step. If False then Trick will not run the derivative jobs after the last integration step.

Table 19 State Integration Options

Option	Accuracy	DiffEQ	# Deriv	Comments
Euler	1st Order	1st Order	1	yn + 1 = yn + y'n*dt
Euler_Cromer	2nd Order	2nd Order	2	yn + 1 = yn + y'n + 1*dt
ABM_Method				Adams-Bashforth-Moulton Predictor Corrector
Nystrom_Lear_2	2nd Order	2nd Order	1	4th order accuracy for orbital state propagation, circular motion
Runge_Kutta_2	2nd Order	2nd Order	2	Good general purpose integrator
Modified_Midpoint_4	4th Order	2nd Order	3	Good accuracy with less derivative evaluations, be careful with high frequency statesr
Runge_Kutta_4	4th Order	1st Order	4	Good general purpose integrator, although a little time consuming
Runge_Kutta_Gill_4	4th Order	1st Order	4	Good general purpose integrator, although a little time consuming
Runge_Kutta_Fehlberg_45	5th Order	1st Order	6	Designed for larger time steps and smooth states, orbital state propagator
Runge_Kutta_Fehlberg_78	8th Order	1st Order	12	Designed for larger time steps and smooth states, orbital state propagator
User_Defined	N/A	N/A	N/A	Used to bypass trick integration utilities

The Option column are the integration algorithm options. The Accuracy column gives the order of accuracy for the integrator. The DiffEQ column gives the order of teh differential equation set the integrator formulation assumes. For example, a 1st order DiffEQ integrator integrates accelerations to velocities independently of the velocity to position integration. However, a 2nd order DiffEQ integrator integrates the velocity to position states dependent on the acceleration to velocity state integration. The # Deriv column specifies the number of derivative evaluations performed to integrate across a full time step (also known as the number of integration passes). The Comments column gives some special notes for the usage of each integrator.

Continue to Frame Logging