Links
📦

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).

Getting started

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_tokento 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)

API overview

Reading the inline documentation

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.

Loading models

list_models

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()

load_model

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

Running simulations

run_simulation

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.

Simulation.show_logs

This function will print out the logs as shown in the “Output” tab in the model editor.

Simulation.results

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.

SimulationResults.to_pandas

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.

Model.find_block

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.

Model.find_blocks

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 with theta:
  • name will only match exact names. Here we see it returned two blocks with the same name, that belongs to different submodels:
  • case (defaults to False) enables case sensitive search

Defining Model Parameters

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.

Model.get_parameters

The model parameters can be read via the get_parameters() method on a loaded Model object:

Model.set_parameters

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:

Model.parameters

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

run_simulation(parameters={...})

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:

Importing data from Python

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

Example

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: