CLI

CLI is for data scientist or software engineers to trigger a simulation run via bash, there's also an SDK which could possibly suit your use-case better. Make sure to check it out here.

Requirement

• Authenticated gcloud cli running

gcloud auth application-default login

• Set the default project-id

gcloud config set project almanak-production

danger

We do not support Conda environments, these will cause random and unexplainable behaviour. Please use poetry for most projects and tools like pyenv can help a lot with managing your python environment.

Installation

Add this to ~/.pypirc

[distutils]
index-servers =
    almanak-py

[almanak-py]
repository: https://europe-west4-python.pkg.dev/almanak-production/almanak-py/

Make sure this is in the pip.conf file of which the location you can fine here. (If the file is in the wrong location it won't work, for me it's ~/.config/pip/pip.conf )

[global]
extra-index-url = https://europe-west4-python.pkg.dev/almanak-production/almanak-py/simple/

If this is set you can do

pip install keyrings.google-artifactregistry-auth
pip install simcli

Commands for simcli

Generate

Generate will create a local folder with the boilerplate setup for a simulation. It uses the lastest version of the simulation and gives you several files so you can get started quickly. It requires a folderName which is the name of the folder it will make and put the boilerplate files into.

simcli generate folderName

Create

When create command is ran

• A UUID4 id will be generated for the simulation
• Files such as configuration and models at the root of the where the create command is ran will be uploaded to Google cloud storage
• Simulation meta data be added to Firestore.

simulation. Make sure to compile the configuration first. See the CLI command Please note that only a compiled configuration can be used to create a for that below.

simcli create

You can also specify parameters through an argument. These have to be passed in as a JSON object with a name and value paramater as an object. Has to be an array. An example would be:

simcli create '[{"name": "swapping_fees_ETH_1", "value": 0.002}]'

This will update the value of the parameter before creating the simulation.

Available paramaters:

Paramater	Type	Example
--staging	Flag	--staging
--parameter	list[tuple]	--parameter swapping_fees_ETH_2 0.002
--parameters-as-json	str	--parameters-as-json [{"name": "swapping_fees_ETH_1", "value": 0.002}]
--gcs-link	str	--gcs-link gs://almanak-simulations-prod/test-folder/test-file
--sim-id	str	--sim-id a2ddba31-3736-4897-a28d-beb116f19778
--path	str	--path /example/simulation-1/

Get

Expects the a uuid to be provided and will return the status and GCS url of the simulation if a simulation with that ID exists.

simcli get XXXX

Result

Expects the a uuid to be provided and will return the result of the simulation in plaintext. Usefull for automation purposes, prevents from having to parse the output of the get command.

simcli result XXXX

Logs

To make troubleshooting easier you can retreive the simulation logs using the logs command. It requires an id and will only return logs if the simulation started. It might take a few seconds for the simulation to start producing logs so be patient.

simcli logs XXXX

Metrics

The Metrics are being logged to a database, for easy troubleshooting you can retreive a plaintext version of the metrics through this cli command. A tip for processing it is printing it to a file by using > metrics.json after the command.

simcli metrics XXXX

Compile

Using the compile command you will compile the configuration down into a single file that is used as the input for the simulator. It takes a directory as an argument, this directory has to contain the configuration.yaml and all the relevant files.

simcli compile .