Getting Started

The best environment to start using OpenSimula is with Jupyter notebooks or Google Colab. We recommend the use of JupyterLab Desktop

Installing OpenSiumula

To install OpenSimula you can use any of the methods that Python makes possible. For example, to install using pip we must use:

pip install OpenSimula

OpenSimula uses in different parts of the code the following Python packages, which will be installed automatically when OpenSimula is installed:

First example

First we are going to define a Python dictionary that contains the information of our project:


project_dict = {
    "name": "First example project",
    "time_step": 3600,
    "n_time_steps": 24*365,
    "initial_time": "01/01/2001 00:00:00",
    "components": [
        {
            "type": "Day_schedule",
            "name": "working_day",
            "time_steps": [8*3600, 5*3600, 2*3600, 4*3600],
            "values": [0, 100, 0, 80, 0],
            "interpolation": "STEP",
        },
        {
            "type": "Day_schedule",
            "name": "holiday_day",
            "time_steps": [],
            "values": [0],
            "interpolation": "STEP",
        },
        {
            "type": "Week_schedule",
            "name": "working_week",
            "days_schedules": [
                "working_day",
                "working_day",
                "working_day",
                "working_day",
                "working_day",
                "holiday_day",
                "holiday_day",
            ],
        },
        {
            "type": "Week_schedule",
            "name": "holiday_week",
            "days_schedules": ["holiday_day"],
        },
        {
            "type": "Year_schedule",
            "name": "year",
            "periods": ["01/08", "01/09"],
            "weeks_schedules": ["working_week", "holiday_week", "working_week"],
        },
    ],
}

All OpenSimula projects must contain the project definition parameters and a key called components with the list of project components. The project parameters in this example are:

The project contains two components of type Day_schedule, two of type Week_schedule and one of type Year_schedule. The first Day_schedule component called working_day describes how a value changes throughout the day. The day is divided into five periods described in the time_steps parameter:

  1. 8*3600 s (00:00 to 8:00).
  2. 5*3600 s (8:00 to 13:00)
  3. 2*3600 s (13:00 to 15:00)
  4. 4*3600 s (15:00 to 19:00)
  5. Rest of day (19:00 to 24:00)

The values for these periods are defined in the values parameter, in our example they are 0, 100, 0, 0, 80 and 0. the STEP value of the interpolation parameter sets the value to change in steps from 0 to 100 at 8:00. The other option for the interpolation parameter is LINEAR which would perform a linear interpolation to obtain the values at each simulation instant. The other Day_schedule component called holiday_day sets a single all-day period with value 0.

The Week_schedule components define two different types of weeks, the working_week in which a Day_schedule reference is set through the days_schedules parameter setting working_day for Monday through Friday and holiday_day for Saturday and Sunday. The holiday_week component sets a single Day_schedule reference to be used for all days of the week equal to holiday_day.

Finally, the Year_schedule named year sets three annual periods using the periods parameter and their respective references to Week_schedule using weeks_schedules parameter which are:

To simulate this project that we have defined, we first import the OpenSimula.Simulation object to create a simulation environment in the sim variable, a project within that simulation environment called pro. We load the project reading the dictionary that we have explained previously with the read_dict function available for projects and we simulate it using the simulate() function. 


import OpenSimula.Simulation as Simulation

sim = Simulation()
pro = sim.new_project("First example project")
pro.read_dict(project_dict)
pro.simulate()

We will get the following in response to these commands: 


Reading project data from dictonary
Reading completed.
Checking project: First example project
ok
Simulating First example project: ...
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.

After the simulation, each of the components will have its time variables calculated. In our case the year component has a temporary variable called values that we can obtain. the Simulation.plot function can be used to draw an interactive graph (plotly library), the first argument are the dates of the simulation steps (pro.dates() return the array of simulated dates) and the second a list of the varibles to draw.


variables = [pro.component("year").variable("values")]
sim.plot(pro.dates(), variables)

We obtain an interactive graph with the 8760 values on which we can zoom in to show, as an example, the first week of the year.

First example plot