SPARK::TProblem Class Reference

Representation of a problem object in the SPARK solver. More...

#include <problem.h>

List of all members.

Public Types

typedef std::bitset< DIAGNOSTICTYPES_L > TDiagnosticLevel

Bitset used to specify the diagnostic level with the different diagnostic types.

enum DiagnosticTypes {
  DiagnosticType_CONVERGENCE,
  DiagnosticType_INPUTS,
  DiagnosticType_REPORTS,
  DiagnosticType_PREFERENCES,
  DiagnosticType_STATISTICS,
  DiagnosticType_REQUESTS,
  DIAGNOSTICTYPES_L
}

Level of more or less detailed diagnostic to the run log output stream. More...

enum SimulationFlags {
  SimulationFlag_OK = 0,
  SimulationFlag_BAD_NUMERICS,
  SimulationFlag_NO_CONVERGENCE,
  SimulationFlag_SINGULAR_SYSTEM,
  SimulationFlag_TIMESTEP_TOO_SMALL,
  SimulationFlag_FAILED_STEP,
  SimulationFlag_IDLE,
  SIMULATIONFLAGS_L
}

Simulation flags. More...

Public Member Functions

Structors

TProblem (unsigned numInverses, SPARK::TInverse *inverses[], unsigned numVariables, SPARK::TVariable *variables[], unsigned numComponents, SPARK::TComponent *components[]) throw (SPARK::XMemory)

Constructs a TProblem object from the structure specified by the variable arrays and the solution sequence described by the component array.

~TProblem () throw ()

Destructor that frees memory allocated for the various solvers.

Main methods invoked by driver function

void Initialize (const SPARK::TRuntimeControls &controls) throw (SPARK::XMemory)

Performs run-time initialization.

void LoadPreferenceSettings (const SPARK::TPreferenceSettings &preferences) throw (SPARK::XMemory)

Loads preference settings (default and for each component).

SimulationFlags Simulate () throw (SPARK::XInitialization)

Computes solution from InitialTime to FinalTime.

void Terminate ()

Ends processing and writes statistics to run log file.

State management functions

These method let you save and restore the problem state in order to allow for a simulation restart from the saved state.

void Save (SPARK::TProblem::TState &state) const throw (SPARK::XInitialization)

Saves problem state at current time.

void Restore (const SPARK::TProblem::TState &state)

Restores problem state at the time specified in the state structure.

Access functions

const char * GetName () const

Returns the name of the problem as const char*.

void SetName (const char *name)

Sets the problem name from name.

unsigned long GetStepCount () const

Returns the number of simulation steps performed so far.

SPARK::TGlobalSettings * GetGlobalSettings ()

Returns pointer to global settings object.

const SPARK::TGlobalSettings * GetGlobalSettings () const

Returns pointer to const global settings object.

Access operations for global problem variables

const SPARK::TVariable & GetGlobalTime () const

Returns a const reference to the TVariable object that describes the global time link.

const SPARK::TVariable & GetGlobalTimeStep () const

Returns a const reference to the TVariable object that describes the global time step link.

Access operations for the problem variables

SPARK::TVariable & GetVariable (unsigned handle) throw (SPARK::XAssertion)

const SPARK::TVariable & GetVariable (unsigned handle) const throw (SPARK::XAssertion)

SPARK::TVariable & GetVariable (const char *name) throw (SPARK::XAssertion)

const SPARK::TVariable & GetVariable (const char *name) const throw (SPARK::XAssertion)

Access operations for the problem inverses

SPARK::TInverse * GetInverse (unsigned handle)

Returns pointer to TInverse object by handle.

SPARK::TInverse * GetInverse (const char *name)

Returns pointer to TInverse object by name.

Access operations for the problem objects

SPARK::TObject * GetObject (unsigned handle)

Returns pointer to TObject object by handle.

SPARK::TObject * GetObject (const char *name)

Returns pointer to TObject object by name.

Predicate methods

bool IsInitialTime () const

Returns true if global time is equal to initial time.

bool IsFinalTime () const

Returns true if global time is equal to final time.

bool Starting () const

bool IsStaticStep () const

Returns true if current step is a static step.

bool IsTimeStepVariable () const

Returns true if key VariableTimeStep is set to 1 in runtime controls.

bool IsReady () const

Returns true if problem is ready for simulation. False otherwise.

bool IsDiagnostic () const

Returns true if any diagnostic is set.

bool IsDiagnostic (DiagnosticTypes d) const

Returns true if diagnostic d is set.

IO functions

bool WriteStamp (std::ostream &os) const

Writes current step stamp to output stream os.

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

Writes simulation statistics to output stream os.

void GenerateSnapshot (const std::string &filename) const throw (SPARK::XInitialization)

Generates the snapshot file named "filename".

Detailed Description

Representation of a problem object in the SPARK solver.

Class methods implement :

read values from input files
generate snapshot files and write reported values to output or trace files
solve system of equations for the unknown problem variables at $Clock=t_{initial}$ where $t_{initial}=InitialTime$ as specified in the runtime controls
solve system of equations for the unknown problem variables for $t_{initial}+dt <= t <= t_{final}$ where and $t_{final} = FinalTime$ as specified in the runtime controls file
save current values of problem variables as history

Note:

The TProblem class relies for all runtime information on a SPARK::TRuntimeControls object that is passed to the TProblem::Initialize() method.

Invoke the TProblem::Initialize() method to bind the SPARK::TRuntimeControls object with a TProblem object.
Before re-invoking the TProblem::Initialize() method, make sure that you have invoked the method TProblem::Terminate() first to reset the various managers.

Examples:: multiproblem_example1.cpp, and sparksolver.cpp.

Member Typedef Documentation

typedef std::bitset<DIAGNOSTICTYPES_L> SPARK::TProblem::TDiagnosticLevel

Bitset used to specify the diagnostic level with the different diagnostic types.
To make a run with convergence and preferences diagnostic, specifiy DiagnosticLevel( 9 () ) in the runtime controls file whereby 9 = 1 (DiagnosticType_CONVERGENCE) + 8 (DiagnosticType_PREFERENCES)

Member Enumeration Documentation

enum SPARK::TProblem::DiagnosticTypes

Level of more or less detailed diagnostic to the run log output stream.

Enumeration values:

DiagnosticType_CONVERGENCE (=1) show convergence behavior at each iteration

DiagnosticType_INPUTS (=2) show where the variables get their input from

DiagnosticType_REPORTS (=4) show reported values at each report event

DiagnosticType_PREFERENCES (=8) show preference settings as loaded in LoadPreferenceSettings()

DiagnosticType_STATISTICS (=16) show run statistics at the end of simulation

DiagnosticType_REQUESTS (=32) show atomic class requests

DIAGNOSTICTYPES_L Number of diagnostic types.

enum SPARK::TProblem::SimulationFlags

Simulation flags.

Enumeration values:

SimulationFlag_OK Step was computed successfully.

SimulationFlag_BAD_NUMERICS Bad numerics detected.

SimulationFlag_NO_CONVERGENCE Could not obtain convergence while solving nonlinear system(s).

SimulationFlag_SINGULAR_SYSTEM Detected a singular or "badly-conditioned" linear system.

SimulationFlag_TIMESTEP_TOO_SMALL Time step selection is limited by MinTimeStep from runtime controls file.

SimulationFlag_FAILED_STEP Step was rejected too many times in response to user's requests.

SimulationFlag_IDLE Default step when starting the simulation.

SIMULATIONFLAGS_L Number of simulation flags.

Constructor & Destructor Documentation

SPARK::TProblem::TProblem ( unsigned numInverses,

SPARK::TInverse * inverses[],

unsigned numVariables,

SPARK::TVariable * variables[],

unsigned numComponents,

SPARK::TComponent * components[]

) throw (SPARK::XMemory)

Constructs a TProblem object from the structure specified by the variable arrays and the solution sequence described by the component array.

Parameters:

numInverses Number of inverses

inverses Array of pointers to TInverse objects

numVariables Number of problem variables

