ETHZ_Logo RAMSES_Logo_Right   RAMSES   RAMSES_Logo_Left Systems Ecology  
Start    search button      Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE SimMaster;

  (*****************************************************************

    Module  SimMaster     (MW_V3.0)

      Copyright (c) 1986-2006 by Markus Ulrich, Andreas Fischlin, Dimitrios
      Gyalistras and ETH Zurich.

    Purpose   Master module controlling the 'ModelWorks' simulation
              environment.

    Remarks   This module uses the 'Dialog Machine' for conducting the
              user dialog during an interactive simulation session.

              This module is part of the mandatory client interface of
              'ModelWorks', an interactive Modula-2 modelling and
              simulation environment.


    Programming

      o Design
        Markus Ulrich             09/09/1986
        Andreas Fischlin          22/04/1989
        Dimitrios Gyalistras      02/05/1989

      o Implementation
        Markus Ulrich             09/09/1986
        Andreas Fischlin          22/04/1989
        Dimitrios Gyalistras      02/05/1989


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  05/01/1994  DG

  *******************************************************************)


  (****************************************************************)
  (*  Running of the standard interactive simulation environment  *)
  (****************************************************************)

  PROCEDURE RunSimEnvironment( initSimEnv: PROC );
  (*
    Starts the standard interactive simulation environment of
    ModelWorks. This procedure is typically called within the
    body of a program module (a "model definition program", in short
    "MDP") containing or importing model definitions.  Procedure
    "initSimEnv" may be used to extend the standard simulation
    environment by e.g. installing additional menus with their
    commands or also to install a particular model.  See the
    description of the "Dialog Machine" to see how user interface
    extensions are programmed. Typically, initSimEnv will
    contain calls to procedures such as DMMenus.InstallMenu or
    DMWindows.CreateWindow.  A sample program text
    follows:

          MODULE MyModelDefProg;

            FROM DMMenus IMPORT InstallMenu,...;
            FROM DMWindows IMPORT CreateWindow,...;

            FROM SimMaster IMPORT RunSimEnvironment;
            FROM SimBase IMPORT DeclM,...;
            ...

            PROCEDURE ModelDefinitions;
            BEGIN
              DeclM(...); DeclM(...); ...
            END ModelDefinitions;

            PROCEDURE InitMySimEnvironment;
            BEGIN
              InstallMenu(...);
              CreateWindow(...);
            END InitMySimEnvironment;

          BEGIN
            ModelDefinitions;
            RunSimEnvironment( InitMySimEnvironment );
          END MyModelDefProg;

    RunSimEnvironment may be called more then once given that
    each new call occurs on a next higher subprogram level (see
    also DMMaster, DMSystem, and DMOpSys). If you wish to exit
    the simulation environment under control of another program
    (i.e. not by selecting the command "File/Quit") call StopRun
    followed by a call to the DialogMachine-procedure
    DMMaster.QuitDialogMachine. (Re)starting of the interactive
    simulation environment after exiting it on a certain sub-
    program level is possible by calling RunSimEnvironment again.
  *)

  PROCEDURE SimEnvRunning( progLevel: CARDINAL ):BOOLEAN;
  (*
    Returns true if RunSimEnvironment has been called on the
    program level progLevel. SimEnvRunning( DMSystem.CurrentDMLevel() )
    checks whether the simulation environment runs on your
    program's level.
  *)

  PROCEDURE InstallDefSimEnv( defineSimEnv: PROC );
  (*
    Install the procedure "defineSimEnv" as the client procedure
    used to (re)define the interactive simulation environment
    immediately after ModelWorks objects, such as the regular menu
    bar and IO-windows, have been activated and displayed and after
    the simulation environment initialization procedure (see
    "RunSimEnvironment" above) has been called. In particular,
    "defineSimEnv" may be reexecuted by the simulationist by choosing
    the menu command "Settings/Define simulation environment".
    Typical usage of this procedure will open an additional window
    for customized output or will read data from a file.
  *)

  PROCEDURE ExecuteDefSimEnv;
  (*
    Executes the simulation environment (re)definition procedure
    installed bu means of InstallDefSimEnv at the current program
    level.
  *)



  (***************************************************************)
  (*            States of the simulation environment             *)
  (***************************************************************)

  TYPE
    MWState =
        (noSimulation,  (* no simulation going on *)
        simulating,     (* during simulation *)
        pause,          (* current simulation temporarily halted *)
        noModel);       (* no models declared *)
    MWSubState =
        (noRun,      (* in an experiment but not in SimMaster.SimRun *)
        running,     (* in an experiment and in SimMaster.SimRun *)
        noSubState,  (* not in an experiment *)
        stopped);    (* in an experiment which has been stopped (killed) *)

  PROCEDURE GetMWState(VAR s: MWState);
  PROCEDURE GetMWSubState(VAR ss: MWSubState);
  (*
    Allows to determine the current state of ModelWorks during a
    simulation session.
  *)

  PROCEDURE InstallStateChangeSignaling( doAtStateChange: PROC );
  (*
    Installs the client's procedure "doAtStateChange" in ModelWorks
    which will be called each time a change in the state of
    ModelWorks during a simulation session occurs. The current
    state my be obtained by calling GetMWState and GetMWSubState
    (see above).
  *)


  (***************************************************************)
  (*                   Simulation run conditions                 *)
  (***************************************************************)

  TYPE
    StartConsistencyProcedure = PROCEDURE(): BOOLEAN;
    TerminateConditionProcedure = PROCEDURE(): BOOLEAN;

  PROCEDURE InstallStartConsistency( startAllowed: StartConsistencyProcedure );
  (*
    Procedure "startAllowed" is called at the begin of a simulation
    run, right after the execution of the "Initial"-procedures of
    all models (see procedure SimBase.DeclM) or before resuming a
    simulation run after a pause. If it returns FALSE, the
    simulation will be aborted and the simulation environment
    returns to the program state "noSimulation" if no experiment is
    currently running or to the state "simulating/noRun", if an
    experiment is currently executed. If startAllowed returns TRUE
    the simulation is normally continued. Typically this procedure
    is used to check consistency in the initial conditions, e.g. to
    test relations among parameters and initial values.  Since the
    simulationist may interactively change values of parameters
    independently from each other (entry forms test only range
    errors), this consistency test is important in case the model
    equations would be undefined if the conditions were not met.
  *)


  PROCEDURE InstallTerminateCondition( isAtEnd: TerminateConditionProcedure );
  (*
    Procedure "isAtEnd" is called at the end of each time
    (integration) step during simulation.  If it returns TRUE, the
    simulation will be terminated. i.e one of the states
    "noSimulation" or "simulating/noRun" is assumed, the latter
    being the case if an experiment is currently executed. Note
    however, that this mechanism does not correspond to a real
    state event handling, as no iterations to find exact values and
    location on time axis are executed.
  *)


  (***************************************************************)
  (*     Control of elementary and structured simulation runs    *)
  (***************************************************************)

  PROCEDURE SimRun;
  (*
    Perform a single simulation run with the current parameter and
    other variable settings.  Typically this routine is used to do
    several simulation runs, e.g. the construction of a whole phase
    portrait by means of a single menu command or to indentify a
    model parameter.
  *)

  PROCEDURE PauseRun;
  (*
    Sets the flag for the state transition from the program state
    "simulating" into the program state "pause" and will only
    return after the simulationist has chosen the menu command
    "Resume run" under menu "Solve" or until the procedure ResumeRun
    is called, e.g. by means of an additionally installed menu.
  *)

  PROCEDURE ResumeRun;
  (*
    Sets the flag for the state transition from the program state
    "pause" into the program state "simulating".
  *)

  PROCEDURE StopRun;
  (*
    Sets the flag for the state transition from one of the program states
    "simulating" or "pause" into one of the program states "noSimulation"
    or "noModel" (the second state is assumed if no models are present
    after termination of the run).
  *)



  PROCEDURE InstallExperiment( doExperiment: PROC );
  (*
    Install an experiment which may be executed by the user by
    selecting the menu command "Start Experiment" under menu
    "Solve" which corresponds to the call of procedure SimExperiment.
    The procedure "doExperiment" is provided by the modeller and
    contains typically calls to the procedure SimRun (see above).
  *)

  PROCEDURE SimExperiment;
  (*
    Performs the experiment declared for the current program level
    by means of procedure InstallExperiment.
  *)

  PROCEDURE StopExperiment;
  (*
    If an experiment is currently running, this procedure sets the
    flag for the state transition from the program state/substate
    "simulating/running" or "pause/running" into the program state
    "simulating/stopped". In this new state any further calls to
    SimRun are discarded until your experiment-procedure is
    actually finished. Than one of the states "noSimulation" or
    "noModel" is assumed, according to whether any models are
    present after termination of the experiment or not.
    To stop only an individual simulation run, but not the entire
    experiment, use StopRun or InstallTerminateCondition (see above).
  *)



  PROCEDURE ExperimentRunning(): BOOLEAN;
  (*
    ExperimentRunning returns true if a structured simulation run
    is currently in execution, i.e. if the simulationist has
    reached the state simulating by selecting the menu command
    "Start experiment" from menu "Solve" or if the procedure
    SimExperiment has been called. It corresponds to the
    boolean expression "MWSubState<>noSubState".
  *)

  PROCEDURE ExperimentAborted(): BOOLEAN;
  (*
    ExperimentAborted returns true if a running structured
    simulation (experiment) has been stopped (killed)  by the
    simulationist or due to a call to StopExperiment.  It
    corresponds to the boolean expression "MWSubState=stopped".
  *)

  PROCEDURE CurrentSimNr(): INTEGER;
  (*
    Returns the current simulation run number k. This procedure is
    typically called in the client procedure Initial, e.g. to
    assign parameter values depending on the current run k in a
    structured simulation (k = 1, 2, 3, ...).
  *)

  PROCEDURE CurrentTime(): REAL;
  (*
    Returns the current simulation time.
  *)

  PROCEDURE CurrentStep(): INTEGER;
  (*
    Returns the index associated to the current discrete time, i.e.
    the number of coincidence timepoints that have occurred till
    now since begin of the simulation (if the current timepoint is
    a coincidence timepoint, it has already occurred).
  *)

  PROCEDURE LastCoincidenceTime():REAL;
  (*
    Returns the last coincidence time, i.e. the last timepoint at
    which the state of any possibly declared discrete models would
    have been updated.
  *)


END SimMaster.

  Contact RAMSES@env.ethz.ch Last updated: 25-Jul-2011 [Top of page]