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.

The classes and methods described here are listed, with their arguments, in the API reference.

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:

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:

# one update per 1 % of the time steps (8760 hourly steps: every 87)
with mo.status.progress_bar(total=100, title="Simulating") as bar:
    pro.simulate(progress=lambda step, n: bar.update() if step % (n // 100) == 0 else None)

The Show 3D button at the bottom opens a 3D view of the building under the form, and Hide parameters leaves the view on its own. The view is built with Plotly, which is shipped with opensimula and sent to the page the first time the view is opened, so it costs nothing until it is used and needs no internet connection.

Project editor with the 3D view

The Space dropdown shows one space at a time, which is the way to see interior partitions: from outside, the exterior walls hide every surface behind them. The rest of the building stays as a grey wireframe, so the space keeps its place and its size in a recognisable model, and only the surfaces of the chosen space answer the mouse. Openings hides the windows and doors.

The selection is linked both ways: picking a component in the list paints it orange in the view, and clicking a surface in the view selects it in the list and shows its parameters.

The Show graph button shows, in the same place, a graph of the components: one box per component, with its name and type, a row for every parameter that refers to other components (construction, spaces, materials…) and how many of its parameters differ from the default. An arrow goes from each of those rows to the component it names, and the boxes are laid out in layers, so that what a component uses is always to its left: materials, schedules and weather on the left, then constructions, spaces, surfaces and openings, and the systems on the right. The colour of the left edge of a box tells its family (legend in the bar); clicking a family in the legend hides its components and their arrows, and clicking it again shows them (the selected component is always shown).

The graph shows the document being edited, so it follows every change at once. A type with more than six components is folded into one box ("64 × Building_surface"); clicking it shows them one by one, and Fold folds them again. Clicking a box selects the component in the list and in the form, and lights up its arrows and the components at their ends; selecting a component in the list or in the 3D view does the same in the graph. Clicking the empty background clears the selection. Show: selected and what it uses keeps only the selected component, everything it uses down to the materials, and the components that use it. Drag to move the graph; the − / + buttons, or Ctrl/⌘ + wheel (pinch on a trackpad), zoom it, and Fit brings it all back into the panel.

Project editor with the graph of the components

The view shows the project, not the document being edited: geometry needs a built model, with references resolved and origins placed relative to the building, which the document alone does not give. Moving a vertex is a plain change of value, so it reaches the project and the view straight away; adding or removing a surface waits for apply(). refresh_geometry() reloads the view after changing the project from code.

The edited definition is available as editor.value, and not every edit reaches the project the same way.

Changing a value — a number, a dropdown, a list of coordinates — is a local assignment, so it is put into the project as you edit, with nothing to press. The component stays the same object, so a variable holding it does not go stale and its results are not thrown away.

Renaming, adding or removing a component, or changing its type needs the project rebuilt, because components refer to each other by name and those references are resolved when the definition is loaded. Those wait: the bar turns amber saying what is missing, the Apply button lights up, and editor.pending lists them. The button is also disabled while the document does not satisfy the schema, since applying would be refused anyway.

editor.apply() does the same as the button, and can also be called from the notebook:

editor = pro.editor()
editor                       # edit it in the notebook
...
errors = editor.apply()      # rebuild pro from the edited definition

It validates the document first and leaves the project untouched if it does not satisfy the schema, so a half applied definition cannot happen; in that case it returns the schema errors. Otherwise it returns the messages from check(). The project is rebuilt rather than patched, so any variable holding a component from before has to be asked for again with pro.component(name), and any simulation results are dropped along with the components they came from.

A value that does not satisfy the schema never reaches the project either. It stays in the document, marked under its field, and goes in as soon as it is corrected.

editor.validate() gives the schema errors of the document, and editor.is_valid() whether there are any. Both are computed in Python, so they also work in a script, without a browser having rendered the widget.

Project editor example

pro.simulate()
viewer = pro.results("spaces_1.temperature", "Denver.temperature", "system.Q_sensible")
viewer

Results viewer

The toolbar sets the Frequency ("Time step", hourly, daily, monthly or yearly) and the Aggregation used to resample (mean, mean without zeros, sum, sum of positives, sum of negatives, max or min; each period is labelled by its start; the sums of positives and of negatives tell apart heating and cooling in a variable with sign, and the mean without zeros leaves out the hours a variable is 0, such as the EER of a unit while it is off), the From/To dates of the interval shown, and the Height of each chart. Monthly and yearly values are drawn as bars, one per period, side by side when a chart has several variables. Table switches to a table of the values shown, and CSV downloads them.

In the charts, the legend gives the values under the cursor; clicking a legend entry hides or shows that variable, and Shift + click removes it. The × at the top right of a chart removes all its variables. Drag horizontally to zoom in on a period, Shift + drag to move it in time, and double-click to go back to the whole interval; zooming or moving one chart applies to all of them.

Everything can also be set from Python, and the viewer updates itself:

viewer.select("spaces_1.rel_humidity")       # add variables
viewer.frequency = "daily"                   # "none", "hourly", "daily", "monthly", "yearly"
viewer.aggregation = "max"                   # "mean", "mean_nonzero", "sum", "sum_pos", "sum_neg", "max", "min"
viewer.interval = ["2001-07-01", "2001-07-31"]  # [] for the whole simulation
viewer.chart_height = 400                    # pixels of each chart
viewer.height = 750                          # pixels of the whole viewer
df = viewer.dataframe()                      # the values shown, as a pandas DataFrame

The 3D button (or pro.results(..., show_3d=True), or viewer.show_3d = True) shows the geometry of the project above the charts. Clicking a surface or a window there opens it, and the spaces it belongs to, in the list on the left, ready to pick its variables. The surfaces whose variables are plotted are drawn in the colour of their series, and the outline of a space whose variables are plotted takes its colour too, so the charts and the model can be read together.

The Colour selector at the top left of the 3D view colours the surfaces by one of their variables instead (viewer.color_variable = "T_s0"), with its mean, maximum or minimum over the interval shown (viewer.color_statistic), or At cursor ("instant"): the model then follows the cursor of the charts, coloured with the values at the time under it (shown next to the selector), on one scale for the whole interval so that two instants can be compared. With this option the series of all the surfaces are sent to the browser, at the frequency of the charts, so for a large building a shorter interval or a coarser frequency keeps it light. The scale has one hue when all the values have the same sign, and two hues around a grey zero when they have both, as heat flows do; windows are drawn opaque, surfaces without that variable are drawn as an outline only, and hovering a surface gives its value. The Space selector shows one space alone, with the rest of the building as an outline, which is the way to see its interior surfaces.

After simulating the project again, viewer.refresh() reloads the variables.

Building shadows 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.

OpenSimula app

The editor and the results viewer can also be used without writing a notebook, put together in an app that opens in the browser. It needs marimo, installed with the gui extra:

pip install "opensimula[gui]"
opensimula gui project.json

The Examples are a good place to start: opensimula examples copies them to a folder, ready to open. The project file is optional: without it the app starts with an empty project, and Open or create a project opens another JSON file or starts a new one. The page has, from top to bottom:

Relative file names in the project, such as the weather file of File_met, are read from the folder the command is run from (the working folder, shown at the top), as they are in a notebook. To open an ASHRAE 140 case, for example, run it from its test folder: cd ASHRAE_140/LOAD_TEST and opensimula gui cases/case_600.json. --port chooses the port of the app server and --headless does not open a browser; Ctrl+C in the terminal stops it.

OpenSimula app with the results of a simulation

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
Checking completed.
Simulating Project 1: ...
100%|██████████| 52560/52560 [00:26<00:00, 1960.14step/s, n_iter=1]

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="monthly",value="mean")

Jupyter shell:

variable_dataframe

HVAC systems and water plants

The HVAC components are of two kinds: equipment components, which only hold the manufacturer's data of a piece of equipment and are not simulated by themselves (DX_unit, Water_coil, Fan, Pump, Chiller_heat_pump, Boiler), and systems (HVAC_*), which use them, are simulated in each time step and store the variables of the installation. An installation is put together by references between them:

How the HVAC components refer to each other

Zones. An air system serves a Space of a building or a Load_space, a zone defined by load records (sensible and latent loads read, for example, from a File_data), which allows to simulate an installation without the building. Both offer the systems the same: their temperature and humidity, and their balance equations. See example 08.

Air systems. HVAC_perfect_system gives exactly the load (ideal loads, example 05); HVAC_DX_system is an air-to-air heat pump (example 06); HVAC_SZW_system (one zone) and HVAC_MZW_system (several zones, with VAV and reheat) have water coils. With water_source "WATER_SYSTEM" (and reheat_water_source for the reheat coils) their coils take the inlet water temperature from a water plant or circuit and give it their load in each iteration; with "UNKNOWN" they use fixed water temperatures.

Water plant. An HVAC_water_system heats and/or cools water with its generators:

Circuits. An HVAC_water_circuit hangs from a plant: its own pumps, availability and, with a mixing valve (heating_supply_setpoint, cooling_supply_setpoint), its own supply temperature. A plant can feed several circuits at different temperatures. For the coils a circuit is like a plant; for the plant it is one more coil.

Results. Each component stores its own variables: each generator its load, part load, electric and fuel power and efficiency; each circuit its temperatures, flows and the load it gives to the plant; the plant the temperatures of the supply, return and generators, the flows of the primary, secondary and bypass, the balance of its water and the total electric (electric_power) and fuel (generators_fuel_power) power. The water balance of a plant is delta_U = Q_generators + Q_coils + Q_process + Q_loss + Q_pump.

As an example, the water side of example 09: a heat pump first, a condensing boiler as backup, and a circuit at 45 °C at most.


...

pro.new_component("HVAC_water_generator", "heat_pump_generator").set_parameters(
    {"equipment": "heat_pump", "pump": "heat_pump_pump"})
pro.new_component("HVAC_water_generator", "boiler_generator").set_parameters(
    {"equipment": "boiler", "pump": "boiler_pump"})
pro.new_component("HVAC_water_system", "water_plant").set_parameters({
    "generators": ["heat_pump_generator", "boiler_generator"],
    "sequencing": "PRIORITY",
    "heating_water_setpoint": "50",
    "cooling_water_setpoint": "7",
    "total_water_volume": 50,
    "system_control": "LOAD_CONTROL",
})
pro.new_component("HVAC_water_circuit", "south_circuit").set_parameters({
    "water_system": "water_plant",
    "pumps": ["south_pump"],
    "heating_supply_setpoint": "45",
})
# the fan coil (HVAC_SZW_system) refers to the circuit
pro.component("fan_coil_south").set_parameters({
    "water_source": "WATER_SYSTEM",
    "heating_water_system": "south_circuit",
    "cooling_water_system": "south_circuit",
})

The parameters and variables of every component are in the component list.