SYM - the model definition language

A G-Cubed model describes various entities (firms, households, governments etc.) and the economic relationships between them using equations. The equations defining the model are expressed using the SYM language, developed by Peter Wilcoxen.

Together, the SYM declarations of the model equation, and the supporting variables, parameters and sets that they are defined over, are referred to as a SYM model definition and they are stored in one or more SYM files that have a .sym file extension by convention.

The SYM files for a given model are included in the set of files needed to run a model.

Software is needed to process the SYM model definition. That software is referred to as the SYM processor. It analyses a model definition to produce lists of variables and parameters as well as a library of Python functions, one for each equation in the model. The output from the SYM processor are also included in the set of files needed to run a model. The SYM processor is an executable file. It is compiled and installed on your virtual machine when first create it. It is invoked from the commandline. Instructions are provided in the explanation of the model SYM files.

To change a model’s equations, you need to edit the SYM model definition and then run the model definition through the SYM processor again. Changes to a model definition may also require alterations to the model database and other inputs, depending on the changes that have been made.

SYM model documentation

The SYM processor can also transform the model definitions into a single HTML page that documents the model. An example of the documentation is available for the teaching version of the G-Cubed model.

The HTML documentation sets out:

  • definitions of various sets
  • definitions of the model variables and their type and their units etc.
  • the model parameters
  • the model equations

The various links between the model elements facilitate rapid exploration of the G-Cubed model. This documentation is key to understanding the model and to designing your own simulations. But before using the model documentation, it is helpful to understand a bit more about the SYM model definition language and what to expect in a model definition. That understanding can be developed by reviewing the SYM language.


A given variable can be required in a model for various combinations of sectors and regions etc.

For example, in the teaching model, region UU, the United States and region NN, all other countries, both track their nominal GDP. Thus, the nominal GDP variable must be defined over the regions set.

Nominal GDP for the USA will be named GDPN(UU) and nominal GDP for all other countries combined will be named GDPN(NN).

A set is a collection of distinct objects or elements, which are used to define variables, parameters and equations.

In larger models, for example, with many sectors and many regions, these sets can be subsetted in various ways as part of the model definition. This subsetting is evident in the documentation of the model definition.

Region and sector codes

Two types of sets are central to G-Cubed models, a set for regions and a set for sectors.

The regions set

In the teaching model the regions set contains 2 regions:

UU, United States
NN, Not United States

The sectors set

In the teaching model the sectors set contains 2 sectors:

  • a01 The sector that produces energy
  • a02 The sector that produces all other material goods and services (but not capital for production or households)

All G-Cubed models have two additional sectors built into them:

  • Y The sector that produces capital for firms
  • Z The sector that produces capital for households

Care needs to be taken because these two capital-producing sectors are not explicitly included in the sectors set of G-Cubed models.


G-Cubed models include many different variables. The name of each variable has two components:

  1. A prefix, starting with a letter and then followed by zero or more letters and digits.
  2. An optional suffix, contained within round brackets, (), that specifies which members of associated sets, the variable relates to, e.g. GDPN(UU) is nominal GDP, identified by the prefix, for the United States, identified by the suffix that contains the regions set member for the United States.

Variable Types

The variables have different types.

  • end = normal endogenous variables
  • ets = expected next period values of endogenous variables
  • cos = costate (or jumping variables - that depend on expectations of the future)
  • sta = state variables
  • stl = state variables lagged by one period
  • exo = exogenous variables.

Only exogenous variables do not have their own equations in the SYM model definition. Their values, in all years, are determined outside of the model.

Variable Names

Variable names consist of the main name followed by relevant qualifier based on predefined sets enclosed within parentheses.


Government debt in the USA is BOND(USA) where BOND is the main variable identifier and the qualifier contained in () is USA which is the country code for the USA.

The capital stock in sector 1 in the USA is defined as CAP(a01,USA) where CAP is the main variable identifier the first qualifier in () is the sector number and the second qualifier is the region code USA.


Unlike variables, parameters remain constant throughout the projections generated by a model.

Like variables, parameters can also be defined over sets. The syntax for parameter names is the same as that for variables.

When users adjust parameters, (usually) the entire dynamic of the model will change. Thus, (some) parameters can be altered when users design their own experiments. Those user-defined parameters can be altered in the user-defined parameters file.

Many other parameters in the model must be calibrated using information in the model’s database files. The calibration of these parameters is done by the parameter calibration class in the model’s python directory.


Like variables, equations are also defined over one or more sets.

The sets associated with an equation are explicit in the model documentation.

Model equations are divided into 4 groups:

  1. State variable equations
  2. Costate variable equations
  3. Equations describing the formation of expected next-period values for endogenous variables
  4. Endogenous variables

These groups of equations and the way that they are expressed and manipulated to solve the model are explained in the G-Cubed model solution documentation.