variables Array of pointers to TVariable objects

numComponents Number of components comprising the problem

components Array of pointers to TComponent objects

Exceptions:

Throws SPARK::XMemory if out of memory when building the problem.

SPARK::TProblem::~TProblem ( ) throw ()

Destructor that frees memory allocated for the various solvers.

Note:
Destructor does not destroy any data that was passed to the constructor to describe the problem topology. The calling program is responsible for destroying these data structures explicitly if needed.

Member Function Documentation

void SPARK::TProblem::Initialize ( const SPARK::TRuntimeControls & controls ) throw (SPARK::XMemory)

Performs run-time initialization.

Parameters:

controls runtime control parameters for the simulation

Postcondition:
Initializes clock manager
Allocates history and inner values
Prepares input and output managers
Loads initial values
Fires construct callbacks

Examples:
sparksolver.cpp.

void SPARK::TProblem::LoadPreferenceSettings ( const SPARK::TPreferenceSettings & preferences ) throw (SPARK::XMemory)

Loads preference settings (default and for each component).

Parameters:

preferences An object of class SPARK::TPreferenceSettings that contains data from the *.prf file

Postcondition:
The SPARK::TGlobalSettings object is loaded for this problem.
The SPARK::TComponentSettings object are loaded for each component.

Examples:
sparksolver.cpp.

SimulationFlags SPARK::TProblem::Simulate ( ) throw (SPARK::XInitialization)

Computes solution from InitialTime to FinalTime.

Returns:
Simulation flag as enum SimulationFlags

Precondition:
Problem must have initialized with a prior call to TProblem::Initialize()

Postcondition:
Output and trace files are updated after each simulation step until end of simulation.
Initial snapshot file is generated after the first step if requested in the runtime controls file.
Final snapshot file is generated at the last step if requested in the runtime controls file.

Exceptions:

Throws a SPARK::XInitialization exception object if problem was not initialized or if it is in an inconsistent state.

Examples:
sparksolver.cpp.

void SPARK::TProblem::Terminate ( )

Ends processing and writes statistics to run log file.

Postcondition:
Fires destruct callbacks
Deletes input and output managers
Resets internal counters to allow for a fresh simulation run with a new set of runtime controls specified with a call to TProblem::Initialize().

Examples:
sparksolver.cpp.

void SPARK::TProblem::Save ( SPARK::TProblem::TState & state ) const throw (SPARK::XInitialization)

Saves problem state at current time.
This method populates the state object with the state of the problem at the current time.

Parameters:

state Object containing the problem state being saved.

Exceptions:

Throws a SPARK::XInitialization exception object if problem could not be saved

void SPARK::TProblem::Restore ( const SPARK::TProblem::TState & state )

Restores problem state at the time specified in the state structure.
The method initializes the variables with the trajectory values stored in the state object. For now there is no support for class data persistency.

Parameters:

state Object containing the saved problem state to be restored.

const char* SPARK::TProblem::GetName ( ) const

Returns the name of the problem as const char*.

void SPARK::TProblem::SetName ( const char * name )

Sets the problem name from name.

unsigned long SPARK::TProblem::GetStepCount ( ) const

Returns the number of simulation steps performed so far.

SPARK::TGlobalSettings* SPARK::TProblem::GetGlobalSettings ( )

Returns pointer to global settings object.

const SPARK::TGlobalSettings* SPARK::TProblem::GetGlobalSettings ( ) const

Returns pointer to const global settings object.

const SPARK::TVariable& SPARK::TProblem::GetGlobalTime ( ) const

Returns a const reference to the TVariable object that describes the global time link.

const SPARK::TVariable& SPARK::TProblem::GetGlobalTimeStep ( ) const

Returns a const reference to the TVariable object that describes the global time step link.

SPARK::TVariable& SPARK::TProblem::GetVariable ( unsigned handle ) throw (SPARK::XAssertion)

Returns TVariable& object by handle

Parameters:

handle is the unsigned value that uniquely identifies this variable as specified in the XML file. See TVariable::Handle

Exceptions:

