Cosmo Tech platform simulator base image

This container image goal is to accelerate projects with custom simulators engines to create an OCI container image which can be run by the Cosmo Tech Digital Twin Simulation Platform.

For Cosmo Tech, custom simulator engine are engine which do not use the Cosmo Tech simulator language (CosML) and the Cosmo Tech SDK to generate simulators.

The Cosmo Tech Digital Twin Simulation is available as a PaaS offer in the Azure marketplace.

Getting started

You can run with docker or podman or any other container engine.

docker run -it -e CSM_RUN_TEMPLATE_ID=getstarted docker.io/cosmotech/simulator

This command run the simulator base image with mode engine (default mode) for a prepackaged run template: getstarted.

INFO:root:Phoenix Entry Point
DEBUG:root:Setting context from env vars
INFO:root:mode: engine
INFO:root:Running engine...
INFO:root:Provider: local
INFO:root:No path defined in env var, applying default run_templates/%CSM_RUN_TEMPLATE_ID%/engine/
INFO:root:Path: /pkg/share/run_templates/getstarted/engine/
DEBUG:root:Local Python project path is /pkg/share/run_templates/getstarted/engine
INFO:root:No specific packages requirements found in /pkg/share/run_templates/getstarted/engine/requirements.txt
INFO:root:Running script /pkg/share/run_templates/getstarted/engine/main.py
Hello Cosmo!
INFO:root:Finished engine

Custom python run example

The Cosmo Tech base image is delivered with Python 3 pre-installed.

By default, the Cosmo Tech simulator run a run template in engine mode if not defined.

Run templates are coded in Python and you can code or call any Simulator you want.

You can get this finished example here: https://github.com/Cosmo-Tech/platform-simulator/tree/main/examples/python.

To create a custom run template you must define your project in respect to the Cosmo Tech simulator file tree.

In your directory do:

mkdir -p code/run_templates/investment/engine
echo investment-simulator > code/run_templates/investment/engine/requirements.txt
cat << EOF > code/run_templates/investment/engine/main.py
from investment_simulator.portfolios import growth_simulation

asset_weights = [0.5, 0.5]
asset_returns = [0.1, 0.1]
covariance = [[1.0, 0.0], [0.0, 1.0]]
steps = 10

growth_simulation(asset_weights, asset_returns, covariance, steps)
EOF

You can either edit with a text editor of your choice the files requirements.txt and main.py.

This example uses investment-simulator

Now you can run the Cosmo Tech simulator image:

  • Define the new run template name: investment
  • mount the new run template code
docker run -it -e CSM_RUN_TEMPLATE_ID=investment -v $PWD/code/run_templates:/pkg/share/run_templates docker.io/cosmotech/simulator

INFO:root:Phoenix Entry Point
DEBUG:root:Setting context from env vars
INFO:root:mode: engine
INFO:root:Running engine...
INFO:root:Provider: local
INFO:root:No path defined in env var, applying default run_templates/%CSM_RUN_TEMPLATE_ID%/engine/
INFO:root:Path: /pkg/share/run_templates/investment/engine/
DEBUG:root:Local Python project path is /pkg/share/run_templates/investment/engine
INFO:root:Installing packages requirements from /pkg/share/run_templates/investment/engine/requirements.txt
Requirement already satisfied: investment-simulator in /usr/local/lib/python3.9/dist-packages (from -r requirements.txt (line 1)) (0.2.1.2)
Requirement already satisfied: numpy<2.0,>=1.20.rc1 in /usr/local/lib/python3.9/dist-packages (from investment-simulator->-r requirements.txt (line 1)) (1.22.1)
Requirement already satisfied: pydantic<2.0.0,>=1.8.1 in /usr/local/lib/python3.9/dist-packages (from investment-simulator->-r requirements.txt (line 1)) (1.9.0)
Requirement already satisfied: scipy<2.0.0,>=1.6.0 in /usr/local/lib/python3.9/dist-packages (from investment-simulator->-r requirements.txt (line 1)) (1.7.3)
Requirement already satisfied: typing-extensions>=3.7.4.3 in /usr/local/lib/python3.9/dist-packages (from pydantic<2.0.0,>=1.8.1->investment-simulator->-r requirements.txt (line 1)) (4.0.1)
WARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager. It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv
INFO:root:Running script /pkg/share/run_templates/investment/engine/main.py
PortfolioResults(portfolio_return=0.10000000000000009, portfolio_risk=0.7071067811865476, simulation_mean=[1.0, 1.0915331840515137, 1.2126251459121704, 1.478933334350586, 1.6785497665405273, 2.0015294551849365, 2.048198699951172, 2.2812259197235107, 2.2184031009674072, 2.2684638500213623, 2.374610185623169], simulation_std=[0.0, 0.7965768575668335, 1.5783188343048096, 2.730212450027466, 4.506833076477051, 7.255113124847412, 6.189915180206299, 7.6543354988098145, 8.786901473999023, 9.358325004577637, 10.58057975769043])
INFO:root:Finished engine

