.. _template-desc: 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 :code:`model` function - An :code:`entrypoint` function - Definitions for the model When executed, the project will call the :code:`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 :code:`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 :code:`def entrypoint(data, seed)`. The usual :code:`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 :code:`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 :code:`entrypoint`, this function can be renamed, but you have to then to change the :code:`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 :math:`\beta` and :math:`\delta`. Those two parameters are real values, so we would define our model as: .. code-block:: python @ac def model(data, beta=Real(0.0, 1.0) = 0.5, delta=Real(0.0, 1.0) = 0.5): ... The :code:`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 :code:`@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 :code:`GGA_SETTINGS`. We reefer the reader to the official documentation of PyDGGA, available at ``_ ~~~~~~~~~~~~~~~ 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 ``_ ---------- Dockerfile ---------- In order to run a `container `_ with Docker [#]_, 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: .. code-block:: $ make 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 :code:`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 :code:`TAG` - If you plan to push the image to a repository, set the :code:`IMAGE_NAME` such as: :code:`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. .. rubric:: Footnotes .. [#] Docker or any `Open Container Initiative (OCI) `_ compatible tool.