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:
Running Simulations - Previous
Controlling a Simulation
Next - Using Python Notebooks
Using Python Notebooks
Last modified 9mo ago