Control is a higher level API for simulation scheduler. With a control state you have a pointer to one iteration that you can control with play!, next!, move-x ...

 Its design documents are in docs/archi/control/...

 Design decision:
 Control state as an atom containing all information about rendering

 Pros:
 - With atom state can be managed during long-lasting operations
   e.g. during play! we can modify the speed of it, modify pause easily
 - We can reuse atom state to modify the flow from multiple places
 - Atom handles well multithreading
 - Atom can be used both on clj and cljs
 Cons:
 - Not known

 Design decision:
 Split between control and computation

 Pros:
 - Split allows to easier manage responsibility between controling what's current response to render and how to move between them
 - Computation being separated allows for flexibility in how to manage execution of scheduler. This allows for adding later on optimisation, split between backend/frontend rendering, offline/online usag...
Cons:
 - User of rendering needs to have more knowledge about how rendering is working

 Design decision:
 Control based on computation (vs e.g. control based on state and separated from computation)
 Pros:
 - Code is easier to manage and understand (decrease complexity)
 - We are in rendering context so it allows for better solutions for rendering
 Cons:
 - Control knows about computation so code is more entangled

Computation is responsible for execution/storage of scheduler so that it can respond to questions about simulation.
 This namespace consists of protocol that defines core questions to answer and use-case functions of that protocol

For diagram see ![computation](archi/control/computation.png)

Loads chunk of scheduler responses upfront

Naive implementation of computation.
It directly executes scheduler each time it's asked for an answer

Contains all the default possible computation implementation to choose from
For diagram see ![computation](archi/control/computation_registry.png)

Computation response is consisting of status and scheduler response.
Status informs about how the response is related to the query asked to computation.
:success <- it is as expected
:no-next <- it is not what was asked, but it is impossible to continue further in simulation (e.g. model-end, no future events...)
:timeout <- it is not what was asked and it can be continued to search, but it hit a limit of time as it may be endless simulation or question could never be answered
:internal-error <- The response may be corrupted as there was some problem with execution itself

 For diagram see ![computation](archi/control/computation_response.png)

State containing information about and for control (control settings, current-iteration, computation-implementation to use...)
For diagram see ![computation](archi/control/state.png)

Demo usefull for control toy example

Testing the scheduler with no other lib.

Simulation domain, that can be tested from console
Used to help during development of simulation de concepts

An entity is a part of the model living in the `state` with its lifecycle managed.

* ![entity](archi/entity/entity.png)
* ![entity state](archi/entity/entity_state.png)
* ![lifestatus](archi/entity/lifestatus.png)

Event library helpers.

Predicates are functions that takes as a param a value and return true if the value matches predicate, false otherwise and nil if comparison can't be done.
Predicate functions can be expressed via a query language represented with vector.
This namespace is about managing that language

Composed predicates accept other predicates and return value based on their value

Equality predicates compare values and return boolean based on the result

Models resource consumers interaction.

Resource definition:
* A limited quantity of items that are used (e.g. seized and disposed) by entities as they proceed through the system. A resource has a capacity that governs the total quantity of items that may be available. All the items in the resource are homogeneous, meaning that they are indistinguishable. If an entity attempts to seize a resource that does not have any units available it must wait in a queue. It is often representing real world items that availability is limited (e.g. machine, wrench).

Consumer definition:
* A consumer is responsible for seizing and disposing the resource.

Note:
 * All namespaced keywords of the rc bounded context are from this namespace, so rc users need only to refer this one.

Basic preemption policies.

Factory for `preemption-policy`.

Registry for `preemption-policy`.

A resource is a limited quantity of items that are used by entities as they proceed through the system. A resource has a capacity that governs the total quantity of items that may be available. All the items in the resource are homogeneous, meaning that they are indistinguishable. If an entity attempts to seize a resource that does not have any units available it must wait in a queue.
It is often representing real world items that availability is limited (e.g. machine, wrench, ...).

