Main Page | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages | Examples

SPARK::Problem Namespace Reference

Definition of the SPARK problem driver API library used to manage the SPARK::TProblem objects in the driver function. More...


Classes

class  simulation_parameter
 Class used to specify a simulation parameter. More...


Simulation methods

typedef simulation_parameter<
bool > 		TRestartFlag
 Parameter type describing the restart flag.

typedef simulation_parameter<
double > 		TStopTime
 Parameter type describing the stop time.

typedef simulation_parameter<
double > 		TTimeStep
 Parameter type describing the time step.

SPARK::TProblem::SimulationFlags Simulate (SPARK::TProblem *instance, const SPARK::Problem::TRestartFlag &restartFlag, const SPARK::Problem::TStopTime &stopTime, const SPARK::Problem::TTimeStep &initialTimeStep=SPARK::Problem::TTimeStep())
 Simulates the instance problem until the final time or the stopping time is reached, whichever occurs first.

SPARK::TProblem::SimulationFlags Step (SPARK::TProblem *instance, const SPARK::Problem::TTimeStep &timeStep=SPARK::Problem::TTimeStep())
 Computes the next step of the instance problem and returns the simulation flag.

SPARK::TProblem::SimulationFlags StaticStep (SPARK::TProblem *instance)
 Computes one static step for the instance problem and returns the simulation flag.


Methods used to setup a problem for simulation

bool RegisterStaticInstance (const char *pbName, SPARK::TProblem *instance)
 Registers statically-built problem by address with static repository.

bool Unload (const char *pbName)
 Unloads the problem instance named "pbName" from repository and frees memory.

void WriteInstances (std::ostream &os, const std::string &before)
 Writes out the list of loaded problem instances to the output stream os with leading string before.

SPARK::TProblem * Get (const char *pbName)
 Access method to retrieve a previously loaded problem through its unique name from the problem repository.

void Initialize (SPARK::TProblem *instance, const SPARK::TRuntimeControls &controls)
 Initializes the problem with the specified runtime controls.

void LoadPreferenceSettings (SPARK::TProblem *instance, const SPARK::TPreferenceSettings &preferences)
 Loads the preference settings into the problem.

void Terminate (SPARK::TProblem *instance)
 Terminates the problem.


State management methods

void Save (const SPARK::TProblem *instance, SPARK::TProblem::TState &state)
 Saves the state of the problem at the current time.

void Restore (SPARK::TProblem *instance, const SPARK::TProblem::TState &state)
 Restores the problem to the specified state.

Detailed Description

Definition of the SPARK problem driver API library used to manage the SPARK::TProblem objects in the driver function.

Typedef Documentation

typedef simulation_parameter<bool> SPARK::Problem::TRestartFlag
 

Parameter type describing the restart flag.

typedef simulation_parameter<double> SPARK::Problem::TStopTime
 

Parameter type describing the stop time.

typedef simulation_parameter<double> SPARK::Problem::TTimeStep
 

Parameter type describing the time step.

Function Documentation

bool RegisterStaticInstance (  const char *  pbName,
SPARK::TProblem *  instance
) 
 

Registers statically-built problem by address with static repository.

Parameters:
pbName unique problem name
instance address of the SPARK::TProblem instance
Returns:
Returns true if operation was successful, false otherwise
Note:
Used in "problem.cpp" file for precompiled problem file.

The name of the problem instance must be unique for this simulation session, otherwise the SPARK solver will not be able to load this problem at runtime. This will result in the SPARK problem loader throwing a SPARK::XInitialization exception with the exit code SPARK::ExitCode_ERROR_INVALID_PROBLEM when calling the function SPARK::Start().

Warning:
Since this function is typically invoked in the "problem.cpp" file, it is called at startup before entering the main function. Therefore, no error message can be reported to a log file. SPARK::Start() will throw a SPARK::XInitialization exception if any such error occurred at startup.

bool Unload (  const char *  pbName  ) 
 

Unloads the problem instance named "pbName" from repository and frees memory.

Returns:
Returns true if instance successfully unloaded; false otherwise
Parameters:
pbName name of the problem to unload
Note:
If there is no problem instance named after "pbName", the function will return false.

This function unloads both statically-built problems and problems loaded at runtime , i.e. problem instances loaded:

Warning:
An unloaded problem can no longer be:

void WriteInstances (  std::ostream &  os,
const std::string &  before
) 
 

Writes out the list of loaded problem instances to the output stream os with leading string before.

Parameters:
os Output stream for write operation
before Prefix string written before the names of the instances

SPARK::TProblem* Get (  const char *  pbName  ) 
 

Access method to retrieve a previously loaded problem through its unique name from the problem repository.

