3 Simulation Environments (Basic)
A simulation environment encapsulates the state of an executing simulation model. This state information includes the following:
Current simulation time
Now, continuous, and future event lists
Main loop and exit continuations
Process and event being executed
Environment hierarchy
Ordinary differential equation (ODE) solver state
Simulation monitoring hooks
The PLT Scheme Simulation Collection supports multiple simulation environments existing at the same time. This is useful in implementing various simulation techniques:
Nested simulation environments are useful for data collections across multiple simulation model runs. Typically, the outer simulation model defines the global simulation data to be collected across the model runs. It then executes the inner simulation model(s) multiple times and updates the global simulation data with the results of each run. See the Open Loop and Closed Loop examples in Section 8.6 Data Collection Across Multiple Runs for examples.
Nested simulation environments can be used to allow a lower fidelity (but faster) simulation model to reach a steady state before switching to a higher fidelity simulation model.
Multiple simulation can facilitate the development of multiple, independent (or cooperating) simulation models as part of a larger system.
Hierarchical simulation environments allow partitioning of simulation element within a simulation model. Hierarchical simulation models are described in Chapter 14.
This chapter describes the basic features of basic simulation environment.
3.1 The simulation-environment Structure
The simulation-environment structure defines a simulation environment.
| (struct simulation-environment (running? |
| time |
| now-event-list |
| future-event-list |
| loop-next |
| loop-exit |
| event |
| process |
| parent |
| children |
| continuous-event-list |
| evolve |
| control |
| step-type |
| step |
| system |
| step-size |
| dimension |
| y |
| dydt |
| state-changed? |
| max-step-size |
| monitor)) |
| running? : boolean? |
| time : (>=/c 0.0) |
| now-event-list : event-list? |
| future-event-list : event-list? |
| loop-next : (or/c procedure? false/c) |
| loop-exit : (or/c procedure? false/c) |
| event : (or/c event? false/c) |
| process : (or/c process? false/c) |
| parent : (or/c simulation-environment? false/c) |
| children : (listof simulation-environment?) |
| continuous-event-list : event-list? |
| evolve : (or/c ode-evolve? false/c) |
| control : (or/c ode-control? false/c) |
| step-type : (or/c ode-step-type? false/c) |
| step : (or/c ode-step? false/c) |
| system : (or/c ode-system? false/c) |
| step-size : (>/c 0.0) |
| dimension : exact-nonnegative-integer? |
| y : (vectorof real?) |
| dydt : (vectorof real?) |
| state-changed? : boolean? |
| max-step-size : (>/c 0.0) |
| monitor : (or/c procedure? false/c) |
See Section 3.3 Current Simulation Environment Fields for more information on accesing the fields of the current simulation environment.
running? – true, #t, if the simulation main loop is running in this simulation environment and false, #f, otherwise.
time – the simulation clock for the simulation model.
now-event-list – an event list containing the events to be executed now, i.e. before the simulation clock is advanced.
future-event-list – an event list containing the events to be executed in the (simulated) future, i.e. the simulation clock is advanced before the next of these future events is executed.
loop-next – the continuation to return to the simulation main loop that is running in this simulation environment. Calling this continuation signifies the end of process of the current event. This field is false, #f, if the simulation main loop is not running in this simulation environment.
loop-exit – the continuation to exit the simulation main loop that is running in this simulation environment. Calling this continuation signifies the end od the execution of the simulation model. This field is false, #f, if the simulation main loop is not running in this simulation environment.
event – the event currently being executes in the simulation environment or false, #f
process – the process currently being executed in the simulation environment or false, #f
parent – the parent simulation environment of this simulation environment. (See Chapter 14 Hierarchical Environments)
children – a list of the children simulation environments of this simulation environment. (See Chapter 14 Hierarchical Environments)
continuous-event-list – the event list containing the events to be executed continuously. (See Chapter 10 Continuous Simulation Models)
evolve – The ordinary differential equation evolver object. This is created internally. (See Chapter 11 Continuous Simulation Models)
control – The ordinary differential equation control object or false, #f, for fixed step size. This may be specified by the user. (See Chapter 11 Continuous Simulation Models)
step-type – The ordinary differential equation step-type object. This may be specified by the user. (See Chapter 11 Continuous Simulation Models)
step – The ordinary differential equation) stepper object. This is created internally. (See Chapter 11 Continuous Simulation Models)
system – The ordinary differential equation system of equations. This is created internally from the continuous variables in the processes currently working continuously (i.e. on the continuous event list). (See Chapter 11 Continuous Simulation Models)
step-size – The current (last) step size for the ordinary differential equation solver. If the control field is false, #f, this specifies the fixed step size. Otherwise, it is controlled by the control object. (See Chapter 11 Continuous Simulation Models)
dimension – The dimensionality of the system of equations for the ordinary differential equation) solver. This is set internally. (See Chapter 11 Continuous Simulation Models)
y – The state vector for the system of equations for the ordinary differential equation solver. This is created internally from the continuous variables in the processes currently working continuously (i.e. on the continuous event list). (See Chapter 11 Continuous Simulation Models)
dydt – The derivative vector for the system of equations for the ordinary differential equation solver. This is created internally from the continuous variables in the processes currently working continuously (i.e. on the continuous event list). (See Chapter 11 Continuous Simulation Models)
state-changed? – true, #t, if the system of equations for the ordinary differential equation solver has changed and false, #f, otherwise. This is created internally. (See Chapter 11 Continuous Simulation Models)
max-step-size – The limit on the step size for the ordinary differential equation solver. This may be specified by the user. (See Chapter 11 Continuous Simulation Models)
monitor – a procedure that, if specified, is executed prior to advancing the simulation clock. (See Chapter 9 Monitors)
| (make-simulation-environment [parent]) → simulation-environment? |
| parent : (or/c simulation-environment? false/c) = #f |
Returns a new simulation environment with the given parent simulation environment. The newly created simulation environment has time = 0.0 and the simulation main loop is not running (i.e. running? = #f, loop-next = #f, loop-exit = #f, event = #f, and process = #f).
| default-simulation-environment |
Contains the simulation environment that is used as the default value for the current simulation environment (see Section 3.2).
3.2 Current Simulation Environment
The current simulation environment is the simulation environment that is the current focus for most of the simulation calls. It is both thread and continuation specific.
| (current-simulation-environment) → simulation-environment? |
| (current-simulation-environment env) → void? |
| env : simulation-environment? |
Gets or sets the current simulation environment. A guard procedure ensures that the value of current-simulation-environment is indeed a simulation environment, as derermined by simulation-environment?, otherwise a type error is raised.
|
Evaluates its body with the current simulation environment bound to the value of env.
|
Evaluates its body with the current simulation environment bound to a newly created simulation environment. This is the most common way to create and use a new simulation environment.
3.3 Current Simulation Environment Fields
The most common way of accessing the current simulation environment fields is using the following procedures.
| (current-simulation-running? running?) → void? |
| running? : boolean? |
| (current-simulation-running?) → boolean? |
Sets or gets the running? field of the current simulation environment.
time is by far the most frequently used field in the current simulation environment. Use (current-simulation-time) to obtain the current simulation time.
| (current-simulation-time time) → void? |
| time : (>=/c 0.0) |
| (current-simulation-time) → (>=/c 0.0) |
Sets or gets the time field of the current simulation environment.
| (current-simulation-now-event-list now-event-list) → void? |
| now-event-list : (or/c event-list? false/c) |
| (current-simulation-now-event-list) |
| → (or/c event-list? false/c) |
Sets or gets the now-event-list field of the current simulation environment.
| (current-simulation-future-event-list future-event-list) |
| → void? |
| future-event-list : (or/c event-list? false/c) |
| (current-simulation-future-event-list) |
| → (or/c event-list? false/c) |
Sets or gets the future-event-list field of the current simulation environment.
| (current-simulation-loop-next loop-next) → void? |
| loop-next : (or/c procedure? false/c) |
| (current-simulation-loop-next) → (or/c procedure? false/c) |
Sets or gets the loop-next field of the current simulation environment.
Calling (stop-simulation) is the best way to exit the simulation main loop.
| (current-simulation-loop-exit loop-exit) → void? |
| loop-exit : (or/c procedure? false/c) |
| (current-simulation-loop-exit) → (or/c procedure? false/c) |
Sets or gets the loop-exit field of the current simulation environment.
| (current-simulation-event event) → void? |
| event : (or/c event? false/c) |
| (current-simulation-event) → (or/c procedure? false/c) |
Sets or gets the event field of the current simulation environment.
| (current-simulation-process process) → void? |
| process : (or/c process? false/c) |
| (current-simulation-process) → (or/c procedure? false/c) |
Sets or gets the process field of the current simulation environment.
| (current-simulation-parent parent) → void? |
| parent : (or/c simulation-environment? false/c) |
| (current-simulation-parent) |
| → (or/c simulation-environment? false/c) |
Sets or gets the parent field of the current simulation environment.
| (current-simulation-children children) → void? |
| children : (listof simulation-environment?) |
| (current-simulation-children) |
| → (listof simulation-environment?) |
Sets or gets the children field of the current simulation environment.
See Chapter 11 Continuous Models for more information on the use of these procedures to control the integration loop.
| (current-simulation-continuous-event-list continuous-event-list) |
| → void? |
| continuous-event-list : (or/c event-list? false/c) |
| (current-simulation-continuous-event-list) |
| → (or/c event-list? false/c) |
Sets or gets the continuous-event-list field of the current simulation environment.
| (current-simulation-evolve evolve) → void? |
| evolve : (or/c ode-evolve? false/c) |
| (current-simulation-evolve) → (or/c ode-evolve? false/c) |
Sets or gets the evolve field of the current simulation environment.
| (current-simulation-control control) → void? |
| control : (or/c ode-control? false/c) |
| (current-simulation-control) → (or/c ode-control? false/c) |
Sets or gets the control field of the current simulation environment.
| (current-simulation-step-type step-type) → void? |
| step-type : (or/c ode-step-type? false/c) |
| (current-simulation-step-type) → (or/c ode-step-type? false/c) |
Sets or gets the step-type field of the current simulation environment.
| (current-simulation-step step) → void? |
| step : (or/c ode-step? false/c) |
| (current-simulation-step) → (or/c ode-step? false/c) |
Sets or gets the step field of the current simulation environment.
| (current-simulation-system system) → void? |
| system : (or/c ode-system? false/c) |
| (current-simulation-system) → (or/c ode-system? false/c) |
Sets or gets the system field of the current simulation environment.
| (current-simulation-step-size step-size) → void? |
| step-size : (>/c 0.0) |
| (current-simulation-step-size) → (>/c 0.0) |
Sets or gets the step-size field of the current simulation environment.
| (current-simulation-dimension dimension) → void? |
| dimension : natural-number/c |
| (current-simulation-dimension) → natural-number/c |
Sets or gets the dimension field of the current simulation environment.
| (current-simulation-y y) → void? |
| y : (or/c (vector-of real?) false/c) |
| (current-simulation-y) → (or/c (vector-of real?) false/c) |
Sets or gets the y field of the current simulation environment.
| (current-simulation-dydy dydt) → void? |
| dydt : (or/c (vector-of real?) false/c) |
| (current-simulation-dydt) → (or/c (vector-of real?) false/c) |
Sets or gets the dydt field of the current simulation environment.
| (current-simulation-state-changed? state-changed?) → void? |
| state-changed? : boolean? |
| (current-simulation-state-changed?) → boolean? |
Sets or gets the state-changed? field of the current simulation environment.
| (current-simulation-max-step-size max-step-size) → void? |
| max-step-size : (>/c 0.0) |
| (current-simulation-max-step-size) → (>/c 0.0) |
Sets or gets the max-step-size field of the current simulation environment.
See Chapter 9 Monitors for more information on the use of simulation monitors.
| (current-simulation-monitor monitor) → void? |
| monitor : procedure? |
| (current-simulation-monitor) → procedure? |
Sets or gets the monitor field of the current simulation environment.