A resource knows its instantenous capacity, its policies,and the element waiting for its availablility in the queue. The properties of a resource are:
* `capacity` (default 1) total number of available resources, note that this number may evolve over time.
* `currently-consuming` (default []) list of events currently consuming this resource, is useful to track them and enabling preemption and failures. The event contains the information on the waiting entity.
* `preemption-policy` (default ::sim-de-rc/no-preemption) is the policy to apply when a resource is consumed and none is available.
* `queue` (default []) list of blocked entities.
* `renewable?` (default true) when true, the disposing is not giving back the values.
* `unblocking-policy` (default ::simde-rc/FIFO) refers to an entity from the `automaton-simulation-de.rc.policies` registry, that registry will allow to pick one element in a queue.

Resource consumption is what is happening when a resource is available and an entity seizing it.

A consumption has two steps, a consume and a free of the resource.
The resource updates a `::sim-de-rc/currently-consuming` list events that are consuming resources

The queue of a resource is containing all event execution which are blocked while waiting for a resource to be available.

Store and update resource consumer informations in the `::sim-rc/resource` key of the state.
Assuming state is associative.

The simple policies to unblock an event in the queue.

Factory to return the `unblocking-policy`.

Registry for `unblocking-policy`.

When the capacity is updated (through a failure or a capacity update), the `preemption-policy` is deciding which `consumption` should be stopped.

In a queue, the policy selects the next consumer that will be unblocked. (Each queue has its own policy).

Uses editscript as this library is most performant, production used, considers both size optimization and speed
https://github.com/juji-io/editscript

Simulation is a technique that mimics a real system - and simplifies it, to learn something useful about it.
Discrete event simulation is modeling a real system with discrete events.

* Contains a user-specific domain, constraints, a customer-specific state and events modeling and an option to render visually the effects.
* Customer simulation can use directly `DE Simulation` or a library that eases the modeling: `rc modeling`, `industry modeling`, … 

An event is an individual happening, taking place at a given moment. Each event is indivisible and instantaneous. The event execution is defined by its event type.

Discreteness is a property of an event stating that the changes in the state could be counted (i.e. changes are discrete in the mathematical definition).

Each event defines following outputs:
 * a simulation state update regarding the event that happened.
 * a list of events that should be inserted in the future events.
 * some events that are postponed.
 * some events that are cancelled.

[See the entity](docs/archi/event_entity.png)

An event type: The event type is used to define what event execution will happen.

Event structure is a map with at least two keys:
* `type` a the event type as found in `evt-type-priority`.
* `date` as a date.

An event execution is updating the state and may trigger some new events to be added in the future events. The result of the event execution could be dependent on the state or random variable.

* [See entity](docs/archi/event_execution.png)

What is returned by an event.

`stopping-definition` to stop when causality is broken.

Causality is a property of the simulation model stating that a future event cannot change what has been done in the past already, so all changes in the state should not contradict any past event.

In practise, we check the `next-snapshot` `date` is equal or after the current `snapshot`.

`stopping-definition` to stop when the execution of an event is not found in the registry.

`stopping-definition` to stop when an execution has raised an exception.

`stopping-definition` to stop when no future events exists anymore.

built-in `stopping-definition` can create `stopping-cause` but they are not accessible for modellers, they are hard coded.

Stops when the request is not valid.

Stops when the response is not valid.

The `event-registry` contains `event-execution`.

It associates one event type (a keyword) to its `event-execution`.

* [See entity](docs/archi/registry_entity.png)

Registry for middlewares associating a keyword to its middleware function.

Stops when the request is valid through inconsistency and schema.
This criteria is built-in to this middleware as it is requiring the `request` knowledge. User `stopping-criteria` knows only `snapshot`.

Stops when the response is valid through inconsistency and schema.
This criteria is built-in to this middleware as it is requiring the `response` knowledge. User `stopping-criteria` knows only `snapshot`.

Middleware to render state.

Middleware to tap response and requests.

Ordered list of middlewares.

* [See entity](docs/archi/middlewares_entity.png)

A simulation model gathers information required to run the simulation.

It includes:

* `initial-snpashot` snapshot to start the model with.
* `middlewares` sequence of middleware to execute with the model.
* `model-data` data version of this model.
* `ordering` ordering of events.
* `registry` registry.
* `stopping-criterias` list of `stopping-criteria` that defines the end of the model.

Model data is the data used as inputs to generate the model:

* data oriented, so it could be persisted easily.
* ergonomy oriented, so it is easy to use.

