#lang scribble/doc
@(require
  scribble/manual
  scribblings/icons
  (for-label racket/base
             racket/contract
             plot
             (planet williams/science/ode-initval)
             (planet williams/simulation/simulation-with-graphics)))

@title[#:tag "env-basic"]{Simulation Environments (Basic)}

@local-table-of-contents[]

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

@itemize{
  @item{Current simulation time}
  @item{Now, continuous, and future event lists}
  @item{Main loop and exit continuations}
  @item{Process and event being executed}
  @item{Environment hierarchy}
  @item{Ordinary differential equation (ODE) solver state}
  @item{Simulation monitoring hooks}
  }

The Simulation Collection supports multiple simulation environments existing at the same time. This is useful in implementing various simulation techniques:

@itemize{
  @item{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.}
  @item{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.}
  @item{Multiple simulation can facilitate the development of multiple, independent (or cooperating) simulation models as part of a larger system. See Section 15, Simulation Components, for examples.}
  @item{Hierarchical simulation environments allow partitioning of simulation element within a simulation model. Hierarchical simulation models are described in Chapter 14.}
  }

This chapter describes the features of basic simulation environment.

@section{The @scheme[simulation-environment] Structure}

The @scheme[simulation-environment] structure defines a simulation environment.

@defstruct*[simulation-environment
            ((running? boolean?)
             (time (>=/c 0.0))
             (now-event-list event-list?)
             (future-event-list event-list?)
             (loop-next (or/c continuation? false/c))
             (loop-exit (or/c continuation? false/c))
             (event (or/c event? false/c))
             (process (or/c process? false/c))
             (root (or/c simulation-environment? 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-nonegative-integer?)
             (y (vectorof inexact-real?))
             (dydt (vectorof inexact-real?))
             (state-changed? boolean?)
             (max-step-size (>/c 0.0))
             (monitor (or/c procedure? false/c))
             (requeue-cont (or/c continuation? false/c)))
            #:mutable]{

@(margin-note finger "See Section 3.3, Current Simulation Environment Fields for more information on accessing the fields of the current simulation environment.")

@itemize{
  @item{@schemefont{running?}---true, @scheme[#t], if the simulation main loop is running in this simulation environment and false, @scheme[#f], otherwise.}
  @item{@schemefont{time}---the simulation clock for the simulation model.}
  @item{@schemefont{now-event-list}---an event list containing the events to be executed now, i.e. before the simulation clock is advanced.}
  @item{@schemefont{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.}
  @item{@schemefont{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, @scheme[#f], if the simulation main loop is not running in this simulation environment.}
  @item{@schemefont{loop-exit}---the continuation to exit the simulation main loop that is running in this simulation environment. Calling this continuation signifies the end of the execution of the simulation model. This field is false, @scheme[#f], if the simulation main loop is not running in this simulation environment.}
  @item{@schemefont{event}---the event currently being executed in the simulation environment or false, @scheme[#f].}
  @item{@schemefont{process}---the process currently being executed in the simulation environment or false, @scheme[#f].}
  @item{@schemefont{parent}---the parent simulation environment of this simulation environment. (See Chapter 14, Hierarchical Environments).}
  @item{@schemefont{children}---a list of the children simulation environments of this simulation environment. (See Chapter 14, Hierarchical Environments)}
  @item{@schemefont{continuous-event-list}---the event list containing the events to be executed continuously. (See Chapter 10, Continuous Simulation Models)}
  @item{@schemefont{evolve}---the ordinary differential equation evolver object. This is created internally. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{control}---the ordinary differential equation control object or false, @scheme[#f], for fixed step size. This may be specified by the user. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{step-type}---the ordinary differential equation step-type object. This may be specified by the user. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{step}---the ordinary differential equation stepper object. This is created internally. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{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)}
  @item{@schemefont{step-size}---the current (last) step size for the ordinary differential equation solver. If the @schemefont{control} field is false, @scheme[#f], this specifies the fixed step size. Otherwise, it is controlled by the control object. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{dimension}---the dimensionality of the system of equations for the ordinary differential equation solver. This is set internally. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{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)}
  @item{@schemefont{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)}
  @item{@schemefont{state-changed?}---true, @scheme[#t], if the system of equations for the ordinary differential equation solver has changed and false, @scheme[#f], otherwise. This is created internally. (See Chapter 11, Continuous Simulation Models)}
  @item{@schemefont{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)}
  @item{@schemefont{monitor}---a procedure that, if specified, is executed prior to advancing the simulation clock. (See Chapter 9, Monitors)}
  @item{@schemefont{requeue-cont}---the continuation to requeue an interprocess communication (i.e., a rendezvous). This is maintained internally.}
  }
}

@defproc[(make-simulation-environment (parent (or/c simulation-environment? false/c) #f))
         simulation-environment?]{
Returns a new simulation environment with the given @scheme[parent] simulation environment. The newly created simulation environment has @schemefont{time} = 0.0 and the simulation main loop is not running (i.e. @schemefont{running?} = @scheme[#f], @schemefont{loop-next} = @scheme[#f], @schemefont{loop-exit} = @scheme[#f], @schemefont{event} = @scheme[#f], @schemefont{process} = @scheme[#f]), and the other fields at their default values.}

@defidform[default-simulation-environment]{
Contains the simulation environment that is used as the default value for the current simulation environment (see Section 3.2).}

@section{Current Simulation Environment}

The @tech{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.

@defparam[current-simulation-environment env simulation-environment?]{
Gets or sets the current simulation environment. A guard procedure ensures that the value of @scheme[current-simulation-environment] is indeed a simulation environment as determined by @scheme[simulation-environment?], otherwise a type error is raised.}

@defform[(with-simulation-environment env
            body ...+)]{
Evaluates its body with the current simulation environment bound to the value of @scheme[env].}

@defform[(with-new-simulation-environment
            body ...+)]{
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.}

@defform[(with-new-child-simulation-environment
            body ...+)]{
Evaluates its body with the current simulation environment bound to a newly created simulation environment that is a child of the current simulation environment.}
                       
@section{Current Simulation Environment Fields}

The most common way of accessing the current simulation environment fields is using the following procedures.

@defproc*[(((current-simulation-running? (running? boolean?)) void?)
           ((current-simulation-running?) boolean?))]{
Sets or gets the @schemefont{running?} field of the current simulation environment.}

@(margin-note finger  @tt{@schemefont{time}}" is by far the most frequently used field in the current simulation environment. Use " @tt{@scheme[(current-simulation-time)]} " to obtain the current simulation time.")

@defproc*[(((current-simulation-time (time (>=/c 0.0))) void?)
           ((current-simulation-time) (>=/c 0.0)))]{
Sets or gets the @schemefont{time} field of the current simulation environment.}

@defproc*[(((current-simulation-now-event-list (now-event-list (or/c event-list? false/c))) void?)
           ((current-simulation-now-event-list) (or/c event-list? false/c)))]{
Sets or gets the @schemefont{now-event-list} field of the current simulation environment.}

@defproc*[(((current-simulation-future-event-list (future-event-list (or/c event-list? false/c))) void?)
           ((current-simulation-future-event-list) (or/c event-list? false/c)))]{
Sets or gets the @schemefont{future-event-list} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-loop-next (loop-next (or/c procedure? false/c))) void?)
           ((current-simulation-loop-next) (or/c procedure? false/c)))]{
Sets or gets the @schemefont{loop-next} field of the current simulation environment.}
                                                                       
@(margin-note finger "Calling " @tt{@scheme[(stop-simulation)]} " is the best way to exit the simulation main loop.")

@defproc*[(((current-simulation-loop-exit (loop-exit (or/c procedure? false/c))) void?)
           ((current-simulation-loop-exit) (or/c procedure? false/c)))]{
Sets or gets the @schemefont{loop-exit} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-event (event (or/c event? false/c))) void?)
           ((current-simulation-event) (or/c procedure? false/c)))]{
Sets or gets the @schemefont{event} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-process (process (or/c process? false/c))) void?)
           ((current-simulation-process) (or/c procedure? false/c)))]{
Sets or gets the @schemefont{process} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-parent (parent (or/c simulation-environment? false/c))) void?)
           ((current-simulation-parent) (or/c simulation-environment? false/c)))]{
Sets or gets the @schemefont{parent} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-children (children (listof simulation-environment?))) void?)
           ((current-simulation-children) (listof simulation-environment?)))]{
Sets or gets the @schemefont{children} field of the current simulation environment.}

@(margin-note finger "See Chapter 11, Continuous Models for more information on the use of these procedures to control the integration loop.")

@defproc*[(((current-simulation-continuous-event-list (continuous-event-list (or/c event-list? false/c))) void?)
           ((current-simulation-continuous-event-list) (or/c event-list? false/c)))]{
Sets or gets the @schemefont{continuous-event-list} field of the current simulation environment.}
                                                                                
@defproc*[(((current-simulation-evolve (evolve (or/c ode-evolve? false/c))) void?)
           ((current-simulation-evolve) (or/c ode-evolve? false/c)))]{
Sets or gets the @schemefont{evolve} field of the current simulation environment.}
                                                                     
@defproc*[(((current-simulation-control (control (or/c ode-control? false/c))) void?)
           ((current-simulation-control) (or/c ode-control? false/c)))]{
Sets or gets the @schemefont{control} field of the current simulation environment.}
                                                                       
@defproc*[(((current-simulation-step-type (step-type (or/c ode-step-type? false/c))) void?)
           ((current-simulation-step-type) (or/c ode-step-type? false/c)))]{
Sets or gets the @schemefont{step-type} field of the current simulation environment.}

@defproc*[(((current-simulation-step (step (or/c ode-step? false/c))) void?)
           ((current-simulation-step) (or/c ode-step? false/c)))]{
Sets or gets the @schemefont{step} field of the current simulation environment.}

@defproc*[(((current-simulation-system (system (or/c ode-system? false/c))) void?)
           ((current-simulation-system) (or/c ode-system? false/c)))]{
Sets or gets the @schemefont{system} field of the current simulation environment.}

@defproc*[(((current-simulation-step-size (step-size (>/c 0.0))) void?)
           ((current-simulation-step-size) (>/c 0.0)))]{
Sets or gets the @schemefont{step-size} field of the current simulation environment.}

@defproc*[(((current-simulation-dimension (dimension natural-number/c)) void?)
           ((current-simulation-dimension) natural-number/c))]{
Sets or gets the @schemefont{dimension} field of the current simulation environment.}

@defproc*[(((current-simulation-y (y (or/c (vector-of real?) false/c))) void?)
           ((current-simulation-y) (or/c (vector-of real?) false/c)))]{
Sets or gets the @schemefont{y} field of the current simulation environment.}

@defproc*[(((current-simulation-dydy (dydt (or/c (vector-of real?) false/c))) void?)
           ((current-simulation-dydt) (or/c (vector-of real?) false/c)))]{
Sets or gets the @schemefont{dydt} field of the current simulation environment.}

@defproc*[(((current-simulation-state-changed? (state-changed? boolean?)) void?)
           ((current-simulation-state-changed?) boolean?))]{
Sets or gets the @schemefont{state-changed?} field of the current simulation environment.}

@defproc*[(((current-simulation-max-step-size (max-step-size (>/c 0.0))) void?)
           ((current-simulation-max-step-size) (>/c 0.0)))]{
Sets or gets the @schemefont{max-step-size} field of the current simulation environment.}

@(margin-note finger "See Chapter 9, Monitors for more information on the use of simulation monitors.")

@defproc*[(((current-simulation-monitor (monitor procedure?)) void?)
           ((current-simulation-monitor) procedure?))]{
Sets or gets the @schemefont{monitor} field of the current simulation environment.}

@defproc*[(((current-simulation-requeue-cont (requeue-cont (or/c continuation? false/c))) void?)
           ((current-simulation-requeue-cont) (or/c continuation? false/c)))]{
Sets or gets the @schemefont{requeue-cont} field of the current simulation environment.}