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
statementsproperty 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.