SYM files

Table of contents

Each model keeps its definition in the sym directory. The SYM files (those with a .sym file extension) define the model parameters, variables and equations and the sets over which they are defined.

The SYM language was developed by Peter Wilcoxen and its usage is explained in the SYM website.

G-Cubed uses extension features of the SYM language to provided addition details about the model. In particular, attributes on variable declarations provide additional details about how those variables are used in the model.

G-Cubed annotations in SYM variable declarations

For each SYM variable declaration, there are also a number of attributes that can be set in the SYM file to define how the variable works in the model. The attributes are separated by commas. The attributes include the following:

  • an attribute whose value indicates the variable type - the value can be one of:
    • exo for exogenous variables
    • end for endogenous variables
    • sta for state variables
    • stl for lead state variables
    • ets for expected-next-period endogenous variables
    • cos for costate variables
  • an attribute whose value indicates the units that the variable is measured in - the units can be one of:
    • gdp for variables measured as a percent of GDP
    • usgdp for variables measured as a percent of US GDP
    • pct for variables measured as a percentage
    • del for variables measured as in percentage points (e.g. a risk premium)
    • dollar for variables measured in local currency units (LCU) - e.g. a dollar for the USA
    • idx attribute that is used for variable that are indices with a specific base year (e.g. prices and exchange rates);
  • an intertemporal_constant attribute that is used for variables where an intertemporal constant is included in the linear approximation to the equation for that variable when solving the model;
  • exclude_dest_equals_orig is used for variables that are defined over a destination region and a source region but where the source region cannot match the destination region (e.g. imports); and
  • a logged attribute is used for variables that enter the model in natural logs. Where such variables are on the left-hand side of model equations, the right-hand side of the equation needs to be in logs too. This is done for all prices and for all exchange rates. In the linear version of the model, it is not done for quantity variables. In the log version of the model it is also done for quantity variables.

Processing SYM files

Before running a model, the SYM files for that model need to be processed by the SYM processor. That processing creates:

  • a listing of the model sets, parameters, variables and equations in the .lis file
  • an implementation of each of the model equations in Python in the .py file
  • various CSV files that document model details in a way that is easily loaded when running the G-Cubed model.

To run the SYM processor on a model, make sure your current directory is:

/workspace/user_data

Then you can run the SYM processor against the one SYM file that facilitates discovery of all of the other SYM files that together define the model. For example, for model 2R build 178, that SYM file is ggg2r178.sym file. To process it, run:

/workspace/user_data/sym -python ggg2r178.sym model_2R_178.py

HTML model documentation

The SYM processor can also be used to generate HTML documentation of the model. To do so, run:

/workspace/user_data/sym -html ggg2r178.sym model_2R_178.html

Modular SYM model definition

Every time the SYM files are modified, the SYM processor needs to be rerun. This is important because the SYM model definition has been made modular, supporting different ways of representing variables and supporting different policy representations.

The main SYM files for a generic model definition are shown below.

├── sym
│   │   ├── ggg-<VERSION>-<BUILD>.sym
│   │   ├── ggg-<VERSION>-<BUILD>-sets.sym
│   │   ├── linear
│   │   │   ├── ggg-<VERSION>-<BUILD>-configuration.sym
│   │   │   ├── ggg-<VERSION>-<BUILD>-main.sym
│   │   │   ├── *.sym
│   │   ├── log
│   │   │   ├── ggg-<VERSION>-<BUILD>-configuration.sym
│   │   │   ├── ggg-<VERSION>-<BUILD>-main.sym
│   │   │   ├── *.sym
│   │   ├── model_<VERSION>_<NUMBER>_eqnmap.sym
│   │   ├── model_<VERSION>_<NUMBER>_optmap.sym
│   │   ├── model_<VERSION>_<NUMBER>_varmap.sym
│   │   ├── model_<VERSION>_<NUMBER>_varinfo.sym
│   │   ├── model_<VERSION>_<NUMBER>_vars.sym
│   │   ├── model_<VERSION>_<NUMBER>.lis
│   │   ├── model_<VERSION>_<NUMBER>.py

The root SYM file

The SYM processor is always run agains the main SYM file, ggg-<VERSION>-<BUILD>.sym. That SYM file determines how the SYM processor is to find all other SYM files that define the model.

It determines whether the linear or log model is being used. Change that setting by commenting out the import that is not needed (the import of the linear configuration SYM file or the import of the log configuration SYM file).

The root SYM file also imports the set definitions file.

The set definitions file

The ggg-<VERSION>-<BUILD>-sets.sym is where the main sets are defined. These capture key details for a model version including the regions in the model, the sectors in the model and the goods in the model.

The linear and log forms of the model

The sym directory contains two sub-directories, linear and log. Each of these contains its own configuration SYM file and its own main SYM file, along with a number of SYM file modules.

The configuration SYM file imports the associated main SYM file. The main SYM file contains the variable and parameter declarations and the model equations.

The configuration SYM file also determines which modules are being used in the model. Modules are components of the model that can be expressed in different ways. For example, some models have different monetary policy modules. All models have different fiscal closure modules. Most models have modules that allow for different ways of calculating tax revenue. Make sure that the configuration SYM file only imports one file for each module that is being used in the model.