Public Types | Public Member Functions

dsim_integrator Class Reference

An integrator, providing an implementation of an integration algorithm to be applied to object variables. More...

Inherited by dsim_rk4.

List of all members.

Public Types

enum  dsim_integrator_result { dsim_integ_none = 0, dsim_integ_continue = 1, dsim_integ_finished = 2 }
 

A result code for an integration step, indicating where the integration currently stands.

More...

Public Member Functions

 dsim_integrator (const char *name)
 Constructor. Should have few if any side effects.
virtual ~dsim_integrator ()
 Destructor.
virtual void * describe_setup (void *ds)
 Overridden by subclasses to describe the custom setup data that they can handle.
void describe_setup_command (void *ds, const char *command, const char *description)
 Called by subclasses from within describe_setup() to describe a setup command that they accept.
virtual bool parse_setup (const char *command, const char *data)
 Overridden by subclasses to handle custom setup data.
virtual void setup_variable (dsim_variable &variable)
 Overridden by subclasses to take whatever action is necessary to set up a variable for integration.
virtual void cleanup_variable (dsim_variable &variable)
 Overridden by subclasses to clean up variables that have been registered for integration before the integrator is destroyed.
virtual double effective_time_for_step (int step, double t, double dt)
 Overridden by subclasses to provide the current effective simulation time for the integration step specified given the timestep's start time and time delta.
virtual
dsim_integrator::dsim_integrator_result 
step_integration (dsim_variable &variable, int step, double t, double dt)
 Overridden by subclasses to step the integration for a single variable.
void request_new_time_delta (double dt, bool restart=false)
 Requests that the simulation change the time delta to the provided value.
void error (const char *msg,...) const
 Report an error and stop the simulation.
void warning (const char *msg,...) const
 Report a warning.
void log (const char *msg,...) const
 Report an informative notification.

Detailed Description

An integrator, providing an implementation of an integration algorithm to be applied to object variables.

All objects within a DSim simulation have an associated integrator, and any integrated variables at any object are registered with its associated integrator. An integrator provides the actual implementation of a particular implementation algorithm; for instance, the Runge-Kutta 4th Order algorithm is provided by the built-in integrator "DSimRK4". Users can provide their own custom integrator subclasses to provide new integration algorithms.

Most of the functions of dsim_integrator are virtual functions that should be overridden by subclasses when appropriate to customize the integrator's behavior.

All integrators must have an associated factory function conforming to dsim_integrator_factory_t.


Member Enumeration Documentation

A result code for an integration step, indicating where the integration currently stands.

Result codes are returned by step_integration() and are then used by the simulation to determine when integration for a timestep is complete.

Enumerator:
dsim_integ_none 

An error has occurred.

dsim_integ_continue 

The integrator requires additional steps to complete the integration.

dsim_integ_finished 

The integrator has now completed integration and requires no more steps.


Constructor & Destructor Documentation

dsim_integrator::dsim_integrator ( const char *  name )

Constructor. Should have few if any side effects.

If a subclass provides a custom constructor, it is important that the name be passed unchanged to the dsim_integrator constructor. Also, the log(), warning() and error() functions are not available within the constructor.

Parameters:
nameThe name given to this instance of the integrator.

Member Function Documentation

void dsim_integrator::cleanup_variable ( dsim_variable variable ) [virtual]

Overridden by subclasses to clean up variables that have been registered for integration before the integrator is destroyed.

For each variable that is registered with this integrator instance, when the instance is deallocated cleanup_variable() will be called with that variable as an argument. At this time any storage allocated and stored with the variable during setup_variable() should be deallocated. For instance, from the built-in RK4 implementation:

    if (variable.type() == sd_type_matrix)
    {
        ml_matrix *data = (ml_matrix *)variable.integration_ptr();
        delete [] data;
        variable.set_integration_ptr(NULL);
    }
    else if (variable.type() == sd_type_double)
    {
        double *data = (double *)variable.integration_ptr();
        delete [] data;
        variable.set_integration_ptr(NULL);
    }
Parameters:
variableThe variable that should be cleaned up. This function will be called only once for each variable.
void * dsim_integrator::describe_setup ( void *  ds ) [virtual]

Overridden by subclasses to describe the custom setup data that they can handle.

By overriding describe_setup(), integrators are able to self-document the setup commands that they accept. This is necessary for users to properly set up objects of this integrators with the DSim Manager application, as only described setup commands can be used from that application. Integrators that do not accept custom setup commands do not need to provide an implementation of this function, but integrators that override parse_setup() should also override describe_setup().

Within the describe_setup() implemenation, describe_setup_command() should be called once for each setup command that this integrator accepts.

Always call your integrator's superclass's implementation of describe_setup() first.

Parameters:
dsAn opaque pointer to a setup data structure. It should be passed unchanged to calls to describe_setup_command, and then provided as the functions return value.
Returns:
The function should return its argument, ds.
void dsim_integrator::describe_setup_command ( void *  ds,
const char *  command,
const char *  description 
)

Called by subclasses from within describe_setup() to describe a setup command that they accept.

Documents a single setup command accepted by this integrator.

Parameters:
dsThe opaque setup pointer provided as the parameter to the call to describe_setup().
commandA command accepted by this integrator, which should match one of the strings handled by this integrator's implementation of parse_setup().
descriptionA human-readable description of this command. This description will be displayed to users who are setting up instances of this integrator to allow them to properly use the custom setup commands.
double dsim_integrator::effective_time_for_step ( int  step,
double  t,
double  dt 
) [virtual]

Overridden by subclasses to provide the current effective simulation time for the integration step specified given the timestep's start time and time delta.

Returns the effective timestep given an integration step number and the present timestep's time and time delta. Many integration algorithms require that portions of the integration happen at slightly advanced effective timesteps before the intermediate results are combined into a final update for the variable. For instance, from the built-in RK4 implementation:

    switch (step)
    {
        case 0:
            return t;
        case 1:
        case 2:
        case 3:
            return t + dt/2.0;
        default:
            return -1.0;
    }
Parameters:
stepThe integration step number.
tThe current (actual) time step.
dtThe current time delta.
Returns:
The actual time step
void dsim_integrator::error ( const char *  msg,
  ... 
) const

Report an error and stop the simulation.

Output a message at the error priority level. The message will be sent to the simulation's output handler, if on is installed; it will also be sent to the simulation's output log file.

Parameters:
msgThe format string for the message. See printf documentation for details on the format string.
...The additional arguments required by the format string.
void dsim_integrator::log ( const char *  msg,
  ... 
) const

Report an informative notification.

Output a message at the info priority level. The message will be sent to the simulation's output handler, if on is installed; it will also be sent to the simulation's output log file.

Parameters:
msgThe format string for the message. See printf documentation for details on the format string.
...The additional arguments required by the format string.
bool dsim_integrator::parse_setup ( const char *  command,
const char *  data 
) [virtual]

Overridden by subclasses to handle custom setup data.

Handles a custom setup command from the setup file for this object. Exactly what the integrator does with this command is entirely up to the model. Integrators do not have access to the containing simulation object, and variables will not yet be registered at the time that this function is called, so all setup handling must be self-contained.

Integrators that override parse_setup() should also override describe_setup_command() to document the setup commands. Also, any commands not handled by this integrator should be passed to the superclass implementation of the method for handling.

Parameters:
commandThe command string provided for this custom setup line.
dataThe data string for the command. The format and interpretation of this command is entirely determined by the integrator that handles the command.
Returns:
If the command was successfully handled by this integrator (or a superclass), return true. Returning false will stop setup file parsing and report a simulation error (generally stopping the run of the simulation.)
void dsim_integrator::request_new_time_delta ( double  dt,
bool  restart = false 
)

Requests that the simulation change the time delta to the provided value.

The simulation will consider all time delta change requests and attempt to satisfy each. If multiple integrators request different time deltas, the smallest requested delta will be used. Any time delta change will affect the next timestep, not the current one, unless true is passed for the restart parameter. If an integrator would like to keep the timestep from increasing, it should call this function with the current timestep to request that it be maintained, as another integrator may request an increase.

Parameters:
dtThe requested time delta
restartSet to true if the current timestep should restart with the newly requested dt; set to false if the new duration only needs to be updated for the next timestep.
void dsim_integrator::setup_variable ( dsim_variable variable ) [virtual]

Overridden by subclasses to take whatever action is necessary to set up a variable for integration.

For each variable that is registered with this integrator instance, setup_variable() will be called with that variable as an argument. At this time any storage necessary for integration intermediate results should be allocated and saved at the variable with dsim_variable::set_integration_ptr(). For instance, from the built-in RK4 implementation:

    if (variable.type() == sd_type_matrix)
    {
        ml_matrix *data = new ml_matrix[4];
        variable.set_integration_ptr(data);
    }
    else if (variable.type() == sd_type_double)
    {
        double *data = new double[4];
        variable.set_integration_ptr(data);
    }
    else
    {
        throw dsim_type_mismatch_exception("The builtin RK4 integrator can only integrate matrix or double variables.");
    }
Parameters:
variableThe variable that should be set up. This function will be called only once for each variable.
dsim_integrator::dsim_integrator_result dsim_integrator::step_integration ( dsim_variable variable,
int  step,
double  t,
double  dt 
) [virtual]

Overridden by subclasses to step the integration for a single variable.

Calculates and stores an intermediate value for the provided variable, at the provided integration step. In addition, the variable's state should be updated so that At the time that this function is called, the variable's derivative will already have been updated appropriately by its model.

Note that this function may be called after the integrator has already indicated it has completed integration. The integrator should use the provided step number to determine if this is the case, and do nothing if the step number is not valid for this integrator.

Parameters:
variableThe variable to step
stepThe current integration step number. Integration step numbers begin at 0 and increase monotonically.
tThe current timestep
dtThe current time delta
Returns:
The dsim_integ_finished flag
void dsim_integrator::warning ( const char *  msg,
  ... 
) const

Report a warning.

Output a message at the warning priority level. The message will be sent to the simulation's output handler, if on is installed; it will also be sent to the simulation's output log file.

Parameters:
msgThe format string for the message. See printf documentation for details on the format string.
...The additional arguments required by the format string.
 All Classes Files Functions Typedefs Enumerations Enumerator