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.
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.2.0
2. Use the simcli to download the boilerplate project
The simcli includes a boiletplate 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. Compile the configuration
Configurations have to be compiled. This builds all the other files into one big
file to rule them all. This is done simply by using the compile command.
simcli compile
4. 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 atleast 2 maximum retries. But during testing you should never use more than 1 since that's a waste of compute time.
5. 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.
6. 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 SUCCEEEDED 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.