Get Started

To get started with the Almanak Simulator, try working through this tutorial, which starts with the required setup task and works through allowing you to run your first single simulation.

1. Install the simcli

The easiest interface with the simulator is the internal simcli tool. This tool has been built to offer the most low level capabilities and interaction with the simulator.

danger

Please make sure you've signed into the gcloud CLI. Please find instruction on how to install that here.

Also make sure you've authenticated correctly and have set the project to almanak-production.

# Authenticate
gcloud auth application-default login

# Set the default project to almanak-production
gcloud config set project almanak-production

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

#install the google articat keyring
pip install keyrings.google-artifactregistry-auth
# install the simcli
pip install simcli

This will install the latest version of the simcli. It might happen that an update gets release from time to time. To update please specifically mention which version you want to install.

pip install simcli==1.5.0

2. Use the simcli to download the boilerplate project

The simcli includes a boilerplate project that is ready to run out of the box. But also provides a structure according to the best practices. If you're new to the simulator this is the easiest way to get started by configuring your own simulation.

simcli generate test-simulation

This will create the folder test-simulation in your current working directory. Feel free to go into it and explore. The most interesting file is the configuration.yaml. Which is the file that specifies all the parameters that the simulator requires to run.

cd test-simulation

3. Run a simulation

Let's run our first simulation! The boilerplate project is a very short and simple simulation so this won't take long to complete.

simcli single create

Once you've done this you will see an ID in the output (in UUIDv4 format). Which you can use to retrieve information about your simulation.

When doing this the simcli will upload the local configuration to the simulation service which will create a simulation run. By default a simulation will only run once, but you can specify a maximum number of automatic retries --max-attempts 2. This will make it so more than one run can be done, this is useful in case an external system that the simulator could be dependant on has a hiccup.

In production it is preferred to use at least 2 maximum retries. But during testing you should never use more than 1 since that's a waste of compute time.

4. Get simulation status

After a few minutes the simulation should have completed. We can retrieve the status of the simulation by using the following command.

simcli single get ID

Make sure to replace ID with the simulation ID that you got from step 4. If the status field is still RUNNING you should try again in a minute or so.

5. Get simulation metrics

The boilerplate project also logs metrics which you can retrieve by using the following command. It will only show the metrics that were collected during the latest simulation run, regardless of if the status was SUCCEEDED or ERROR.

simcli single metrics ID

From here you should have a good idea of how to use the simulator. To explore the simcli more make sure to use the --help flag. All commands and it's respective parameters and options will be clearly explained there.