sparkapi.h

Go to the documentation of this file.

/////////////////////////////////////////////////////////////////////////////////////////
/// \file  sparkapi.h  
/// \brief Header file defining the functions required to manage the %SPARK problems 
///        in a driver function. 
///
/// This file should be included in the C++ source file where the main driver function 
/// is implemented.
///
/// It defines functions to start, end and exit the simulation session :
/// \li SPARK::Start()
/// \li SPARK::End()
/// \li SPARK::ExitWithError()
///
/// Utility functions :
/// \li SPARK::Log()
/// \li SPARK::GetFileName()
///
/// Access functions :
/// \li SPARK::GetProgramName()
/// \li SPARK::GetBaseName()
/// \li SPARK::GetVersion() 
///
/// \li SPARK::GetRunLog()
/// \li SPARK::GetRunLogFilename()
///
/// \li SPARK::GetErrorLog()
/// \li SPARK::GetErrorLogFilename()
///
/// %SPARK problem API functions used to manage SPARK::TProblem objects :
/// \li SPARK::Problem::StaticBuild::ParseCommandLine()
/// \li SPARK::Problem::StaticBuild::ShowCommandLineUsage()
/// \li SPARK::Problem::StaticBuild::Load()
///
/// \li SPARK::Problem::DynamicBuild::ParseCommandLine()
/// \li SPARK::Problem::DynamicBuild::ShowCommandLineUsage()
/// \li SPARK::Problem::DynamicBuild::Load()
///
/// \li SPARK::Problem::Get() 
/// \li SPARK::Problem::Unload() 
/// \li SPARK::Problem::Initialize()
/// \li SPARK::Problem::LoadPreferenceSettings()
/// \li SPARK::Problem::Terminate()
/// \li SPARK::Problem::Save()
/// \li SPARK::Problem::Restore()
/// \li SPARK::Problem::Simulate()
/// \li SPARK::Problem::Step()
/// \li SPARK::Problem::StaticStep()
///
/////////////////////////////////////////////////////////////////////////////////////////
///
/// \author  Dimitri Curtil (LBNL/SRG)
/// \date    May 21, 2002
///          Extended API in Sept, 2003
///
/////////////////////////////////////////////////////////////////////////////////////////
/// \attention
/// PORTIONS COPYRIGHT (C) 2003 AYRES SOWELL ASSOCIATES, INC. \n
/// PORTIONS COPYRIGHT (C) 2003 THE REGENTS OF THE UNIVERSITY OF CALIFORNIA .
///   PENDING APPROVAL BY THE US DEPARTMENT OF ENERGY. ALL RIGHTS RESERVED.
///
/////////////////////////////////////////////////////////////////////////////////////////


#if !defined(__SPARKAPI_H__)
#define __SPARKAPI_H__


#include <iosfwd>
#include <string>
#include <fstream>

#include "problem.h"    // for SPARK::TProblem, SPARK::TProblem::SimulationFlags, SPARK::TProblem::TState
#include "exceptions.h" // for SPARK::XInitialization
#include "compat.h"     // for API_DECLSPEC


/////////////////////////////////////////////////////////////////////////////////////////
/// \namespace SPARK
/// \brief Definition of global functions and classes used in the %SPARK simulation environment.
///
/////////////////////////////////////////////////////////////////////////////////////////

namespace SPARK {

        /////////////////////////////////////////////////////////////////////////////////////
        // Forward declaration
        /////////////////////////////////////////////////////////////////////////////////////
        class TInverse;
        class TObject;
    class TRuntimeControls;
    class TPreferenceSettings;


        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Functions to manage the SPARK solving environment
        //@{
        
        /// \brief Starts the SPARK solving environment.
        ///
        /// \param  sessionName       Name of the simulation session (used in various output files to identify run)
        /// \param  runLogFilename    Name of the run log file where diagnostics for each problem is sent to
        /// \param  errorLogFilename  Name of the log file where runtime errors will be notified
        /// \param  debugLogFilename  Name of the log file where debug informatiion is written in \c SPARK_DEBUG mode
        /// \param  verbose           If true then generates session diagnostic to run log files; if false session remains silent
        API_DECLSPEC(void) Start(
                const char* sessionName, 
                const char* runLogFilename,
                const char* errorLogFilename, 
                const char* debugLogFilename,
                bool verbose = true
                ) SPARK_THROWING( (SPARK::XInitialization) );
        

