Running FRED

FRED is usually run via the command line. (There are some experimental web interfaces, and other GUIs under development.) This document shows you how to interact with FRED via the command line.

NOTE: Throughout this document, "%" refers to the system prompt and is not part of the typed command.

---

Parameter Files

FRED begins each run by reading in two plain-text parameter files that provide values that control the simulation:

FRED/data/defaults contains the default values of all defined run-time parameters. This file should not be modified.

The second file (usually called params) contains any parameter values that the user wants to override the default values. The params file should be in the project's working directory (which can be anywhere on the system). The params must exists but it may be empty.

Both files have the same format. Lines that begin with a "#" character are considered comments and are ignored. Parameters with scalar values are specified with lines of the form:

 <name> = <value>

For example:

 days = 100
 fips = 42003

Other parameter formats will be described in the Parameters section.

If a parameter appears in both defaults and params, the value in params overrides the value in defaults.

---

Running FRED directly

Usually you will want to use one of job control commands described below for running a large number of simulations with FRED, but for now we will run FRED directly from the command line.

The FRED program takes an optional command line argument, the path to and name of the run-time parameters file:

 % FRED parameter_file_name

If the argument is omitted the file "params" in the current working directory is assumed. The parameter file must exist, but it may be empty if you only want the default parameter values.

By default, FRED will create a directory called OUT and write a daily epidemic report to a file called OUT/out1.txt. Log messages will be printed on the screen, but can be saved to a file:

 % FRED parameter_file_name > LOG.txt

Example: running FRED

Use a text editor to create a params file that contains the lines:

 days = 100
 fips = 42065

These parameters tell FRED to simulate an influenza epidemic in Jefferson County, PA (with FIPS code 42065) for 100 days. All other parameters will be read from FRED/data/defaults

To run FRED, use the command

% FRED params > LOG.txt

Open the file OUT/out1.txt in a text editor to examine it. The file LOG.txt contains log messages that show FRED in action. The LOG file is often helpful if errors occur.

FRED command line options

The FRED program takes up to three command line options:

% FRED [paramfile [run_number [directory]]]

The arguments are optional from right to left.

If all three arguments are given, FRED reads the user-provided parameters from the given paramfile, runs a single simulation with number run_number, and writes its output files to the given directory. The output directory is relative to the current working directory.

If the third argument is omitted, the output directory is taken from the runtime parameter outdir, with default value OUT.

If both the second and third arguments are missing, run_number defaults to 1.

If all arguments are missing, paramfile defaults to params.


Exercise: using FRED command line options

Try the following:

Run FRED with file params and write output files to directory OUT:

% FRED

Run FRED with parameter file params.foo and write output files to OUT:

% FRED params.foo

Run FRED on file params with run_number = 2

% FRED params 2

Run FRED on file params.foo with run number = 2 writing output files to directory OUT.foo:

% FRED params.foo 2 OUT.foo

---

FRED commands

FRED provides commands that facilitate performing several common simulation tasks. FRED commands generally have the form fred_xxx.

fred_help

Use fred_help to list all the available FRED commands:

% fred_help
This is the fred_help command.

To get help for specific topics, try:
   fred_help topic

To get help for any specific command, try:
   <fred_command> --help

Some important fred commands are:

## Documentation
    fred_help -- this program
    fred_param <string> -- search for parameters that contain given string

## Setting up simulation work flows
     fred_set
     fred_calibrate
     fred_get_fips
     fred_make_params
     fred_make_tasks
     fred_make_rt
     fred_rt

## Job control
     run_fred
     fred_clear_all_results
     fred_delete
     fred_job
     fred_jobs
     fred_sa

## Retrieving information from a FRED job
     fred_find
     fred_log
     fred_status
     fred_AR
     fred_CAR
     fred_R0
     fred_cd
     fred_csv
     fred_density
     fred_get_places
     fred_id
     fred_peak
     fred_plot
     fred_tail

## Making maps and movies
     fred_make_map
     fred_make_maps
     fred_make_movie

---

run_fred

The run_fred command performs multiple realizations (runs) in a local directory. Each run uses a distinct seed for the random number generator, so the results will vary from run to run. The format is:

% run_fred -p paramfile -d directory -s start_run -n end_run

The order of the arguments doesn't matter, and all arguments have default values:

p="params"
d=""
s=1
n=1

So

% run_fred -n 3

is the same as:

% FRED params 1 OUT > OUT/LOG1
% FRED params 2 OUT > OUT/LOG2
% FRED params 3 OUT > OUT/LOG3

The random seed for each run is set based on the both the seed value in the params file and on the run number, so a collection of FRED runs can be executed in any order with the same results.

NOTE: You will not normally use run_fred directly; instead, you will use the fred_job command (described next) which uses run_fred and also creates additional files that help you manage your work. But it is a good idea to use run_fred when initially developing or debugging models. If you have errors, check the LOG files in the OUT directory.

---

Job Control

fred_job

A FRED job is a set of simulations that use the same parameters, except for the initial seed for the random number generator. Running multiple replications permits statistical analysis. To start a FRED job, use the command

    fred_job [options]

where options include:

    -h                  -- print help
    -k key              -- assign job the specified key
    -p paramsfile       -- use named param file
    -n number_of_runs	-- number of runs in the job

All the data associated with a job is stored in a database called $FRED_HOME/RESULTS. You can manage the database using these commands:

    fred_jobs                -- lists all jobs in the RESULTS database
    fred_clear_all_results   -- delete all jobs in the RESULTS database
    fred_delete -k key       -- delete the job with given key

Example using fred_job

The fred_job command is used to create a FRED job, consisting of one or more FRED simulations that use the same parameters. FRED jobs are identified by a key that the user selects to name the job. The following command will create a FRED job with key "test" that includes 5 runs of FRED with the parameters specified in the text file params:

    % fred_job -k test -p params -n 5 > test.out &

The "&" symbol runs the job in the background, so you can continue working in the terminal.

While the job is running, you can see its progress using the following commands:

fred_jobs                -- lists all FRED jobs along with their run status
fred_status -k key       -- print the status of job
fred_log    -k key       -- print the last few lines of the log file
fred_find   -k key       -- print the location of the job files

---

fred_status

fred_status prints to current status of the job:

% fred_status -k test
FINISHED Wed Sep  9 12:48:38 2015

---

fred_log

fred_log prints the last few lines of the log file:

% fred_log -k test
STARTED:  Wed Sep 9 12:48:32 2015
FINISHED: Wed Sep 9 12:48:38 2015
tail  LOG1:

day 99 report population took 0.000067 seconds
day 99 maxrss 79015936
day 99 finished Wed Sep  9 12:48:34 2015
DAY_TIMER day 99 took 0.000161 seconds


FRED simulation complete. Excluding initialization, 100 days took 0.290909 seconds
FRED finished Wed Sep  9 12:48:34 2015
FRED took 1.110621 seconds

---

fred_find

fred_find shows the location of the directory containing the data for the job:

% fred_find -k test
~/FRED/RESULTS/JOB/6096

---

fred_delete

Once a job is created, you cannot create the same job again. If you try, you get an error message:

    % fred_job -k test -p params -n 5
    fred_job: key test already used.

To delete the job, use:

    % fred_delete -k test
or
    % fred_delete -f -k test

The latter version assumes you know what you're doing.