Python Package and API Overview
Getting started with Collimator's Python package
collimatorpython package contains various APIs to load models and run simulations.
Load the package via the usual
collimatorpython API is documented and it can be accessed from the notebook via the Python builtin
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.
list_models()to list all the models in the current project. This python list corresponds to the models listed in the left pane.
load_model()to load a specific model, given its name. This returns an object of class
False) enables case sensitive search
Perhaps the most important function in the package,
run_simulationwill execute the model in our distributed cloud environment:
The returned object is of type
Simulationand 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
find_block()returns a single block given a search pattern. The parameters are similar to
find_blocksexcept 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 with
namewill only match exact names. Here we see it returned two blocks with the same name, that belongs to different submodels:
False) 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
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 democontains a single Constant block with its value defined by
We can run simulations with various values of
Kand see that the results change, but the model itself didn’t:
After these simulations, the model hasn’t changed:
Data Sourceblock, 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.DataFrameobject, 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 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')
# Run simulation and show results
sim = collimator.run_simulation(model)
res = sim.results.to_pandas()
This is the expected result: