====== Simulation Page ======

The simulation page lets you run best estimate (deterministic) or probabilistic (Monte Carlo) simulations. The error section lists problems that must be solved before a simulation can be made.

===== Menu =====

|{{:RunAll24.png}}               |Run                         |Starts a simulation.                                                                                             |
|{{:SimulationSettings24.png}}   |Simulation settings...      |Displays the simulation settings window. See [[#simulationsettings|simulation settings]]                         |
|{{:ProbabilisticSettings24.png}}|Probabilistic settings...   |Displays the settings window for probabilistic simulations. See [[#probabilisticsettings|probabilistic settings]]|
|{{:Help24.png}}                 |Help                        |Displays this help page.                                                                                         |

===== Basic settings =====

This section lets you enter the start and end time as well as the type of simulation to perform.

  * **Start time** - The start time for the simulation in the unit given above. Typically a simulation starts at time=0.
  * **End time** - The end time for the simulation.
  * **Type of simulation** - Select the type of simulation to run.
    * **Best estimate** - Run a deterministic simulation, using nominal parameter values.
    * **Probabilistic** - Run a Monte Carlo simulation, using probability density functions for uncertain parameters.
  * **Scenarios** - Include scenarios when running the simulation.
  * **Number of simulations** - Only applies when running a probabilistic simulation. Set the number of realizations (iterations) to perform.

===== Simulation =====

The simulation section will display simulation progress as well as errors that need to be resolved before a simulation can be performed. The {{runall24.png?20|}} button will start a simulation, and the {{:stop24.png?20|}} button will stop an ongoing simulation. The progress bar will show you how far the simulation has progressed. For deterministic simulations it will display the current time point, and for probabilistic simulations it will show the current iteration.

==== Information ====

While the simulation is running, information about the simulation is presented here. If the simulation is aborted for some reason, the error causing the simulation to stop will be displayed here.

==== Errors ====

For a simulation to be run, the model need to be free of errors. The most typical error is a missing parameter value.

===== Simulation settings =====

The simulation settings window contains four pages:

==== General ====

Here you specify the start and the end times for the simulation and output options.

**Simulation time**

  * **Start Time** - This setting specifies the start time of the simulation. Most often this value will be left at zero (default value), but there might be cases where another value is required. //Default value = 0//
  * **End Time** - This setting specifies the stop time of the simulation. //Default value = 100//

**Simulation outputs**

  * **Output option** – By default, the time vector returned from a simulation contains the exact time steps the ODE-solver has chosen. For difficult numerical solutions the number of time points may be very many. Also, it might be of interest to the user to get values for specific time points. The three output options are:
    * Produce no additional output - The time vector will only contain the time steps chosen by the ODE solver. This is the default setting.
    * Produce additional output - The time vector will contain both the time steps chosen by the ODE solver and the time points given in Time Series. Use this setting when your Model contains discrete events to force the ODE solver to include those time points.
    * Produce specified output only - The time vector will contain only the time points given **Time Series**. This setting will greatly decrease memory consumtion and will improve simulation speed.

|Note|For probabilistic and sensitivity analysis simulations the output option should be **Produce specified output only**, otherwise only the start and end time is included in the result. A warning message will be presented in the error section. This is to limit the amount of data produced and to guarantee that the same time vector is returned from all simulations.|

  * **Time series** – This field is only available when the output option is set to either ‘Produce additional output’ or ‘Produce specified output’. To create a time series click the **Add** button. From the window that appears select the type of time series you want to create using the drop-down list. You can add as many time series as you want. However, the possibility to add more than one time series is typically only used when you wish to combine a linear/geometric time series with some custom time points. To remove a time series just click the time series to be deleted and click the **Remove** button.
    * If you select ‘Custom’, enter the time points in the Time point field separated with commas or blank space.
    * If you select ‘Linear’ or ‘Geometric’ time series enter the first and the last time in the Min and Max box respectively. Enter the number of times points in the N box. For example: Start = 5, End = 10, N = 6, Type = Linear will give a time series with the values 5,6,7,8,9 and 10.

In the case of the Linear time series the default value for the Min time is set to the Start Time and for the Max time is set to the End Time. In the case of the ‘Geometric’ time series the default values for the Min and the Max times is set to auto. * If you select ‘Linear Increment’ time series, enter the first and the last time in the Min and Max box respectively. Enter the increment in the increment box. The default value for the Min time is set to the Start Time and for the Max time is set to the End Time. For example: Start = 5, End = 10, Increment = 2.5 will return a time series with the values 5, 7.5 and 10.

==== Outputs ====


{{ :screenshots:edit_simulation_settings_outputs.png?200|}}

The output page lets you choose simulation endpoints. All blocks of the project are displayed and are organized by sub-system. By selecting/unselecting either endpoints or whole sub-system nodes, you determine which simulation outputs will be available after the simulation is finished.

By removing simulation outputs the simulation time and memory consumption decreases. Also, the list of results will be shorter which makes it easier when creating charts and tables.

|Note|By default, values for all enabled blocks and parameters for all enabled contaminants will be returned from the simulation. To exclude contaminants from the simulation you must specify your contaminants in the [[Context Page|context page]].|

==== Solver ====

The solver page lets you select numerical solver and edit it’s settings. The solver to use depends on the model and the model parameters. For [[http://en.wikipedia.org/wiki/Stiff_equation|stiff]] problems you should start with the solver **NDF**, for non-stiff problems with **DOPRI45**.

Each solver has settings which control error tolerances and other specifics. Some common settings include:

**Absolute tolerance** - Absolute error tolerances that apply to the individual components of the solution vector. Absolute tolerance is a threshold value below which the value of the solution component is unimportant. The absolute error tolerances determine the accuracy when the solution approaches zero.

//Default value = 1.0E-6//

**Relative tolerance** - Relative error tolerance that applies to all components of the solution vector y. This tolerance is a measure of the error relative to the size of each solution component. Roughly, it controls the number of correct digits in all solution components, except those smaller than thresholds defined in Absolute tolerance. The default, 1e-3, corresponds to 0.1% accuracy.

//Default value = 0.0010//

**Limit data points to last** - Maximum number of data-points to store. When the number of time points of a simulation exceeds this limit, the first values will be removed.

//Default value = 1000//

===== Probabilistic settings =====

Before starting a probabilistic simulation there are certain settings to make. The minimum is to select which parameters to include in the probabilistic analysis.

==== General ====

**Number of simulations** - This setting specifies how many simulations will be performed during a probabilistic simulation. //Default value = 1000//

**Seed** - Initialises the seed value for the random number generator. If you set the same seed, then the sequence will be the same each run.

**Sampling** - Specifies the type of sampling used during the simulation, either Monte Carlo or Latin Hypercube sampling.

==== Parameters ====

This page lets you select the parameters that will be included in the analysis. Only parameters that have been assigned probability density functions can be selected.

Note that you must select at least one parameter to run a probabilistic simulation.

===== Correlation =====

Correlations between parameters can be assigned in order to reduce noise and to avoid impossible parameter combinations.

A probabilistic simulation starts with sampling values for all the probabilistic parameters, using either a (random) Monte Carlo scheme or Latin Hypercube sampling.

After the values are sorted so that correlated parameter values are used in the same iteration. For example, consider the parameters //weight// and //height//. These parameters are log-normally distributed and are positively correlated, meaning that it is common for heavy humans to also be tall. By assigning a correlation of say 0.5, the likelyhood of the weight parameter being large in the same iteration as the height parameter is large will increase.

To add correlations you must first select the **Enabled** button. You then click the **Add** button for each parameter pair, select the two parameters from the left and right lists and enter a correlation between the two.

===== References =====

  * [[Introduction_to_Ecolego_Player|Introduction to Ecolego Player]]
  * [[Ecolego_Player_Wiki|Ecolego Player Wiki]]