You can of course run the python locally for fast dev cycle:

pip install -r requirements.txt
python3 main.py

Once your simulation is ready to be deployed, you can create a new OCI container image with a Dockerfile for instance.

If your requirements won’t be in conflict with other run templates, it is a good practice to pre-install them at build.

cat << EOF > Dockerfile
FROM docker.io/cosmotech/simulator
COPY code/run_templates /pkg/share/run_templates
RUN pip install -r /pkg/share/run_templates/investment/engine/requirements.txt
EOF
docker build -t cosmotech/investment .

You can now run:

docker run -it -e CSM_RUN_TEMPLATE_ID=investment cosmotech/investment

The built image cosmotech/investment is compatible with the Cosmo Tech Digital Twin Simulation Platform.

The next step is to push this image to the platform container registry and register a Run Template in the platform as explain in the dedicated section.

Custom binary run example

Every Cosmo Tech platform simulation run must be handled by the engine handler of the run template.

But in this python program, you can run whatever installed Simulation you want.

Note: The Cosmo Tech Simulator based image is built on top of Debian 11, so your simulator must be able to run in this environment.

Here we will take an example (example 4) with a simulation of a restaurant from this repository: https://github.com/soldatov-s/go-gpss

You can get the simulation binary here: https://github.com/Cosmo-Tech/platform-simulator/tree/main/examples/binary/code/run_templates/bin and the full finished project here: https://github.com/Cosmo-Tech/platform-simulator/tree/main/examples/binary

To create a custom run template you must define your project in respect to the Cosmo Tech simulator file tree.

In your directory do:

mkdir -p code/run_templates/bin

Copy in code/run_templates/bin the compiled restaurant_simulation binary file.

Then do:

mkdir -p code/run_templates/usage/engine
cat << EOF > code/run_templates/usage/engine/main.py
#!/usr/bin/env python
# -*- coding: utf-8 -*-

import subprocess
print("running subprocess binary")
subprocess.run(["../../bin/restaurant_simulation"])
EOF

You can either edit with a text editor of your choice the file main.py.

This code is using Python subprocess to run another program.

Create the Docker file with:

cat << EOF > Dockerfile
FROM docker.io/cosmotech/simulator
COPY code/run_templates /pkg/share/run_templates
EOF
docker build -t cosmotech/restaurant .

You can now run:

docker run -it -e CSM_RUN_TEMPLATE_ID=usage cosmotech/restaurant

...
Object name " Visitors eating "
Average advance 44.30

Object name " Aggregate dishes "
Number of aggregated transact 29.00
Await end aggregate:
transact 111 wait 1 parts
transact 142 wait 1 parts
transact 117 wait 1 parts
transact 128 wait 1 parts
transact 149 wait 1 parts
transact 155 wait 2 parts
transact 112 wait 2 parts
transact 160 wait 3 parts
transact 171 wait 2 parts
transact 143 wait 1 parts

Object name " Visitors pays "
Average advance 4.97

Object name " Out "
Killed 29
Average advance 177.52
Average life 129.24

Exit program
INFO:root:Finished engine

You can of course install any needed dependencies with apt install -y [DEPENDENCY] or the Dockerfile COPY action.

The built image cosmotech/restaurant is compatible with the Cosmo Tech Digital Twin Simulation Platform.

The next step is to push this image to the platform container registry and register a Run Template in the platform as explain in the dedicated section.

Push the image to the Cosmo Tech platform

WIP

Create and register a run template

WIP

Create a parameter handler for input

WIP

Send results to the Cosmo Tech platform

WIP

Other handlers

WIP

GitHub

View Github