Experiment

An experiment is a procedure undertaken on a model in order to discover how it performs. The default setting is Dynamic simulation. Alternative simulation types appear when hovering over the run button.

Simulate a model

To simulate a model is to run an experiment on it.

1. Execute a simulation by clicking the Simulation button available directly on the model canvas.

2. Simulation type can quickly be changed by hovering over Simulation button to view the sub menu of available simulation types. When available, Steady State and Custom functions are presented under the Simulation button.

About renaming and moving a model

Renaming a model will always break the FMU caching and require recompilation, as well as for models dependent on the model that was renamed.

Moving a model to a different package still breaks the FMU cache. FMU cache is lost when moving a model to a different package.

Set up a simulation

1. Go to Experiment mode and the ANALYSIS tab in the details panel to the right.

2. There are three simulation types available:

   • Dynamic: is always available.
   • Steady State: needs to be activated in settings to be available. Consult the library documentation to see if the model support Steady State.
   • Custom: available when a simulation can be executed as Custom functions using a Python script.

Set up a dynamic simulation

Dynamic analysis presents a standard time based transient analysis, where the user specifies the start and stop time, post-processing interval.

1. Go to Experiment mode, click on EXPERIMENT section in the Details panel, go to the ANALYSIS tab, click on the Dynamic button.

2. Enter Start Time, Stop Time, Interval. Each example model has a default value allowing the model to be simulated without making any changes.

Plotting intervals

The plotting interval directly influences the size of the results: small interval equals big result file. The default plotting interval will follow up solver step. It is recommended to set the plotting interval to e.g. 0.01 sec to avoid too many plotting points, when the time-step is decreased, e.g. during sudden transients.

Set up an advanced dynamic simulation

An advanced dynamic simulation-setting involves changing solver and its tolerance.

1. In the Details panel, click on Advanced to select Solver. An example model from a library has an approrpiate selected solver.

Run a steady state simulation

The steady state simulation presents time constant, converged solution, where all the inputs are constant.

1. Activate Steady State in settings. When Steady State is visible in Experiment section in Analysis tab it means it is available and turned on in settings.

2. In the Details panel, click on the Steady State button in the Simulation tab.

3. A Steady State simulation can be speeded up by using Multi-execution functionality allowing to run multiple simulations in parallel.

Run custom functions

A custom function is an integrated Python interface to Modelon Impact. With a custom function you define a function that do a computation or another operation on an FMU or a model, call it from the simulation browser and return back the result to the result browser.

Impact supports custom functions written in Python. If available, the icon appears next to the Steady State button.

1. For the selected function, parameters can be set using input boxes and toggles.

2. Once parameterized, the function is run using the Execute button.

3. If custom functions have been loaded, they will also be available for selection in the menu under the Simulate button on the model canvas.

Cancelled simulations

1. All results generated until the simulation is cancelled can be displayed
2. This feature provides input to trouble shoot the model and the experiment.
3. A simulation may be cancelled due to:
   • Time out
   • Cancelled by user
   • Inconsistencies in the model or simulation

4. It is also possible to view and plot results for

   • Failed SS simulations: Before the NoConvergenceException is raised, the results from the most recent successful step are stored.
   • Cancelled SS simulations: A result file is generated for a cancelled SS simulation. The results are now saved after each successful step.

Simulation settings

Simulation settings are accessible in the Experimentation mode, under the EXPERIMENT tab and further down, the Analysis tab.

Basic simulation settings

For the general simulation case, a user need only to change these basic simulation options. These settings are stored in the model.

Basic simulation settings

	Default	Description
Start time	0 s	Start time of simulation
End time	1 s	End time of simulation
Interval	0s (Store all result points)	Result output interval. Number of result points = (End time - Start time)/Interval

Note

If the user leaves the Interval field empty, its value will be calculated based on ncp (Number of computation points) specified within Simulation options below. Any change of settings must be saved to take effect.

Advanced simulation settings

Advanced simulation settings require good knowledge of modelling and simulation. These settings are stored in the model.

Advanced simulation settings

	Default	Description
Solver	CVode	Numerical method to be used to solve the simulation problem. Supported solvers are: CVode, Radau5ODE, ExplicitEuler
Tolerance	1e-5	Relative error tolerance for the numerical solver

Note

A small number of the Tolerance will give a more accurate solution. But it will also lead to slower simulation due to the solver will take shorter simulations steps.

Run Multi-execution experiments

