Chapter 2: FRED Models

This chapter reviews the fundamental elements of the FRED programming languauge, as well as the basic requirements of any valid FRED model.

The Structure of a FRED Program

A FRED model consists of a collection of one or more statements and blocks. Even the most complex models can be broken down into these fundamental elements.

statements

The majority of lines of code in a given model will generally be dedicated to statements. There are three types of statments in the FRED programming langauge:

  • include statements

  • property statements

  • rule statements

include statements allow models to be split up into multiple FRED files. All FRED files are plain text files. By convention, the file extension .fred is used to indicate a file contains valid FRED model elements. A entire model may be contained in a single .fred file, or it may be split up into mutliple files for convenience.

Include statements have the form:

include <filename.fred>

This type of statement has the effect of inserting the contents of the file, <filename.fred>, into the FRED model at that point. The include statement allows a user to collect mutliple files into a single location. Breaking up models into elements is discussed in more detail in Chapter 14.

Property statements have the form:

<property> = <value>

where <property> is one of the properties defined in later chapters of this guide.

Note

If multiple statements define the same property, the property definition occurring latest in the program will be used to set the value of the property.

Rule statements (i.e rules), are a broad class of statements found within states. These may include actions, wait rules, and transition rules. Each of these rules may contain any number of expressions. These rules are discussed in detail in chapter Chapter 4.

Note

Statements are terminated by an end-of-line. If the final character of a statement is a \, the statement is continued onto the next line.

Note

Comments are introduced by the # character–all characters after a # are ignored until an end-of-line. Lines containing only comments or white space are ignored.

blocks

Blocks can be thought of as a collection of related property and/or rule statements. There are a variety of blocks which may appear in a FRED model, including some fundamental blocks:

  • simulation

  • condition

  • state

  • variables

  • place

  • network

  • startup

  • agent_startup

  • use

  • comment

and a few more advanced-usage blocks:

  • configuration

  • restart

  • agent_restart

  • prototype

Blocks have the form:

<block_type> [<block_name>] {
    ...
}

Some blocks must be named (e.g. condition, state, place, and network blocks) while other blocks do not take a name (e.g. simulation, variables, and startup blocks). For example, in the simple program discussed in the introduction to this guide, a condition block called ACTIVE was defined:

condition ACTIVE {
   ...
}

The simulation and comment blocks are discussed in this chapter. The remaining block types are discussed at length at various points within this guide.

Other than comment lines beginning with a # and include statements, all other statements must occur within one of these blocks. Some blocks may contain other blocks. For example, a condition block will generally contain several state blocks, and comment blocks can be placed within any other block. As discussed in Chapter 4, state blocks may contain any number of rule statements that together define the meaning of conditions and the behaviour of agents.

If a program contains multiple instances of any block, the FRED compiler concatenates the instances in the order of occurrence. For example:

simulation {
    start_date = 2020-Jan-01
}

simulation {
    end_date = 2020-Dec-31
}

is equivalent to

simulation {
    start_date = 2020-Jan-01
    end_date = 2020-Dec-31
}

The notation <name>.<property> = <value> can also be used to add to or modify property statements to previously defined conditions, places, or networks. This is sometimes referred to as dot notation. For example:

place School { }
School.contact_rate = 0.35

is equivalent to

place School {
    contact_rate = 0.35
}

The Simulation Block

The simulation block defines some basic properties of a model, including the simulation location(s), the simulation time frame (start and end dates), and the simulation logging and output levels.

Warning

A simulation block is required for all valid FRED models.

A basic simulation block may look like the following:

simulation {
    locations = Pittsburgh_PA
    start_date = 2020-Jan-01
    end_date = 2020-Dec-31
}

This block indicates that the simulation will be run with a synthetic population associated with Pittsburgh, PA. The simluation will begin on January 1, 2020 and run through December 31, 2020.

Multiple locations can be specified using a comma-separated list. White space is also permitted around the commas.

simulation {
    locations = Allegheny_County_PA, Jefferson_County_PA
    start_date = 2020-Jan-01
    end_date = 2020-Dec-31
}

The locations property indicates which portion of a synthetic population should be used in a given model. While it may vary for different synthetic populations, valid locations will be associated with an administrative district like a U.S. county or state. Synthetic populations are discussed in more detail in chapter 3.

There are two ways to specify the time period, by providing an end_date or a days property. If days is set to a positive number, it overrides the end_date property.

A simulation block must contain three statements defining the location(s) and time period. If any of these element is missing, an error will be generated when compiling the model. If no location is desired, set location = none.

The complete set of properties and their default values are shown below. Each of theses properties is described in later section of this Guide and in the Reference pages.

simulation {

    ##### Simulation Options
    locations = none
    start_date = none
    end_date = none
    days = 0
    seed = 123456
    max_loops = 1000000
    update_progress = 60
    substeps = 0
    default_model = 1
    all_group_agents = 0

    ##### Output Options
    weekly_data = 0
    file_buffer_size = 10000
    dump_files = 0
    test = 0
    snapshot_interval = 0
    snapshot_final = 0
    snapshot_date = none
    snapshots = 0
    condition_timing = 0

    ##### Input Options
    population_directory = none
    country = usa
    population_version = US_2010.v5

    ##### Flags
    use_mean_latitude = 1
    enable_transmission_bias = 1
    enable_population_dynamics = 0
    enable_aging = 1
    use_index_id = 0

}

The Comment Block

A comment block is used to document a model and to provide metadata such as the author’s name or the creation date of the model. Comment blocks are optional and are ignored by the FRED compiler. Comment blocks take the form:

comment [<optional comment_name>] {
       All contents of this block are treated as comments.
       ...
}

Comment blocks may appear anywhere in the program, including within other blocks. All content within a coment block is ignored.