SPARK::XAssertion Could not find a variable for this handle

const SPARK::TVariable& SPARK::TProblem::GetVariable ( unsigned handle ) const throw (SPARK::XAssertion)

Returns const TVariable& object by handle

Parameters:

handle is the unsigned value that uniquely identifies this variable as specified in the XML file. See TVariable::Handle

Exceptions:

SPARK::XAssertion Could not find a variable for this handle

SPARK::TVariable& SPARK::TProblem::GetVariable ( const char * name ) throw (SPARK::XAssertion)

Returns TVariable& object by name

Parameters:

name const char* that stands for the name of the variable as specified in the XML file. See TVariable::Name

Note:
The variable name is case-sensitive.

Exceptions:

SPARK::XAssertion Could not find a variable with this name.

const SPARK::TVariable& SPARK::TProblem::GetVariable ( const char * name ) const throw (SPARK::XAssertion)

Returns const TVariable& object by name

Parameters:

name const char* that stands for the name of the variable as specified in the XML file. See TVariable::Name

Note:
The variable name is case-sensitive.

Exceptions:

SPARK::XAssertion Could not find a variable with this name.

SPARK::TInverse* SPARK::TProblem::GetInverse ( unsigned handle )

Returns pointer to TInverse object by handle.

SPARK::TInverse* SPARK::TProblem::GetInverse ( const char * name )

Returns pointer to TInverse object by name.

SPARK::TObject* SPARK::TProblem::GetObject ( unsigned handle )

Returns pointer to TObject object by handle.

SPARK::TObject* SPARK::TProblem::GetObject ( const char * name )

Returns pointer to TObject object by name.

bool SPARK::TProblem::IsInitialTime ( ) const

Returns true if global time is equal to initial time.

bool SPARK::TProblem::IsFinalTime ( ) const

Returns true if global time is equal to final time.

bool SPARK::TProblem::Starting ( ) const

Returns true if first step of simulation.

Note:
True for first step computed when calling TProblem::Simulate() This is different than checking for GetStepCount()==1 since the StepCount counter is incremented at every step, possibly for multiple calls to TProblem::Simulate(). StepCount is reset to 0 only when calling TProblem::Initialize().

bool SPARK::TProblem::IsStaticStep ( ) const

Returns true if current step is a static step.

bool SPARK::TProblem::IsTimeStepVariable ( ) const

Returns true if key VariableTimeStep is set to 1 in runtime controls.

bool SPARK::TProblem::IsReady ( ) const

Returns true if problem is ready for simulation. False otherwise.

bool SPARK::TProblem::IsDiagnostic ( ) const [inline]

Returns true if any diagnostic is set.

bool SPARK::TProblem::IsDiagnostic ( DiagnosticTypes d ) const [inline]

Returns true if diagnostic d is set.

bool SPARK::TProblem::WriteStamp ( std::ostream & os ) const

Writes current step stamp to output stream os.

void SPARK::TProblem::ReportStatistics ( std::ostream & os,

const std::string & before

) const

Writes simulation statistics to output stream os.

void SPARK::TProblem::GenerateSnapshot ( const std::string & filename ) const throw (SPARK::XInitialization)

Generates the snapshot file named "filename".

The documentation for this class was generated from the following file:

problem.h

Generated on 5 Nov 2003 for VisualSPARK 2.01


Public Types
typedef std::bitset< DIAGNOSTICTYPES_L >	TDiagnosticLevel
	Bitset used to specify the diagnostic level with the different diagnostic types.
enum	DiagnosticTypes { DiagnosticType_CONVERGENCE, DiagnosticType_INPUTS, DiagnosticType_REPORTS, DiagnosticType_PREFERENCES, DiagnosticType_STATISTICS, DiagnosticType_REQUESTS, DIAGNOSTICTYPES_L }
	Level of more or less detailed diagnostic to the run log output stream. More...
