Chapter 1: Introduction

Here we give a brief introduction to the FRED modeling language. For some background on agent-based modeling in general and FRED, please see the FRED Modeling Language Introduction document.

Note

Throughout this guide, the terms FRED model and FRED program are used interchangeably. These terms are used when discussing a collection of code that defines a valid model, able to be compiled and executed using the FRED modeling platform.

Before beginning, it is important to note that FRED is not itself a model. Rather, FRED is a language and a platform for building models. The model comes from you, the FRED user, the modeler. It should be recognized that building a model is a challenging activity that often requires a lot of effort on the modeler’s part. FRED makes it easier to define and build a model, by efficiently executing simulation runs of the user’s model, and by providing numerous ways to collect data and to visualize the results of the model. The ultimate quality of the results depends on the success of the modeler in building an appropriate model for the purpose at hand and in communicating the model to FRED for execution. Having said that, we believe that using FRED can save the modeler significant effort by eliminating the need to develop custom simulation software, and that interacting with the FRED user community may also contribute to the user’s successful modeling efforts.

Building a serious model is almost always an iterative process. Working toward building a model with FRED usually includes the following steps:

  1. Decide if FRED is suited to your problem

  2. Create a conceptual model

  3. Create rules for individuals

  4. Create and run a FRED Model

  5. Analyze model output and test against other known data

  6. Revise model and repeat

Hopefully this guide and our other documentation will inspire you to learn FRED and to build great models.

Hello FRED

Before reviewing the various elements and syntax of FRED models, we begin with a very simple model. The following model prints out “Helo, World!”

simulation {
   locations = none
   default_model = none
   start_date = 2020-Jan-01
   end_date = 2020-Jan-01
}

startup {
   print("Hello, World!")
}

The first block, the simulation block, specifies a location to simulate. In this case, no location is selected. By default, a simulation includes a “default model” that has every individual in the selected location pursue a set of daily activities. In this case, we’re skipping the default model. Finally, every FRED model indicates a start_date and and end_date. In this case, we’re simulating a single day.

The startup block indicates actions to take at the start of the simulation. In this case the only action is to print a message.

A First Simulation Model

In addition to the simulation location and time frame, most models include at least one condition.

A minimal FRED model is shown below:

simulation {
   # simulated location
   locations = Jefferson_County_PA  # a small county in Pennsylvania

   # simulated time frame
   start_date = 2020-Jan-01
   end_date = 2020-Jan-10
}

# a trivial condition
condition ACTIVE {
   start_state = Start

   state Start {
      wait(0)
      default(Excluded)
   }
}

When this model is run, the population of Jefferson County, PA, comprised of 45,318 individuals, is loaded into the simulation, and individual agents are assigned to a variety of places that include households, schools, and workplaces. In this model, agents follow their normal activities for a period of 10 days. All individual agents begin in the Start state of a trivial condition called ACTIVE and immediately transition to the Excluded state of this condition, where they remain. Clearly, nothing of interest is added by the ACTIVE condition in this model. Later in this guide, more complex conditions will be discussed.

Note

Every condition includes the Excluded state which does not need to be explicitly defined.

Suppose that the model above is stored in a file called minimal.fred. The model can then be executed using the command line:

$ fred_job -k hello_fred -p minimal.fred

This command executes the model as a simulation. -k hello_fred calls this simulation “hello_fred”, while -p minimal.fred tells the FRED Modeling Platform™ which file contains the model.

Note

It is conventional to use the .fred suffix on FRED model files, but it is not required.

The output of the simulation includes a spreadsheet that shows the counts of how many agents are in each state in the model at the end of each day:

_images/chapter2.excel.png

The first three columns give the day counter, the date, and the epi-week for each simulation day. This is followed by three columns for each of the states. For example, the Start state has columns called ACTIVE.newStart, ACTIVE.Start, and ACTIVE.totStart. The newStart column contains the number of agents who enter that state during the day. The Start column gives the number of agents in that state and the end of the day. The totStart column is a running total of all agents who have ever entered that state. The final column, ACTIVE.RR, gives the reproductive rate, or transmission rate for this condition, which is not applicable in this particular model.

Note

An epidemiological week, i.e. epi-week, contains seven days, beginning with Sunday and ending with Saturday. By definition, the end of the first week of the year must fall at least four days into the year. Weeks are numbered 1 to 53, although most years consist of only 52 epi-weeks.

The FRED Simulation Cycle

The FRED language represents a fully functioning agent-based simulation system that can be completely customized as needed. FRED offers a discrete-time model with a time step of one second. The duration of simulations can be from one day to 100 years. To use FRED, the user creates a FRED model in the FRED programming language. The FRED Modeling Platform™ compiles and executes the simulation cycle represented by a FRED program.

The simulation cycle consists of the following:

  1. Select a geographic location for the simulation. This is one or more locations represented in the synthetic population.

  2. Select the timeframe for the simulation.

    • The simulation begins at midnight on the start date.

    • The simulation ends at 11:59:59pm on the end date.

  3. For each step of the simulation, perform the following for each condition in the program.

    • Identify the agents that need to be updated according to the program-defined rules.

    • For each identified agent:

      1. Select the agent’s next state.

      2. Perform the actions associated with the agent’s next state.

      3. If the condition involves interactions among agents, then:

        • simulate the agent interactions within the defined interaction groups

        • update this or other agent’s current state based on these interactions.

  4. After each day of simulation, record statistics about the conditions in the population.

A complete simulation cycle for a single program as described above is called a run. Since FRED models are stochastic, it is often desirable to perform several runs in order to produce meaningful statistics about the performance of the model. A set of runs of the same model is called a job. Upon completion of a FRED job, the user can obtain reports of the output, including spreadsheets, plots, and videos that display the location of user-selected events on a report of the simulation area.

Declarative Programming in FRED

FRED is a declarative programming langauge for writing agent based models. Declarative programming is a programming paradigm that expresses the logic of the computation without expressing the control flow. (Lloyd, J.W., Practical Advantages of Declarative Programming). Within the general class of declarative programming languages, FRED can be classified as a domain-specific language whose domain is agent-based modeling (ABM). The FRED language consists of two primary kinds of statements: property statements and rule statements. Property statements define the static features of the model, including the location, the range of dates for the simulation, all concepts of interest, what information should be tracked and reported, and the initial conditions. Rule statements define the dynamic features of the model, including how agents and their environment change state over time. The FRED platform processes the FRED program, sets up the population, applies the initial conditions, simulates the activities and interactions of the agents, and tracks all user-defined conditions within the population. FRED outputs several reports, charts, and visualizations.

The declarative programming style of FRED provides several advantages for agent-based modeling:

  • No traditional computer programming experience is required.

  • You can focus on scientific effort (e.g. data collection, conceptual modeling, experimental design).

  • FRED provides a simple workflow environment for you and manages all the data produced by the simulation and associated metadata.