        /// \brief Terminates the SPARK solving environment.
        ///
        /// Closes all log files. Performs garbage collection for all problems loaded at runtime.
        ///
        /// \post  The SPARK::TProblem objects that have been constructed at runtime using the SPARK::Problem::DynamicLoad()
        ///        function will be automatically destructed following the call to SPARK::End().
        ///
        /// \warning Never explicitly destroy a TProblem object in your code!
        API_DECLSPEC(void) End();


        /// \brief Terminates program execution with exit code
        ///
        /// Writes out to the run log output stream the error message contained in \c ossErrMsg if not NULL.
        ///
        /// \param ec is the exit code of type SPARK::ExitCodes
        /// \param callingSub contains the name of the caller / owner (e.g., problem, atomic class)
        /// \param msg contains the description of the error message. 
        /// \param problem  points to the problem object that is requesting to terminate the simulation (usually the 
        ///        currently active problem).
        ///
        /// \post  The simulation is terminated properly with a call to the function SPARK::End(), therefore
        ///        cleaning up log files and performing garbage collection. 
        ///
        /// \note  If <code> ec == SPARK::ExitCode_OK </code>, then the function returns without doing anything.
        API_DECLSPEC(void) ExitWithError(
                SPARK::ExitCodes ec,                // Error code (should be different than SPARK::ExitCode_OK)
        const std::string& callingSub,      // Name of calling function
                const std::string& msg,             // Description of the error 
                const SPARK::TProblem* problem = 0  // Pointer to currently active problem if available
        );

        //@}
        /////////////////////////////////////////////////////////////////////////////////////



        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Utility functions
        //@{

        /// \brief Returns the pointer to the first string in the argv[] that has the specified extension. 
        ///        If cannot find file with desired extension, returns 0
        ///
        /// This function is more versatile than the SPARK::StaticBuild::ParseCommandLine() and SPARK::DynamicBuild::ParseCommandLine() 
        /// functions as it lets you retrieve one file at a time for the specified extension.
        ///
        /// \note  The string comparison againt the specified extension is case insensitive.
        /// \exception If the desired extension is invalid, throws the SPARK::XInitialization exception.
        API_DECLSPEC(char*) GetFileName(unsigned argc, char* argv[], const char* extension) SPARK_THROWING( (SPARK::XInitialization) );


        /// \brief Writes a message to the specified log file 
        ///
    /// \param os             reference to the std::iostream object where the log entry is displayed
        /// \param strFileName    name of the atomic class file. Use preprocessor macro \c __FILE__ to pass file name automatically.
        /// \param strSenderName  name of the sender object. E.g., pass C-string with inverse function name.
        /// \param strMsg         C-string message terminated by '\\0' character to be displayed in error log file.
        /// \param problem        pointer to the target problem (if available)
        API_DECLSPEC(void) Log(
        std::ostream& os,
                const char* strFileName,
                const char* strSenderName,
                const char* strMsg,
                const SPARK::TProblem* problem=0
        );


        /// \brief Writes a message to the specified log file from a static callback file in a %SPARK atomic class.
        ///
    /// \param os        reference to the std::iostream object where the log entry is displayed
        /// \param sender    pointer to the Inverse instance that sends the message
        /// \param line      indicates the line number in file where the message is sent from
        /// \param strMsg    C-string message terminated by '\\n' character to be displayed in error log file.
        API_DECLSPEC(void) Log(
        std::ostream& os,
                const SPARK::TInverse* sender,
                unsigned line, 
                const char* strMsg
        );


