Comment on page
📦
Python Package and API Overview
Getting started with Collimator's Python package
The
pycollimator
python package contains APIs to load models and run simulations from any Jupyter Notebook (e.g. VSCode on desktop or Deepnote online).The
pycollimator
package can be installed in a Notebook from pypi as follows:pip install pycollimator
Load the package via the usual
import
instruction:import pycollimator as collimator
To access the API from a Notebook and be able to run simulations programmatically, generate a token from the API Key Manager (in the top right corner of the Collimator app dashboard) and copy the relevant project UUID from the address bar. Call
set_auth_token
to authenticate on the server. The notebook cell should look like the following:pip install pycollimator
import pycollimator as collimator
token = "ae71014a-a82a-11ed-afa1-0242ac120002" #copy your token here
project_uuid = "ba393cc2-a82a-11ed-afa1-0242ac120002" #copy your project uuid here
collimator.set_auth_token(token, project_uuid)
The
collimator
python API is documented and it can be accessed from the notebook via the Python builtin help()
function:
Note that
help()
may show documentation about some unstable or internal APIs that may be removed at any time. Please consider this documentation page as reference of stable APIs.Call
list_models()
to list all the models in the current project. This python list corresponds to the models listed in the left pane.collimator.list_models()

Call
load_model()
to load a specific model, given its name. This returns an object of class Model
.
Optional parameters
case
(defaults toFalse
) enables case sensitive search

Perhaps the most important function in the package,
run_simulation
will execute the model in our distributed cloud environment:
The returned object is of type
Simulation
and contains logs and result data.This function will print out the logs as shown in the “Output” tab in the model editor.

This object contains the raw result data from the simulation.

To plot and analyze the results data, you can access individual block outputs by indexing the results object with the block’s name.
Access the raw results by calling the
to_pandas()
method.
This API is subject to change. In particular, the syntax used to index results by column or find blocks by name is likely to be improved to more naturally match the model structure.
find_block()
returns a single block given a search pattern. The parameters are similar to find_blocks
except that this function will fail if zero or more than one block matches the search.find_blocks()
returns a list of blocks given a search pattern. When called without any argument, this function will list all the blocks in a model.pattern
(the default argument) is a regular expression, that can be used to easily search for multiple blocks. Here we see it return various blocks whose names start withtheta
:

name
will only match exact names. Here we see it returned two blocks with the same name, that belongs to different submodels:

case
(defaults toFalse
) enables case sensitive search

Before running a simulation, you can change the value of model-level parameters to use for a specific simulation run. Those new parameter values will override the default values defined in the model editor UI at Using Model Parameters, but only for a single simulation run and they do not change the values defined in the model editor UI.
The model parameters can be read via the
get_parameters()
method on a loaded Model
object:
This allows you to override some or all parameters on a loaded
Model
. Those changes will only apply to a simulation started from the notebook and will not be reflected in the editor UI.
Only existing model parameters can be overridden, new parameters can not be added:

As a convenience, the parameters are also exposed directly as a read/write dictionary:

Finally, you can pass parameter overrides directly in the call to
run_simulation()
. In the below example, Basic demo
contains a single Constant block with its value defined by K
:

We can run simulations with various values of
K
and see that the results change, but the model itself didn’t:
After these simulations, the model hasn’t changed:

This feature is currently limited to time series of a single floating point value. See also Importing Data for more documentation about the Data Source block.
Using a
Data Source
block, it is possible to import data computed from the notebook directly into a model. There is no need to manually upload a CSV file to the project. In short:- Create a
pandas.DataFrame
object, with a single column of values that will be used by the Data Source block. - Find the Data Source block in a loaded model and call
block.set_data(df)
to set the input data in this block. - Run simulations and plot results
With the following model (all parameters left to their defaults):

And the following code:
import collimator
import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
# Create some data in python
times = np.arange(0,20,0.1)
values = np.sin(times)
df = pd.DataFrame(values, index=times)
# Load the model
model = collimator.load_model('data source')
# Assign the data to the block
ds = model.find_block('DataSource')
ds.set_data(df)
# Run simulation and show results
sim = collimator.run_simulation(model)
sim.show_logs()
res = sim.results.to_pandas()
plt.plot(res)
plt.legend(res.columns)
plt.show()
This is the expected result:
