Chapter 1: FRED Local Installation

This chapter describes how to install the FRED Local product, which is provided as a Docker image, and running an initial FRED model to configure and verify the installation.

Note

This documentation assumes use of the bash shell for Linux / macOS environments; use of another shell is expected to be compatible but may require slight modifications to the commands shown in this document.

Preparing to Install

Before you install the FRED Local solution, this section provides some background and configuration steps that are important to install successfully.

FRED Local Docker Hardware Requirements

  • Adequate physical memory (RAM): FRED requires at least 8 gigabytes of RAM for basic models and small population sizes. For most models 32 gigabytes is recommended, and complex simulations may require much larger memory sizes. At Epistemix, we regularly use containers with 256 GB or more available memory.

  • Adequate disk space: FRED’s engine is quite reasonable in size, but the synthetic population files can be quite large as can some of the results produced by FRED simulations. At least 50 GB of disk space is required, and we recommend at least 256 GB to accommodate population files, model data, results files, visualizations, and other files.

Installation Prerequisites

These instructions are for installing and running FRED version 7. Before getting started, please ensure you have the following software installed on the computer where you plan to run FRED.

You should also have been granted a username and password (known in AWS parlance as a client ID and client secret) to access the Epistemix Container Registry.

Please contact Epistemix customer service if you encounter any problems.

Create FRED Directories

It is useful to have a local fred directory to serve as the root of your working area for FRED. Under this directory we recommend creating the following directories. It is not technically required to organize your directories in this manner, though this document will assume you have done so in the examples and discussion.

The following illustrates how to create these directories from a shell / command-line:

$ cd $HOME
$ mkdir fred
$ mkdir fred/results
$ mkdir fred/models
$ mkdir fred/data
$

Configuring the FRED_HOME environment variable

It is also useful to create a local environment variable FRED_HOME that points to the location of your fred directory. We will assume this environment variable exists in our examples and discussions. It is suggested but not required that you make this environment variable “permanent” via mechanisms appropriate to your operating system (such as modifying your .bashrc file).

$ FRED_HOME=$HOME/fred
$ cd $FRED_HOME
$

Installing FRED Local

Installing the FRED Local product requires that the FRED synthetic population be available as well. We also download some FRED models that we will use to verify the installation. The solution itself is a Docker image.

Install the FRED Population Files

A Synthetic Population is a data set that represents each person and household in a given location with geospatial accuracy and contains no personally identifiable information.

Epistemix provides a synthetic population of the United States, though this does not come pre-installed on the Docker image. Because population files are large and you may only need a subset of them for your modeling purposes, these are not included “inside” the FRED Docker image. The full set of population files is distributed separately from the simulation platform and is downloaded as a zip file.

The steps below describe how to download and unzip the entire USA synthetic population. The end result is that the contents of the zip reside within the data directory of your FRED_HOME directory. The example code uses the command line tool cURL though any tool capable of downloading a zip file will work. You download these population files “outside” the Docker image and make them accessible within the container.

$ curl -o fred-data.zip https://synthetic-population-epistemix-usa-2010v4-all.s3.amazonaws.com/FRED-data.zip
$ tar xvf fred-data.zip --directory $FRED_HOME/data
$ rm fred-data.zip

Download a Sample Model

Epistemix provides a public Tutorials repository with a collection of models that demonstrate essential features of the FRED Modeling Language. The documentation for these models is part of the Epistemix Documentation and you can download this repository from GitHub.

$ cd $FRED_HOME/models
$ git clone https://github.com/Epistemix-com/FRED-tutorials.git
Cloning into 'FRED-tutorials'...
remote: Enumerating objects: 300, done.
remote: Counting objects: 100% (300/300), done.
remote: Compressing objects: 100% (175/175), done.
remote: Total 300 (delta 176), reused 231 (delta 120), pack-reused 0
Receiving objects: 100% (300/300), 2.14 MiB | 6.32 MiB/s, done.
Resolving deltas: 100% (176/176), done.

Retrieve the FRED Docker Image

Assuming Docker and the AWS CLI are installed, start a terminal or command window and log in to the Epistemix container repository 335566905560.dkr.ecr.us-east-1.amazonaws.com using the aws configure and aws ecr get-login-password commands and piping results to docker login. You will be prompted for your AWS Access Key ID and AWS Secret Access Key. Replace the placeholders below with the values provided to you by Epistemix.

$ aws configure
AWS Access Key ID [None]: YOUR_KEY_ID_PROVIDED_BY_EPISTEMIX
AWS Secret Access Key [None]: YOUR_SECRET_ACCESS_KEY_PROVIDED_BY_EPISTEMIX
Default region name [None]: us-east-1
Default output format [None]:

$ aws ecr get-login-password --region us-east-1 | docker login --username AWS \
--password-stdin 335566905560.dkr.ecr.us-east-1.amazonaws.com
Login Succeeded

Once you are logged in, retrieve the latest FRED image from the repository using docker pull. This will make the image available locally. The example output below will likely differ from what you see as it depends on the specific version of the Docker image.

$ docker pull 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local
Using default tag: latest
latest: Pulling from fred-local
f08d8e2a3ba1: Pull complete
3baa9cb2483b: Pull complete
94e5ff4c0b15: Pull complete
1860925334f9: Pull complete
123eba5a6d56: Pull complete
81d2ef2d3de4: Pull complete
f838d164515f: Pull complete
51261d5cb74a: Pull complete
cfbbb1179df2: Pull complete
588ede05e9b6: Pull complete
1bd07ab3b240: Pull complete
cd198a91dc5a: Pull complete
Digest: sha256:23c959bb1471d8ba734b3e864d5da0de7e5cdd2272c9f0e48d817d7f2a639108
Status: Downloaded image for 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local:latest
335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local:latest

Verifying the Installation

Now that the Docker image is available, we can run the sample model within this image to verify that everything is configured correctly. Running a model will access the synthetic population files.

Run the FRED Local Container

With the image available and directories configured, you can now run the FRED Docker image in a container. The following command establishes a local container with the data, results, and models directories accessible within the model. Note that this uses the environment variable FRED_HOME created in a prior section.

$ docker run -dit -v "$FRED_HOME"/data:/fred/data \
-v "$FRED_HOME"/results:/fred/results \
-v "$FRED_HOME"/models:/fred/models \
--name fred 335566905560.dkr.ecr.us-east-1.amazonaws.com/fred-local

Note

Should you need to redo these commands for any reason, you will have to stop your running container (if it’s running) and possibly remove / rebuild the docker image. This can be accomplished with docker stop fred and docker rm fred commands, respectively. Please see the Docker documentation for more details.

Verify the Container Configuration

Once the container has finished start-up activities, verify that the container is properly configured for FRED modeling with the following command.

$ docker exec -it fred fred_verify_container_configuration
No issues found! Container configuration verified!

If a problem is found, an error message will appear instead.

Run a Sample Model

Now that the container is running and verified, you can execute the sample model in the FRED-tutorials directory. We mounted this in the container as the /fred/models directory, and the container’s current working directory should be this location as well.

You will see a few models in the directory. While any of these can be used, in our example we will use the model in the simpleflu directory, which simulates a simple Influenza strain in Jefferson Country, Pennsylvania.

By convention, the core FRED program file for a model is called main.fred and a sample run script file to test the model is called METHODS. The following command executes the METHODS script found in the FRED-tutorials/simpleflu directory within the container. A successful output is shown.

$ docker exec -it fred /bin/bash -c "cd /fred/models/FRED-tutorials/simpleflu && ./METHODS"

fred_job: starting job simpleflu at Wed Mar 10 15:47:35 GMT 2021

fred_compile -p main.fred
No errors found.
No warnings.

fred_job: running job simpleflu id 55 run 1 ...
fred_job: running job simpleflu id 55 run 2 ...
run_set 0 completed at Wed Mar 10 15:47:37 GMT 2021

fred_job: running job simpleflu id 55 run 3 ...
fred_job: running job simpleflu id 55 run 4 ...
run_set 1 completed at Wed Mar 10 15:47:39 GMT 2021

fred_job: finished job simpleflu 55 at Wed Mar 10 15:47:40 GMT 2021

fred_plot: image_file = daily.pdf
fred_plot: image_file = weekly.pdf

If you run this command more than once, you will see a call to fred_delete in the output as well, which deletes the output from the prior run. This output is not shown here.

The METHODS file calls fred_plot, which creates an image of the results as a PDF file. This and other tutorials are discussed in the FRED Language Tutorials available on the Epistemix Documentation site. Here, the PDF files daily.pdf and weekly.pdf are created in your model directory. You can display these by opening the PDF files directly or in the viewer of your choice to see the results of this simulation.

$ cd $FRED_HOME/models/FRED-tutorials/simpleflu
$ open daily.pdf
$ open weekly.pdf

Next Steps

At this point, your FRED Local Docker installation is complete, verified, and ready! We recommend reading the rest of this guide for some ideas to get you started.