        /// \brief Writes a message to the specified log file from a non-static callback file in a %SPARK atomic class.
        ///
    /// \param os        reference to the std::iostream object where the log entry is displayed
        /// \param sender    pointer to the TObject instance that sends the message
        /// \param line      indicates the line number in file where the message is sent from
        /// \param strMsg    C-string message terminated by '\\n' character to be displayed in error log file.
        API_DECLSPEC(void) Log(
        std::ostream& os,
                const SPARK::TObject* sender,
                unsigned line, 
                const char* strMsg
        );

        //@}
        /////////////////////////////////////////////////////////////////////////////////////



        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Access methods
        // @{

        /// \brief  Returns the name of the program as specified during the call to SPARK::Start()
        ///
        /// \return program name as <code>const char*</code>
        API_DECLSPEC(const char*) GetProgramName() ;

        /// \brief  Returns the base name of the program name (i.e., the program name witout path and 
        ///         without any extension)
        ///
        /// \return base name as <code>const char*</code>
        API_DECLSPEC(const char*) GetBaseName() ;

        /// \brief  Returns the version of the solver library being used
        ///
        /// \return full solver version as <code>const char*</code>
        API_DECLSPEC(const char*) GetVersion() ;

        /// \brief  Returns the output stream for the run log
        ///
        /// \return output stream as <code>std::ostream&</code>
        API_DECLSPEC(std::ostream&) GetRunLog() ;
        
        /// \brief  Returns the output stream for the error log
        ///
        /// \return output stream as <code>std::ostream&</code>
        API_DECLSPEC(std::ostream&) GetErrorLog() ;

        /// \brief  Returns the name of the run log file as specified during the call to SPARK::Start()
        ///
        /// \return run log file name as <code>const char*</code>
        API_DECLSPEC(const char*) GetRunLogFilename() ;

        /// \brief  Returns the name of the error log file as specified during the call to SPARK::Start()
        ///
        /// \return error log file name as <code>const char*</code>
        API_DECLSPEC(const char*) GetErrorLogFilename() ;

        /// \brief  Returns the name of the debug log file as specified during the call to SPARK::Start()
        ///
        /// \return debug log file name as <code>const char*</code>
        API_DECLSPEC(const char*) GetDebugLogFilename() ;

        //@}
        /////////////////////////////////////////////////////////////////////////////////////

}; // namespace SPARK



/////////////////////////////////////////////////////////////////////////////////////////
/// \namespace SPARK::Problem::StaticBuild
/// \brief Definition of the functions used to load a statically-built %SPARK problem.
///
/// These API functions are used to implement the driver function of the stand-alone
/// %SPARK engine.
/////////////////////////////////////////////////////////////////////////////////////////

namespace SPARK { namespace Problem { namespace StaticBuild {

        /// \brief Parses up to argc command-line arguments in argv[] to produce the names of the
        ///        files with extensions "*.run" and "*.prf" as needed to run a statically-built problem.
        ///
        /// This function is used to extract the names of the *.run and *.prf files at the command line
        /// as required by a statically-built simulator, i.e. a simulator that does not need the *.xml
        /// file to load the problem description as it is compiled and linked along the driver function.
        ///
        /// \note No memory is allocated for the 2 strings passed in the argument list. Upon returning 
        ///       from this function, the char*& are pointing to the entries in argv[] that contain the
        ///       corresponding file names with the correct extensions.
        ///
        /// \param  argc        first argument of the main() function declared in the "main.cpp" file
        /// \param  argv        second argument of the main() function declared in the "main.cpp" file
        /// \param  runFileName points to argv[] with name of the file with extension "*.run" 
        /// \param  prfFileName points to argv[] with name of the file with extension "*.prf"
        ///
        /// \exception SPARK::XInitialization  Thrown if more than one *.run or *.prf file is detected at the command-line.
        API_DECLSPEC(void) ParseCommandLine(
                unsigned argc, 
                char** argv, 
                char*& runFileName, 
                char*& prfFileName
        ) SPARK_THROWING( (SPARK::XInitialization) );

        
        /// \brief Writes command-line usage of stand-alone SPARK engine for a statically-built problem to output stream \c os
        ///
        /// \param os     output stream where to write the command-line usage
        API_DECLSPEC(void) ShowCommandLineUsage(std::ostream& os);