enum	SimulationFlags { SimulationFlag_OK = 0, SimulationFlag_BAD_NUMERICS, SimulationFlag_NO_CONVERGENCE, SimulationFlag_SINGULAR_SYSTEM, SimulationFlag_TIMESTEP_TOO_SMALL, SimulationFlag_FAILED_STEP, SimulationFlag_IDLE, SIMULATIONFLAGS_L }
	Simulation flags. More...
Public Member Functions
Structors
	TProblem (unsigned numInverses, SPARK::TInverse inverses[], unsigned numVariables, SPARK::TVariable variables[], unsigned numComponents, SPARK::TComponent *components[]) throw (SPARK::XMemory)
	Constructs a TProblem object from the structure specified by the variable arrays and the solution sequence described by the component array.
	~TProblem () throw ()
	Destructor that frees memory allocated for the various solvers.
Main methods invoked by driver function
void	Initialize (const SPARK::TRuntimeControls &controls) throw (SPARK::XMemory)
	Performs run-time initialization.
void	LoadPreferenceSettings (const SPARK::TPreferenceSettings &preferences) throw (SPARK::XMemory)
	Loads preference settings (default and for each component).
SimulationFlags	Simulate () throw (SPARK::XInitialization)
	Computes solution from InitialTime to FinalTime.
void	Terminate ()
	Ends processing and writes statistics to run log file.
State management functions
These method let you save and restore the problem state in order to allow for a simulation restart from the saved state.
void	Save (SPARK::TProblem::TState &state) const throw (SPARK::XInitialization)
	Saves problem state at current time.
void	Restore (const SPARK::TProblem::TState &state)
	Restores problem state at the time specified in the state structure.
Access functions
const char *	GetName () const
	Returns the name of the problem as const char*.
void	SetName (const char *name)
	Sets the problem name from name.
unsigned long	GetStepCount () const
	Returns the number of simulation steps performed so far.
SPARK::TGlobalSettings *	GetGlobalSettings ()
	Returns pointer to global settings object.
const SPARK::TGlobalSettings *	GetGlobalSettings () const
	Returns pointer to const global settings object.
Access operations for global problem variables
const SPARK::TVariable &	GetGlobalTime () const
	Returns a const reference to the TVariable object that describes the global time link.
const SPARK::TVariable &	GetGlobalTimeStep () const
	Returns a const reference to the TVariable object that describes the global time step link.
Access operations for the problem variables
SPARK::TVariable &	GetVariable (unsigned handle) throw (SPARK::XAssertion)
const SPARK::TVariable &	GetVariable (unsigned handle) const throw (SPARK::XAssertion)
SPARK::TVariable &	GetVariable (const char *name) throw (SPARK::XAssertion)
const SPARK::TVariable &	GetVariable (const char *name) const throw (SPARK::XAssertion)
Access operations for the problem inverses
SPARK::TInverse *	GetInverse (unsigned handle)
	Returns pointer to TInverse object by handle.
SPARK::TInverse *	GetInverse (const char *name)
	Returns pointer to TInverse object by name.
Access operations for the problem objects
SPARK::TObject *	GetObject (unsigned handle)
	Returns pointer to TObject object by handle.
SPARK::TObject *	GetObject (const char *name)
	Returns pointer to TObject object by name.
Predicate methods
bool	IsInitialTime () const
	Returns true if global time is equal to initial time.
bool	IsFinalTime () const
	Returns true if global time is equal to final time.
bool	Starting () const
bool	IsStaticStep () const
	Returns true if current step is a static step.
bool	IsTimeStepVariable () const
	Returns true if key VariableTimeStep is set to 1 in runtime controls.
bool	IsReady () const
	Returns true if problem is ready for simulation. False otherwise.
bool	IsDiagnostic () const
	Returns true if any diagnostic is set.
bool	IsDiagnostic (DiagnosticTypes d) const
	Returns true if diagnostic d is set.
IO functions
bool	WriteStamp (std::ostream &os) const
	Writes current step stamp to output stream os.
void	ReportStatistics (std::ostream &os, const std::string &before) const
	Writes simulation statistics to output stream os.
void	GenerateSnapshot (const std::string &filename) const throw (SPARK::XInitialization)
	Generates the snapshot file named "filename".