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, we can import the package that we will usually name with the alias "osm".

The first step is to create a simulation environment using the Simulation() function.


import OpenSimula as osm

sim = osm.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 as osm

sim = osm.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 as osm

sim = osm.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, in bulk using a dictionary and the set_parameter(dictonaty) function, or interactively using the project and component editors.


import OpenSimula as osm

sim = osm.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:

Compoenent 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 one
ok
Simulating Project one: 10% 20% 30% 40% 50% 60% 70% 80% 90% 100%  End

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

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.

with the following possible arguments (In bold the default values):

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