[Go to first, previous, next page;   contents;   index]

Chapter 3

Simulation Environments (Basic)

A simulation environment encapsulates the state of an executing simulation model. This state information includes the following:

The PLT Scheme Simulation Collection supports multiple simulation environments existing at the same time. This is useful for implement various simulation techniques.

Nested simulation environments are useful for data collection across multiple simulation model runs. Typically, an outer simulation model defines the global simulation data to be collected across the model runs. It then executes the inner simulation model 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 also be used to allow a lower fidelity (but faster) simulation model to reach a steady state before starting a higher fidelity simulation model.

Multiple simulation environments can facilitate the development of multiple, independent (or cooperating) simulation models as part of a larger system.

Note that these usages of multiple simulation environments is different than hierarchical simulation environments, which allow partitioning of simulation elements within a simulation model. Hierarchical simulation models are described in Chapter 13.

This section describes the basic features of simuation environments.

3.1  The simulation-environment Structure

simulation-environment

Structure: 
simulation-environment

Contract: 

(struct simulation-environment
        ((running? boolean?)
         (time (>=/c 0.0))
         (now-event-list event-list?)
         (future-event-list event-list?)
         (loop-next (union/c procedure? #f))
         (loop-exit (union/c procedure? #f))
         (event (union/c event? #f))
         (process (union/c process? #f))
         (parent (union/c simulation-environment? #f))
         (children (list-of simulation-environment?))
         (continuous-event-list event-list?)
         (evolve (union/c ode-evolve? #f))
         (control (union/c ode-control? #f))
         (step-type (union/c ode-step-type? #f))
         (step (union/c ode-step? #f))
         (system (union/c ode-system? #f))
         (step-size (>/c 0.0))
         (dimension (integer-in 0 +inf.0))
         (y (vector-of real?))
         (dydt (vector-of real?))
         (state-changed? boolean?)
         (max-step-size (>/c 0.0))
         (monitor (union/c procedure? #f))))

This structure defines a simulation environment. The following describes the fields and what they represent with respect to the simulation model running in the simulation environment.
running? - #t if the simulation main loop is running in this simulation environment, #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 between these events.
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 processing of the current event. This field is #f if the simulation main loop is not running in this simulation environment.
loop-exit - The continuation to exit the simulation main loop running in this simulation environment. Calling this continuation signifies the end of the execution of the simulation model. This field is #f if the simulation main loop is not running in this simulation environment.
event - The event currently being executed in the simulation environment, or #f.
process - The process currently being executed in the simulation environment, or #f.
parent - The parent simulation environment. (See Chapter 13 Hierarchical Environments)
children - A list of children simulation environments. (See Chapter 13 Hierarchical Environments)
continuous-event-list - An event list containing the events to be executed continuously. (See Chapter 10 Continuous Simulation Models)
evolve - The ordinary differential equation (ODE) evolver object. This is created internally. (See Chapter 10 Continuous Simulation Models)
control - The ordinary differential equation (ODE) control object or #f for fixed-size steps. This may be specified by the user. (See Chapter 10 Continuous Simulation Models)
step-type - The ordinary differential equation (ODE) step-type object. This may be specified by the user. (See Chapter 10 Continuous Simulation Models)
step - The ordinary differential equation (ODE) stepper object. This is created internally. (See Chapter 10 Continuous Simulation Models)
system - The ordinary differential equation (ODE) system of equations. This is created internally from the continuous variables in the processes currently working continuously. (See Chapter 10 Continuous Simulation Models)
step-size - The current (last) step size for the ordinary differential equation (ODE) solver. If the control field is #f this should specify the fized step size. Otherwise, it is controlled by the control object. (See Chapter 10 Continuous Simulation Models)
dimension - The dimension of the system of equations for the ordinary differential equation (ODE) solver. This is created internally. (See Chapter 10 Continuous Simulation Models)
y - The state vector for the system of equations for the ordinary differential equation (ODE) solver. This is created internally from the continuous variables in the processes currently working continuously. (See Chapter 10 Continuous Simulation Models)
dydt - The derivative vector for the system of equations for the ordinary differential equation (ODE) solver. This is created internally from the continuous variables in the processes currently working continuously. (See Chapter 10 Continuous Simulation Models)
state-changed? - #t if the system of equations for the ordinary differential equation (ODE) solver has changed and #f otherwise. This is created internally. (See Chapter 10 Continuous Simulation Models)
max-step-size - The limit on the step size for the ordinary differential equation (ODE) solver. (See Chapter 10 Continuous Simulation Models)
monitor - A procedure that, if specified, is executed prior to advancing the simulation clock. (See Chapter ?? Monitors)

make-simulation-environment

Function: 
(make-simulation-environment parent)
(make-simulation-environment)

Contract: 

(case-> (-> simulation-environment? simulation-environment?)
        (-> simulation-environment?))

This function returns a new simulation environment with the given parent simulation environment. The newly created simulation environment has time = 0.0, the event lists are empty, and the simulation main loop is not running (e.g. running? = #f, loop-next = #f, loop-exit = #f, event = #f, and process = #f).

default-simulation-environment

Variable: 
default-simulation-environment

This variable 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 collection calls. It is both thread and continuation specific.

current-simulation-environment

Function: 
(current-simulation-environment env)
(current-simulation-environment)

Contract: 

(case-> (-> simulation-environment? any)
        (-> simulation-environmment?))

Gets or sets the current simulation environment. A guard procedure ensures that the value of current-simulation-environment is indeed a simulation environment, as determined by simulation-environment?, otherwise a type error is raised.

with-simulation-environment

Macro: 
(with-simulation-environment simulation-environment
  body ...)

This macro evaluates its body with the current simulation environment bound to the value of simulation-environment.

with new-simulation-environment

Macro: 
(with-new-simulation-environment
  body ...)

This macro evaluates its body with the current simulation environment bound to a newly created simulation-environment. This is most common way to create and use a new simulation environment.

3.2.1  Current Simulation Environment Fields

current-simulation-running?

Function: 
(current-simulation-running? running?)
(current-simulation-running?)

Contract: 

(case-> (-> boolean? any)
        (-> boolean?))

Sets or gets the running? field of the current simulation environment.

current-simulation-time

Function: 
(current-simulation-time time)
(current-simulation-time)

Contract: 

(case-> (-> (>=/c 0.0) any)
        (-> (>=/c 0.0)))

Sets or gets the time field of the current simulation environment.

current-simulation-now-event-list

Function: 
(current-simulation-now-event-list now-event-list)
(current-simulation-now-event-list)

Contract: 

(case-> (-> (union/c event-list? #f) any)
        (-> (union/c event-list? #f)))

Sets or gets the now-event-list field of the current simulation environment.

current-simulation-future-event-list

Function: 
(current-simulation-future-event-list future-event-list)
(current-simulation-future-event-list)

Contract: 

(case-> (-> (union/c event-list? #f) any)
        (-> (union/c event-list? #f)))

Sets or gets the future-event-list field of the current simulation environment.

current-simulation-loop-next

Function: 
(current-simulation-loop-next loop-next)
(current-simulation-loop-next)

Contract: 

(case-> (-> (union/c procedure? #f) any)
        (-> (union/c procedure? #f)))

Sets or gets the loop-next field of the current simulation environment.

current-simulation-loop-exit

Function: 
(current-simulation-loop-exit loop-exit)
(current-simulation-loop-exit)

Contract: 

(case-> (-> (union/c procedure? #f) any)
        (-> (union/c procedure? #f)))

Sets or gets the loop-exit field of the current simulation environment.

current-simulation-event

Function: 
(current-simulation-event event)
(current-simulation-event)

Contract: 

(case-> (-> (union/c event? #f) any)
        (-> (union/c event? #f)))

Sets or gets the event field of the current simulation environment.

current-simulation-process

Function: 
(current-simulation-process process)
(current-simulation-process)

Contract: 

(case-> (-> (union/c process? #f) any)
        (-> (union/c process? #f)))

Sets or gets the process field of the current simulation environment.

current-simulation-parent

Function: 
(current-simulation-parent parent)
(current-simulation-parent)

Contract: 

(case-> (-> (union/c simulation-environment? #f) any)
        (-> (union/c simulation-environment? #f)))

Sets or gets the parent field of the current simulation environment.

current-simulation-children

Function: 
(current-simulation-children children)
(current-simulation-children)

Contract: 

(case-> (-> (list-of simulation-environment?) any)
        (-> (list-of simulation-environment?)))

Sets or gets the children field of the current simulation environment.

current-simulation-continuous-event-list

Function: 
(current-simulation-continuous-event-list continuous-event-list)
(current-simulation-continuous-event-list)

Contract: 

(case-> (-> event-list? any)
        (-> event-list?))

Sets or gets the continuous-event-list field of the current simulation environment.

current-simulation-evolve

Function: 
(current-simulation-evolve evolve)
(current-simulation-evolve)

Contract: 

(case-> (-> (union/c ode-evolve? #f) any)
        (-> (union/c ode-evolve? #f)))

Sets or gets the evolve field of the current simulation environment.

current-simulation-control

Function: 
(current-simulation-control control)
(current-simulation-control)

Contract: 

(case-> (-> (union/c ode-control? #f) any)
        (-> (union/c ode-control? #f)))

Sets or gets the control field of the current simulation environment.

current-simulation-step-type

Function: 
(current-simulation-step-type step-type)
(current-simulation-step-type)

Contract: 

(case-> (-> ode-step-type? any)
        (-> ode-step-type?))

Sets or gets the step-type field of the current simulation environment.

current-simulation-step

Function: 
(current-simulation-step step)
(current-simulation-step)

Contract: 

(case-> (-> (union/c ode-step? #f) any)
        (-> (union/c ode-step? #f)))

Sets or gets the step field of the current simulation environment.

current-simulation-system

Function: 
(current-simulation-system system)
(current-simulation-system)

Contract: 

(case-> (-> (union/c ode-system? #f) any)
        (-> (union/c ode-system? #f)))

Sets or gets the system field of the current simulation environment.

current-simulation-step-size

Function: 
(current-simulation-step-size step-size)
(current-simulation-step-size)

Contract: 

(case-> (-> (>/c 0.0) any)
        (-> (>/c 0.0)))

Sets or gets the step-size field of the current simulation environment.

current-simulation-dimension

Function: 
(current-simulation-dimension dimension)
(current-simulation-dimension)

Contract: 

(case-> (-> natural-number/c any)
        (-> natural-number/c))

Sets or gets the dimension field of the current simulation environment.

current-simulation-y

Function: 
(current-simulation-y y)
(current-simulation-y)

Contract: 

(case-> (-> (union/c (vector-of real?) #f) any)
        (-> (union/c (vector-of real?) #f)))

Sets or gets the y field of the current simulation environment.

current-simulation-dydt

Function: 
(current-simulation-dydt dydt)
(current-simulation-dydt)

Contract: 

(case-> (-> (union/c (vector-of real?) #f) any)
        (-> (union/c (vector-of real?) #f)))

Sets or gets the dydt field of the current simulation environment.

current-simulation-state-changed?

Function: 
(current-simulation-state-changed? state-changed?)
(current-simulation-state-changed?)

Contract: 

(case-> (-> boolean? any)
        (-> boolean?))

Sets or gets the state-changed? field of the current simulation environment.

current-simulation-max-step-size

Function: 
(current-simulation-max-step-size max-step-size)
(current-simulation-max-step-size)

Contract: 

(case-> (-> (>/c 0.0) any)
        (-> (>/c 0.0)))

Sets or gets the max-step-size field of the current simulation environment.

current-simulation-monitor

Function: 
(current-simulation-monitor monitor)
(current-simulation-monitor)

Contract: 

(case-> (-> (union/c procedure? #f) any)
        (-> (union/c procedure? #f)))

Sets or gets the monitor field of the current simulation environment.
[Go to first, previous, next page;   contents;   index]