Links
📒

Using Python Notebooks

Getting started with Python notebooks
Notebooks are environments where you can write Python code to load models and run simulations over them programmatically. This will allow you to run multiple simulations with different parameters or input data, and find the optimal parameters for your model. You can also use Python code to more closely look at the simulation results data, plot the data in different ways with matplotlib, or even analyze the linearized version of a submodel.
The Python API relies on the same modeling and simulation infrastructure as the model editor, and will be further documented Python Package and API Overview.

Creating notebooks

First, you’ll need to create a new notebook by clicking the “New Notebook” button from within a project, and give it a name.
Alternatively, you can click the + icon next to Notebooks in the left pane to create new notebooks.
After a while, the notebook editor page should come up. It will likely ask you to select a kernel: choose python3.

Notebook editor

Once inside the notebook, you can create various cells that contain either python code, markdown text or raw text. Each cell can be executed as many times as you wish, which will run the python code it contains, or render the text following the markdown

Python cells

By default, cells are created with the type python3 which means they should contain valid Python 3 code. Collimator provides each Notebook environment with a package called collimator that is the reference Python API. More documentation at Python Package and API Overview.

Markdown cells

Cells of type markdown can contain markdown-formatted text, meaning it can contain section titles, bold or slanted text, small tables, formulas, etc... The full specification for markdown and its syntax can be found at https://daringfireball.net/projects/markdown/basics.
Here is an example of a markdown cell with its raw contents and its rendered output:
Markdown cells can be used to add documentation to your projects and models.

Raw cells

These cells are non-code text cells that can only contain plain text, without any specific formatting.

Available libraries

Currently, various Python libraries are preinstalled in the Notebook python environment, including, but not limited to:
More default scientific libraries can be added upon request to the Collimator team.

Using notebooks

Here are a couple of general tips to make the best use of the notebooks.

Running cells

Press Shift+Enter to run the current cell and jump to the next one, or create a new one if this is the last cell.
Press Ctrl+Enter to run the current cell without changing focus.
Press Alt+Enter (Option+Enter on macOS) to run the current cell and always create a new one.
The top navigation bar offer various controls to interact with the running notebook.
  • go back to the dashboard, via the collimator icon
  • see the list of models, files and notebooks in the current project
  • see the currently running kernels

Editing controls

  • save the notebook
  • insert a new cell
  • cut, copy and paste existing cells

Execution controls

  • execute the current cell
  • stop the current cell
  • restart the kernel, which resets the python environment entirely
  • restart the kernel and replay the entire notebook
Note that stopping a cell execution will not cancel running simulations as those are executed in a separate, distributed cloud environment.

Type selector

  • select the type of the currently selected cell. This allows switching between python and text types.

Removing cells

Press Esc to get the focus out of a cell and d twice to delete the selected cell(s).

Getting some help

The documentation for collimator python package can be accessed via the python help() built in function. This inline documentation will always be the most up-to-date version since it is based on inline comments in the code.

Auto-completion

The notebooks hosted by Collimator offer some basic auto-completion that can be triggered using the Tab key.
Further information can be displayed with the Shift+Tab key.

List the running kernels

In the left pane, you can select the Kernel browser tab to see which python kernels are currently running on your server.

Console

At the bottom of the page, you can find two tabs: Variables and Console. If you open the console, you will have access to a Python console that runs within the same environment as the Notebook cells. This can allow you to run some quick Python commands and prototype code before moving it back to a notebook cell.
Closing the Console tab will reset its contents.

Variables inspector

Left from the Console tab, the Variables tab can be found. Its contents should reflect the top-level variables defined in the currently running python environment. Use it to observe at a quick glance what variables are defined and their values.
The x button allows you to remove variables from the environment. This has the same effect as calling del in Python.