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

Inherited by dsim_rk4.

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

enum dsim_integrator::dsim_integrator_result

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:

name	The 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:

variable The 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:

ds	An 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:

ds	The opaque setup pointer provided as the parameter to the call to describe_setup().
command	A command accepted by this integrator, which should match one of the strings handled by this integrator's implementation of parse_setup().
description	A 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:

step	The integration step number.
t	The current (actual) time step.
dt	The 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:

msg	The 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:

msg	The 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:

command	The command string provided for this custom setup line.
data	The 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:

dt	The requested time delta
restart	Set 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:

variable The 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:

variable	The variable to step
step	The current integration step number. Integration step numbers begin at 0 and increase monotonically.
t	The current timestep
dt	The 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:

msg	The format string for the message. See printf documentation for details on the format string.
...	The additional arguments required by the format string.

dsim_integrator Class Reference

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation