Template description

The template provided is structured as follows:

  • project/

    • main.py

    • gga

    • model.py

    • settings.py

    • data/

  • Dockerfile

  • Makefile

  • requirements.txt

Of those files, you need to edit the following:

  • project/model.py to implement the epidemic model

  • project/settings.py to change the calibration process settings

  • project/data/ folder to add your dataset

  • requirements.txt to add python dependencies

  • Dockerfile to add system dependencies

  • Makefile to change the Docker image name that will be created

Project folder

The project folder contains the relevant code for the model to be executed and calibrated.

The model file

The most important file is the model.py file. In this file, the user implements the epidemic model that will be calibrated.

It contains the following:

  • A model function

  • An entrypoint function

  • Definitions for the model

When executed, the project will call the entrypoint function. In particular, when we configure for a specific data file, the data value will contain the path to the file. Also, as some models might be stochastic, a seed is passed to the entrypoint.

The entrypoint is the responsible to manage the data and seed parameters.

Warning

If they are not needed, they can be discarded, but the function must still be defined as def entrypoint(data, seed).

The usual entrypoint function does the following:

  1. Load the model data from the filename provided

  2. Set the pseudo number generator with the provided seed

  3. Call the model function with the non-configurable parameters

  4. Interpret the model result

  5. Print the error (aka: cost) of the model

Note

The mandatory steps from the previous workflow are 3 and 5.

The model function is responsible for performing the real computation of your model. Note that this function is completely empty, you must add the parameters and the body of the function. Unlike the entrypoint, this function can be renamed, but you have to then to change the CONFIGURABLE_FUNCTIONS = ... line to point to your model function.

The model can have two types of parameters:

Configurable parameters

Those parameters will represent the model variables and will be calibrated. Those parameters do not need to be set by the entrypoint function.

Non-configurable parameters

Other parameters such as the dataset, the seed, number of days to consider… Those must be set by the entrypoint function.

For example, let’s assume a basic SIR model, with the parameters \(\beta\) and \(\delta\). Those two parameters are real values, so we would define our model as:

@ac
def model(data,
          beta=Real(0.0, 1.0) = 0.5,
          delta=Real(0.0, 1.0) = 0.5):
    ...

The Real(a, b) = c is the annotation for each configurable parameters, where a is the minimum value, b is the maximum value, and c is the default value.

The basic annotation types available are:

  • Bool, for boolean parameters

  • Int, for integer parameters

  • Real, for real parameters

  • Categorical, for a set of predefined values

For a full description of the annotations available, see the official documentation of OptiLog (Tuning)

Note

The entrypoint does not need to set the configurable parameters, they will be set automatically by OptiLog.

Warning

Do not remove @ac before the model. This line instructs OptiLog to calibrate this function.

The settings file

The file settings.py file allows to change the hyper-parameters for the AC tool (PyDGGA). The usual parameters to change are:

  • Single execution time limit

  • Max configuration time limit

  • Memory limit

You can also modify parameters in GGA_SETTINGS. We reefer the reader to the official documentation of PyDGGA, available at https://ulog.udl.cat/software/

The data folder

This folder is intended to be the place where the data that the model will use during the calibration process is stored.

Although it is not necessary to use this folder, it is the default path that Docker will use to find the data if it is not explicitly specified.

requirements.txt

This file indicates which python packages are required to run the model.

More info of the format of this file can be found at https://pip.pypa.io/en/stable/reference/requirements-file-format/

Dockerfile

In order to run a container with Docker 1, we need to create an image.

The Dockerfile contains the description of how to create the image. The provided Dockerfile inherits from an image which contains OptiLog and PyDGGA installed and ready to be used.

Unless additional packages must be installed for the model to run, it is recommended to leave the Dockerfile untouched.

Makefile

To simplify the creation of the Docker image we provide a Makefile, with three main targets:

  • build: Creates the docker image with the implemented model

  • push: Pushes the docker image to the desired registry

  • clean: Removes all the images from the local system

The targets can be executed by running:

$ make <target>

The Makefile also contains extra targets:

  • help: Lists the available targets and what they do

  • run: Runs the docker image in a local container. As no parameters are specified, if the Dockerfile is not modified, then the container will configure the model.

Note that, although we provide the Makefile to run those tasks, this type of file are simply a description of the commands to be run to execute the task, so the usage of this file is not required as the commands can be executed manually.

Note

  • Modify the IMAGE_NAME from the Makefile for a name that makes sense

  • If you plan to create and keep multiple versions of the same model, modify the TAG

  • If you plan to push the image to a repository, set the IMAGE_NAME such as: repository/name

  • To push an image to a repository you need access. If the push fails, please verify that you have access to the repository and you are pushing to the correct one.

Footnotes

1

Docker or any Open Container Initiative (OCI) compatible tool.