User Guide

In this guide you will find information on how to use OpenSimula from an environment that can run Python.

The best environment to start using OpenSimula is with Jupyter notebooks.

Simulation environment

Once we have OpenSimula installed, the base component to work with OpenSimula is the “Simulation” object that we must import and create an instance of it, which we will call “sim”.


import OpenSimula.Simulation as Simulation

sim = Simulation()

The simulation object will be used to create and manage the different projects. To create a new project in our simulation environment we will use the new_project(name) function. the project name is stored in a parameter of the project that can be changed later.


import OpenSimula.Simulation as Simulation

sim = Simulation()
pro = sim.new_project("Project 1")

Simulation functions

The following is a list of the most useful functions of the Simulation object:

Project editor example

Projects

Projects contain a set of components defining a case that can be temporarily simulated.

Project parameters

Example of project for the simulation of the first week of june with 15 min time step.


import OpenSimula.Simulation as Simulation

sim = Simulation()
pro = sim.new_project("Project one")
pro.parameter("description").value = "Project example"
pro.parameter("time_step").value = 60*15
pro.parameter("n_time_steps").value = 24*4*7
pro.parameter("initial_time").value = "01/06/2001 00:00:00"

Project and component parameters can be changed one by one or in bulk using a dictionary and the set_parameter(dictonary) function, or interactively using the project and component editors.


import OpenSimula.Simulation as Simulation

sim = Simulation()
pro = sim.new_project("Project one")
param = {
    "description": "Project example",
    "time_step": 60*15,
    "n_time_steps": 24*4*7,
    "initial_time": "01/06/2001 00:00:00"
}
pro.set_parameters(param)

Project functions

The following is a list of the most useful functions of the Project object:

Component editor example

the first simulation instant is the initial_time plus 1/2 of the time_step. For example, if initial_time = “01/01/2001 00:00:00” and time_step = 3600, then the first simulation instant is: “01/01/2001 00:30:00”, the second: “01/01/2001 01:30:00”, and so on.

Components

Components are objects included in projects that contain parameters and variables. Component list describe the different types of Components in OpenSimula.

As an example, we will see how to create three different types of components and how to manage them in our project. this code is a continuation of the definition of the previous project.


...

working_day = pro.new_component("Day_schedule","working_day")
param = {
    "time_steps": [8*3600, 5*3600, 2*3600, 4*3600],
    "values": [0, 100, 0, 80, 0]
}
working_day.set_parameters(param)

holiday_day = pro.new_component("Day_schedule","holiday_day")
param = {
    "time_steps": [],
    "values": [0]
}
holiday_day.set_parameters(param)

week = pro.new_component("Week_schedule","week")
param = {
    "days_schedules": ["working_day","working_day","working_day","working_day","working_day","holiday_day","holiday_day"]
}
week.set_parameters(param)

year = pro.new_component("Year_schedule","year")
param = {
    "periods": [],
    "weeks_schedules": ["week"]
}
year.set_parameters(param)

To create the components we use project "new_component" function. For example, to create a Day_schedule we will use pro.new_component("Day_schedule","name"). Where the first argument is the type of component and the second the name of the component.

After creating the components we can modify any of their parameters.

After defining a project with its components, changing the parameters one by one or using a dictionary to define it, we can check if there is any error using the check() function and perform the temporary simulation with the simulate() function.


...

pro.check()
pro.simulate()

Python shell output:


Checking project: Project 1
ok
Simulating Project 1: ...
10%: N_iter: 1.00
20%: N_iter: 1.00
30%: N_iter: 1.00
40%: N_iter: 1.00
50%: N_iter: 1.00
60%: N_iter: 1.00
70%: N_iter: 1.00
80%: N_iter: 1.00
90%: N_iter: 1.00
100%: N_iter: 1.00
Simulation completed.

The list of parameters of a project can be obtained in pandas DataFrame format using the project functions parameter_dataframe(). For the components we can get parameters and variables dataframes with parameter_dataframe() and variable_dataframe().

To obtain the list of components in a project with the parameters as columns use the function component_dataframe(comp_type="all"). In the "type" argument of the function we can indicate the type of components we want to list (for example: "Day_schedule"), or indicate "all" (this is the default value), which will show all components including only the three parameters common to all components: "name", "type" and "description".

With Jupyter notebooks or Google Collab, writing the python variable of a project the parameter and component dataframe will be shown, and writing one component python variable parameter and variable dataframe will be shown. Next example shows the parameter and component dataframes of our project:


...

pro

Jupyter shell:

Project in jupyter

Components functions

The following is a list of the most useful functions of the Components object:

This is the meaning of the arguments of the variable_dataframe function. (In bold the default values):

Parameters

Parameters are used to define the characteristics that make up the projects and components.

Paremeters

The parameters will be defined as Python dictionary keys (or json format files), that is the format we will use in the examples shown in the documentation. Parameters can be of different types depending on the type of information they contain:

All of the above types can also be defined as parameter lists, giving rise to the following types:

The Parameter_component, Parameter_variable, Parameter_component_list and Parameter_variable_list can refer to a component of the same project, in that case it is only necessary to put the name of the component, or a component of another project. In this last case we must write "project_name->component_name". e.g. "meteo_file": "Project 1->Sevilla".

To get or set the value of a parameter we must use the attribute "value" of the parameter. If the parameter contain a list we can set/get each value using index, for example: pro.component("week").parameter("days_schedules").value[0] will return "working_day"


...

pro.component("year").parameter("description").value = "Example of year schedule"
pro.component("year").parameter("description").value

Jupyter output:


'Example of year schedule'

Variables

Variables are elements included in the components to store the temporal information generated during the simulation.

Variables

Variables are lists of floating values, one for each instant of simulated time.

To access the values of a variable we use the values attribute which returns a numpy.array object (NumPy library array object).


...

pro.component("year").variable("values").values

Jupyter output:


array([  0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0., 100.,
       100., 100., 100., 100., 100., 100., 100., 100., 100., 100., 100.,
       100., 100., 100., 100., 100., 100., 100., 100.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,  80.,  80.,  80.,  80.,  80.,  80.,
        80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
...
       100.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,  80.,  80.,
        80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,  80.,
        80.,  80.,  80.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,   0.,
         0.])
Output is truncated. View as a scrollable element or open in a text editor. Adjust cell output settings...

The variable_dataframe(units, frequency, value, interval, pos_neg_columns) method of the components returns a pandas dataframe with all the variables of the component.

As an example we can see how to obtain the monthly average values of the variables of a meteorological file (File_met component):


...

pro.component("met_file").variable_dataframe(frequency="M",value="mean")

Jupyter shell:

variable_dataframe