Returns:
Address of the SPARK::TProblem instance describing the problem named "pbName"
Parameters:
pbName name of the problem whose address is to be returned
Note:
Returns NULL if problem name was not previouly loaded or if no problem with this name exists in global repository.
Examples:
multiproblem_example1.cpp, and sparksolver.cpp.

void Initialize (  SPARK::TProblem *  instance,
const SPARK::TRuntimeControls &  controls
) 
 

Initializes the problem with the specified runtime controls.

Calls the SPARK::TProblem::Initialize() method.

Parameters:
instance Address of the SPARK::TProblem object
controls Runtime controls as specified in a *.run file
Examples:
multiproblem_example1.cpp.

void LoadPreferenceSettings (  SPARK::TProblem *  instance,
const SPARK::TPreferenceSettings &  preferences
) 
 

Loads the preference settings into the problem.

Calls the SPARKK::TProblem::LoadPreferenceSettings() method.

Parameters:
instance Address of the SPARK::TProblem object
preferences Preference settings as specified in a *.prf file
Examples:
multiproblem_example1.cpp.

void Terminate (  SPARK::TProblem *  instance  ) 
 

Terminates the problem.

Calls the SPARK::TProblem::Terminate() method.

Postcondition:
The problem must be re-initialized with a call to SPARK::TProblem::Initialize() to allow for a new simulation.
Parameters:
instance Address of the SPARK::TProblem object
Examples:
multiproblem_example1.cpp.

void Save (  const SPARK::TProblem *  instance,
SPARK::TProblem::TState &  state
) 
 

Saves the state of the problem at the current time.

Calls the SPARK::TProblem::Save() method.

Postcondition:
The state object will contain the new state. If it contained another state, it will be overriden. The problem object remains unchanged.
Parameters:
instance Address of the SPARK::TProblem object
state SPARK::TProblem::TState object containing the stored state

void Restore (  SPARK::TProblem *  instance,
const SPARK::TProblem::TState &  state
) 
 

Restores the problem to the specified state.

Calls the SPARK::TProblem::Restore() method.

Precondition:
The state to restore must have been saved with a call to SPARK::Problem::Save().
Postcondition:
The problem is restored to the state, in particular the global time, the current values of all variables as well as their history.
Parameters:
instance Address of the SPARK::TProblem object
state SPARK::TProblem::TState object containing the state to restore

SPARK::TProblem::SimulationFlags Simulate (  SPARK::TProblem *  instance,
const SPARK::Problem::TRestartFlag &  restartFlag,
const SPARK::Problem::TStopTime &  stopTime,
const SPARK::Problem::TTimeStep &  initialTimeStep = SPARK::Problem::TTimeStep()
) 
 

Simulates the instance problem until the final time or the stopping time is reached, whichever occurs first.

This function calls the TProblem:Simulate() method after having sent the appropriate requests for the specified simulation parameters. Uses the initial time step if specified. By default there is no initial time step parameter. Starts with a static step if the restart flag is set to true.

Precondition:
The problem must have been initialized.
Returns:
Simulation flag
Parameters:
instance Address of the SPARK::TProblem object
restartFlag Boolean flag. If true, forces the simulation to (re-)start with a static step to ensure consistent initialization.
stopTime Value of the desired stopping time as a double parameter. If not specified, the simulation ends when the final time specified in the runtime controls is reached.
initialTimeStep Value of the candidate initial time step as a double parameter.
Examples:
multiproblem_example1.cpp.

SPARK::TProblem::SimulationFlags Step (  SPARK::TProblem *  instance,
const SPARK::Problem::TTimeStep &  timeStep = SPARK::Problem::TTimeStep()
) 
 

Computes the next step of the instance problem and returns the simulation flag.

This function essentially sends a stop() request to the instance problem and calls the TProblem::Simulate() method. This forces the finite-state machine to stop after the first step.

If the finite-state machine is set to perform a static step following a prior restart request, then the next step is a static step. Otherwise, it will perform the next dynamic step with the candidate time step if specified.

Note:
When calling this function make sure that the runtime controls do not request a final snapshot file as this would be generated each time the problem steps forward, therefore being very resource intensive. When stepping the problem as opposed to simulating it, prefer requesting a snapshot file using the snapshot request when needed.
Precondition:
The problem must have been initialized.
Parameters:
instance Address of the SPARK::TProblem object
timeStep Candidate time step

SPARK::TProblem::SimulationFlags StaticStep (  SPARK::TProblem *  instance  ) 
 

Computes one static step for the instance problem and returns the simulation flag.

This function essentially sends a stop() request to the instance problem and calls the TProblem::Simulate() method. This forces the finite-state machine to stop after the first step.

Precondition:
The problem must have been initialized.
Parameters:
instance Address of the SPARK::TProblem object

Generated on 5 Nov 2003 for VisualSPARK 2.01