        /// \brief Loads the statically-built problem named "pbName".
        ///
        /// By statically-built problem, we refer to a problem whose definition is compiled from the corresponding 
        /// "problem.cpp" file and linked along with the solver library and driver function.
        ///
        /// \return True if operation was successful, false otherwise.
        ///
        /// \param pbName  the unique name for this instance of the problem 
        ///
        /// \post If the problem was loaded successfully, then the SPARK::TProblem instance is stored in the 
        ///       global problem repository with its name for later retrieval through a call to 
        ///       SPARK::Problem::Get().
        ///
        API_DECLSPEC(bool) Load(const char* pbName);


}; }; }; // namespace SPARK::Problem::StaticBuild



/////////////////////////////////////////////////////////////////////////////////////////
/// \namespace SPARK::Problem::DynamicBuild
/// \brief Definition of the functions used to load a %SPARK problem at runtime.
///
/// These API functions are used to implement the driver function of the stand-alone
/// %SPARK engine.
/////////////////////////////////////////////////////////////////////////////////////////

namespace SPARK { namespace Problem { namespace DynamicBuild {

        /// \brief Parses up to argc command-line arguments in argv[] to produce the name of the
        ///        files with extensions "*.run", "*.prf" and "*.xml" as needed to run a problem
        ///        loaded at runtime.
        ///
        /// \note No memory is allocated for the 3 strings passed in the argument list. Upon returning 
        ///       from this function, the char*& are pointing to the entries in argv[] that contain the
        ///       corresponding file names with the correct extensions.
        ///
        /// \param  argc        first argument of the main() function declared in the "main.cpp" file
        /// \param  argv        second argument of the main() function declared in the "main.cpp" file
        /// \param  runFileName points to argv[] with name of the file with extension "*.run" 
        /// \param  prfFileName points to argv[] with name of the file with extension "*.prf"
        /// \param  xmlFileName points to argv[] with name of the file with extension "*.xml"
        ///
        /// \exception SPARK::XInitialization  Thrown if more than one *.run or *.prf or *.xml file is detected at the command-line.
        API_DECLSPEC(void) ParseCommandLine(
                unsigned argc, 
                char** argv, 
                char*& runFileName, 
                char*& prfFileName,
                char*& xmlFileName
        ) SPARK_THROWING( (SPARK::XInitialization) );


        /// \brief Writes command-line usage of stand-alone SPARK engine for a problem loaded at runtime to output stream \c os
        ///
        /// \param os     output stream where to write the command-line usage
        API_DECLSPEC(void) ShowCommandLineUsage(std::ostream& os);


        /// \brief Loads the problem named "pbName" at runtime and sets name of problem instance after unique 
        ///        identifier "pbName" 
        ///
        /// \return True if operation was successful, false otherwise.
        ///
        /// \param pbName       the unique name for this instance of the problem 
        /// \param xmlFileName  name of the xml file with the problem description
        ///
        /// \post If the problem was loaded successfully, then the SPARK::TProblem instance is stored in the 
        ///       global problem repository with its name for later retrieval through a call to 
        ///       SPARK::Problem::Get().
        ///
        /// \post Furthermore, if the problem was loaded successfully using the runtime loading mechanism, 
        ///       then the problem factory used to construct the problem is stored in the factory
        ///       repository to support garbage collection upon the call to the function SPARK::End().
        API_DECLSPEC(bool) Load(
                const char* pbName, 
                const char* xmlFileName
        );

        
}; }; }; // namespace SPARK::Problem::DynamicBuild



/////////////////////////////////////////////////////////////////////////////////////////
/// \namespace SPARK::Problem
/// \brief Definition of the %SPARK problem driver API library used to manage the  
///        SPARK::TProblem objects in the driver function.
/////////////////////////////////////////////////////////////////////////////////////////

namespace SPARK { namespace Problem {

        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Methods used to setup a problem for simulation
        // @{

        /// \brief Registers statically-built problem by address with static repository 
        ///
        /// \param  pbName    unique problem name 
        /// \param  instance  address of the SPARK::TProblem instance
        /// \return Returns true if operation was successful, false otherwise
        ///
        /// \note    Used in "problem.cpp" file for precompiled problem file.
        /// \note    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.
        ///
        API_DECLSPEC(bool) RegisterStaticInstance(
                const char* pbName, 
                SPARK::TProblem* instance
        );


        /// \brief Unloads the problem instance named "pbName" from repository and frees memory.
        ///
        /// \return Returns true if instance successfully unloaded; false otherwise
        /// \param  pbName   name of the problem to unload
        ///
        /// \note   If there is no problem instance named after "pbName", the function will return
        ///         false.
        /// \note   This function unloads both statically-built problems and problems loaded at runtime
        ///         , i.e. problem instances loaded:
        ///         - either with a call to SPARK::Problem::StaticBuild::Load() or 
        ///         - with a call to SPARK::Problem::DynamicBuild::Load().
        ///
        /// \warning An unloaded problem can no longer be:
        ///          - used in the driver function or 
        ///          - retrieved with a call to the function SPARK::Problem::Get().
        API_DECLSPEC(bool) Unload(const char* pbName);


        /// \brief Writes out the list of loaded problem instances to the output stream \c os with 
        ///        leading string \c before
    ///
    /// \param os      Output stream for write operation
    /// \param before  Prefix string written before the names of the instances
        API_DECLSPEC(void) WriteInstances(std::ostream& os, const std::string& before);


    /// \brief Access method to retrieve a previously loaded problem through its unique name 
    ///        from the problem repository.
        ///
        /// \return Address of the SPARK::TProblem instance describing the problem named "pbName"
        /// \param  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.
        API_DECLSPEC(SPARK::TProblem*) Get(const char* pbName);


    /// \brief  Initializes the problem with the specified runtime controls
    ///
    /// Calls the SPARK::TProblem::Initialize() method.
    ///
    /// \param  instance   Address of the SPARK::TProblem object
    /// \param  controls   Runtime controls as specified in a *.run file
    API_DECLSPEC(void) Initialize(SPARK::TProblem* instance, const SPARK::TRuntimeControls& controls);


    /// \brief Loads the preference settings into the problem
    ///
    /// Calls the SPARKK::TProblem::LoadPreferenceSettings() method.
    ///
    /// \param  instance    Address of the SPARK::TProblem object
    /// \param  preferences Preference settings as specified in a *.prf file
    API_DECLSPEC(void) LoadPreferenceSettings(SPARK::TProblem* instance, const SPARK::TPreferenceSettings& preferences);


    /// \brief Terminates the problem.
    ///
    /// Calls the SPARK::TProblem::Terminate() method.
    ///
    /// \post The problem must be re-initialized with a call to SPARK::TProblem::Initialize() to allow for
    ///       a new simulation.
    /// 
    /// \param  instance   Address of the SPARK::TProblem object
    API_DECLSPEC(void) Terminate(SPARK::TProblem* instance);


        //@}
        /////////////////////////////////////////////////////////////////////////////////////

    
        /////////////////////////////////////////////////////////////////////////////////////
        /// \name State management methods
        // @{

    /// \brief Saves the state of the problem at the current time
    ///
    /// Calls the SPARK::TProblem::Save() method.
    ///
    /// \post The state object will contain the new state. If it contained another state, it will
    ///       be overriden. The problem object remains unchanged.
    ///
    /// \param  instance   Address of the SPARK::TProblem object
    /// \param  state      SPARK::TProblem::TState object containing the stored state
    API_DECLSPEC(void) Save(const SPARK::TProblem* instance, SPARK::TProblem::TState& state);

    /// \brief Restores the problem to the specified state
    ///
    /// Calls the SPARK::TProblem::Restore() method.
    ///
    /// \pre  The state to restore must have been saved with a call to SPARK::Problem::Save().
    /// \post The problem is restored to the state, in particular the global time, the current
    ///       values of all variables as well as their history.
    ///
    /// \param  instance   Address of the SPARK::TProblem object
    /// \param  state      SPARK::TProblem::TState object containing the state to restore
    API_DECLSPEC(void) Restore(SPARK::TProblem* instance, const SPARK::TProblem::TState& state); 

        //@}
        /////////////////////////////////////////////////////////////////////////////////////


        /////////////////////////////////////////////////////////////////////////////////////
        /// \name Simulation methods 
        // @{

    /// \class simulation_parameter
    /// \brief Class used to specify a simulation parameter.
    ///
    /// Wrapper class around a POD object of type T that keeps track of whether the parameter 
    /// was initialized in the constructor.
    /// Used in the various simulation methods that accept parameters as arguments.
    ///
    template<typename T>
    class CLASS_DECLSPEC simulation_parameter  {
    public:
        /////////////////////////////////////////////////////////////////////////////////
        // Type definition
        typedef T  value_type;  ///< template type for the parameter 


        /////////////////////////////////////////////////////////////////////////////////
        // Structors 
        
        /// Default constructor: empty parameter
        simulation_parameter() 
            : EmptyFlag(true) 
        {} 
        /// Explicit constructor: stores value as parameter
        explicit simulation_parameter(T value) 
            : EmptyFlag(false), Value(value) 
        {} 
        /// Copy constructor: deep copy of parameter value
        simulation_parameter(const simulation_parameter& p) 
            : EmptyFlag(p.EmptyFlag), Value(p.Value) 
        {} 
        ~simulation_parameter() 
        {}

        
        /////////////////////////////////////////////////////////////////////////////////
        // Access methods
        
        /// Returns true if parameter is empty, false otherwise.
        bool empty() const { return EmptyFlag; } 
        /// Returns a copy of the parameter value
        value_type get() const { return Value; } 
        /// Automatic conversion to parameter type
        operator value_type() const { return get(); } 

    private:
        simulation_parameter& operator=(const simulation_parameter& p);

        const bool EmptyFlag;
        value_type Value;
    };


    // Helper function that returns an empty simulation_parameter object for the template type.
    template<typename T>
    inline simulation_parameter<T> make_empty_parameter() { return simulation_parameter<T>(); }
    
    // Helper function that returns a simulation_parameter object for the template type specified in argument list.
    template<typename T>
    inline simulation_parameter<T> make_parameter(T value) { return simulation_parameter<T>( value ); }

    
    // Type definition for the supported parameters so far
    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


    /// \brief Simulates the <code>instance</code> 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.
    ///
    /// \pre The problem must have been initialized.
    ///
    /// \return Simulation flag
    /// \param  instance        Address of the SPARK::TProblem object
    /// \param  restartFlag     Boolean flag. If true, forces the simulation to (re-)start with a static step to 
    ///                         ensure consistent initialization.
    /// \param  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.
    /// \param  initialTimeStep Value of the candidate initial time step as a double parameter.
    API_DECLSPEC(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()
    );


    /// \brief  Computes the next step of the <code>instance</code> 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.
    ///
    /// \pre The problem must have been initialized.
    ///
    /// \param  instance   Address of the SPARK::TProblem object
    /// \param  timeStep   Candidate time step
    API_DECLSPEC(SPARK::TProblem::SimulationFlags) Step(
        SPARK::TProblem* instance, 
        const SPARK::Problem::TTimeStep& timeStep = SPARK::Problem::TTimeStep()
    );


    /// \brief  Computes one static step for the <code>instance</code> 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.
    ///
    /// \pre The problem must have been initialized.
    ///
    /// \param  instance   Address of the SPARK::TProblem object
    API_DECLSPEC(SPARK::TProblem::SimulationFlags) StaticStep(SPARK::TProblem* instance);


        //@}
        /////////////////////////////////////////////////////////////////////////////////////


};  }; // namespace SPARK::Problem
/////////////////////////////////////////////////////////////////////////////////////////


#endif  //__SPARKAPI_H__

---