Modelon Impact offers the possibility to create and run multi-experiments for a given model. This lets the user investigate the parameter space of the model and gain an understanding of its behavior relative to certain parameters.

1. Go to Experiment mode.

2. Press the + New experiment link to add a new experiment. Give it a suitable name using the context menu of the experiment list item.

3. Experiments are saved automatically when edited. In order to rename an experiment, click on the Edit icon that appears when hovering over the experiment name or select "Rename" by right-clicking on the experiment.

4. Select a component on the canvas by clicking on it.

5. There are two operators to help set up multi-execution exeperiment:

   • range(start_value,end_value,no_of_steps)
   • choices(value_1,value_2,value_n)

6. The range and choices operator can only be set in experiment mode. Applying it in another mode, will result in an error message.

   • range

   Set a range of values for a parameter range(start_value,end_value,no_of_steps). Notice how it appears in the Modifications tab in the Experiment widget.

   In the case below, the J parameter will be swept from 1 to 5 in 10 steps.

   • choices

   choices defines an arbitrary sequence to sweep, that is enables different values for a parameter regardless of relationship to each other.

   With choices the user can run multiple experiments setting free and arbitrary set of values. Choices is applied to parameters on component level and, when possible, on model level.

   Select a component and set values to be simulated for a parameter choices(value_1,value_2,value_n).

   By using choices on another parameter, Modelon Impact will combine the number of values and produce the equivalent number of simulations.

Note

Range can be set for as many parameters as you like. Note, however, that all combinations of settings are simulated so the number of simulations increases rapidly with the number of range parameters.

• Parameter_1: choices(a1,a2,a3)
• Parameter_2: choices(b1,b2)

• Simulations: a1b1, a1b2,a2b1, a2b2, a3b1, a3b2.

  values_a x values_b = 3 x 2 = 6 simulations.

7. Use the Simulate button to run the multi-execution.

8. The results can be viewed in plots and stickies just like a single simulation. Plots will show the curves from all simulation cases for each variable.

Multiexecution plot

9. Running an experiment shifts the canvas mode from Experiment mode to Result mode as soon as the execution is completed. It is not possible to access the Experiment widget from Result mode. To run other defined experiments, go back to Experiment mode.

10. A case slider is activated next to the time slider to select which case is shown on stickies. Together with the time slider, values for a specific time can be viewed for a selected case.

Warning

A syntax error will generate an error message and the experiment will not run. Note that a red exclamation mark next to result means that one or more cases failed. Right click on the case to show simulation log.

Steady state simulation analysis

Scatter plots are used to analyze steady state simulations.

Scatter plot functionality allows the user to visualize multiple cases in one chart and isolate results of one variable in relationship to another.

1. Run the experiment in Steady State.

2. Expand the details panel to the right.

3. Go to the CALCULATED VALUES tab at the bottom right.

4. Drag variables from CALCULATED VALUES to show variable results from experiment.

5. Drag and drop a new variable to an existing scatterplot (on the x-axis) and both values will be presented in one graph.

6. Click on various points to see results of variables in relation to other variables as results of the experiment.

Scatter plot

User defined experiment meta data

Users can associate extra information with experiments as metadata. The data is added in the form of a dict with String, Boolean or Real values. This may be useful to include information that is not readily available through the model parameters/variables to provide a description of the experiment.

Note

There are some limitations:

• Flat list of key-value pairs
• Up to a total of 2 kB of uncompressed data per experiment

The meta data can be added through the Python client REST API, when executing the experiment.

user_data = {"Author": "John Doe", "parameterizationFrom":3.4, "dataFromMeasurement":True}
experiment = workspace.execute(experiment_definition, user_data=user_data).wait()

This affects the POST /workspaces/{workspace}/experiments, the example above will add a custom userData property to an experiment as shown below. This data is also accessible through storage_api.get_experiment_meta()

{ 
    "experiment": {
        "version": 2,
        "base": {
            "model": {
                "fmu": {
                    "id": "{{fmu_id}}"
                }
            },
            "modifiers": {
                "variables": {
                    "inertia1.J": "range(1, 2, 10)"
                }
            },
            "analysis": {
                "type": "dynamic",
                "parameters": {
                    "start_time": 0,
                    "final_time": 1
                }
            }
        }
    },
    "userData": {
        "Author": "John Doe",
        "parameterizationFrom":3.4,
        "dataFromMeasurement":True
    }
}