Registry for ordering.

Gathers the registries of a simulation.

The `scheduler` is working with a `model` describing the problem to solve.

For each scheduler snapshot created, the scheduler is sorting the `future-events` based on the event ordering defined in the event-registry. The first event of that order is executed (see event execution). The resulting new values of state, past events, future events are used to create the new scheduler snapshot.

An event has three parameters `(event-execution current-event state new-future-events)`:
* `current-event` which is the current event to execute
* `state` which is the state value before the event execution
* `new-future-events` which is the list of future events without the current event

The returned value is a `event-return`, which future events have no needs to be sorted, they will be by the scheduler.

![entities](archi/scheduler_entity.png)
![aggregate](archi/scheduler_aggregate.png)
![state diagram](archi/scheduler_state.png)

`stopping-definition` to stop at a given bucket.

`stopping-definition` to stop at a given iteration.

`stopping-definition` to stop right now.

Stopping registry contains all `stopping-definition`.

![Entities](archi/simulation_engine/stopping_registry.png)

A reason why the `scheduler` stops. A `stopping-cause` contains:

* `context` data describing the context of the `stopping-criteria`, note its schema is defined freely by each `stopping-definition`.
* `current-event` the event that is about to be executed now. It could be null, if future-event is nil and no first event found.
* `stopping-criteria` telling the intent of the user to stop.

![Entities](archi/simulation_engine/stopping_cause.png)

Declares a `stopping-criteria` to instantiate `stopping-definition`s, it precises the `params` necessary for `stopping-evaluation`.
The data are:

* `model-end?` is set to `true` if the stopping-criteria is one possible end of the model. Note that more than one is possible for the same model. Note that these model `stopping-criteria` are not supposed to be linked with anything else than the business model itself (not the rendering, not the control/computation, ...)
* `params` is a map of parameters, which content is defined by the `stopping-definition`.
* `stopping-definition` is the `stopping-definition` as found in the `stopping-registry`.

![entities][archi/simulation_engine/stopping_stopping-criteria.png]

A `stopping-definition` defines what could cause the scheduler to stop.

* `doc` describes the definition.
* `id` name of the `stopping-definition`
* `next-possible?` tells if the next call of the `scheduler` will raise the same error.
* `stopping-evaluation` is the function to be called to evalute the criteria and decides if stops is true or not.

Note that only `stopping-definition` with `stopping-evaluation` properly set are callable by users. Others are built-in `stopping-definition` triggering `stopping-cause` in the `simulation-engine` bounded context.

![Entities](archi/simulation_engine/stopping_definition.png)

Defines a middleware, wrapping an handler to prepare the request before the handler execution, and modify the response after handler execution.
Note that a middleware wrapping an handler returns a new handler, that can be wrapped again.

*  [See entity](docs/archi/middleware_entity.png)

Event ordering is a part of the event registry meant to sort the future events.

It is especially important to manage simultaneous events. These events does not exists in the real life, but the.

* [See entity](docs/archi/ordering_entity.png)

## Date ordering
Date ordering is sorting events by date
It could be done with `compare-field` on the date field of the event (typically `::sim-engine/date`)

## Simultaneous event ordering
A simultaneous event ordering apply user defined decision on which event should be executed first
It could leverage `compare-types` and `compare-field` or what user defined functions

## Simultaneous events
Two or more events are simultaneous if they happen at the same date in the scheduler.

Sequence of `ordering`.

Build a request for an handler.

Contains:

* `current-event`
* `event-execution`
* `snapshot`
* `sorting`
* `stopping-causes`, the scheduler snapshot and the current event.
* ![entities](archi/request_entity.png)

Is a response of scheduler.

It contains:
* `stopping-causes`
* `snapshot`.

A scheduler snapshot is a consistent set of data for the scheduler.
It is containing the simulation state, past events and future events and iteration number scheduler snapshot is identified with an id property and is related to exactly one date. Past and Future events are sorted collection of events.

Remarks:
* An entity using the scheduler snapshot should not access past or future events to have some information on the state the simulation.

  * [See entity](docs/archi/snapshot_entity.png)

Transformation contains useful functions for rendering
* [See transformation big-picture](docs/archi/transformation/transformation_big_picture.png)