Brief Contents
Detailed Contents
Index

GEMPACK manual

Jill Harrison, Mark Horridge,
Michael Jerie, Ken Pearson

29 Nov 2016
ISBN 978-1-921654-34-3

This online version of the GEMPACK documentation is designed for effective searching and navigation within your browser. You can click on on any blue link to jump to the indicated place, and use the Back button to return. Use the middle mouse button to open a link in a new tab. A yellow panel is visible at top right, with links to the Contents page and Index. To find information on a particular topic, go to the Index first. You can also use your browser's Edit..Find command to search through the entire document.

You can use your browser's View menu to adjust the text size. Or, using your keyboard, press CTRL and + or CTRL and - to zoom in or out. If your mouse has a wheel, hold down the CTRL key, and then scroll the wheel to zoom in or out. You may need to wait a second or two to see the effect.

This manual refers to GEMPACK Release 11 and later — but will be useful too for earlier releases. Previous GEMPACK documentation was contained in a number of separate manuals called GPD-1 to GPD-9. Now most of these documents have been revised and consolidated into this single manual.

Each section or subsection has a "topic ID" which appears in green at the end of section headings. Usually, the topic IDs refer to previous GEMPACK documentation. For example, to search for section 3.11 of GPD-2 [ZERODIVIDE], you could use your browser's Edit..Find command to search through the entire document for "gpd2.3.11".

GEMPACK programs may emit warning or error messages that refer you to sections of this manual. The references may include section numbers, section titles and topic IDs. The last identifier [topic ID] is most likely to remain unchanged through successive revisions of the manual.

If you want to print out sections, use the matching PDF file, GPmanual.pdf.

To cite this manual, use:

Harrison, Horridge, Jerie & Pearson (2014), GEMPACK manual, GEMPACK Software, ISBN 978-1-921654-34-3

Other GEMPACK-related citations are suggested in section 1.7.

Brief Table of Contents

Detailed Table of Contents

 

1    Introduction [gpd1.1]

Click here for detailed chapter contents

GEMPACK (General Equilibrium Modelling PACKage) is a suite of economic modelling software designed for building and solving applied general equilibrium models. It can handle a wide range of economic behaviour and contains powerful capabilities for solving intertemporal models. GEMPACK calculates accurate solutions of an economic model, starting from an algebraic representation of the model equations. These equations can be written as levels equations, linearized equations or a mixture of these two.

The software includes a range of utility programs for handling the economic data base and the results of simulations, and is fully documented with plenty of examples.

GEMPACK provides

New features of GEMPACK Release 11 (2011) are listed in section 72.8, and section 72.9 lists some additions for Releases 11.1 (2012), 11.2 (2013) and 11.3 (2014).

The remainder of this chapter contains the following sections:

1.1    Organization of this manual [manualoutline]

Previous GEMPACK documentation was contained in a number of separate manuals called GPD-1 to GPD-9. Now most of these documents have been revised1 and consolidated into this single manual, organized as follows:

A list of GEMPACK documents (including the former GPD documents) is given in chapter 81.

1.2    Using this manual [usingmanual]

This manual is available in two formats which you can view on your PC:

In each case the Contents and Index sections should help you find the information you need.

The manual is still evolving. When it eventually stabilizes, a printed copy of the PDF manual may be produced. However, to reduce bulk, material after chapter 47 will be omitted from this paper version (except for the References and the Index). The omitted material is more technical or less generally useful. You could still view or print it from the online versions described above.

1.2.1    For experienced GEMPACK users [gpd1.1.5.2]

If you have worked with an earlier version of GEMPACK, the first thing you will want to see is a list of the new features. The latest new feature list is at the webpage http://www.copsmodels.com/gprelnotes.htm. There is a summary in section 72.8 below. Features introduced for previous GEMPACK Releases are listed in chapter 72.

1.2.2    For new GEMPACK users — getting started [gpd1.1.5.1]

We suggest you read the Introduction to GEMPACK chapters 3 to 7, working through the examples.

We have built these chapters around the sorts of modelling tasks you will want to do. The most important of these tasks are:

We suggest that you begin with the first of these tasks (simulations). Chapter 3 tells you how to carry out simulations with existing models, and how to look at the results. We suggest that you read this in detail and carry out the simulations described there for yourself. This chapter includes detailed hands-on instructions for using the relevant GEMPACK programs. You will find sufficient detail there to carry out all the steps involved.

The simulations in chapter 3 are based on the Stylized Johansen model, which is a small model. Even if your purpose in using GEMPACK is to work with another model (possibly ORANI-G or GTAP), we strongly recommend that you work through chapter 3 in detail first. After that, you will be in a position to carry out simulations with your chosen model.

At the end of chapter 3 we give suggestions as to what to do next. Roughly speaking, the possibilities are:

We now encourage you to skip the rest of this chapter and to go straight to chapter 3.

1.3    Supported Operating Systems [supportedos]

The complete range of GEMPACK features are available only on PCs running Microsoft Windows. Nevertheless GEMPACK will run (with some limitations) on other operating systems, such as MacOS or Unix (see chapter 69 for more details).

GEMPACK supports both 32-bit and 64-bit versions of Windows XP, Windows Vista and Windows 7 to 10. The 64-bit versions are more suitable for large modelling tasks (see section 49.3.1), particularly if you wish to exploit the parallel-processing capability of modern PCs — see chapter 31.

More recent Windows versions have caused some small problems. See:
http://www.copsmodels.com/gp-vistaprob.htm
for a description of some problems and work-arounds.

1.4    The GEMPACK programs [gpd9.1.5]

GEMPACK includes a number of separate programs. They fall into two broad groups:

1.4.1    The original command-line programs [gpd9.1.5.1]

The original GEMPACK programs, all written in Fortran, are command-line programs (without a graphical interface). They form the core of GEMPACK and are still directly used by experienced modellers. They are portable between different operating systems. The chief programs are:

ProgramDescription
TABLOtranslates a TAB file into an executable program (or, optionally, into bytecode [GEMSIM Auxiliary files]). See chapter 8.
GEMSIMan interpreter: executes bytecode versions of TABLO-generated programs.
SLTOHTtranslates an SL4 (Solution) file into a HAR or a text file. See chapters 39 and 40.
SEEHARtranslates a HAR file into a text file. See chapter 37.

Some special command-line programs may be needed to transfer models between computers that use different operating systems: MKHAR, RWHAR, MKEQ, RWEQ, RWSOL, MKSOL, CMPSOL, and COMPEQ. These programs are documented in chapter 71. The program MODHAR (see chapter 54) can be used on non-Windows operating systems to translate text data into a HAR (header array) file.

1.4.2    The Windows programs [gpd9.1.5.2]

Since 1995, additional GEMPACK programs have been available, which only run on Windows PCs. These have a more modern graphical interface, and are written in Pascal [Delphi]. Most of these Windows programs make some use of the core command-line programs listed above: they are really "wrappers" or "shells" which provide a more convenient interface to the original GEMPACK programs. The main Windows programs are:

ProgramDescriptionUsing core programs:
TABmateA text editor tailored to GEMPACK use.TABLO
ViewHARUsed to view and modify HAR data files.none
ViewSOLUsed to view simulation results.SLTOHT (sometimes)
AnalyseGEUsed to analyse simulation results: presents an integrated view of input data, model equations, and results.TABLO, SLTOHT and others
WinGEMA portal to all the other GEMPACK programs, which guides the user through the stages of specifying a model, creating data files, and running simulations.all
RunGEMA convenient interface for running simulations and viewing results.SLTOHT and others

Another Windows program, RunDynam, is used to organize, perform, and interpret multi-period simulations with recursive-dynamic CGE models. RunDynam is not included in the standard GEMPACK package — it may be purchased separately. See section 36.7 for more about RunDynam.

1.4.3    TABLO-generated programs [gpd1.1.7.1]

There is another class of programs in GEMPACK called TABLO-generated programs. These programs are not supplied as part of the GEMPACK software — you create them yourself.

A TABLO-generated program is a Fortran program, written by the program TABLO, designed to solve a particular model specified in a TABLO input (TAB) file supplied by you. You need a Source-code version of GEMPACK to write TABLO-generated programs — see sections 1.6.1 and 3.5.1 below. These Fortran programs can be compiled and linked to the GEMPACK libraries of subroutines using your Fortran compiler to make an Executable image. The Executable-Image (EXE) can be used to run simulations instead of using the program GEMSIM.

1.5    Models supplied with GEMPACK [gpd1.1.8]

A variety of example CGE models are supplied with GEMPACK including:

Chapter 60 contains more details. Hands-on examples using some of these models appear in chapters 42 to 46.

1.6    Different versions of GEMPACK and associated licences [gpd1.1.9]

Currently there are four main types of GEMPACK licence:

  1. The Source-code version is the most powerful and expensive option. You can produce a model-specific EXE program which solves large models quickly, and can be shared with other people. A Fortran compiler is needed.
  2. The Unlimited executable-image version also allows you to create and solve large models, using the general-purpose program GEMSIM. No Fortran compiler is needed — you cannot turn your model into an EXE file.
  3. The cheaper Limited executable-image version allows you to create and solve models up to a certain size.
  4. The cheapest Introductory licence is needed by persons (with no other GEMPACK licence) who wish to solve a large model using a model-specific EXE program generated by another (source-code) GEMPACK user.

GEMPACK licences are usually site licences, that is, multi-user licences which can be used on any number of computers at the same site within the relevant organisation. However, individual licences are available for types 3 and 4 above.

More details about these licence types follow. Alternatively, consult these web-pages:

To find out which version of GEMPACK you are running now, see section 2.9.7.

1.6.1    Source-code versions and licences [gpd1.1.9.1]

Source-code licences provide the most flexibility for modellers. The size of the models that can be handled is limited only by the amount of memory on your PC. Large models are usually solved using TABLO-generated programs — which are model specific and can solve large models considerably faster than the general-purpose program GEMSIM. A suitable Fortran compiler is required — see:
http://www.copsmodels.com/gpfort.htm

The Source-code version is the only GEMPACK version that can run "natively" on non-Windows computers: see chapter 69.

1.6.2    Unlimited executable-image version and licence [gpd1.1.9.3]

Like the Source-code version, the Unlimited Executable-image2 version allows you to create and solve models of any size — as long as your PC has sufficient memory. No Fortran compiler is needed: all simulations are carried out with the GEMPACK program GEMSIM. With large models (for example, 115 sector ORANI-G or 15-region, 15-commodity GTAP), GEMSIM is noticeably slower than the corresponding TABLO-generated program (which can only be created with a Source-code licence). [Some CPU times are reported in chapter 73.]

If users with an Unlimited Executable-image version find that their simulations are taking an unacceptably long time, they can upgrade to a Source-code version.

1.6.3    Limited executable-image version and licence [gpd1.1.9.2]

With this version, all simulations are carried out with the GEMPACK program GEMSIM. "Limited" means that the size of models that can be solved is limited.

Modellers with the Limited Executable-image version of GEMPACK can carry out the full range of modelling tasks, including building and solving new models, and modifying existing ones. The only restrictions are on the size of the models that can be handled.

The size of models that can be solved is limited to what we call "medium-sized" models. For example, this version is able to solve most single-country models with up to about 40 sectors (for example, it will solve 37-sector ORANI-G), and it will usually solve 12-region, 12-commodity GTAP; but it will not solve 50-sector ORANIG or 15-region, 20-commodity GTAP. The full details of size limits for simulations with the Limited Executable-image version can be seen in chapter 62.

This version of GEMPACK is often supplied at training courses run by the Global Trade Analysis Project or by the Centre of Policy Studies.

If users with a Limited Executable-image version find that their models have become too large, they can upgrade to a Source-code or Unlimited Executable-image version.

1.6.4    Using Exe-image and Source-code GEMPACK together [gpeisc]

A Source-code GEMPACK licence is a site licence covering the whole of some department or section of an organization. The standard installation procedure is not very quick and requires that a suitable Fortran compiler is installed. If there are many GEMPACK users, the cost of multiple Fortran licences could be considerable.

An efficient alternative might be for a small core group of modellers to install the full Source-code GEMPACK (with Fortran compiler) and for an outer group of less frequent (or less advanced) users to use the Unlimited Exe-image version of GEMPACK (without Fortran compiler). No additional licence is needed, because a Source-code licence file will also enable use of the Unlimited Exe-image version.

For example, a university department with a Source-code GEMPACK licence might install full Source-code GEMPACK (with Fortran compiler) on the PCs of several academic staff, while students used the same licence file to run the Unlimited Executable-Image Version. The Executable-Image Version is also well-suited to a Computer Lab environment.

For more details, see http://www.copsmodels.com/gpeisc.htm.

1.6.5    When is a licence needed [gpd1.1.9.7]

A GEMPACK licence is required:

  1. to run TABLO or GEMSIM
  2. to run a TABLO-generated program using a larger dataset
  3. to use some more advanced features of GEMPACK Windows programs

All three tasks above can be accomplished using either an Executable-image or a Source-code licence. But tasks 2 and 3 (but not 1) could also be accomplished using the cheaper Introductory licence described next.

1.6.6    Introductory licence [gpd1.1.9.5]

This type of licence is typically needed by someone who has not installed any full version of GEMPACK, but who has obtained GEMPACK-related material (for example, a TABLO-generated program and/or some data files) from another GEMPACK user.

Some type of GEMPACK licence may be required to run a TABLO-generated program or to use more advanced features of some GEMPACK Windows programs. The Introductory licence is the cheapest way to meet this requirement. It was previously called Large-simulations licence.

TABLO-generated programs distributed to others.

A GEMPACK user with a Source-code licence can create executable images of TABLO-generated programs to solve the models they build or modify. These TABLO-generated programs can be distributed to others (including others who do not have a GEMPACK licence) so that they can carry out simulations with the model. However, if the model is larger than medium sized (as defined in chapter 62), running simulations will require some type of GEMPACK licence. For example, any Source-code or Executable-image licence will do, even older ones. But the Introductory GEMPACK licence, designed for just this purpose, is the cheapest solution.

For example, a modeller who (freely) downloaded the TABLO-generated program GTAP.EXE, would, with no GEMPACK licence be restricted to using data no larger than 12 regions and sectors. If she purchased an Introductory GEMPACK licence, she could solve models of any size (that her PC could manage).

Note also:
(a) An Introductory GEMPACK licence will not allow you to create or modify models.
(b) An Introductory GEMPACK licence will not allow you to run TABLO or GEMSIM.
(c) You do not require a licence file for GEMPACK utility programs such SLTOHT.

Other programs (ViewHAR, AnalyseGE etc).

A trial version of GEMPACK can be freely downloaded from the GEMPACK web site: see http://www.copsmodels.com/gpeidl.htm. After the trial licence expires, you will no longer be able to create or edit new models. However, most Windows programs will continue to work, as they do not require a GEMPACK licence for much of their functionality. However some of the more advanced features of these programs require a moderately recent GEMPACK licence3. For example,

The Introductory licence is the least expensive way to satisfy these requirements.

1.7    Citing GEMPACK [citinggempack]

When you report results obtained using GEMPACK, we ask you to acknowledge this by including a reference to GEMPACK in your paper or report. This acknowledgement is a condition of all GEMPACK licences.

For example, please include a sentence or footnote similar to the following:

The results reported here were obtained using the GEMPACK economic modelling software [Harrison and Pearson (1996)].

and include amongst your references:

W.J. Harrison and K.R. Pearson, "Computing Solutions for Large General Equilibrium Models Using GEMPACK", Computational Economics, Vol. 9 (1996), pp.83-127.

For a general account of CGE solution software, focussing on GEMPACK, GAMS and MPSGE, you could cite Horridge et al. (2012). If you use complementarities in your model, consider citing Harrison, Horridge, Pearson and Wittwer (2002). For subtotal results, cite HHP.

To cite this manual, use:

Harrison, Horridge, Jerie & Pearson (2014), GEMPACK manual, GEMPACK Software, ISBN 978-1-921654-34-3

1.8    Communicating with GEMPACK [gpd1.1.2]

Latest contact details are at
http://www.copsmodels.com/gpcont.htm.

1.8.1    GEMPACK web site [gpd1.1.3]

The GEMPACK Web site is at http://www.copsmodels.com/gempack.htm.

This contains up-to-date information about GEMPACK, including information about different versions, prices, updates, courses and bug fixes. We encourage GEMPACK users to visit this site regularly.

In particular, this site contains a list of Frequently Asked Questions (FAQs) and answers at http://www.copsmodels.com/gp-faq.htm.

This is updated regularly. It is a supplement to the GEMPACK documentation. If you are having problems, you may find the solution there. We welcome suggestions for topics to include there.

There are also alternative GEMPACK web sites at http://www.gempack.com and http://www.gempack.com.au and you can send email to info@gempack.com or support@gempack.com. At present these alternative web sites merely point to the main GEMPACK site. Email to gempack.com is forwarded to the GEMPACK team.

1.8.2    GEMPACK-L mailing list [gpd1.1.4]

GEMPACK-L is a mailing list designed to let GEMPACK users communicate amongst themselves, sharing information, tips, etc. The GEMPACK developers occasionally make announcements on it (new releases, bugs, courses, etc). The list is moderated to prevent spam.

We encourage all GEMPACK users to subscribe to it. Once you have subscribed, you can send mail messages to all others on the list, and you will receive as mail any messages sent to the list. For more details, see http://www.copsmodels.com/gp-l.htm.

1.9    Acknowledgments [ackintro]

The improvement of GEMPACK over many years owes a great deal to its users. Some have contributed very useful suggestions, whilst others have patiently supplied us with details needed to reproduce, and ultimately fix, annoying program bugs. We are very grateful to these people, some of whom are listed below.

Agapi SomwaruAlan FoxAlex WhitmarshAshley Winston
Athoula NaranpanawaErnesto ValenzuelaFederica SantuccioFrank van Tongeren
Greg WattsGuy JakemanHom PantIain Duff
Ian WebbJames GieseckeJoe FrancoisJorge Hernandez
Joseph FrancoisKevin HanslowLars-Bo JacobsenLindsay Fairhead
Marinos TsigasMartina BrockmeierMatt ClarkMaureen Rimmer
Terry MaidmentMichael KohlhaasOwen GabbitasPeter Dixon
Peter JohnsonPeter WilcoxenPhilip AdamsRobert Ewing
Robert McDougallRonald WendnerSteven RoseKevin Hanslow
Tom HertelTom RutherfordYiannis ZahariadisGlyn Wittwer
Markus LipsHans van MeijlChantal NielsenWusheng Yu
Tran Hoang NhiAlan PowellMichael BourneGeorge Verikios

2    Installing GEMPACK on Windows PCs [gpd6.1]

Click here for detailed chapter contents

This chapter tells you how to install GEMPACK Release 11 on a PC which is running Windows. To install GEMPACK Release 10 (or earlier) please refer to the install documents (GPD-6, GPD-7) that accompanied the earlier Release.

Some parts of the install procedure differ between the Executable-Image and the Source-Code versions of GEMPACK — the text below will indicate these differences.

All components of GEMPACK are contained in a single install package, which you might download or receive on a CD or USB drive.

The package will install

The Executable-Image package will also install a number of vital command-line programs such as TABLO.EXE and GEMSIM.EXE. The Source-Code package instead installs Fortran source code files for these programs: during installation these sources are compiled to produce TABLO.EXE and GEMSIM.EXE.

2.1    Preparing to install GEMPACK [gpd6.2]

2.1.1    System requirements [gpd6.2.1]

Requirements for installing GEMPACK are:

2.1.2    Your GEMPACK licence file [gplic]

The installation procedure will ask where to locate your GEMPACK licence file — so you should probably find it yourself before installing. This small file will have suffix ".GEM" and was probably sent to you as a zipped email attachment, or might be located on the GEMPACK CD. During installation, a copy of the file, named LICEN.GEM, is placed in the GEMPACK folder (ie, the folder where GEMPACK is installed).

You could also use the LICEN.GEM file in the GEMPACK directory from a previous install of Release 11 GEMPACK (but a Release 10 or earlier licence will not work).

If you cannot find your GEMPACK licence file, you can still install GEMPACK. In this case:

Then, after installation, you should manually place a copy of your licence file, renamed if necessary to LICEN.GEM, into your GEMPACK folder.

2.1.3    Where to install [instdir]

First decide where to install GEMPACK, bearing the following in mind:

2.1.4    Notes for IT support [itsupport]

You can install GEMPACK as Administrator, and run as Limited or Standard user, as long as permissions are set to allow Limited or Standard users to access needed files. Users of GEMPACK need to be able to read and execute the programs in the GEMPACK directory. In their working directories, Limited Users need full rights to read, write, execute and delete files.

Users of Source-code GEMPACK need to be able to create their own EXE files using their Fortran compiler.

The software requires that users be able to open and use a command prompt (cmd.exe) window, and to run BAT scripts.

Please assist the user by switching off "Hide file extensions of known file types" (From Explorer, Tools...Folder Options...View).

If you are installing GEMPACK on a network please see section 2.9.5.

2.1.5    [Source-code only] Testing the Fortran installation [gpd6.3.3]

Skip this section if you are installing Executable-Image GEMPACK.

Before installing Source-Code GEMPACK you need to test your Fortran installation by compiling and running a small 'Hello World!' program. The webpage http://www.copsmodels.com/gpfort.htm links to compiler-specific instructions for installing and testing your Fortran. It is important that the 'Hello World!' test succeeds before you install GEMPACK.

The test requires that specific Fortran files are present on the PATH. These files are:

The GFortran and Lahey installers should automatically add the right folders to your PATH. For Intel, you need to edit the PATH variable [the web instructions tell you how].

2.1.6    Configure Anti-virus programs [antivirus]

Some user report that anti-virus programs delete GEMPACK programs or prevent GEMPACK programs from being installed. To avoid such problems you could, before installing GEMPACK:

You may choose also to exclude from virus-checking the folders where GEMPACK-related work will be done — anti-virus programs can slow down simulations (especially RunDynam simulations). See point 3, section 30.

2.2    Installing GEMPACK [gpd6.4]

Exit from all Windows programs before beginning the install procedure.

Use Windows Explorer to locate the GEMPACK install package; double-click to run it.

  1. Perhaps the "User Elevation" dialog will appear; if so, you may need to supply the Administrator password, or simply agree to run the install.
  2. Welcome and Copyright warning. To agree to the copyright conditions click Next.
  3. Destination Location. Here you choose where GEMPACK will be installed; we refer to this directory as the GEMPACK directory. We recommend that you accept the suggested C:\GP directory. You may choose another existing or new directory by clicking the Browse button. If you do so, when you return to the original screen check carefully that the folder or directory name is what you want. Sometimes the install program adds \GP to the end of the name you have selected. In choosing a folder name, avoid names that contain non-English characters or parentheses. Avoid installing under the Program Files directory: Windows may prevent you changing files there.
  4. Changes to your PATH and Environment. The Install program can make changes to your PATH and the Environment variable called GPDIR. We strongly recommend that you agree to these changes. If you do not, you must make these changes yourself later: see section 2.8.
  5. Selecting a GEMPACK licence file. If the Installer does not find an existing LICEN.GEM in the GEMPACK directory you may click Browse to select your licence file for installation. If there already is a LICEN.GEM file in your chosen GEMPACK directory, the Installer will not overwrite it, and the Browse button will be disabled. If the existing licence file is an old or wrong licence it is your responsibility to later place the correct Release 11 licence file into your GEMPACK directory, renamed if necessary to LICEN.GEM.
  6. [Source-code only] Select Fortran Compiler. Indicate which Fortran compiler you will use. This compiler should be installed and working, as described above.
  7. Ready to begin installation. You may review your settings, click Back to make changes. Click Next to begin the installation. The Install program copies many files to your GEMPACK directory. Leave the CD in the drive until the installation is complete.
  8. [Source-code only] Continue with compiling libraries and executable images. After file copying is finished you are prompted to launch BuildGP by clicking Next. When you click on Next, the install program will exit and the BuildGP program will be launched. BuildGP builds the GEMPACK libraries and executable images of the Fortran-based GEMPACK programs. This will take several minutes. If all goes well, you will eventually see a message saying that the libraries and images have been built successfully. In that case, just click OK and go on to section 2.8. If there is a problem, see section 2.2.2.

2.2.1    If a warning appears after installing [pcawarning]

Sometimes, just after installing GEMPACK, a warning screen appears, titled "Program Compatibility Assistant" and announcing that "This program might not have installed correctly". You are offered two options (a) "Reinstall using recommended settings", or (b) "This program installed correctly. We believe that the warning is needless and that you should click "This program installed correctly".

2.2.2    [Source-code only] If an error occurs [gpd6.4.1.1]

If an error occurs during the BuildGP process, you will be told the name of the procedure when the error occurred. We suggest that you note this name on paper, then exit from BuildGP. Usually an Error log is shown. This should give you some idea what is happening.

Possible Checks and Actions to try:

2.2.3    GEMPACK licence [gpd6.4.4]

Your GEMPACK licence must be called LICEN.GEM and it must be placed in your GEMPACK directory (that is, the directory in which you installed GEMPACK). The installer may have already done this: if so, skip this section.

If you already have a Release 11 licence on your computer in another directory, please copy the file LICEN.GEM to your current GEMPACK directory.

See section 1.6 for details about GEMPACK licences.

2.2.4    Changes to your PATH and Environment [gpd6.4.4a]

If (against our advice) you did not allow the Install program to make changes to your PATH and the Environment variable called GPDIR, you must now make these changes yourself: see section 2.8.

2.3    Testing the Installation [gpd6.5]

The following test should be performed whether you have the Executable-Image or the Source-Code version of GEMPACK.

The test runs a simulation with the small Stylized Johansen model [SJ].

Create a folder, for example, C:\TEMP, where you can do the test. Copy the following files from the Examples subdirectory of your GEMPACK folder (probably C:\GP\EXAMPLES) to your test folder (eg C:\TEMP):

SJ.TABSJ.HARSJLB.CMF

Open a command prompt (DOS box) by going Start..Run and type in "cmd" and hit OK. This will start a DOS box running. In that DOS box, type in the command

cd /d C:\TEMP

to move to your test folder (assuming that you are testing in C:\TEMP). Then type

dir sj*.*

You should see that the example files listed above are in the test folder.

Step 1: running TABLO

Now type:

tablo -pgs SJ

You should see many messages flash past. If the messages end with

 (Information file is 'C:\temp\SJ.inf'.)
 (The program has completed without error.)
  Total elapsed time is: less than one second.

go straight on to Step 2 below.

If on the other hand you see:

'tablo' is not recognized as an internal or external command,
operable program or batch file.

then the GEMPACK folder is not on your PATH. Please check the steps in section 2.8 and then repeat this part of the testing.

If the messages ended with something like:

  %% Stopping now because of fatal GEMPACK licence problem reported earlier.
  [Search for "%%" in the LOG file to see the earlier message.]
  (ERROR RETURN FROM ROUTINE: TABLO )
  (E-Licence information unavailable.)
  (The program terminated with an error.)

then your GEMPACK folder contains no licence (or the wrong licence). The error message will tell you where TABLO looked for the licence file. Please check that your Release 11 licence file (it must be called LICEN.GEM) is in your GEMPACK directory. If TABLO looks for LICEN.GEM in a directory which is different from the one in which you installed GEMPACK, check the parts of section 2.8 which relate to the Environment variable GPDIR. Repeat this testing once you have remedied any problems.

Step 2: running GEMSIM

Assuming Step 1 (TABLO) worked OK, type

gemsim -cmf sjlb.cmf

You should see many messages flash past, ending with

 (The program has completed without error.)
  Total elapsed time is: less than one second.
 (Output has also been written to log file 'C:\temp\sjlb.log'.)

Congratulations — you have just run a simulation!

If this simulation does not work, start again at section 2.2. If again you have problems, see section 2.5.

If you have the Executable-Image version of GEMPACK, go straight on to section 2.6. If you have the Source-Code version of GEMPACK, you need to do the further tests in the next section.

2.4    [Source-code only] Re-Testing the Installation [gpd6.5s]

This test agains runs a simulation with the small Stylized Johansen model [SJ]. However, while the previous test used GEMSIM (useful whether you have either the Executable-Image or the Source-Code version of GEMPACK), the next test uses a Tablo-generated program (SJ.EXE) to run the simulation. You need the Source-Code version of GEMPACK to create Tablo-generated programs.

Again use the DOS box in your test folder, as described previously.

Step 1: running TABLO

In that DOS box, type in the command

tablo -wfp SJ

You should see messages flash past, ending with

  Successful completion of TABLO.
  The program is
    'sj.for'.
  This program
      o can create the Equations file
      o can carry out multi-step simulations
  ************************************************
 (Information file is 'C:\temp\sj.inf'.)
  (The program has completed without error.)
  Total elapsed time is: less than one second.
Step 2: running LTG

Assuming Step 1 (TABLO) worked OK, type

LTG SJ

You should see your Fortran compiler (Intel, GFortran or Lahey) at work, ending with the message:

sj.EXE made successfully

If there is a problem, please check that you have installed Fortran correctly as described in section 2.1.5.

Step 3: running a simulation with SJ.EXE

Assuming Step 2 (LTG) worked OK, type

SJ -cmf sjlb.cmf

You should see many messages flash past. If the message ends with:

 (The program has completed without error.)
  Total elapsed time is: less than one second.
 (Output has also been written to log file 'C:\temp\sjlb.log'.)

the test was successful and you should go on to section 2.6.

2.5    If you still have problems [witsend]

If, after re-checking all steps on the install procedure, you still have problems, please run ViewHAR and select

Help | About ViewHAR/Diagnostics | Diagnostics

Save this information in a file, and email it to support@gempack.com. Be sure to describe just when and how the problem appeared.

2.6    More simulations to test GEMPACK and WinGEM [gpd6.5.3]

After you have installed GEMPACK correctly, you will want to start using it! If you are new to GEMPACK, we recommend that you work through the introductory Chapters 3and 4 of the main GEMPACK manual.

To test that GEMPACK and WinGEM are working correctly, we suggest that you carry out the simulations with Stylized Johansen in section 3.4. If you have source-code GEMPACK, run the simulations using a TABLO-generated program as described in section 3.5.2. If you have Executable-Image GEMPACK, use GEMSIM as described in section 3.5.3. In either case, check that the results of the simulation are as expected (see, for example, section 3.7).

If any of these tests does not work, re-check the installation steps described above.

2.7    Working with GEMPACK [gpd6.6]

The following sections contain other information relevant to working with GEMPACK.

2.7.1    New model's directory location [gpd6.6.2]

We suggest that you put each new model you build in a separate directory on the hard disk, outside of the GEMPACK directory (usually C:\GP). Your PATH setting should ensure that the GEMPACK programs are found correctly. Conversely if your PATH and GPDIR are not set correctly, the GEMPACK programs will not run.

When you use WinGEM with any model, make sure that you set WinGEM's working directory to point to the directory containing the files for this model (as spelled out in section 3.4.2).

2.7.2    [Source-code only] GEMSIM or TABLO-generated programs ? [gpd6.6.3]

Both source-code and executable versions of GEMPACK allow you to use the program GEMSIM to run TABLO programs which solve your model or perform other tasks. There are 2 stages:

The source-code version of GEMPACK offers the alternate 3-stage approach of:

Compared to GEMSIM, the TABLO-generated programs [EXE files] run faster with models that have a large database (some CPU times are reported in Chapter 73). However, the additional LTG stage can take some time — this is roughly proportional to the size of the TAB file. If you are going to run the EXE a number of times1, and if your model has a large database, you will soon recoup the time spent doing LTG. But if you are:

you may well find the simpler GEMSIM approach to be quicker.

2.7.3    Text editor [gpd6.6.4]

When installing and using GEMPACK, you will need to be able to edit text files. This is best done using a text editor (that is, an editor designed especially for handling text files).

We recommend that you use GEMPACK's text editor: TABmate. TABmate has syntax highlighting which is helpful if you are writing or debugging TABLO Input files. TABmate can also be used for other text files, can open several files at the same time and has various Tools which are useful for GEMPACK development.

Other text editors include NotePad (which is supplied with Windows), the older GEMPACK text editor GemEdit, and VIM and EMACS (which each have their devoted followers). If you use a word processor (such as Microsoft Word) to edit text files, be careful to save the resulting file as a text file.

2.7.4    If you installed in a new directory (not C:\GP) [gpd6.4.3]

If you did NOT install GEMPACK in C:\GP, you may need to help some Windows programs to find and use GEMPACK programs. For example, in RunDynam, click on the Options menu and use menu items such as Which ViewSOL to use to tell the program which versions of ViewSOL, ViewHAR and AnalyseGE to use. In RunGTAP, Click on Tools..Options and then use the various Change buttons to tell RunGTAP where to find Gemsim, ViewHAR, ViewSOL, TABmate, AnalyseGE, Tablo etc.

2.7.5    If a program runs out of memory [gpd6.6.5]

GEMPACK programs may require more memory than is available on your computer. If so you will receive a message saying that the program is stopping because it is unable to allocate sufficient memory. Often this error occurs because you have forgotten to condense your model, or have not condensed it enough (see chapter 14).

Other possible remedies include:

2.7.6    Copying GEMPACK programs to other PCs [gpd6.6.9]

If you have a GEMPACK site licence, you are entitled to copy GEMPACK programs to PCs covered by your site licence, for example, within the same department or institute.

You should note that the GEMPACK programs TABLO and GEMSIM require a GEMPACK licence. Accordingly, under the terms of your GEMPACK licence, you must not copy (or send copies of) executable images of these to machines outside the site which is covered by your GEMPACK licence. Of course you must not send a copy of your GEMPACK licence outside the site covered by your licence.

An individual GEMPACK licence entitles you to copy TABLO, GEMSIM and your GEMPACK licence only to other PCs used by you.

You are allowed to send copies of the other GEMPACK programs, including your TABLO-generated programs, outside of the site covered by your GEMPACK licence. However, you should note that both TABLO-generated programs and SAGEM.EXE may require an Introductory licence if they are used with a larger model. The model size limits are set out in Chapter 62.

Versions of TABLO and GEMSIM programs must match exactly. Hence, do not send GSS/GST files generated by TABLO to others -- the GSS/GST files would only work if used with the right GEMSIM version (that matched your TABLO). Rather send only the TAB file — then the recipient can use their matching TABLO and GEMSIM programs.

2.8    Manually setting the PATH and GPDIR [gpd6.4.2]

For GEMPACK to run, you must make sure that the GEMPACK directory (usually C:\GP) is on your PATH, and that the Environment variable GPDIR is set to the GEMPACK directory.

If you did not allow the installer to make changes to your PATH and the Environment variable GPDIR (see section 2.2), you must make the required changes yourself, as described next.

2.8.1    Checking and setting PATH and GPDIR [gpd6.4.2.1]

The usual method to change the PATH and set the Environment variable GPDIR is by editing the System Properties. The important changes are that

You will need administrator access to make these changes. Follow the steps below to check that the installer made these changes, or to make them yourself:

  1. For users of Windows 7 or later, if you are not using an administrator level account you will be prompted for an administrator password during this procedure [Windows XP users must be using an administrator level account when beginning this procedure]. Right click on My Computer (Windows XP) or Computer (later Windows versions). From the right click menu select Properties then click on the Advanced tab. This brings up the System Properties dialogue window, click on Environment Variables to bring up the Environment Variables dialogue window. Notice that the top half of the window contains user variables, the bottom contains system variables.
  2. Edit the system Path variable and add the GEMPACK directory, noting the following. Entries must be separated by a semicolon ";". New entries may be added between any existing entries, however we recommend adding to the beginning of the Path. For example, suppose your GEMPACK directory is C:\GP, then the system path should look like C:\GP;C:\mingw-w64;%SystemRoot%... . If you have a previous GEMPACK directory on the Path delete it and add the new GEMPACK directory to the beginning of the system Path.
  3. Add a new (or edit the existing) system environment variable GPDIR to have value set to the GEMPACK directory. This must be the same directory you added to the beginning of the system Path in the previous step.
  4. Click on the Ok button to accept these changes to the Environment.

These changes will take effect when you next start a program or open a new DOS box. Test these changes by opening a new DOS box and entering "SET". This should show the altered path and the environment variable GPDIR. If you don't see the changes you expect got to the environment trouble-shooting section and work through the points in the next section 2.8.2.

2.8.2    Trouble-shooting environment variables [envvartrouble]

If you have made changes to the system Path or variable GPDIR which have had the effect you expected, please try the following:

2.9    Technical Topics [gpd6.7]

In this section we discuss various technical topics. We expect that most GEMPACK users can happily ignore these.

2.9.1    [Source-code only] Running BuildGP [gpd6.7.3]

The program BuildGP is designed to carry out the following tasks:

  1. Check your system to see: if Fortran is installed, if there is enough disk space, whether the licence is in the correct place, and if the PATH and GPDIR environment variables are correctly set.
  2. Make the GEMPACK libraries by compiling many groups of subroutines.
  3. Make the Fortran-based GEMPACK programs (executable images) by compiling the programs and linking to the libraries.

Usually BuildGP does all these automatically when you install GEMPACK. However, there may be situations when you need to run BuildGP yourself. For example, if you discovered a GEMPACK bug, you might be sent a patch file to repair the problem. Detailed instructions would come with the patch file. We provide only brief notes here.

Run the program BUILDGP.EXE in the GEMPACK directory from the command prompt or from My Computer or Windows Explorer.

Check that BuildGP correctly displays your GEMPACK directory and compiler (GFortran or LF95 or Intel).

Now click on the Start build button.

If you installed GEMPACK successfully with one compiler (say, LF95), and you later wished to use another compiler (say, Intel), you need to install from the CD again. It is not enough to merely re-run BuildGP. The installer copies compiler-specific files from the CD. If you want to repeatedly switch between compilers, see the notes at http://www.copsmodels.com/gpmultifort.htm.

2.9.2    [Source-code only] Compiling individual GEMPACK programs [gpd6.7.2.2]

With Source-code GEMPACK, the executable images (EXE files) for most command-line GEMPACK programs are made during the BuildGP phase of the installation. However you may occasionally wish to remake just one of these programs.

From the command line, change to the directory where you installed the GEMPACK programs (usually C:\GP):

cd /d c:\gp

Then to make a main program for example ACCUM, enter the command

mkmain accum

This command mkmain works with all the main programs except GEMSIM and TABLO, where the appropriate commands are mkgemsim and mktablo.

2.9.3    File association [gpd6.6.7]

"File association" is the Windows mechanism due to which (for example):

These happen because files suffixed HAR are "associated" with ViewHAR.exe. Usually the "association" is set up at install time. Only one program can be associated with each file type . so programs might compete to possess more popular suffixes. To stop such contests, Windows may prevent a program from changing an existing association. This may mean, for example, that the GEMPACK installer cannot associate TABmate with TAB files (because Microsoft wants the TAB suffix for Visual Studio). In such cases, you must set up the association manually. You can change the HAR file association as follows:

2.9.4    Keep and Temporary directories and GEMPACK Windows programs [gpd6.6.8]

Programs often need to have folders to store user configuration choices, or to write temporary files. Windows provides default folders for these purposes.

GEMPACK Windows programs store user configuration choices in INI files which are (by default) located below a folder chosen by Windows. We call that folder the "Keep" folder. For example, for user "John", the INI file for TABmate might be located at:

C:\Users\John\My Documents\GPKEEP\TABmate\TABmate.ini

Similarly GEMPACK Windows programs by default write temporary files in a subdirectory of the temporary folder provided by Windows2.

For very unusual cases, GEMPACK gives a way to avoid problems with the Keep and the default Temporary directories by setting environment variables called GPKEEP and GPTEMP. Set a new environment variable called GPKEEP if you want to change the usual Keep Directory. Set a new environment variable called GPTEMP if you want to change the default temporary directory without changing the environment variable TMP.

In RunGEM, WinGEM, AnalyseGE and RunDynam there are Menu Options within the programs which allow you to set your Temporary directory to a directory of your choosing. The program remembers this Temporary directory setting. When you start the programs for the first time, the default temporary directory is set from the value of the TMP or TEMP environment variable.

If you are having problems with these features of one of the GEMPACK Windows programs, consult the relevant Help file for details and advice.

2.9.5    Installing GEMPACK on a network [gpd6.8]

Some organisations have found it desirable to run the Source-code Version of GEMPACK and the associated Fortran compiler from a network. For example, this can reduce the need for separate copies of the compiler.

Below are some pointers to using GEMPACK and/or Fortran on a network.

2.9.6    Uninstalling GEMPACK [gpd6.7.6]

To uninstall GEMPACK from your computer, use the standard Add/Remove Programs method. If that fails you could simply:

2.9.7    Finding GEMPACK Version and Release Information [identver]

Especially when troubleshooting, it may be useful to check which version of GEMPACK (or of a particular GEMPACK program) you are using. You may wish to know the:

Most GEMPACK Windows programs (like ViewHAR and TABmate) give two methods to gather the information above.

First, the GEMPACK Licence command (usually under the Help Menu) shows:

Figure 2.1 GEMPACK licence command

Second, the About/Diagnostics command (also usually under the Help Menu) shows:

Figure 2.2 About/diagnostics

Program Version and GEMPACK Release Information for Command-line or Fortran-based GEMPACK programs is contained in the first 4 or 5 lines of the log file (if there is one) or in the first 4 or 5 lines of screen output when you run that program from the command-line. Usually this information has scrolled off the top of the Command prompt window before you have time to read it. You may need to scroll back to see it. Or, to capture the output to a file, type:

sltoht <nul: >temp.log

and then examine the top of file temp.log. You might see:

 <SLTOHT   Version 5.52  January 2011>
   This program accesses some of the routines in the GEMPACK software release
 <GEMPACK Release 11.1.200   May 2012>

In ViewHAR the History command will show you Program Version and GEMPACK Release Information about the program that created a HAR file — see section 49.1.2. The same information is echoed to the log whenever a Command-line GEMPACK program reads a HAR file.

3    How to carry out simulations with models [gpd1.2]

Click here for detailed chapter contents

This chapter is where we expect new users of GEMPACK to start learning about simulations. We describe how simulations are carried out, and explain some of the terms used in GEMPACK, such as: implementation, simulation, levels and percentage-change variables.

In section 3.1, there is a very brief overview of the Stylized Johansen model and the simulation that you will carry out. The rest of this chapter consists of detailed instructions for carrying out the simulations and interpreting their results.

We encourage you to work through this whole chapter before starting to work with GEMPACK on your own model. At the end of this chapter we suggest different directions you may wish to go in.

Implementation

A model is implemented in GEMPACK when

For most GEMPACK models, the equations are written down in a linearized form, usually expressed in terms of percentage changes in the variables. But you can choose instead to write down the original (or "levels") equations. In either case you need to write them down in a text file which we call a TABLO Input file or TAB file, since TABLO is the name of the GEMPACK program which processes this information.

The procedure for implementing models is described in detail in chapter 4.

Simulation

Once a model is implemented, the model can be used to carry out simulations. Many simulations are the answer to "What if" questions such as "If the government were to increase tariffs by 10 percent, how much different would the economy be in 5 years time from what it would otherwise have been?". From the original solution supplied as the starting point, a simulation calculates a new solution to the equations of the model. GEMPACK usually reports the results of a simulation as percentage changes from the original solution. Levels results may also be available.

Solving models

within GEMPACK is always done in the context of a simulation. You specify the values of certain of the variables (the exogenous ones) and the software calculates the values of the remaining variables (the endogenous ones).

The new values of the exogenous variables are usually given by specifying the percentage changes (increases or decreases) from their values in the original solution.

Levels and Percentage-Change Variables

When the model is implemented, the equations may be linearized (that is, differentiated). The variables in these linearized equations are usually interpreted as percentage changes in the original variables. The original variables (prices, quantities etc) are referred to as the levels variables and the (usually nonlinear) equations relating these levels variables are called the levels equations.

For example, the levels equation

V = P Q

relates the dollar value V of a commodity to its price P ($ per ton) and its quantity Q (tons). The linearized version of this is

p_V = p_P + p_Q

(as explained later in chapter 4 below) which says that, to first order, the percentage change p_V in the dollar value is equal to the sum of the percentage changes p_P in the price and p_Q in the quantity.

Data

The data for a model often consists of input-output data (giving dollar values) and parameters (including elasticities). The data given are usually sufficient to read off an initial solution to the levels equations. (Usually all basic prices are taken as 1 in the initial solution.)

3.1    An example simulation with stylized Johansen [gpd1.2.1]

In this chapter we show you how to carry out simulations with an existing model (that is, one built by someone else). We use as an example the Stylized Johansen model described in Chapter 3 of Dixon et al (1992), hereafter referred to as DPPW. The model equations are listed in table 4.1 in section 4.1.

The Stylized Johansen model is chosen because it is simple. Once you know how to carry out simulations with it in GEMPACK, you will find it easy to carry out simulations with other, more complicated models (including ones you build yourself).

3.1.1    Introduction to the stylized Johansen model [gpd1.2.1.1]

The Stylized Johansen model is a very simple model of a single country. It recognises two sectors "s1" and "s2" each producing a single commodity, one final demander (households) and two primary factors (labor and capital). There are no exports or imports. Output of each sector is a Cobb-Douglas aggregate of labor, capital, and intermediate inputs. Household demands are also Cobb-Douglas.

The initial input-output data base is shown below in Table 3.1. For example, households consume 4 (million) dollars' worth of commodity 2 and industry 2 uses 3 (million) dollars' worth of labor. Note that the first two row totals (value of sales each of good) equal the first two column totals (costs of each sector).

Table 3.1 Input-output data base for Stylized Johansen
Demanders:Industry 1Industry 2HouseholdsTotal Sales
Inputs
Commodity14.02.02.08.0
Commodity22.06.04.012.0
Labor31.03.04.0
Capital41.01.02.0
Total Production8.012.06.0

In the GEMPACK implementation, the levels variables are as in Table 3.2 below.

Table 3.2 Levels variables of Stylized Johansen
GEMPACK variableMeaningDPPWNotation
YValue of household incomeY
PC(i)Price of commodity iPi(i=1,2)
PF(f)Price of factor fPf(f=3,4)
XCOM(i)Supply of commodity iXi(i=1,2)
XFAC(f)Supply of factor fXf(f=3,4)
XH(i)Household use of commodity iXi0(i=1,2)
XC(i,j)Intermediate input of commodity i to industry jXij(i,j=1,2)
XF(f,j)Input of factor f to industry jXfj(f=3,4;j=1,2)
DVCOMIN(i,j)Dollar values for intermediate inputs(i,j=1,2)
DVFACIN(f,j)Dollar values for factor use by industry(f=3,4;j=1,2)
DVHOUS(i)Dollar values for household consumption(i=1,2)

Note that most of the variables have one or more arguments (indicating associated sectors and/or factors). We refer to such variables as vector or matrix variables. For example, PC(i) is a vector variable with 2 components, one for each sector, namely PC("s1") and PC("s2"). XF(f,j) is a matrix variable with the following 4 components:

component 1 XF("labor","s1")input of labor (factor 1) to sector 1
component 2 XF("capital","s1")input of capital (factor 2) to sector 1
component 3 XF("labor","s2")input of labor (factor 1) to sector 2
component 4 XF("capital","s2")input of capital (factor 2) to sector 2

Variables which have no arguments ('Y' is the only one here) are referred to as scalar or macro variables.

Corresponding to each levels variables, there is an associated percentage change variable. TABLO adds the prefix "p_" to the name of the levels variable to indicate a percentage change. For example, p_XF is the percentage change in the levels variable XF. In DPPW, lower case letters are used to denote percentage-change variables.

More details about the model are given in chapter 4. A full TABLO Input file can be found in section 4.3.3.

3.1.2    The simulation [gpd1.2.1.2]

In the example simulation with the Stylized Johansen model used throughout most of this chapter, we choose a closure in which supplies of the two factors, labor and capital, are the exogenous variables. This means we will specify the percentage changes in the variable XFAC, namely p_XFAC, and solve the model to find the percentage changes in all the other variables. You will also be able to see the levels results (for example, the post-simulation value of household income).

For this simulation, we increase the supply of labor by 10 per cent and hold the supply of capital fixed.

The starting points for any simulation with the Stylized Johansen model are

3.2    Preparing a directory for model SJ [gpd1.2.4.2]

We assume that you have already installed GEMPACK correctly as described in chapter 2.

To keep all example files for the Stylized Johansen model together in one area, you should first create a separate directory (folder) for these files and copy the relevant files into this directory.

Use Windows Explorer (or My Computer) to create a new folder or subdirectory called \sj and copy all the sj*.* files from the directory containing the GEMPACK model examples (usually C:\GP\EXAMPLES) to this directory \sj.

3.3    Using GEMPACK: WinGEM or command prompt? [gpd1.2.3]

There are two ways of operating GEMPACK:

We describe both methods, but suggest that you first work through this chapter using the WinGEM method — then, if you wish, repeat the exercise using the Command prompt instructions which are shown like this:

Command-prompt users should read (but not do) the WinGEM instructions, then should execute the corresponding DOS commands, which will be shown just after the WinGEM instructions.

3.4    Stylized Johansen example simulation [gpd1.2.4]

3.4.1    Starting WinGEM [gpd1.2.4.1]

In Windows, double-click on the WinGEM icon to start GEMPACK for Windows. The main WinGEM menu should appear, as a ribbon menu across the top of the screen:

WinGEM  -  GEMPACK for Windows
File   Simulation   HA Files   Other tasks   Programs   Options   Window   Help

3.4.2    Setting the working directory [gpd1.2.4.3]

WinGEM uses the idea of a working directory to simplify choosing files and running programs. This working directory is where all the files for the model you are using are stored.

For the Stylized Johansen model examples here, the working directory needs to be the directory \SJ you have just created. To set this, first click on File in the main WinGEM menu. This will produce a drop-down menu. In the drop-down menu, click on the menu item Change both default directories.

The notation we use for this sequence of clicks (first File then Change both default directories) is

File | Change both default directories.

In the file selection box that appears, choose drive C: (or the drive containing your directory \SJ if it is on a different drive). Then double-click on C:\ (this will be at the top of the list of directories shown) and then double-click on the subdirectory SJ. [Make sure that the directory name shown in blue above the selection box changes to C:\SJ (or D:\SJ etc if your \SJ directory is on another drive).] Click on the Ok button.

Command-prompt users should open a DOS box in the C:\sj directory.1

3.4.3    Looking at the data directly using ViewHAR [gpd1.2.4.4]

The input-output data used in the Stylized Johansen model are contained in the data file SJ.HAR. This is a special GEMPACK binary file - called a Header Array file - so you cannot just look at it in a text editor. Instead you will look at SJ.HAR using the ViewHAR program. Select from the main WinGEM menu: HA Files | View VIEWHAR

The ViewHAR window will appear. Click on File | Open and select the file SJ.HAR. This will open the file SJ.HAR and show its contents on the Contents screen.

Command-prompt users can open SJ.HAR by typing "viewhar SJ.HAR" into the DOS box.

Each row of the ViewHAR Contents screen corresponds to a different array of data on the file. Look at the "Name" column to see what data are in these arrays.

HeaderTypeSizeName
1CINPRESECTxSECTIntermediate inputs of commodities to ind.
2FINPRESECTxFACTIntermediate inputs of primary factors - dollar
3HCONRESECTHousehold use of commodities - dollar values

The first array is the "Intermediate inputs of commodities to industries - dollar values". The Header CINP is just a label for this array (headers can have up to 4 characters). The array is of Type RE — an array of real numbers with set and element labelling (see chapter 5.0.3).

Double-click on CINP to see the numbers in this array.

DVCOMINs1s2Total
s14.002.006.00
s22.006.008.00
Total6.008.0014.00

Compare these numbers with the input-output data for Stylized Johansen shown in Table 3.1. The actual data in the file at this header is just the 2x2 matrix. ViewHAR calculates and shows the row and column totals.

To return to the Contents Screen, click on Contents in the ViewHAR menu, or click twice on any number.

Look at the other Header Arrays called FINP and HCON to see where their numbers fit in the input-output data base.

Close ViewHAR by selecting File | Exit.

3.5    Implementing and running model SJ [gpd1.impsj]

There are three steps involved in carrying out a simulation using GEMPACK.

Step 1 - Implement the model (using TABLO)

Step 2 - Solve the equations of the model (ie, run a simulation)

Step 3 - View the results

3.5.1    TABLO-generated program or GEMSIM? [gpd1.2.4.5]

The details of steps 1 and 2 vary according to whether you have the Executable-image or the Source-code version of GEMPACK. With either version, you can use GEMSIM to run simulations. The Source-code version also allows you to create a model-specific, TABLO-generated, EXE file, which you can run to solve the model. Especially for larger models, the TABLO-generated program will usually solve quicker.

The Source-code method is described next. If you have the Executable-image version of GEMPACK, you will need to skip onto the GEMSIM instructions in section 3.5.3.

3.5.2    Source-code method: using a TABLO-generated program [gpd1.2.4.6]

In the next examples we are assuming that you have the Source-code version of GEMPACK and have a Fortran compiler on your DOS PATH.

From the WinGEM menu at the top of the screen choose Simulation. In the drop-down menu the choices are

TABLO Implement
Compile & Link
TABmate Implement
-------------------
Run TG Program
GEMSIM Solve
SAGEM Johansen Solve
---------------------
View Solution (ViewSOL)
AnalyseGE
GEMPIE Print Solution

The items from this menu you will be using in this simulation are

TABLO Implement
Compile & Link
Run TG Program
View Solution (ViewSOL)
.

In the TABLO-generated program method, the GEMPACK program TABLO is used to convert the algebraic equations of the economic model into a Fortran program (.FOR file) specific to your model. This Fortran program (which is referred to as the TABLO-generated program or TG Program in the above menu) is compiled and linked to a library of GEMPACK subroutines. The EXE file of the TABLO-generated program produced by the compiler is used to run simulations (instead of using the program GEMSIM). This method provides faster execution times for large models than the GEMSIM alternative but means you must have an appropriate Fortran compiler.

WinGEM will guide you through the various steps and indicate what to do next.

Step 1 - Implementing the model SJ using TABLO

Step 1(a) - Run TABLO to create the TABLO-generated program

The TABLO Input file is called SJ.TAB. It contains the theory of the Stylized Johansen model. Choose

Simulation | TABLO Implement

A window for TABLO will appear. Click on the Select button to select the name of the TABLO Input file SJ.TAB2. This is all TABLO needs to implement this model. 3

At top right of the TABLO window are choice buttons for FORTRAN and GEMSIM.

Check that the first, FORTRAN, option is selected (we want you to create the TABLO-generated Fortran program).

Click on the Run button. The program runs TABLO in a DOS box and when complete, returns you to the TABLO window with the names of files it has created: the Information file SJ.INF and the Log file. Look at both of these files by clicking the View buttons beside them.

The Information file SJ.INF gives information about the TABLO Input file such as whether there are any syntax or semantic errors during checking by TABLO. Search the file for %% to see if there are any errors. Search the file for "syntax error" to see how many syntax errors and semantic problems there are (hopefully none). Go to the end of the file to see what actions can be carried out by the TABLO-generated program produced in this TABLO run.

Command-prompt users can perform Step 1(a) by typing "tablo -wfp sj -log sj.log". To see LOG or INF files, type "tabmate SJ.INF" or "tabmate SJ.LOG".

Step 1(b) - Compile and Link the TABLO-generated Program

When you have looked at these two files, click on the Go to Compile and Link button at the bottom of the TABLO window to run the Fortran compiler. (Alternatively you can start this window by choosing Simulation | Compile and Link... from WinGEM's main menu.)

In the Compile and Link window, the file SJ.FOR is already selected as the TG Program Name. Click on the button Compile and Link and wait a little while the compiler converts the Fortran file SJ.FOR into the SJ.EXE program that you can run.

When finished, click on the button Go to 'Run TG Program' to proceed to the next step in running a simulation.

Command-prompt users can perform Step 1(b) by typing "LTG sj". Type "dir sj.exe" to check that file SJ.EXE has been produced.

Step 2 - Solve the equations of the model using TABLO-generated program

The Go to 'Run TG Program' button takes you to the window for running the TABLO-generated program SJ.EXE. (Alternatively you can start this window by choosing Simulation | Run TG Program... from WinGEM's main menu.)

First Select the Command file called SJLB.CMF. Since Command files are text files, look at this Command file in the text editor by clicking the Edit button.

How is the closure specified? What shock is applied?

What data file is used by this model? How many steps are used in the multi-step solution?

Details about using a GEMPACK Command file to specify a simulation are given in section 3.8 below. For the present, we suggest that you take this on trust and continue with the simulation.

Select File | Exit to close the editor and return to the "Run TG Program" window.

Click on Run to run SJ.EXE with the Command file SJLB.CMF.

When SJ.EXE finishes running, an accuracy summary window will pop up. This gives a graphical view as to how accurately the equations have been solved4. You can ignore this for the present (it is discussed in section 3.12.3) so click OK.

If SJ.EXE produces the Solution file, click on Go to ViewSOL5.

If there is an error, view the Log file.

Command-prompt users can examine the Command file SJLB.CMF by typing "TABmate SJLB.CMF". Run the simulation by typing "sj -cmf SJLB.CMF". Then, to see the results, type "ViewSOL SJLB.SL4".

Now please skip the next (GEMSIM) section and go on to the ViewSOL instructions in 3.5.4.

3.5.3    Executable-image method: using GEMSIM [gpd1.2.4.7]

In the WinGEM menu at the top of the screen choose Simulation. In the drop-down menu the choices are6.

TABLO Implement
Compile & Link
TABmate Implement
-------------------
Run TG Program
GEMSIM Solve
SAGEM Johansen Solve
---------------------
View Solution (ViewSOL)
AnalyseGE
GEMPIE Print Solution

The items from this menu you will be using in this simulation are

TABLO Implement
GEMSIM Solve
View Solution (ViewSOL).

WinGEM will guide you through the various steps and indicate what to do next.

Step 1 - Implementing the model SJ using TABLO (for GEMSIM output)

The TABLO Input file is called SJ.TAB. It contains the theory of the Stylized Johansen model. Choose Simulation | TABLO Implement...

A window for TABLO will appear. Click on the Select button to select the name of the TABLO Input file SJ.TAB7. This is all TABLO needs to implement this model 8.

At top right of the TABLO window are choice buttons for FORTRAN and GEMSIM.

Check that the second, GEMSIM, option is selected (we want you to create the GEMSIM Auxiliary files).

By "implement" we mean convert the TABLO Input file into binary computer files which are used by the simulation program GEMSIM in the next step. These files are referred to as Auxiliary files (or sometimes as the GEMSIM Statement and Table files) and in this case, are called SJ.GSS and SJ.GST.

Click on the Run button. The program TABLO runs in a DOS box and when complete returns you to the TABLO window with the names of files it has created: the Information file SJ.INF and the Log file. Look at both of these files by clicking the View buttons beside them. To close the file, click on the X in the top right-hand corner of the view, or click File..Exit using the File menu.

The Information file SJ.INF gives information about the TABLO Input file such as whether there are any syntax or semantic errors found during checking by TABLO. Search the file for %% to see if there are any errors. Search the file for "syntax error" to see how many syntax errors and semantic problems there are (hopefully none). Go to the end of the file to see what actions GEMSIM can carry out with the Auxiliary files produced in this TABLO run.

When you have looked at these two files, click on the Go to GEMSIM button at the bottom of the TABLO window to go on to the next step in running a simulation:

Command-prompt users can perform Step 1 by typing "tablo -pgs sj -log sj.log". To see LOG or INF files, type "tabmate SJ.INF" or "tabmate SJ.LOG".

Step 2 - Solve the equations of the model using GEMSIM

The Go To GEMSIM button takes you to the GEMSIM window. (Alternatively you can start this window by choosing Simulation | GEMSIM Solve from WinGEM's main menu.)

First Select the Command file called SJLB.CMF. Since Command files are text files, look at this Command file in the text editor by clicking the Edit button.

How is the closure specified? What shock is applied?

What data file is used by this model? How many steps are used in the multi-step solution?

Details about using a GEMPACK Command file to specify a simulation are given in section 3.8 below. For the present, we suggest that you take this on trust and continue with the simulation.

Select File | Exit to close the editor and return to the GEMSIM window.

Click on Run to run GEMSIM with the Command file SJLB.CMF.

When GEMSIM finishes running, an accuracy summary window will pop up. This gives a graphical view as to how accurately the equations have been solved9. You can ignore this for the present (it is discussed in section 3.12.3) so click OK.

If GEMSIM produces the Solution file, click on Go to ViewSOL10.

If there is an error, view the Log file.

Command-prompt users can examine the Command file SJLB.CMF by typing "TABmate SJLB.CMF". Run the simulation by typing "sj -cmf SJLB.CMF". Then, to see the results, type "ViewSOL SJLB.SL4".

3.5.4    Step 3 - View the Solution using ViewSOL [gpd1.2.viewsol]

You cannot view the Solution file SJLB.SL4 in a text editor because it is a binary file, not a text file. Instead we use ViewSOL to examine the Solution file.

In WinGEM, the Go to ViewSOL button starts the program ViewSOL running and opens the Solution file SJLB.SL4 . [Alternatively you can start this window by choosing Simulation | View Solution (ViewSOL) from WinGEM's main menu.]

Command-prompt users should type "ViewSOL SJLB.SL4".

You will see the Contents page listing many of the variables of the model. ViewSOL has 3 slightly different formats for this Contents list. Select Format... from ViewSOL's main menu and there click on Arrange vectors by name (in the panel headed Vector options); then click Ok which will put you back to the Contents list.

To see the results of one of these variables listed by name, just double-click on the corresponding row in the Contents list. First double-click on the p_XCOM row to see the results for this variable (demand for the two commodities). Select 3 decimal places (see the third drop-down list box along the top row of the current ViewSOL window - the only one with a single figure in it). Then you should see something like the following:

p_XCOMsjlbPre sjlbPost sjlbCh/%Ch sjlb
s15.8858.0008.4710.471
s26.89912.00012.8280.828

Across the s1 row you see the percentage change result (5.885%), the pre-simulation levels value (8.000), the post-simulation levels value (8.471) and the change (0.471); these are the results for the total supply of commodity s1.

Then click on Contents to return to the Contents list.

To see the p_XFAC results, double-click on this row. You will see

p_XFACsjlbPre sjlbPost sjlbCh/%Ch sjlb
labor10.0004.0004.4000.400
capital02.0002.0000

This time all the numbers are in red which is used to remind you that, for this simulation, both components of this variable p_XFAC are exogenous. You should easily be able to understand all of these results.

Then click on Contents to return to the Contents list (or click twice on any number).

To see the p_XC(i,j) results [intermediate inputs of commodity i into industry j], double-click on this row. Now you see

p_XCs1s2
s15.8855.885
s26.8996.899

and, in the second drop-down box you should see "1 sjlb". This indicates that you are just seeing the linearized simulation results (the percentage changes in the four components of this variable). You can't see the pre- and post-simulation levels results at the same time since this variable p_XC is a matrix variable. To see the pre-simulation levels results, click on the second drop-down list box (the one showing "1 sjlb") and select the second alternative ("2 Pre sjlb"). Then you will see the pre-simulation levels results. You might also like to look at the post-simulation levels results and the changes.

Then click on Contents to return to the Contents list.

When you have finished looking at the results, exit from ViewSOL.

3.6    The steps in carrying out a simulation [gpd1.2.5]

This section recapitulates the steps (that you just followed) to implement a model and carry out a simulation.

In all cases, after the TABLO Input file for a model has been written, there are 3 steps on the computer to carry out a first simulation with the model. These steps are:

Step 1 - Implement the model

Step 2 - Simulation (Solve the equations of the model)

Step 3 - View the results with ViewSOL or perhaps AnalyseGE.

Step 1 always involves running the program TABLO.

The details of Steps 1 and 2 are a little different depending on whether you have a Source-code or Executable-image version of GEMPACK, as we explain below.

Next we describe the Source-code procedure. The Executable-image version of steps 1 and 2 is described in section 3.6.2.

3.6.1    Steps 1 and 2 using a TABLO-generated program (source-code GEMPACK) [gpd1.2.5.1]

The steps are illustrated in Figure 3.1 below.

Figure 3.1 The steps in carrying out a simulation using a TABLO-generated program
steps in carrying out a simulation using a tablo-generated program
Step 1. Computer Implementation of the Model

Step 1(a) - Run TABLO to create TABLO-generated program

Process the TABLO Input file for the model by running the program TABLO. Select the option WFP which tells TABLO to write a Fortran program (referred to as the TABLO-generated program of the model) which captures the theory of the model.

Step 1(b) - Compile and Link the TABLO-generated program [LTG]

Compile and link the TABLO-generated program of the model, produced in Step 1(a). This will produce an EXE file of the TABLO-generated program11.

Step 2. Simulation (Solve the equations of the model)

Run the EXE file of the TABLO-generated program, as produced in Step 1(b). Take inputs from a Command file which tells the program which base data files are to be read and describes the closure (that is, which variables are exogenous and which are endogenous) and the shocks. This program then computes the solution to your simulation and writes the results to a Solution file

Step 3. Printing or Viewing the Results of the Simulation

The last step is to view simulation results with ViewSOL or AnalyseGE12. An alternative is to use the program SLTOHT to process results (for example, to produce tables for reports), as introduced in section 3.10 below.

3.6.2    Steps 1 and 2 using GEMSIM [gpd1.2.5.2]

The steps using GEMSIM are illustrated in Figure 3.2.

Figure 3.2 The steps in carrying out a simulation using GEMSIM
steps in carrying out a simulation using gemsim
Step 1. Computer Implementation of the Model

Process the TABLO Input file for the model by running the GEMPACK program TABLO. Select the option PGS which asks TABLO to produce the GEMSIM Auxiliary files for the GEMPACK program GEMSIM (see Step 2). These files capture the theory of the model, as written in the TABLO Input file.

Selecting option PGS rather than the option WFP as in section 3.6.1 above is what initiates the GEMSIM route rather than the TABLO-generated program route.

Step 2. Simulation (Solve the equations of the model)

Run the GEMPACK program GEMSIM13 and tell it to use the GEMSIM Auxiliary (GSS/GST) files produced in Step 1. Take inputs from a Command file which tells the program which base data files are to be read and describes the closure (that is, which variables are exogenous and which are endogenous) and the shocks. GEMSIM then computes the solution to your simulation and writes the results to a Solution file.

Step 3. Printing or Viewing the Results of the Simulation

The last step is to view simulation results with ViewSOL or AnalyseGE14. An alternative is to use the program SLTOHT to process results (for example, to produce tables for reports), as introduced in section 3.10 below.

Comparing the steps in the two cases

Note that Step 1 above is very similar to Step 1(a) in the TABLO-generated program case (see section 3.6.1 above). The LTG step 1(b) in section 3.6.1 has no analogue in the GEMSIM case since GEMSIM is a general-purpose program which can be used to solve any model. Step 2 is different only in that GEMSIM is run rather than the TABLO-generated program. Step 3 is identical in the two cases.

3.6.3    Other Simulations [gpd1.2.5.othsims]

Once you have carried out one simulation with a model, you will probably want to carry out others, for example, to change the closure and/or shocks, or even to run from different base data. In such cases, you do not have to repeat Steps 1(a) and 1(b). All you have to do is carry out Steps 2 and 3. A hands-on example is given in section 3.11 below. (Of course Step 1 must be repeated if you change the TABLO Input file in any way.)

3.7    Interpreting the results [gpd1.2.7]

You have already looked at the results via ViewSOL (see Step 3 in section 3.5.4). From the ViewSOL Contents page you clicked on and examined variables such as Macros, p_XH, p_PC, p_XF, p_DVHOUS. We have copied some of the results from ViewSOL to a spreadsheet (via the Copy menu item in ViewSOL). These are shown in Table 3.3 below.

We think that you will find the tables fairly easy to interpret.

Table 3.3 Results (ViewSOL) from the solution file SJLB.SL4
MacrossjlbPre sjlbPost sjlbChng sjlb
p_Y5.88536.00006.35310.3531
p_XHsjlbPre sjlbPost sjlbChng sjlb
s15.88532.00002.11770.1177
s26.89934.00004.27600.2760
p_PCsjlbPre sjlbPost sjlbChng sjlb
s10.00001.00001.00000.0000
s2-0.94861.00000.9905-0.0095
p_XFs1s2
labor10.000010.0000
capital0.00000.0000
p_DVHOUSsjlbPre sjlbPost sjlbChng sjlb
s15.88532.00002.11770.1177
s25.88534.00004.23540.2354

The results show what happens if the supply of labor is increased by 10 per cent and the supply of capital is held fixed. For example,

Recall that, within GEMPACK, all simulations are set up and solved as perturbations from an initial solution, and results are usually reported as changes or percentage changes from this original solution. In this case the original solution values are as shown in Table 3.2 above, which shows million dollar values of activity. Suitable levels values for quantities can be obtained by assuming that, initially, all prices are 1. (This just sets the units in which quantities are measured.) Then, for example, since households consume 4 million dollars' worth of commodity 2, this means that they consume 4 million units of that commodity.

Hence the three simulation results mentioned above mean that, once labor is increased by 10 per cent and capital is held fixed:

1. Total nominal household expenditure Y has increased to approximately 6.353 million dollars (5.8853 per cent more than the original value of 6 million dollars).

(The other three values given with p_Y in Table 3.3 are

6.0000which is the pre-simulation level of Y,
6.3531which is the post-simulation level of Y and
0.3531the change between these two values.)

2. Household consumption (XH) of commodity 2 has increased to 4.2760 million units (6.8993 per cent more than the original 4 million units).

3. The commodity price (PC) of commodity 2 has fallen from one dollar per unit to approximately 99.051 cents per unit (a fall of 0.9486 per cent).

4. The dollar value of household consumption (DVHOUS) of the commodity produced by sector "s2" has risen from 4 million dollars to approximately 4.2354 million dollars (an increase of 5.8853 per cent).

The updated values in (2), (3) and (4) above should be related since dollar value should equal price times quantity. The levels equation for commodity 2 ("s2") is

DVHOUS("s2") = PC("s2) x XH("s2")

Note that this equation is true for the post-simulation values, since, from (2) and (3) above, the post-simulation price times the post-simulation quantity is

0.99051 x 4.2760 = 4.2354

which is equal to the post-simulation dollar value in (4). This confirms that the solution shown in ViewSOL satisfies the levels equation connecting price, quantity and dollar value of household consumption of this commodity. You might like to check some of the other levels equations in this way.

3.8    Specifying a simulation [gpd1.2.8]

In order to specify the details for carrying out a simulation, you must

Figure 3.3 The information required to specify a simulation
the information required to specify a simulation

Within GEMPACK, the normal way of specifying this information to the software is via a Command (CMF) file. Indeed, when you carried out the example simulation above, this is exactly what happened in Step 2 above since there you ran either the TABLO-generated program or GEMSIM and took inputs from the Command file SJLB.CMF.

The instructions in this Command file must be prepared in advance in a text editor.

The next section explains the statements in this GEMPACK Command file SJLB.CMF.

3.8.1    Specifying a simulation via a GEMPACK command file [gpd1.2.8.1]

In Step 2 of the example simulation, the program took all the information required to specify the simulation from the GEMPACK Command file SJLB.CMF. The file SJLB.CMF is shown in full in Figure 3.4 below.

Figure 3.4 The GEMPACK command file SJLB.CMF
! The following GEMPACK Command file (usually called SJLB.CMF)  
!  carries out a multi-step simulation 
!  for the Stylized Johansen model.  
!  Auxiliary files (usually tells which TAB file)
auxiliary files = sj ;  
! Data files
file iodata = SJ.HAR ;
updated file iodata = <cmf>.upd ;  
! Closure
exogenous p_xfac ;
rest endogenous ; 
! Solution method information
method = euler ;
steps = 1 2 4 ;
! Simulation part
! Name of Solution file is inferred from name of Command file
! (See section 20.5.)
shock  p_xfac("labor") = 10 ;  
verbal description =
Stylized Johansen model. Standard data and closure.
10 per cent increase in amount of labor. (Capital remains unchanged.) ;
! Options.extrapolation accuracy file = yes ;
log file = yes ;
! End of Command file   

The statements in SJLB.CMF are discussed briefly below.

The statement

auxiliary files = sj ;

tells GEMSIM or the TABLO-generated program to use the Auxiliary files produced in Step 1. (This effectively tells which TABLO Input file (or model) to work with, since these files are just a processed version of the TABLO Input file SJ.TAB for the Stylized Johansen model.) [If you are using the TABLO-generated program SJ.EXE, the Auxiliary files are SJ.AXS and SJ.AXT produced when you ran TABLO in Step 1. If you are using GEMSIM, the Auxiliary files are SJ.GSS and SJ.GST produced when you ran TABLO in Step 1.]. You can find more details about these Auxiliary files in 21.

The statement

file iodata = SJ.HAR ;

tells SJ.EXE or GEMSIM to read base data from the file SJ.HAR (which contains the data in Table 3.1 above).

The line

! Data files

above this line is a comment since it begins with an exclamation mark !. While such comments are ignored by the software, they are very important in organising and documenting the Command file and in making it an intelligible record of the simulation. [You can see several other comment lines in the file.]

The statements:

exogenous p_xfac ;
rest endogenous ;

give the closure (that is, which variables to take as exogenous and which to take as endogenous), while the statement

shock p_xfac("labor") = 10 ;

gives the shock needed to increase the supply of labor by 10 per cent.

When the TABLO-generated program SJ or GEMSIM carries out a simulation, as well as being able to report the changes in the endogenous variables, the program produces an updated version of the original data file(s). The data in these updated data files represent post-simulation values (that is, the ones that would hold after the shocks have worked their way through the economy). For Stylized Johansen, this contains post-simulation dollar values of the entries in Table 3.1 above. The statement

updated file iodata = <cmf>.upd ;

names the file to contain this updated data [examined in section 3.9 below]. The <cmf> in this line indicates that this part of the name comes from the name of the Command file. Since the Command file is usually called SJLB.CMF, the program replaces <cmf> by SJLB (the name of the Command file ignoring its suffix .CMF) so that the updated iodata file will be called SJLB.UPD. The <cmf> syntax is explained further in section 20.5.

The most important output from a simulation is the Solution file which contains the results for the percentage changes in prices and quantities. Here we have omitted the name of the Solution file so the name of this file is taken from the name of the Command file. Because the Command file is called SJLB.CMF, the Solution file will be called SJLB.SL4 (the same basic name SJLB followed by .SL4 which is the standard GEMPACK suffix for Solution files). Another alternative is to add a statement of the form

solution file = ... ;            ! Not included in this SJLB.CMF

in the Command file. Such a statement is allowed, but it is customary to omit it so that the name of the Solution file is inferred from the name of the Command file.

You are required to give a verbal description of the simulation. This description, which can be several lines of text, goes on the Solution file and is visible from ViewSOL and other programs. You can use this to remind yourself (and others) about salient features of the simulation. The statement

verbal description = .Stylized Johansen model. 
 Standard data and closure.
 10 per cent increase in amount of labor (Capital remains unchanged.)
 1,2,4-step solutions plus extrapolation. ;

in SJLB.CMF give 4 lines of text for the verbal description in this case. The semicolon ';' indicates the end of this description — indeed all statements in GEMPACK Command files must end with a semicolon ';'.

With GEMPACK, you can choose one of 4 related solution methods for each simulation. These are introduced in section 3.12.3 below. The statements

method = euler ;
steps = 1 2 4 ;

in the Command file tell the program to use Euler's method based on 3 separate solutions using 1, 2 and 4 steps respectively. (See section 3.12.3 below for an explanation about step numbers.)

The accuracy of the solution depends on the solution method and the numbers of steps. SJ.EXE or GEMSIM can be asked to provide information about the accuracy on an Extrapolation Accuracy file. The statement

extrapolation accuracy file = yes ;

asks the program to produce such a file. The information on this file is described in section 3.12.3 below. (The name of this file is the same as that of the Solution file except that it has a different suffix, namely '.XAC', which makes the full name SJLB.XAC.)

The statement

log file = yes ;

asks the software to produce a LOG file showing all the screen activity as the program runs. This LOG file is called SJLB.LOG - it takes its name from the name SJLB.CMF of the Command file but changes the suffix from .CMF to .LOG. This LOG file is a useful record of the simulation.

Further details of Command files and running simulations are given in chapters 19 and following, which describe running simulations with GEMSIM, TABLO-generated Programs and SAGEM. A summary of the statements that can be used in a GEMPACK Command file for running TABLO-generated programs or GEMSIM is given in chapter 35.

In particular, we know that new users of GEMPACK find the auxiliary files (the statement above is "auxiliary files = sj ;") and the file statements (the statements above are "file iodata = SJ.HAR; " and "updated file iodata = <cmf>.upd ;") confusing initially. More details about these can be found in chapters 21 and 22.

3.9    The updated data - another result of the simulation [gpd1.2.9]

Once the simulation shocks have worked their way through the economy, prices and quantities change (as reported by the simulation results). These price and quantity changes imply changes in the values contained in the original data base for the model. When you carry out a simulation, the GEMPACK programs compute these new values. These new values are written to a file which is referred to as the updated data or post-simulation data.

As you saw in section 3.8 above, the line

updated file iodata = <cmf>.upd ;

in the Command file SJLB.CMF means that, when you ran the simulation, the software produced the updated data file SJLB.UPD. This file contains the data as it would be after the shocks (in this case, the increase in labor supply) have worked their way through the model.

You learned in section 3.4.3 how to use ViewHAR to look at the base (or pre-simulation) data file SJ.HAR. This file is the starting point for the simulation; and, when you look at this file you see the numbers shown in Table 3.1 above.

You can also use ViewHAR to look at the updated data in file SJLB.UPD.

If you are using WinGEM, select from the main WinGEM menu : HA Files | View VIEWHAR. The ViewHAR window will appear. Click on File | Open... and select the file SJLB.UPD.

Command-prompt users can open SJLB.UPD by typing "viewhar SJLB.UPD" into the DOS box.

In ViewHAR's contents screen, each row corresponds to a different array of data on the file. Look at the column under the heading "Name" to see what data are in these arrays. Look at values within the three arrays.

You can check that these post-simulation values are consistent with the results of the simulation as discussed in section 3.7 above. For example, the p_DVHOUS results in Table 3.3 show that the value of household expenditure on commodity s2 increased by 5.8853 percent from its pre-simulation value of 4 to its post-simulation value of 4.2354 (which agrees with the Commodity 2 Households value in the table above).

The most obvious results of a simulation are the percentage changes in the variables. The updated data (which is always obtained when you run a simulation) is another important "result" of the simulation, one which is sometimes overlooked. You can look at this updated data to see how the data base has changed as a result of the simulation.

3.10    Preparing tables and graphs for a report [gpd1.2.10]

When you have run some simulations and analysed the simulation results, the next step is usually to write a report containing a selection of the results in tables or graphs.

This section describes how you can transfer simulation results into a spreadsheet program, such as Microsoft Excel. You can use the spreadsheet program to produce tables and graphs which can be copied and pasted into your report.

All the examples below start with the Solution file for Stylized Johansen SJLB.SL4 created in the example simulation described above.

Once you have suitable tables in your spreadsheet program, you can use it to create graphs of the results.

3.10.1    Example 1: Copying from ViewSOL to Spreadsheet and WordProcessor [gpd1.2.viewsolexport]

Open file SJLB.SL4 in ViewSOL. Select Format and then select Arrange vectors by size and set.

In Contents screen, click on the line Vectors size: 2 SECT 4

The Data Window shows the results for all vector variables which range over the set SECT. Use the Decimal Places list box (in middle of upper toolbar) to display at least 4 decimal places.

In the ViewSOL menu, select Export | Copy. This copies the table of numbers to the clipboard.

Open your spreadsheet program and paste into a new spreadsheet. Use the spreadsheet editing to make the table ready for the report. Copy the table from your spreadsheet and paste it into the report document in your word processor, in the usual Windows way. You should see a table like the following.

p_DVHOUSp_PCp_XCOMp_XH
s15.885305.88535.8853
s25.8853-0.94866.89936.8993

ViewSOL has many different Formats that you can use to set up the data to export. Consult the ViewSOL Help for details.

3.10.2    Example 2: Using the GEMPACK Program SLTOHT and Option SSS [gpd1.2.sltoht1]

In the previous example, you interactively pasted from ViewSOL into a spreadsheet the results for one variable.

The SLTOHT method, described here, is more fiddly to set up. However, once you have created a Spreadsheet Mapping file (see below) you can, in one operation, import results for many variables into a spreadsheet. This means that you can automate the production of quite complex reports.

SLTOHT produces a CSV (Comma Separated Value) file. This is a text file which can be opened in your spreadsheet program to import the numbers generated by the simulation. Many arrays, even big arrays with many rows and columns, can be imported, and then (perhaps after some reformatting) moved to your report.

In your text editor, create the file sj1.map which contains just the two lines:

p_xcom
p_xf

This is an example of a Spreadsheet Mapping file (see sections 39.3 and 40.1) used by the program SLTOHT to pick out particular variables on the Solution file.

If you are working in WinGEM, select from the main WinGEM menu

Click on the Select button and choose the Solution file SJLB.SL4.

Choose to print Totals solutions. Click the Ok button.

In the SLTOHT window, select from the menu Options | SLTOHT Options. A screen of SLTOHT option choices will appear. Click on SSS Short SpreadSheet output and select a Comma as separator. (A comma is the default choice.)

Click on Ok to accept these options and return to the main SLTOHT screen.

In the SLTOHT window, select from the menu Options | Use mapping file and select the file SJ1.MAP.

Run the program SLTOHT. This will create the CSV text file called SJLB.CSV. When the program has completed, View the text file SJLB.CSV, which is shown below (after the Command prompt case).

Command prompt Users can start SLTOHT running by typing "sltoht" and entering the responses:

SSS      ! Option SSS   
,        ! Data separator is a comma
-SHL     ! Do not include levels results
<carriage-return>    ! Finish option selection
sjlb     ! Name of Solution file
c        ! Cumulative totals
y        ! Yes, use an existing Spreadsheet mapping file
sj1.map  ! Spreadsheet mapping file name
sjlb.csv  ! Name of Output file (CSV)

Look at the file sjlb.csv in your text editor.

The output in file sjlb.csv should look like the box below with the labels and numbers separated by commas. Only the values for variables p_XCOM and p_XF are shown because these were the only two variables in the Spreadsheet Mapping file.

CSV file SJLB.CSV
Solution,sjlb,
 p_XCOM(s1),  5.8852696    ,
 p_XCOM(s2),  6.8992925    ,
 p_XF(labor:s1),  9.9999990    ,
 p_XF(capital:s1),-4.48017488E-07,
 p_XF(labor:s2),  10.000002    ,
 p_XF(capital:s2), 4.48017488E-07,

Start your spreadsheet program (for example Excel) and open the file SJLB.CSV (as a text file with commas for separators). If you format the number cells to show three decimal places, you get a neat spreadsheet table with the labels in one column and the values in the second column. (In a report you would probably want to replace the column of labels with more meaningful labels.)

Document table
Solutionsjlb
p_XCOM(s1)5.885
p_XCOM(s2)6.899
p_XF(labor:s1)10.000
p_XF(capital:s1)0.000
p_XF(labor:s2)10.000
p_XF(capital:s2)0.000

3.10.3    Example 3: Using the Program SLTOHT and Option SES [gpd1.2.sltoht2]

There are various different options available in SLTOHT used to produce different kinds of tables as described in chapter 40. Option SES (Spread Sheet with Element labels) produces a table of results using the element names as row and column labels.

In your text editor, create the file sj2.map which contains just the two lines:

p_xcom : p_pc
p_xc

If you are using WinGEM, in the SLTOHT window, select from the WinGEM menu Options | SLTOHT Options. A screen of SLTOHT option choices will appear. Click on SES and select a Comma as separator. (A comma is the default choice.)

Click on Ok to accept these options and return to the main SLTOHT screen.

In the SLTOHT window, select from the menu Options | Use mapping file and select the file SJ2.MAP. Run the program SLTOHT.

SLTOHT will tell you that, by default, this will produce output file SJLB.CSV which already exists. [You created it in Example 2 above.] Click on Yes to say that you wish to change the name of the output file, and choose the name SJLB2.CSV.

When the program has completed, View the text file SJLB2.CSV, which is shown below (after the Command prompt case).

Command prompt Users can start SLTOHT running by typing "sltoht" and entering the responses:

SES      ! Option SES 
,        ! Data separator is a comma
-SHL     ! Do not include levels results
<carriage-return>    ! Finish option selection
sjlb     ! Name of Solution file
c        ! Cumulative totals
y        ! Yes, use an existing Spreadsheet mapping file
sj2.map  ! Spreadsheet mapping filename
sjlb2.csv  ! Name of Output file (CSV)

Open the file sjlb2.csv in your spreadsheet program. The values for variables p_XCOM and p_PC are shown side by side and then the array p_XC is shown below, all with element labels.

! Table of 2 variables.

p_XCOMp_PC
s15.8850.000
s26.899-0.949

! Variable p_XC # Intermediate inputs of commodity i to industry j #

! Variable p_XC(SECT:SECT) of size 2x2

s1s2
s15.8855.885
s26.8996.899

You can import either of these tables into your word processor.

3.10.4    Graphs [gpd1.2.10.1]

Once you have suitable tables in your spreadsheet program, you can use it to create graphs of the results. Alternatively the Charter program supplied with GEMPACK (see section 36.2.1) can be used to produce simple graphs directly from ViewHAR or ViewSOL.

3.11    Changing the closure and shocks [gpd1.2.11]

You can carry out several simulations on the same model by changing the closure and/or the shocks in the Command file.

Note that, if you change the closure and/or shocks, but do not change the model (that is, do not change the TABLO Input file), you do not need to repeat Step 1 (running TABLO) in section 3.6. You only need to do Steps 2 and 3 there.

The following example shows you how to make a new Command file in the text editor and then run another simulation using SJ.EXE (or alternatively GEMSIM).

The new simulation is to increase the price of labor by 3 per cent and to increase the supply of capital by 10 per cent. In order to increase the price of labor, the variable p_PF("labor") needs to be exogenous. You need to change the closure and also apply these different shocks.

To change the command file SJLB.CMF, copy it to a new name SJLB2.CMF as follows:

If you are working in WinGEM, in the main WinGEM menu, choose File | Edit file... then open the file SJLB.CMF. Click on File | Save As... and save the file under the new name SJLB2.CMF.

If you are working at the Command prompt, type "copy sjlb.cmf sjlb2.cmf".

Then use the text editor to modify this file, following the steps below.

(1) In the original closure, both components of p_XFAC (supplies of labor and capital) are exogenous. Here you keep the supply of capital exogenous, but set the price (rather than the supply) of labor exogenous. [p_PF is the variable in the model denoting the percentage change in the price of the factors, labor and capital.]

Find the statement

exogenous   p_xfac ;

and change this to

exogenous   p_pf("labor")   p_xfac("capital")   ;

(Be careful not to leave a space between the variable name p_pf and the bracket. However, it does not matter if you use upper or lower case, or a mixture, in Command files.)

(2) Shock p_pf("labor"), the price of labor, by 3 per cent and shock p_xfac("capital"), the supply of capital, by 10 per cent.

You will need two separate shock commands:

 shock   p_pf("labor")   =  3  ;
 shock  p_xfac("capital") = 10 ;

[Remember to put a semicolon ";" after each statement.]

(3) Change the verbal description to describe the new closure and shocks. [This starts after "verbal description =" and ends with a semi-colon ";". There can be several lines of text in it.]

Exit from the editor after saving your changes.

If you are working in WinGEM:

If you have Source Code GEMPACK, click on Simulation | Run TG program... and then Select the TG EXE file to be SJ.EXE.

If you have an Executable-Image version, click on Simulation | GEMSIM Solve... .

Now both cases continue in the same way.

Select the Command file SJLB2.CMF.

Run the program with this Command file SJLB2.CMF. This is Step 2 of the simulation steps listed in section 3.6.

If there are errors when this runs, you will see a window headed "Error during Simulation". To correct the errors in the Command file, click on the button Edit Command file to use split screen editing. The Command file SJLB2.CMF will be shown in the top part of the screen and the LOG file in the bottom part of the screen. The errors will be marked in the LOG file, usually near the end of the file. When you have identified what is causing an error, you must make the appropriate change in the Command file in the top part of the screen (not the LOG file). The Next error button may help you to find errors. [If you have problems identifying or correcting the errors, you can find more assistance in section 4.7.2 below.] When you have corrected all errors, use File | Exit and save the changes you have made to the Command file SJLB2.CMF. Then close the error window by clicking on Close in it. Now click on Run to run the simulation again.

When SJ.EXE (or GEMSIM) has run successfully, click on Go to ViewSOL to look at the results.

If you are working at the Command prompt,

Edit the Command file sjlb2.cmf to make the changes above.

To run the simulation, type in at the Command prompt:

sj  -cmf  sjlb2.cmf

to run sj.exe or, to run GEMSIM:

gemsim -cmf sjlb2.cmf

View the Log file to see if there are any errors.

If there are errors, the errors will be marked in the LOG file (which is probably called sjlb2.log), usually near the end of the file. When you have identified what is causing an error, you must make the appropriate change in the Command file (not the LOG file). After you correct an error, rerun the simulation. [If you have problems identifying or correcting the errors, you can find more assistance in section 4.7.2 below.]

When sj.exe (or GEMSIM) has run successfully, use ViewSOL to examine the Solution file sjlb2.sl4.

3.12    How Johansen and multi-step solutions are calculated [gpd1.2.13]

Johansen solutions are approximate results of a simulation. In contrast, multi-step solutions can be made arbitrarily accurate by taking enough steps. In this section we describe the main ideas involved in calculating these different solutions.

3.12.1    The linearized equations of a model [gpd1.2.13.1]

Johansen solutions are calculated by solving the linearized equations15 of the model once; multi-step solutions are obtained by solving these equations several times.

The system of linearized equations of any model can be written in the form

C z = 0                                     (1)

where

C is the n x m matrix of coefficients of the equations, known as the Equations .Matrix (which is closely related to the Equations file16,

z is the m x 1 vector of all the variables (usually in percentage change form) of the model,

n is the total number of equations, and

m is the total number of variables.

We call C the Equations Matrix of the model17. It is often useful to think of this matrix as a rectangular array or tableau 18 with the vector variables across the top and the equation blocks along the left-hand side. Each vector variable occupies as many columns as its number of components, and each equation block occupies as many rows as the number of actual equations in it.

To illustrate this, part of the tableau for the 27 x 29 Equations Matrix C for the Stylized Johansen model (from the TABLO Input file SJ.TAB) is shown in Table 3.4.

Notice that we use the words "variable" and "equation" in two different senses. For example, we usually say that Stylized Johansen is a model with 29 variables and 27 equations, where we count as variables all the components of the vector variables and we count as equations all the individual equations in the equation blocks. In this sense, the number of variables is the number of columns in the Equations Matrix while the number of equations is the number of rows. Alternatively we may say that the TABLO Input file for Stylized Johansen has 11 variables (meaning vector variables) and 10 equations (meaning equation blocks). Usually the context will make clear which of these two meanings is intended.

Table 3.4 Tableau of the equations matrix for Stylized Johansen
                1     2       2       2            4        2
              p_Y   p_PC   p_PF    p_XCOM....   p_DVFACIN p_DVHOUS  
  cols -->      1   2  3   4  5     6  7          24..27  28  29
        rows  ___________________________________________________
           1 |   |       |       |       |      |        |      | 
 Comin     2 |   |       |       |       |      |        |      |
     4     3 |   |       |       |       |      |        |      |
           4 |___|_______|______ |_______|______|________|______|
           5 |   |       |       |       |      |        |      |
 Facin     6 |   |       |       |       |      |        |      |
     4     7 |   |       |       |       |      |        |      |
           8 |___|_______|______ |_______|______|________|______|
 House     9 |   |       |       |       |      |        |      |
     2    10 |___|_______|_______|_______|______|________|______|
             |   |       |       |       |      |        |      |
     :       |   |       |       |       |      |        |      |
     :       |   |       |       |       |      |        |      |
             |___|_______|_______|_______|______|________|______|
 Numeraire 27|   |       |       |       |      |        |      |
     1       |___|_______|_______|_______|______|________|______|

In general, n is less than m in the system of equations in (1) above, so when you carry out a simulation (Johansen or multi-step) you must specify

For Stylized Johansen, the total number of variables (m) is 29 and the total number of equations (n) is 27, so we need 2 exogenous variables. We can shock either 1 or 2 of these exogenous variables.

The numerical values of some of the entries in the Equations Matrix can be seen in section 4.4.5 below.

3.12.2    Johansen solutions [gpd1.2.13.2]

Johansen solutions are defined to be solutions obtained by solving the linearized equations of the model just once. Because the levels equations of the model are usually nonlinear, the results of this calculation are only approximations (sometimes good approximations and sometimes not-so-good) to the corresponding solution of the levels equations of the model.

Once the exogenous/endogenous split has been chosen, the system of equations C z = 0 in (1) above, becomes .

A z1 = -D z2                           (2)

where z1 and z2 are respectively the (column) vectors of endogenous and exogenous variables,. A is n x n and D is n x (m-n).

The matrix A is referred to as the LHS Matrix (Left Hand Side Matrix) of the simulation. The LHS matrix A consists of the columns of the Equations matrix corresponding to the endogenous variables in the given closure. Similarly the columns of the matrix D are just the columns of C corresponding to the exogenous variables in the closure. The shocks are the values to use for z2. Once these are known, we have a system

A z1 = b                               (3)

to solve (where the RHS vector b is an n x 1 vector equal to -Dz2). It is the solution z1 of this matrix equation (3) which is the Johansen solution of the simulation19.

3.12.3    Multi-step simulations and accurate solutions of nonlinear equations [gpd1.2.13.3]

The idea of a multi-step simulation is to break each of the shocks up into several smaller pieces. In each step, the linearized equations are solved for these smaller shocks. After each step the data, shares and elasticities are recalculated to take into account the changes from the previous step. In general, the more steps the shocks are broken into, the more accurate will be the results.

Figure 3.5 below makes this easy to visualise. In that figure we consider just one exogenous variable X (shown on the horizontal axis) and one endogenous variable Y (vertical axis); these are constrained to stay on the curve g(X,Y) = 0. We suppose that they start from initial values X0,Y0 at the point A and that X is shocked from value X0 to value X1. Ideally we should follow the curve g(X,Y)=0 in solving this. In a Johansen (that is, a 1-step) solution we follow the straight line which is a tangent to the curve at point A to reach point BJ and so get solution YJ.

Figure 3.5 Illustration of Euler's method
illustration of euler's method

In Euler's method the direction to move at each step is essentially that of the tangent to the curve at the appropriate point. In a 2-step Euler solution (see Figure above), we first go half way along this tangent to point C2, then recompute the direction in which to move, and eventually reach point B2, giving solution YE2. The exact solution is at B where Y has value Y1. In a 4-step Euler simulation we follow a path of 4 straight-line segments, and so on for more steps.

The default method used by GEMPACK is Gragg's method which uses an even more accurate method than Euler's method for calculating the direction in which to move at each step. When the shocks are broken into N parts, Euler's method does N separate calculations while Gragg's method does N+1. Usually the computational cost of this extra calculation is more than repaid by the extra accuracy obtained. More information about Gragg's method (and the similar midpoint method) can be found in section 30.2.

So one way of increasing accuracy is to increase the number of steps. It turns out, however, that the best way to obtain an accurate solution is to carry out 2 or 3 different multi-step calculations with different numbers of steps and to then calculate the solution as an appropriate weighted average of these. This is what is meant by the extrapolated solution.

To illustrate this, we have shown below the different results for the percentage change in household expenditure 'p_Y' in the Stylized Johansen model for the simulation in section 3.1 above, in which labor supply is increased by 10 per cent and capital remains in fixed supply. The table below shows Euler and Gragg results for different step numbers and extrapolations based on them. Note that the exact result is 5.88528.

Multi-step results for different methods and step numbers
   Method     Number of steps
                1         2         4          6        100
    Euler    6.00000   5.94286   5.91412    5.90452    5.88644
    Gragg    5.89091   5.88675   5.88545    5.88529  
Extrapolated results
    From Euler 1,2-step results        5.88571    
    From Euler 1,2,4-step results      5.88527
    From Gragg 2,4,6-step results      5.88529  

Note that, in this case,

These results are typical of what happens in general.

The general messages are:

When you extrapolate, if you ask for an Extrapolation Accuracy file (or .XAC file)20, this file shows how accurate the solution is for each endogenous variable. The separate columns show the results for the different multi-step solutions calculated, and the last column of results is the extrapolated result. When you extrapolate from 3 different multi-step results (which is what we recommend), the last two columns give conservative information about the accuracy of each result. (If they show M figures agreement, this means that the 2 different extrapolations based respectively on just the first two and just the first and third agree to this number of figures.)

For example, for the 1,2,4-step Euler results for household expenditure 'p_Y' reported above for the SJLB.CMF simulation (see sections 3.4), the relevant line in the Extrapolation Accuracy file would21 be

p_Y     1       6.00000    5.94286   5.91412   5.88527   CX  4  L5

The results are the 1,2,4-step results and the extrapolation based on them. The comment "CX 4" is an abbreviation meaning that you can have confidence in the extrapolated result (this is the 'CX') and that the two extrapolations (the first based just on the 1,2-step results and the second based on the 2,4-step results) agree to 4 figures (or more). Note that the agreements are reported as figures, not decimal places. (For example 123.4567 and 123.4014 agree to 4 figures, but only one decimal place.) The abbreviations (such as 'CX') used on this file are explained at the top of the file. (The first "1" in the line displayed above means that this line refers to the first - in this case, the only - component of variable p_Y.) The "L5" at the end of this line means that you can be confident of 5 figures accuracy in the level of income Y. [See section 26.2.1 for more details.]

At the end of the file is a summary (we refer to it as the Extrapolation Accuracy Summary) which states how many components fall into each category (EMA, CX etc). For a simulation with Stylized Johansen, this may look something like that shown below.

SUMMARY OF CONVERGENCE RESULTS                 Number  Min Figs Agree
      ------------------------------           ------  --------------
 EMA  Last two results equal to machine accuracy  3         6
 FC0  Fair confidence that the result is zero     2
 CX   Confidence in the extrapolated result      22         2  
   2 results are judged accurate to 2 figures.
   4 results are judged accurate to 3 figures.
   16 results are judged accurate to 4 figures.
   3 results are judged accurate to 6 figures.
 
  Above is for linearised variables.
  Below are for levels values of percent-change and change results.

   1 results are judged accurate to 4 figures.
   21 results are judged accurate to 5 figures.
   5 results are judged accurate to 6 figures.
   
    (The summary above covers the XAC-retained variables.)    

The first part is a summary of the number of times different comments (in the example above, "EMA", "FC0" and "CX") have been used for the different results. The second part tells how many results (linearised, then levels) have been judged accurate to different numbers of figures.

More details about Extrapolation Accuracy Summaries and Extrapolation Accuracy files are given in section 26.2.

The only restriction on step numbers is that, for Gragg's method and the midpoint method, the step numbers must either be all odd or all even (for example, 2,4,6 or 3,5,7). Note also that a 1-step Gragg or midpoint is a little unusual and is probably best avoided (since it is more like Euler than Gragg or midpoint).

More details are given in section 30.2 and some of the theory behind multi-step methods can be found in Pearson (1991).

3.12.4    Smiling or frowning face numbers are reported [gpd5.9.2.1]

If you use WinGEM, RunGEM or RunGTAP, you know that after each simulation is completed, you see smiling or frowning faces which indicate how accurately the simulation was solved (provided that you are extrapolating from 3 multi-step calculations). Within ViewSOL, the accuracy summary can be displayed via an icon:

on the upper toolbar.

At the end of the simulation, and at the end of each subinterval if there is more than one, GEMSIM and TABLO-generated programs report (to the terminal and to the LOG file) the face number (between 1 and 10, where 10 is accurate and 1 is very inaccurate). Separate face numbers are shown for the variable and the data accuracy. If there is more than one subinterval, the face number for the overall variable accuracy is shown at the end of the Overall Accuracy Summary (see section 26.3.1).

3.12.5    Fatal error if accuracy too low (GEMSIM and TG-programs) [gpd5.9.2.2]

Suppose that you are extrapolating from 3 multi-step calculations. If the accuracy is extremely low, it is highly unlikely that the simulation results are of any value. Accordingly, the program stops with a fatal error in order to draw your attention to this poor accuracy (but the solution file is still saved).

This can happen at the end of the whole simulation, or it can happen at the end of any subinterval which is solved inaccurately. However it does not happen at the end of a subinterval if you are using automatic accuracy since then you may redo the subinterval in question.

We believe it is your responsibility to decide whether or not a simulation has been solved sufficiently accurately. You should always look at the information provided by the software, especially the Accuracy Summaries (see sections 26.2 and 26.3.1). We are reluctant to intervene and, as when equations are not satisfied very accurately (see section 30.6.1), we end with a fatal error only in what we consider are extreme cases. At present, if any of the face numbers is 3 or less, we stop with a fatal error. Choosing 3 here does not mean that we think face numbers 4,5 and 6 are ok (since often they will not be) - rather we leave the decision to you in such cases.

3.13    GEMPACK programs - an overview [gpd1.2.14]

As you have already seen, GEMPACK is not a single program. There are a number of different programs making up GEMPACK. In this section we give a brief overview of these different programs, grouped by task.

You have not yet used all of the programs below. As you become more experienced with GEMPACK, you may need to come back to this section to check out those programs you have not used.

3.13.1    Working with TABLO input files [gpd1.2.14.1]

TABmate is a special editor for TABLO Input (TAB) files. Use TABmate to create and modify the theory of a model - that is, the TABLO Input file for the model.

TABLO converts the model TAB file into a TABLO-generated program or Auxiliary files for GEMSIM. You must do this before you can carry out a simulation with a model. [See Step 1 in section 3.6.]

In fact TABmate runs the program TABLO in the background. So TABmate and TABLO can perform very similar functions. You can use either TABLO or TABmate to carry out Step 1 for simulations (see section 3.6).

3.13.2    Carrying out simulations [gpd1.2.14.2]

You can use either GEMSIM or the relevant TABLO-generated program to carry out Step 2 for simulations (see section 3.6). Which you use depends on how you ran TABLO in Step 1 (see section 3.6.1 or 3.6.2 above).

GEMSIM. Run GEMSIM to carry out a simulation. Specify the Auxiliary files, starting data files, closure and shocks in a Command file.

TABLO-generated program. Run the EXE file of the TABLO-generated program to carry out a simulation. Specify the starting data files, closure and shocks in a Command file. You can only create TABLO-generated programs if you have a Source-code version of GEMPACK.

3.13.3    Looking at, and processing, simulation results [gpd1.2.14.3]

ViewSOL is for looking at results — see Step 3 in section 3.6.

AnalyseGE is for analysing simulation results. You can view model equations, simulation results and the values of items in the data base. Section 36.6 introduces AnalyseGE. A hands-on introduction to AnalyseGE in the context of a simulation with Stylized Johansen can be found in section 46.1.

SLTOHT is a command-line program that converts simulation results (on a Solution file) either (a) into tables of results which you can import into a spreadsheet, or (b) into a Header Array file. See section 3.10 above and chapters 39 and 40 for information about SLTOHT.

When you report simulation results, you will probably use other standard tools (including spreadsheet programs such as Excel) for making tables and graphs.

3.13.4    Working with data [gpd1.2.14.4]

In GEMPACK data for models are usually held on Header Array files. Because these are binary (ie, non-text) files, you need special programs to work with the data in this form.

ViewHAR is for looking at data on Header Array files. You used ViewHAR to look at original and updated data in the Stylized Johansen example above. ViewHAR can also be used to create a Header Array file and to modify data on a Header Array file (see section 6.1 below and section 6.2).

CMPHAR can be used to compare the data on two Header Array files — see section 37.2.

CMBHAR can be used to combine the data on two or more Header Array files (for example, data representing two or more years). See section 37.3.

Data comes from various sources. You may use other standard tools and programs (including spreadsheet programs such as Excel) when working with data.

3.13.5    Windows modelling environments [gpd1.2.14.5]

WinGEM provides a Windows environment for carrying out modelling and associated tasks.

RunGEM provides a Windows environment for carrying out simulations with a fixed model. Users with little experience of modelling can carry out simulations by choosing just the closure and shocks. See section 36.5 and chapter 45.

RunDynam and variants including RunGDyn are sold as as a separate product. They are Windows interfaces for use with recursive dynamic models such as USAGE and dynamic GTAP. See section 36.7.

3.13.6    Other programs for special tasks [gpd1.2.14.6]

These are programs used for specialised tasks, usually by power users. You will not need to use any of them until you are more experienced with GEMPACK.

ACCUM and DEVIA are used for working with recursive dynamic models such as USAGE which are solved annually over a period of several years. ACCUM and DEVIA collect the results for several years. [See chapter 41.]

SUMEQ is for looking at data on an Equations file. SUMEQ can also be used to diagnose homogeneity problems with a model — see chapter 57.

SEENV is for working with Environment files (which store the set of exogenous and endogenous variables in one closure for a model) — see chapter 56.

3.13.7    Programs for use on non-Windows PCs [gpd1.2.14.7]

Windows programs, such as WinGEM, ViewHAR or ViewSOL, will not run on non-Windows PCs22 -- so other, command-line programs are needed to turn data (HAR) and results (SL4) files into text files that you can view. These are:

SEEHAR turns a Header Array file into a viewable text file — see section 37.1.

GEMPIE turns a results (SL4) file into a viewable text file — see chapter 79.

RWHAR and MKHAR are used to convert Header Array files from one operating system (eg, Windows) to another operating system (eg, Unix) — see chapter 71.

3.14    Different GEMPACK files [gpd1.2.15]

As you have seen, GEMPACK programs produce and use several different types of files (for example, Solution files and Header Array files). New users often ask us "Why are there so many different files?".

In this section we give more details about these different files and how they are used.

In our experience, some users are keen to have detailed information about this topic while others are not very interested. Since a detailed knowledge about this topic is not essential for doing effective modelling, you should feel free to skip this section or to skim it very quickly. You can always refer back to it later on, if and when you need to.

A table summarising the different files is given in section 3.14.7 below.

3.14.1    The most important files [gpd1.2.15.1]

We begin with the most important files, namely TABLO Input files, data files, Command files and Solution files, all of which you have met earlier in this chapter.

TABLO Input files. These contain the theory (equations etc) for a model. Alternatively they may be for data manipulation. These files have suffix .TAB. These files are inputs to the program TABLO. The program TABmate (see section 36.4) can be used to create and or modify these files.

Data files. These may be Header Array files or text files. The suffix is not prescribed by the software, though suffix .HAR is recommended (.DAT is sometimes used). Data files can be inputs to a simulation (the original input-output data, the parameters) and updated versions are output from a simulation. Updated data files are usually given the suffix .UPD . Chapter 6 below contains an introduction to the different ways in which you can create data files and modify data on existing data files.

Command files. These contain the details of a simulation, including closure, shocks, starting data and solution method (see section 3.8). The suffix is not prescribed by the software, though .CMF is usual23. Command files are inputs for GEMSIM and TABLO-generated programs. The statements allowed in Command files are documented in chapter 35.

Solution files. These are the main outputs from a simulation. They contain the change or percentage change results for all the linearized variables. They may also contain levels results. These files have suffix .SL4. They are inputs to various post-simulation programs such as ViewSOL, SLTOHT, and AnalyseGE. Solution files are documented in chapter 27.

Equations files. These contain numerical versions of the linearized equations of a model. They are usually only produced when you wish to use SAGEM to obtain several Johansen (approximate) solutions of a model, as explained in chapter 58. You may also create an Equations file if your model is not homogeneous in prices or quantities (see section 57.1). Equations files have suffix .EQ4. Equations files are documented in chapter 59.

Shock files. Sometimes it is necessary to shock the different components of a variable by different amounts. If the variable has a large number of components, or if the shocks are calculated by a program, it is convenient to put the numerical values of the shocks onto a so-called "shocks file". This file may be a text file or a Header Array file. The suffix for shocks files is not prescribed by the software, though often .SHK is used. The use of shock files is documented in sections 24 to 66.2.

Solution Coefficients (SLC) files. These are output from a simulation. They contain the pre-simulation values of all data and of all Coefficients in the TABLO Input file for the model. These files have suffix .SLC and have the same name (apart from suffix) as the Solution file from the simulation24. The program AnalyseGE reads both the Solution and SLC file when you analyse the results of a simulation25. You can also examine SLC files with ViewHAR. SLC files are documented in section 28.1.

Extrapolation Accuracy files. You can ask26 for an Extrapolation Accuracy file to be produced when you extrapolate from 3 separate multi-step calculations (as you have seen in section 3.12.3 above). These text files show estimates as to how accurate the different simulation results are. They have suffix .XAC and have the same name (apart from suffix) as the Solution file from the simulation. Extrapolation Accuracy files are documented in section 26.2.

3.14.2    Files for communication between programs [gpd1.2.15.2]

There are a number of files which are used for communication between programs. The most important of these are the Auxiliary files which allow communication between TABLO and GEMSIM or the TABLO-generated program.

Auxiliary files. These are either

TABLO-generated program (Fortran file). This is the Fortran (.FOR) file for the TABLO-generated program which is produced by TABLO (see section 3.6.1 above). Auxiliary files (.AXS and .AXT files) are always produced at the same time. In Step 1(b) for simulations (see section 3.6.1), this program is compiled and linked to produce the EXE file of the TABLO-generated program27. It is this EXE file which is run to carry out a simulation.

When the EXE file of a TABLO-generated program is used to carry out a simulation, the Auxiliary files (AXS and AXT files) are required. They communicate vital information from the TABLO Input file to the simulation.

Similarly, if GEMSIM is used to carry out a simulation, the GEMSIM Auxiliary files (GSS and GST files) are required.

3.14.3    LOG files [gpd1.2.15.3]

Often a program runs very quickly and/or puts a lot of information on the screen. If you need to check this output (for example, to see where an error occurs), you can ask for a LOG file to be created28. You can then look at this log file in your favourite text editor. The suffix for LOG files is not prescribed by the software, though suffix .LOG is usual.

3.14.4    Stored-input (STI) files [gpd1.2.15.4]

These days, GEMPACK Windows programs such as TABmate, RunDynam or WinGEM are the main interface seen by most GEMPACK users — but a lot of the work they seem to perform is in fact carried out by command-line programs running in the background.

In previous times, before the GEMPACK Windows programs were available, GEMPACK users usually ran programs like TABLO, GEMSIM and SLTOHT from the command line. The program would ask a sequence of questions — the responses were usually single letters (to indicate options) or filenames (for input and output).

Obviously it could be very tedious to repeatedly run programs in this way. Stored-input files or STI files were a way to reduce the drudgery — they consist of a text file which stores the necessary responses to the questions that the program asked. Then, to repeat an SLTOHT job, one merely typed, say:

sltoht -sti report3.sti

where report3.sti is a text file of the responses needed to generate some report. To produce report3.sti you would, the first time you ran this job, either note responses on a scrap of paper (the old way) or activate the SIF option in SLTOHT which will record your responses in a file.

STI files are rather hard to read and understand — you only see one half of a conversation.

For modern GEMPACK users the most-frequently encountered STI files may be those used for input to TABLO which specify the condensation (section 14.1.2 gives an example). For new models you can and should specify condensation actions — such as Omit, Substitute and BackSolve — within the TAB file, but this option is relatively new, so many older models still use a STI file to store the condensation.

Apart from this, the main remaining uses of STI files are:

Stored-input files are further described in section 48.3. They usually have suffix .STI (although other suffixes may be used). You will need to learn about STI files as you become more experienced. You can find introductory examples of creating and working with them in sections 14.1.2, 14.1.4 and 54.11.

3.14.5    Files for power users [gpd1.2.15.5]

A number of files can be created in order to speed up or simplify subsequent tasks. These are typically used mainly by experienced GEMPACK users so you don't need to know any details about them at this stage. Examples are Stored-input files (see section 3.14.4 above), Environment files (see section 23.2) and various Mapping files (see sections 39.3, 39.8 and 40.1).

3.14.6    Work files [gpd1.2.15.6]

Many programs create and use working files while they are running. These work files can be large. Usually these work files are deleted when the program finishes so you do not see them or need to know about them. Occasionally these files are left around on your hard disk if the program finishes with an error. See section 30.7 for more details.

3.14.7    Summary of files [gpd1.2.15.7]

Table 3.5 Summary of the different files
File Type and SuffixInput toOutput from
TABLO Input file (TAB)TABLO, TABmateTABmate
Data files(often HAR)Simulations, Data-manipulation TAB files, ViewHAR, CMBHAR, SEEHAR etcSimulations, Data-manipulation TAB files,ViewHAR, SLTOHT etc
Command files (usually CMF)TABLO-generated programs, GEMSIM, SAGEMtext editor
Solution files (SL4)ViewSOL, ViewHAR, AnalyseGE, SLTOHTTABLO-generated programs, GEMSIM, SAGEM
Equations files (EQ4)SAGEM, SUMEQTABLO-generated programs, GEMSIM
Shock files (often SHK)TABLO-generated programs, GEMSIM, SAGEMtext editor, TABLO-generated programs, GEMSIM
SLC files (SLC)AnalyseGETABLO-generated programs and GEMSIM
Extrapolation Accuracy files(XAC)TABLO-generated programs and GEMSIM
Auxiliary files (GSS/GST or AXS/AXT)GEMSIM or TABLO-generated programTABLO
TABLO-generated Fortran program (FOR)Compile and link - Step 1(b) in section 3.6.1TABLO
LOG files (usually LOG)Any command-line GEMPACK program
Stored-input files (usually STI or SIF)Any command-line GEMPACK programText editor, or any GEMPACK program
(see options SIF and ASI in section 48.3).

3.15    For new users - what next? [gpd1.2.16]

Congratulations. You have just learnt the most important things about GEMPACK, namely how to set up and carry out simulations, and how to look at the results.

Where you go next in learning about GEMPACK depends on your main purpose in using the software.

Whatever your main interest, we strongly encourage you to at least skim chapter 4 first, and then go on to your main interest. You must be familiar with at least the basics of TABLO Input (TAB) files in order to work properly with, and understand, any model implemented via GEMPACK.

4    Building or modifying models [gpd1.3]

Click here for detailed chapter contents

In order to build a model within GEMPACK, it is necessary to prepare a TABLO Input file containing the equations of the model and to construct one or more data files whose purpose is essentially to give one solution of the levels equations of the model.

The preparation of a TABLO Input file involves

We describe the preparation of TABLO Input files in section 4.3 and the preparation of the actual data files in chapter 6. We illustrate each step in the process by doing it for the Stylized Johansen model.

Of course, to modify an existing model, you modify the TABLO Input file (to change the theory of the model) and/or the data file(s).

The TABLO Input file given for Stylized Johansen in section 4.3.3 is a mixed one (in the sense that it contains a mixture of linearized and levels equations). In sections 4.4.1 and 4.5.1 we describe alternative TABLO Input files for Stylized Johansen consisting only of linearized or levels equations respectively.

TABLO linearizes all levels equations in TABLO Input files and converts all levels variables to the associated linear ones (change or percentage change in the associated levels variables). This is described in section 4.6.

We conclude this chapter in section 4.7 where we give you advice about building your own model by writing a TABLO Input file from scratch or by modifying an existing one. We include hands-on examples showing how to identify and correct errors in TABLO Input files and Command files.

If you are familiar with using GAMS for general equilibrium modelling, you may prefer to work through the document Kohlhaas and Pearson (2002) instead of, or before, reading this chapter. The many similarities between GEMPACK and GAMS make it relatively easy for a GAMS modeller to begin using GEMPACK productively.

Table 4.1 Levels and linearized equations of the Stylized Johansen model
stylised johansen equations

In Table 4.1, upper-case Roman letters represent the levels of the variables; lower-case Roman letters are the corresponding percentage changes (which are the variables of the linearized version shown in the second column). The letters P, X and D denote prices, quantities and dollar values respectively, while the symbols A and a denote parameters. Subscripts 1 and 2 refer to the (single) commodities produced by industries 1 and 2 (subscript i), or to the industries themselves (subscript j); i = 3 refers to labour while i = 4 refers to the model's one (mobile-between-industries) type of capital; subscript j = 0 identifies consumption. Because the first three equation blocks are identically linear in the logarithms they are natural candidates for presentation and explanation of the model.

4.1    Writing down the equations of a model [gpd1.3.1]

TABLO Input files contain the equations of a model written down in a syntax which is very similar to ordinary algebra. Once you have written down the equations of your model in ordinary algebra, it is a simple matter to put them into a TABLO Input file, as we illustrate in section 3.3 below.

You are free to use levels or linearized versions of the equations or a mixture of these two types. For example, if a certain dollar value D is the product of the price P and quantity Q, the levels equation is

D = P * Q

(where the "*" indicates multiplication), and the associated linearized equation is

p_D = p_P + p_Q

where "p_" denotes "percentage change in". The linearized version says that, to first order of approximation, the percentage-change in the dollar value is the sum of the percentage changes in the price and the quantity. Whichever version of the equation you include, GEMPACK can still produce accurate solutions of the underlying levels equations (which are usually nonlinear).

We say more about the process of linearizing equations in section 3.7 below.

The best way of making the above clear is to take a concrete example, as we do below, using Stylized Johansen as our example model.

4.1.1    Writing down the equations of Stylized Johansen [gpd1.3.1.1]

We start from the equations as written down in Chapter 3 of DPPW (to which we refer readers interested in the derivation of, and motivation behind, these equations). An excerpt from that chapter, SJ.PDF, is included in the "examples" subfolder of your GEMPACK directory.

The equations of the model are shown in Table 4.1. In that table, both the levels and linearized versions of each equation are shown, taken essentially unchanged from DPPW1. Notice that upper case letters (for example, X) denote levels quantities while lower case letters (for example, x) denote percentage change in the corresponding levels quantity.

For our first implementation of Stylized Johansen (see section 4.3 below), we have chosen a mixed representation, based on the shaded blocks in Table 4.1. That is, we decided to use the levels versions of some of the equations (most are accounting identities and one is the numeraire equation) and the linearized versions of the top three equations (which are behavioural equations). Later, in sections 4.4 and 4.5 respectively, we describe implementations based on exclusively linearized equations (section 4.4) and exclusively levels equations (section 4.5). Of course, each of these 3 implementations is valid and all three produce the same results.

The notation in DPPW involves a liberal use of subscripts which are not suitable for the linear type of input usually required by computers (and required in the TABLO Input file). Hence we use a different notation. The levels variables of the model are as follows. In DPPW subscripts 1 and 2 refer to sectors (commodity or industry), subscripts 3 and 4 refer to factors (3 is labor and 4 is capital) while subscript 0 refers to households.

Table 4.2 Levels variables for Stylized Johansen
GEMPACK variableMeaningDPPWNotation
YValue of household incomeY
PC(i)Price of commodity iPi(i=1,2)
PF(f)Price of factor fPf(f=3,4)
XCOM(i)Supply of commodity iXi(i=1,2)
XFAC(f)Supply of factor fXf(f=3,4)
XH(i)Household use of commodity iXi0(i=1,2)
XC(i,j)Intermediate input of commodity i to industry jXij(i,j=1,2)
XF(f,j)Input of factor f to industry jXfj(f=3,4;j=1,2)
DVCOMIN(i,j)Dollar values for intermediate inputs(i,j=1,2)
DVFACIN(f,j)Dollar values for factor use by industry(f=3,4;j=1,2)
DVHOUS(i)Dollar values for household consumption(i=1,2)
Table 4.3 Parameters for Stylized Johansen levels equations
ParametersDescriptionDPPWNotation
ALPHACOM(i,j)Commodity exponents in production function for sector j (E3.1.4)ALPHAij(i,j=1,2)
ALPHAFAC(i,j)Factor exponents in production function for sector j (E3.1.4)ALPHAfj(f=3,4; j=1,2)

We introduce sets SECT, the set of two sectors say "s1" and "s2", and FAC, the set of the two factors "labor" and "capital".

Below in Table 4.4, we have rewritten the selected equations from Table 4.1, this time using the GEMPACK variables and notation as in Tables 4.2 and 4.3. Note that below we also use the GEMPACK convention that "p_" indicates percentage change in the relevant levels variable. For example, p_XH(i) denotes the percentage change in XH(i), household consumption of commodity i. In these equations we use "*" to denote multiplication and "/" to denote division. We also use SUM(i,<set>,<expression>) to denote sums (usually expressed via Greek sigma) over all i in the set <set>; here <set> is SECT or FAC.

Note that below we also use the GEMPACK convention that "p_" indicates percentage change in the relevant levels variable. For example, p_XH(i) denotes the percentage change in XH(i), household consumption of commodity i. In these equations we use "*" to denote multiplication and "/" to denote division. We also use SUM(i,<set>,<expression>) to denote sums (usually expressed via Greek sigma) over all i in the set <set>; here <set> is SECT or FAC.

Table 4.4 Stylized Johansen equations in GEMPACK notation
        Equation                                      Subscripts         No. in DPPW
(E1)  p_XH(i)   = p_Y - p_PC(i)                       i in SECT          E3.2.1
(E2)  p_XC(i,j) = p_XCOM(j) - [p_PC(i) - p_PC(j)]     i,j in SECT        E3.2.2, E3.2.3
(E3)  p_XF(f,j) = p_XCOM(j) - [p_PF(f) - p_PC(j)]     f in FAC,j in SECT E3.2.2, E3.2.3
(E4)  p_PC(j)   = SUM(i,SECT, ALPHACOM(i,j)*p_PC(i)) 
                + SUM(f,FAC,  ALPHAFAC(f,j)*p_PF(f))  j in SECT          E3.2.3
(E5)  XCOM(i)   = XH(i) + SUM(j,SECT, XC(i,j))        i in SECT          E3.1.6  
(E6)  XFAC(f)   = SUM(j,SECT, XF(f,j))                f in FAC           E3.1.7  
(E7)  PC("s1")  = 1.                                                     E3.1.23 
(E8)  XC(i,j)   = DVCOMIN(i,j) / PC(i)                i,j in SECT           -
(E9)  XH(i)     = DVHOUS(i) / PC(i)                   i in SECT             -
(E10) XF(f,j)   = DVFACIN(f,j) / PF(f)                f in FAC, j in SECT   -

These equations appear essentially as above in the TABLO Input file (see section 4.3.3 below).

4.2    Data requirements for the linearized equations [gpd1.3.2]

As a general rule, GEMPACK requires an initial levels solution of the model. Thus it is necessary to provide data from which initial (that is, pre-simulation) values of all levels variables and the values of all parameters of the model can be inferred. As we shall see in section 4.2.1 for Stylized Johansen, it is frequently the case that the data required are

Once dollar values are known, it is often possible to set basic prices equal to 1 (this amounts to a choice of units for the related quantities), from which the quantities can be derived by dividing the dollar value by the price. [The choice of 1 for the basic price is, of course, arbitrary. Any other fixed value would be as good.]

4.2.1    Data requirements for Stylized Johansen [gpd1.3.2.1]

Suppose that we know the following pre-simulation dollar values.

DVCOMIN(i,j)    Intermediate inputs
DVHOUS(i)       Household consumption
DVFACIN(f,j)    Factor use by industry 

Then, if we set all the prices to one for

PC(i)           Price of commodities
PF(f)           Price of factors  

we can infer all other levels variables in Table 4.2 as follows.

XC(i,j) = DVCOMIN(i,j) / PC(i)      Intermediate inputs     
XH(i)   = DVHOUS(i) / PC(i)         Household use     
XF(f,j) = DVFACIN(i,j) / PF(f)      Factor use     
Y       = SUM(i, SECT, DVHOUS(i))   Household expenditure 

The only other quantities in the equations (E1)-(E10) are the parameters ALPHACOM(i,j) and ALPHAFAC(f,j) in (E4). Because there is a Cobb-Douglas production function involved, it is well-known that these are cost shares, namely

ALPHACOM(i,j) = DVCOMIN(i,j) / DVCOSTS(j),     
ALPHAFAC(f,j) = DVFACIN(f,j) / DVCOSTS(j), 

where DVCOSTS(j) is an abbreviation for

SUM(i, SECT, DVCOMIN(i,j)) + SUM(f, FAC,  DVFACIN(f,j)),

the total costs in industry j. [These results are easily obtained from equations (E3.1.10) and (E3.1.12) in DPPW.]

Thus the only data requirements are the dollar values

DVHOUS(i),  DVCOMIN(i,j)  and  DVFACIN(f,j)

One instance of the data required is as shown in the body of Table 3.1 in section 3.1.1 above.

In the TABLO Input file, the pre-simulation values of these data will be read and the values of all others will be calculated from them.

4.3    Constructing the TABLO input file for a model [gpd1.3.3]

The TABLO Input file of the model is the means of communicating the theory of the model to the computer, in particular to the GEMPACK program TABLO. It consists of the equations written in a syntax which is very similar to ordinary algebra. It also contains a description of the data to be read, where it is to be read from, and how this data is to be used to calculate values of parameters and pre-simulation values of the other levels variables occurring in the equations.

The main part of a TABLO Input file is the equations, which usually come at the end of the file. Before the equations must come

The order of these in the TABLO Input file is somewhat flexible but follows the general rule that items cannot be used until they have been declared. Thus the SET statements (saying which sets are involved) usually come first. Then the declarations of data files (via FILE statements) often come next, followed by the declarations of the VARIABLEs and parameters.

These ideas are best learnt and understood by example. Hence we launch straight into the preparation of the TABLO Input file for Stylized Johansen.

4.3.1    Viewing the TABLO input file [gpd1.3.3.1]

When working with GEMPACK, many of the input files that you create are text files, so you need a text editor. You can use any text editor you are familiar with.

GEMPACK includes two text editors, TABmate and GemEdit. We suggest you use TABmate since it has coloured highlighting of TABLO syntax, and a powerful Gloss feature which displays all parts of the TABLO code where a chosen variable or coefficient is used. If TABmate is not the default editor in WinGEM, select, in the WinGEM main menu,

Options | Change editor...

then select your editor Use TABmate. You should only have to do this once: WinGEM should remember which editor you chose.

Open the TABLO Input file for Stylized Johansen SJ.TAB in the TABmate editor. In WinGEM, to edit a text file, select in the WinGEM menu,

File | Edit file...

The edit box should show various files in the directory C:\SJ. If the Open box does not start at the correct directory C:\SJ, set the Working directory again as described in section 3.4.2.

Select the file SJ.TAB, the TABLO Input file for the Stylized Johansen model.

Search the TABLO Input file for "EQUATION House" using Search | Find. We will discuss the details of this equation in the next section.

4.3.2    Constructing part of the TABLO input file for Stylized Johansen [gpd1.3.3.2]

In this subsection we consider just two equations of Stylized Johansen, namely (E9) and (E4) in section 4.1.1 above. We show how these are written in the TABLO Input file. (We show the full TABLO Input file in section 4.3.3 and then discuss the rest of this file in section 4.3.4 below.)

Equation (E9)

Consider the very simple equation (E9) relating prices, quantities and dollar values of household consumption.

In the TABLO Input file this equation is written as2

EQUATION House # Household demand for commodity i #
    (all,i,SECT) XH(i) = DVHOUS(i) / PC(i) ;

where

For this equation to be meaningful, we must explain in the TABLO Input file all the names used in the equation.

The levels variables are declared (that is, explained) via the statements

VARIABLE (all,i,SECT) XH(i)  .    # Household demand for commodity i # ; 
VARIABLE (all,i,SECT) DVHOUS(i).  # Dollar value of household use of commodity i # ; 
VARIABLE (all,i,SECT) PC(i)       # Price of commodity i # ;

Notice that, by convention, these declarations also declare associated linear variables p_XH, p_DVHOUS and p_PC which denote the percentage-change in the relevant levels variables. These linear variable names are used in reporting simulation results (see the results in section 3.7 above, for example) and are available for use in linearized equations in the TABLO Input file (see, for example, the EQUATION named "Price_formation" discussed later in this section) without further explicit declaration.

The fact that SECT is a set with two sectors "s1" and "s2" in it is indicated via the SET statement

SET SECT  # Sectors #   (s1-s2) ;

We must also indicate how pre-simulation values of the levels variables can be read or calculated from the data base. We do this via the statements

READ DVHOUS  from FILE iodata HEADER "HCON" ; 
FORMULA (all,i,SECT)   PC(i) = 1 ; 
FORMULA (all,i,SECT)   XH(i) = DVHOUS(i)/PC(i) ;

In the first of the above statements,

In the second and third statements, FORMULA is the keyword.

The third of these contains the same expression as the equation we are considering. Indeed, we can combine the EQUATION and FORMULA into a single statement on the TABLO Input file, namely.3

FORMULA & EQUATION House # Household demand for commodity i #
  (all,i,SECT)   XH(i) = DVHOUS(i) / PC(i) ;

The statement

FILE iodata # input-output data for the model # ;

declares "iodata" as the logical name4 of the file containing the actual data.

This ends the discussion of the equation (E9) and of all the statements needed for the EQUATION House.

Using the Gloss feature in TABmate

In TABmate, there is a quick way of finding all places where a name such as XH occurs in the TABLO Input file SJ.TAB. In TABmate, click on TABLO Check in the bar near the top of the TABmate screen5. Click on the word EQUATION in the "EQUATION House" and then click on Gloss in the bar near the top of the TABmate screen. A box (shown below) appears showing all names used in the EQUATION House in the TABLO Input file.

FORMULA & EQUATION House # Household demand for commodity i # 
   (all,i,SECT) XH(i) = DVHOUS(i) / PC(i) ;
Line
~41: SET SECT # Sectors # (s1-s2) ;
~69: Coefficient Variable (GE 0) (all,i,SECT) XH(i) # Household demand for commodity i # ;
~86: Coefficient Variable (GE 0) (all,i,SECT) DVHOUS(i)
                                        # Dollar value of household use of commodity i # ;
~59: Coefficient Variable (GE 0) (all,i,SECT) PC(i) # Price of commodity i # ;

Click on the X in the top right-hand corner of the Glossary box to exit from the Gloss box.

Click on the word XH in the "EQUATION House" and then click on the Gloss button. The Gloss box (shown below) appears showing all occurrences of the name XH in the TABLO Input file.

Coefficient   XH
Line
~69: Variable (GE 0) (all,i,SECT) XH(i) # Household demand for commodity i # ;
~138: FORMULA & EQUATION House # Household demand for commodity i #
   (all,i,SECT) XH(i) = DVHOUS(i) / PC(i) ;
~142: FORMULA & EQUATION Com_clear # Commodity market clearing #
   (all,i,SECT) XCOM(i) = XH(i)+SUM(j,SECT,XC(i,j));

Try clicking on the word DVHOUS to see where DVHOUS is used in the TABLO Input file SJ.TAB.

Equation (E4)

Now consider the equation (E4) "price formation for commodities". This is written in the TABLO Input file as

EQUATION (LINEAR) Price_formation 
         (all,j,SECT) p_PC(j) = SUM(i,SECT, ALPHACOM(i,j)*p_PC(i)) +
                                SUM(f,FAC,  ALPHAFAC(f,j)*p_PF(f)) ; 

in which

VARIABLE (all,i,SECT) PC(i) # Price of commodity i # ; 
VARIABLE (all,f,FAC)  PF(f) # Price of factor f # ;

the associated linear variables p_PC(i) and p_PF(f) are automatically considered declared. In this equation, ALPHACOM and ALPHAFAC are parameters. To calculate ALPHACOM and ALPHAFAC from the data base, FORMULA statements are used:

FORMULA  .# Share of intermediate commodity i in costs of industry j # 
(all,i,SECT)(all,j,SECT)  ALPHACOM(i,j) = DVCOMIN(i,j) /
    [SUM(ii,SECT,DVCOMIN(ii,j)) + SUM(ff,FAC,DVFACIN(ff,j)) ] ;
FORMULA  .# Share of factor input f in costs of industry j # 
(all,f,FAC)(all,j,SECT)  ALPHAFAC(f,j) = DVFACIN(f,j) /
    [SUM(ii,SECT,DVCOMIN(ii,j)) + SUM(ff,FAC,DVFACIN(ff,j)) ] ;

where FORMULA is the keyword. The fact that ALPHACOM and ALPHAFAC are parameters can be indicated via the statements

COEFFICIENT(PARAMETER) (all,i,SECT)(all,j,SECT) ALPHACOM(i,j) ;
COEFFICIENT(PARAMETER) (all,f,FAC) (all,j,SECT) ALPHAFAC(f,j) ;

in which COEFFICIENT is the keyword and (PARAMETER) is a qualifier.

If you are using the TABmate editor, try using the Gloss button. Click on the word p_PC in the EQUATION Price_formation and click on the Gloss button to see all occurrences of p_PC in the TABLO Input file SJ.TAB. Click on the word "FAC" and Gloss to see all occurrences of the set FAC.

This ends the discussion of the equation (E4) and of all the statements needed for the EQUATION Price_formation.

Statements in a TABLO Input File

The main types of statements in a TABLO Input file, namely EQUATIONs, FORMULAs, READs, VARIABLEs, COEFFICIENTs, SETs and FILEs have been introduced in connection with equations House (E9) and Price_formation (E4) above

Each entity (VARIABLE, COEFFICIENT, etc) must be declared in the TABLO Input file before it is used in EQUATIONs and FORMULAs. This partly determines the order of the statements in the TABLO Input file.

We suggest that you now look at the complete TABLO Input file for this model, as set out in section 4.3.3 below, or using the editor TABmate (or your text editor). This file is usually called SJ.TAB when supplied with the GEMPACK Examples. You will find all the statements shown above in that file.

Since declarations must come before use, you will find the TABLO statements in pretty much the reverse order from that in which we have introduced them above.

We discuss the rest of this TABLO Input file in section 4.3.4.6

4.3.3    "Mixed" TABLO input file for the Stylized Johansen model [gpd1.3.3.3]

!-------------------------------------------------------------------! 
!                  Mixed TABLO Input file for the                   ! 
!                    Stylized Johansen model                        !
!                                                                   !
!         following the description in Chapter 3 of the text        ! 
!   "Notes and Problems in Applied General Equilibrium Economics"   ! 
!       by P.Dixon, B.Parmenter, A.Powell and P.Wilcoxen [DPPW]     ! 
!              published by North-Holland 1992.                     ! 
!                                                                   ! 
!-------------------------------------------------------------------!  
! Text between exclamation marks is a comment.                      ! 
! Text between hashes (#) is labelling information.                 !  
!-------------------------------------------------------------------! 
!     Set default values                                            ! 
!-------------------------------------------------------------------! 
VARIABLE (DEFAULT = LEVELS) ; 
EQUATION (DEFAULT = LEVELS) ; 
COEFFICIENT (DEFAULT = PARAMETER) ; 
FORMULA (DEFAULT = INITIAL) ;  
!-------------------------------------------------------------------! 
!      Sets                                                         ! 
!-------------------------------------------------------------------!  
! Index values i=1,2 in DPPW correspond to the sectors called s1,s2. 
  Index values i=3,4 in DPPW correspond to the primary factors, 
  labor and capital.   The set SECT below doubles as the set of  
  commodities  and the set of industries. !  
SET SECT # Sectors # (s1-s2)  ;  
SET FAC # Factors  # (labor, capital) ;  
SET NUM_SECT # Numeraire sector - sector 1 #  (s1) ;  
SUBSET  NUM_SECT is subset of SECT ;  
!-------------------------------------------------------------------! 
!      Levels variables                                             ! 
!-------------------------------------------------------------------!  
! In the DPPW names shown below, : denotes subscript.               ! 
! For example, x:j indicates that j is a subscript.                 ! 
VARIABLE               Y    # Total nominal household expenditure #
                              ! This is also Y in DPPW ! ; 
VARIABLE (all,i,SECT)  PC(i)   # Price of commodity i #
                                ! This is p:i (i=1,2) in DPPW ! ; 
VARIABLE (all,f,FAC)   PF(f)   # Price of factor f #
                                ! This is p:i (i=3,4) in DPPW ! ; 
VARIABLE (all,i,SECT)  XCOM(i)   ! This is x:i (i=1,2) in DPPW !
       # Total demand for (or supply of) commodity i # ;
VARIABLE (all,f,FAC)   XFAC(f)   ! This is x:i (i=3,4) in DPPW !
      # Total demand for (or supply of) factor f    # ; 
VARIABLE (all,i,SECT)  XH(i)   # Household demand for commodity i #
                                ! This is x:i0 (i=1,2) in DPPW ! ; 
VARIABLE (all,i,SECT) (all,j,SECT)     XC(i,j)
      # Intermediate inputs of commodity i to industry j #
     ! This is x:ij (i,j=1,2) in DPPW ! ; 
VARIABLE (all,f,FAC)(all,j,SECT)       XF(f,j)
      # Factor inputs to industry j #
     ! This is x:ij (i=3,4; j=1,2) in DPPW ! ;  
!-------------------------------------------------------------------! 
!     Dollar values read in from database                           ! 
!-------------------------------------------------------------------! 
VARIABLE (all,i,SECT)(all,j,SECT)      DVCOMIN(i,j)
      # Dollar value of inputs of commodity i to industry j # ; 
VARIABLE (all,f,FAC)(all,j,SECT)       DVFACIN(f,j)
     # Dollar value of factor f used in industry j # ; 
VARIABLE (all,i,SECT)                  DVHOUS(i)
      # Dollar value of household use of commodity i # ;  
!-------------------------------------------------------------------!
!     Parameters                                                    ! 
!-------------------------------------------------------------------! 
COEFFICIENT (all,i,SECT)(all,j,SECT)  ALPHACOM(i,j)
   # Share of intermediate use of commodity i in costs of industry j # ;
COEFFICIENT (all,f,FAC)(all,j,SECT)   ALPHAFAC(f,j)
   # Share of factor input f in costs of industry j # ;  
!-------------------------------------------------------------------! 
!      File                                                         ! 
!-------------------------------------------------------------------!  
FILE iodata # input-output data for the model # ;  
!-------------------------------------------------------------------! 
!      Reads from the data base                                     ! 
!-------------------------------------------------------------------!  
READ DVCOMIN from FILE iodata HEADER "CINP" ; 
READ DVFACIN from FILE iodata HEADER "FINP" ; 
READ DVHOUS  from FILE iodata HEADER "HCON" ; 
!-------------------------------------------------------------------!
!      Formulas                                                     ! 
!-------------------------------------------------------------------! 
FORMULA (all,i,SECT) PC(i) = 1.0 ; 
FORMULA (all,i,FAC) PF(i) = 1.0 ; 
FORMULA (all,i,SECT)(all,j,SECT) ALPHACOM(i,j) = DVCOMIN(i,j) /
            [SUM(ii,SECT,DVCOMIN(ii,j)) + SUM (ff,FAC,DVFACIN(ff,j))] ;
FORMULA (all,f,FAC)(all,j,SECT) ALPHAFAC(f,j) = DVFACIN(f,j) /
            [SUM(ii,SECT,DVCOMIN(ii,j)) + SUM (ff,FAC,DVFACIN(ff,j))] ;

! Formula to give initial value of Y !
FORMULA Y = SUM(i,SECT,DVHOUS(i)) ;
!-------------------------------------------------------------------! 
!       Formulas and levels equations                               ! 
!-------------------------------------------------------------------! 
FORMULA & EQUATION Comin
     # Intermediate input of commodity i to industry j #
   (all,i,SECT)(all,j,SECT) XC(i,j) = DVCOMIN(i,j) / PC(i) ;  
FORMULA & EQUATION Facin      # Factor input f to industry j #
 (all,f,FAC)(all,j,SECT) XF(f,j) = DVFACIN(f,j) / PF(f) ;
FORMULA & EQUATION House      # Household demand for commodity i #
 (all,i,SECT) XH(i) = DVHOUS(i) / PC(i) ;         
FORMULA & EQUATION Com_clear ! (E3.1.6) in DPPW !
    # Commodity market clearing #
 (all,i,SECT) XCOM(i) = XH(i) + SUM(j,SECT,XC(i,j)) ;  
FORMULA & EQUATION Factor_use ! (E3.1.7) in DPPW !
     # Aggregate primary factor usage #
 (all,f,FAC) XFAC(f) = SUM(j,SECT,XF(f,j)) ;  
!-------------------------------------------------------------------! 
!      Equations                                                    ! 
!-------------------------------------------------------------------! 
EQUATION(LINEAR)  Consumer_demands ! (E3.2.1) in DPPW !
     # Household expenditure functions #
 (all,i,SECT) p_XH(i) = p_Y - p_PC(i) ;
EQUATION(LINEAR)  Intermediate_com
! From (E3.2.2) with i=1,2 in DPPW. The term p_PC(j) is included
   because of (E3.2.3) in DPPW. !
    # Intermediate demands for commodity i by industry j #
(all,i,SECT)(all,j,SECT) p_XC(i,j) = p_XCOM(j) - (p_PC(i) - p_PC(j)) ;
EQUATION(LINEAR)  Factor_inputs
! From (E3.2.2) with i=3,4 in DPPW. The term p_PC(j) is included
   because of (E3.2.3) in DPPW. !
    # Factor input demand functions #
(all,f,FAC)(all,j,SECT) p_XF(f,j) = p_XCOM(j) - (p_PF(f) - p_PC(j)) ;
EQUATION(LINEAR) Price_formation   ! (E3.2.3) in DPPW !
     # Unit cost index for industry j #
 (all,j,SECT) p_PC(j) = SUM(i,SECT,ALPHACOM(i,j)*p_PC(i)) + 
                               SUM(f,FAC,ALPHAFAC(f,j)*p_PF(f)) ;
EQUATION Numeraire  ! (E3.1.23) in DPPW !
     # Price of commodity 1 is the numeraire #
 (all,i,NUM_SECT)  PC(i) = 1 ;
!--------------end of TABLO Input file------------------------------! 

4.3.4    Completing the TABLO input file for Stylized Johansen [gpd1.3.3.4]

Notice that the TABLO Input file consists of a number of statements, each beginning with its relevant keyword (such as SET or VARIABLE). Some statements include a qualifier such as (LINEAR) in EQUATION(LINEAR). Each statement ends with a semicolon ';'. Text between exclamation marks '!' is treated as a comment; such text can go anywhere in the TABLO Input file. Text between hashes '#' is labelling information; the positioning of this labelling information is restricted (see chapter 10 for full details).

The TABLO Input file is not case-sensitive so for example, XH and Xh would be identical so far as TABLO is concerned.

First come the DEFAULT statements. In TABLO Input files, EQUATIONs and VARIABLEs can be linear or levels. It is possible to distinguish each type by using the appropriate qualifier (LEVELS) or (LINEAR) after the keyword each time, as in, for example,

VARIABLE (LEVELS) Y # Nominal household expenditure # ; 
VARIABLE (LINEAR) (all,f,FAC) p_PF(f) # Price of factors # ; 

When most variables being declared are levels variables, it seems wasteful to have to keep repeating the qualifier (LEVELS). There are DEFAULT statements which allow you to reduce the number of qualifiers required in your TABLO Input files. If you put the statement

VARIABLE (DEFAULT = LEVELS) ;

early in a TABLO Input file, then, after it, any VARIABLE declaration is taken as the declaration of a levels variable unless a different qualifier (LINEAR) is present. Similarly for EQUATIONs coming after the statement

EQUATION (DEFAULT = LEVELS) ;

Of course, if most equations in your TABLO Input file are linearized ones, you could put the opposite default statement

EQUATION (DEFAULT = LINEAR) ;

near the start of your file, and then you would only have to flag, using the qualifier (LEVELS), the levels equations.

Similarly, the statements

COEFFICIENT (DEFAULT = PARAMETER) ; 
FORMULA (DEFAULT = INITIAL) ;

set the default types for COEFFICIENTs declared and FORMULAs. The only COEFFICIENTs in the TABLO Input file in section 4.3.3 above are parameters, while the only FORMULAs are used to set initial values (that is, pre-simulation values) of levels variables, or to set the values of the parameters. You will see non-parameter COEFFICIENTs and non-initial FORMULAs in section 4.4.1 below, when you look at linearized TABLO Input files.

Next come the declarations of the SETs, namely SECT (sectors) and FAC (primary factors). A further set NUM_SECT to stand for the single numeraire sector (sector s1) is also defined; this is only used for the last of the equations, the numeraire equation. The reason for the SUBSET statement will be explained when we discuss that equation below.

Then come the declarations of the VARIABLEs. Note that the arguments (if any) of each are clearly described, using the "(all,<index>,<set-name>)" quantifier(s) at the start of the declarations.

These quantifiers refer to the SETs, which is why the SET declarations must precede the VARIABLE declarations. The variables declared are all levels variables (because of the DEFAULT statement earlier). Although not explicitly mentioned here, the associated linear variables p_Y, p_XH etc are taken as automatically declared by convention, and can be used in subsequent EQUATIONs without further explicit declaration.

Then comes the declaration of the parameters - which must always be declared as COEFFICIENTs. The qualifier (PARAMETER) is not needed here because of the earlier DEFAULT(COEFFICIENT=PARAMETER) statement.

Next comes the declaration of the single data FILE required. This file is given the logical name 'iodata'. The actual name of the file on your computer containing this data is not limited by this logical name. You can give the actual file any convenient name. GEMSIM or the TABLO-generated program will prompt you for this actual name when you run it; the prompt will use the logical name 'iodata' from the TABLO Input file. Or, if you use a GEMPACK Command file (as we recommend), you will need to use the logical name as well as the actual name in the relevant statement (for example, "file iodata = SJ.HAR ;"). See section 22.1 for more details.

Then come READ statements telling the program to read in initial (that is, pre-simulation) values of certain levels variables. Each READ statement says from where the data is to be read (that is, which file and which header on the file).

Next come some FORMULAs assigning initial values to other levels variables. The left-hand side of a FORMULA (that is, the part before the '=' sign) must be a simple VARIABLE or COEFFICIENT, but the right-hand side can be a complicated expression. In such an expression, the symbols for the arithmetic operations are '+' and '-' for addition and subtraction, '*' and '/' for multiplication and division, and '^' for exponentiation. Note that '*' must be shown explicitly wherever multiplication is required. Notice also the use of the syntax

SUM(<index>,<set-name>, <expression to be summed> )

to express sums over sets.

Finally come the EQUATIONs (see (E1) to (E10) in section 4.1.1 above). As explained in section 4.3.2, some of these double as FORMULAs, in which case the statement must begin with FORMULA & EQUATION to indicate that there are really two statements here.

The syntax of the last equation (the numeraire equation) may surprise you. We could have expressed this as

PC("s1") = 1 ;

using the sector element name "s1" to indicate which price is fixed at one. Instead we have introduced the new set NUM_SECT consisting of just this sector "s1" and written the equation as

(all,i,NUM_SECT)  PC(i) = 1 ;

This illustrates the point of SUBSET declarations. The VARIABLE PC has been declared to have one argument ranging over the set SECT, but here we need to give it an argument ranging over the smaller set NUM_SECT. The earlier SUBSET statement

SUBSET  NUM_SECT  is subset of  SECT ;

alerts TABLO to the fact that an argument ranging over NUM_SECT is always in the set SECT. Without this, the use of PC(i) with i ranging over NUM_SECT would trigger a semantic error since TABLO checks that all arguments range over appropriate sets.

As stated earlier, the order of the statements in the TABLO Input file can be varied. For example, especially with larger models, some COEFFICIENTs may only be relevant to a small number of the EQUATIONs and it may be better to declare these and assign values to them just before the relevant EQUATION or group of EQUATIONs.

WRITE statements send the values of COEFFICIENTs (or levels VARIABLEs) to a file so you can examine them (or use them as a input to another program). Try this out by adding the following statements at the end of the TABLO Input file for Stylized Johansen and then re-running Steps 1, 2 and 3 in chapter 3.

File (new) Output;
Write ALPHACOM to file Output header "ACOM";
Write ALPHAFAC to file Output header "AFAC";

You'll also need to add into the CMF the line:

file Output = <cmf>out.har;

Complete documentation of TABLO Input files is given in chapters 8 to 18, which you will need to consult when you start to build a new model.

4.3.5    Change or percentage-change variables [gpd1.3.3.5]

Many levels variables (for example, prices, quantities, dollar values) are always positive and so it is natural for the associated linear VARIABLE to be a percentage change.

However, when the relevant levels variable can be positive or zero or negative (examples are the Balance of Trade and an ad valorem tax rate), it is wiser to specify that the associated linear VARIABLE is an ordinary change. This is because, in such a case, if the levels value happens to be zero at the start of any step of a multi-step simulation, the associated percentage change could not be calculated (since it would require division by zero). Also, there are often numerical problems (which slow or hinder convergence of the solutions) when a percentage-change variable changes sign in the levels; these problems may be overcome if an ordinary change variable is used because then TABLO works with a slightly different linearization of the EQUATIONs involving this VARIABLE.7 In summary, we suggest the following guidelines.

The (CHANGE) qualifier tells TABLO to automatically declare the associated linear variable as an ordinary change (the prefix "c_" is usually added to the levels name).8 For example, if you have a declaration

VARIABLE (CHANGE) BT  # Balance of trade # ;

in your TABLO Input file, the associated change linear variable c_BT is automatically available for use in linearized equations and will be used in reporting simulation results. Alternatively a linear change variable can be declared directly, using the two qualifiers LINEAR and CHANGE as in.

VARIABLE (LINEAR,CHANGE) delB  # Change in trade balance # ;

(When you declare a linear change variable explicitly, you are not required to begin the name with "c_".)

4.3.6    Variable or parameter ? [gpd1.3.3.6]

When you build a model, you have in mind the sorts of questions you will be using the model to answer. You may be thinking of holding some quantities constant and varying others.

Within GEMPACK, the quantities you may wish to vary will be declared as VARIABLEs while those which cannot vary can be declared as COEFFICIENT(PARAMETER)s.

Traditionally GEMPACK users declare as VARIABLEs (rather than as parameters) any quantity which might conceivably vary.9 For example, you may have a model which includes tax rates which you do not (at present) intend to vary. You could declare them as COEFFICIENT(PARAMETER)s but it may be more useful to declare them as VARIABLEs. In the latter case, you can convey the fact that they do not vary by indicating that the VARIABLEs are exogenous and not shocked.10 Later, if you wish to model the consequences of these tax rates changing, you do not have to change the model.

In Stylized Johansen, there are only two exogenous variables, the supplies of the primary factors labor and capital, so this issue does not arise. However, it does arise in most of the more serious models implemented via GEMPACK. For example, in ORANI-G (see section 60.5), many quantities which do not change in most simulations (for example, household subsistence demands, various technology terms and various shifters) are declared as Variables rather than as Parameters.

4.3.7    TABLO language - syntax and semantics [gpd1.3.3.7]

Full details of the syntax and semantics used in TABLO Input files are given in chapters 10 to 11. The description there applies to all TABLO Input files - that is, to those containing just levels equations, just linearized ones and to those (such as the one in section 4.3.3 above) containing a mixture of levels and linearized equations. We will introduce more information about the syntax and semantics in sections 4.4 and 4.5 below (where we describe alternative TABLO Input files for Stylized Johansen, firstly one containing just linearized equations and secondly one containing just levels equations).

4.4    Linearized TABLO input files [gpd1.3.4]

The majority of the more well-known models implemented in GEMPACK use a TABLO Input file containing only linearized equations; we refer to such TABLO Input files as linearized TABLO Input files.

We illustrate this by giving in full in section 4.4.1 below such a TABLO Input file for Stylized Johansen. This file is usually called SJLN.TAB when supplied with the GEMPACK Example files.

In comparison with the mixed TABLO Input file for Stylized Johansen in section 4.3.3 above, the main differences to note are as follows.

We give the full TABLO Input file in section 4.4.1 and then discuss noteworthy features of it in section 4.4.2 below.

Advice about linearizing equations by hand can be found in section 18.2.

4.4.1    A linearized TABLO input file for Stylized Johansen [gpd1.3.4.1]

!-------------------------------------------------------------------!
!               Linearized TABLO Input file for the                 !
!                       Stylized Johansen model                     !
!           following the description in Chapter 3 of the text      !
!    "Notes and Problems in Applied General Equilibrium Economics"  !
!       by P.Dixon, B.Parmenter, A.Powell and P.Wilcoxen [DPPW]     !
!                published by North-Holland 1992.                   !
!-------------------------------------------------------------------!
! Text between exclamation marks is a comment.                      !                        
! Text between hashes (#) is labelling information.                 !
!-------------------------------------------------------------------!
!      Sets                                                         !
!-------------------------------------------------------------------!
! Index values i=1,2 in DPPW correspond to the sectors called s1,s2.
  Index values i=3,4 in DPPW correspond to the primary factors, labor 
  and capital.   The set SECT below doubles as the set of 
  commodities  and the set of industries. !
SET
 SECT # Sectors # (s1-s2)  ;
 FAC # Factors  # (labor, capital) ;
 NUM_SECT # Numeraire sector - sector 1 #  (s1) ;
SUBSET  NUM_SECT is subset of SECT ;
!-------------------------------------------------------------------!
!  File                                                             !
!-------------------------------------------------------------------!
 FILE iodata # the input-output data for the model # ;
!-------------------------------------------------------------------!
VARIABLE ! All variables are percent changes in relevant levels quantities !
!  In the DPPW names shown below,  : denotes subscript.             !
!  Thus, for example,   x:j indicates that j is a subscript.        !
 (ORIG_LEVEL=Y) p_Y  # Total household expenditure [DPPW y]#; 
 (ORIG_LEVEL=1) (all,i,SECT) p_PC(i) 
     # Price of commodities [DPPW p:i (i=1,2)]#;
 (ORIG_LEVEL=1) (all,f,FAC) p_PF(f)  
     # Price of factors [DPPW p:i  (i=3,4)]#;
 (ORIG_LEVEL=DVCOM) (all,i,SECT) p_XCOM(i)  
     # Total demand for (or supply of) commodities [DPPW x:i (i=1,2)]#;
 (ORIG_LEVEL=DVFAC) (all,f,FAC) p_XFAC(f)  
     # Total demand for (or supply of) factors [DPPW x:i  (i=3,4)]#;
 (ORIG_LEVEL=DVHOUS) (all,i,SECT) p_XH(i)  
     # Household consumption of commodities [DPPW x:i0  (i=1,2)]#;
 (ORIG_LEVEL=DVCOMIN) (all,i,SECT)(all,j,SECT) p_XC(i,j)  
     # Intermediate commodity inputs [DPPW x:ij  (i,j=1,2)]#;
 (ORIG_LEVEL=DVFACIN) (all,f,FAC)(all,j,SECT) p_XF(f,j)  
     # Intermediate factor inputs [DPPW x:ij  (i=3,4; j=1,2)]#;
!-------------------------------------------------------------------!
!  Base data, updates and reads                                     !
!   (Base data is as in Table E3.3.1 of DPPW)                       !
!-------------------------------------------------------------------!
 COEFFICIENT (GE 0)  (all,i,SECT)(all,j,SECT) DVCOMIN(i,j)  
   # Dollar value of inputs of commodity i to industry j # ;
 UPDATE (all,i,SECT)(all,j,SECT) DVCOMIN(i,j) = p_PC(i)*p_XC(i,j) ;

 COEFFICIENT (GE 0)  (all,f,FAC)(all,j,SECT)  DVFACIN(f,j)  
   # Dollar value of inputs of factor f to industry j # ;
 UPDATE (all,f,FAC)(all,j,SECT)  DVFACIN(f,j) = p_PF(f)*p_XF(f,j) ;

 COEFFICIENT (GE 0)  (all,i,SECT) DVHOUS(i)  
   # Dollar value of household use of commodity i # ;
 UPDATE (all,i,SECT)             DVHOUS(i) = p_PC(i)*p_XH(i) ;
!-------------------------------------------------------------------!
!  Reads from the data base                                         !
!-------------------------------------------------------------------!
 READ DVCOMIN FROM FILE iodata HEADER "CINP" ;
 READ DVFACIN FROM FILE iodata HEADER "FINP" ;
 READ DVHOUS  FROM FILE iodata HEADER "HCON" ;
!-------------------------------------------------------------------!
!  Other coefficients and formulas for them                         !
!-------------------------------------------------------------------!
 COEFFICIENT  Y    # Total nominal household expenditure # ;
 FORMULA Y = SUM(i,SECT,DVHOUS(i)) ;

 COEFFICIENT (all,i,SECT) DVCOM(i) # Value of total demand for commodity i # ;
 FORMULA     (all,i,SECT) DVCOM(i) = SUM(j,SECT, DVCOMIN(i,j)) + DVHOUS(i) ;
 
 COEFFICIENT (all,f,FAC) DVFAC(f) # Value of total demand for factor f # ;
 FORMULA     (all,f,FAC) DVFAC(f) =  SUM(j,SECT,DVFACIN(f,j)) ;

 COEFFICIENT(PARAMETER)   (all,i,SECT)(all,j,SECT) ALPHACOM(i,j)  
   # alpha(i,j) - commodity parameter in Cobb-Douglas production function # ;
   ! = initial share of commodity i in total inputs to industry j  
     This is  alpha:ij  (i=1,2; j=1,2) in (E3.1.4) of DPPW ! 
 FORMULA(INITIAL)(all,i,SECT)(all,j,SECT) ALPHACOM(i,j) = DVCOMIN(i,j)/DVCOM(j);
 
COEFFICIENT(PARAMETER)   (all,f,FAC)(all,j,SECT) ALPHAFAC(f,j)  
   # alpha(f,j) - factor parameter in Cobb-Douglas production function. #;
   ! = initial share of factor f in total inputs to industry j  
     This is  alpha:ij  (i=3,4; j=1,2) in (E3.1.4) of DPPW !  
 FORMULA(INITIAL)(all,f,FAC)(all,j,SECT) ALPHAFAC(f,j) = DVFACIN(f,j)/DVCOM(j);

 COEFFICIENT   (all,i,SECT)(all,j,SECT) BCOM(i,j)  
   # beta(i,j) - share of industry j in total demand for commodity i # ; 
   ! This is  beta:ij  (i=1,2; j=1,2) in (E3.2.4) of DPPW !  
 FORMULA   (all,i,SECT)(all,j,SECT) BCOM(i,j) = DVCOMIN(i,j)/DVCOM(i) ;

 COEFFICIENT   (all,i,SECT)  BHOUS(i)  
   # beta(i,0) - share of households in total demand for commodity i # ; 
   ! This is  beta:i0  (i=1,2) in (E3.2.4) of DPPW !  
 FORMULA   (all,i,SECT) BHOUS(i) = DVHOUS(i)/DVCOM(i) ;

 COEFFICIENT   (all,f,FAC)(all,j,SECT) BFAC(f,j)  
   # beta(f,j) - share of industry j in total demand for factor f #; 
   ! This is  beta:ij  (i=3,4; j=1,2) in (E3.2.5) of DPPW !  
 FORMULA   (all,f,FAC)(all,j,SECT) BFAC(f,j) = DVFACIN(f,j)/DVFAC(f) ;
!-------------------------------------------------------------------!
!  Equations (Linearized)                                           !
!-------------------------------------------------------------------!
EQUATION  Consumer_demands # Household expenditure functions [DPPW E3.2.1]# 
(all,i,SECT) p_XH(i) = p_Y - p_PC(i) ;

EQUATION  Intermediate_com # Intermediate demands [DPPW E3.2.2 i=1,2]#
! The term p_PC(j) is included because of (E3.2.3) in DPPW. !
(all,i,SECT)(all,j,SECT) p_XC(i,j) = p_XCOM(j) - (p_PC(i) - p_PC(j)) ;

EQUATION  Factor_inputs # Factor input demand functions [DPPW E3.2.2 i=3,4]#
! The term p_PC(j) is included because of (E3.2.3) in DPPW. !
(all,f,FAC)(all,j,SECT) p_XF(f,j) = p_XCOM(j) - (p_PF(f) - p_PC(j)) ;

EQUATION  Price_formation  # Unit cost index for industry j [DPPW E3.2.3]#
    (all,j,SECT) p_PC(j) = SUM(i,SECT,ALPHACOM(i,j)*p_PC(i)) +
                           SUM(f,FAC,ALPHAFAC(f,j)*p_PF(f)) ;

EQUATION Com_clear # Commodity market clearing [DPPW E3.2.4]#
   (all,i,SECT) p_XCOM(i) = BHOUS(i)*p_XH(i) + SUM(j,SECT,BCOM(i,j)*p_XC(i,j)); 
 
EQUATION Factor_use # Aggregate primary factor usage [E3.2.5 in DPPW]#
   (all,f,FAC) p_XFAC(f) = SUM(j,SECT,BFAC(f,j)*p_XF(f,j)) ; 
 
EQUATION NUMERAIRE # Numeraire is price of commodity 1 [DPPW E3.2.6]#
   (all,i,NUM_SECT)  p_PC(i) = 0; 
   ! Alternatively, this could be written as   p_PC( "s1" ) = 0 !
!-------------------------------------------------------------------!
!      Balance check for data base                                  !
!-------------------------------------------------------------------!
! In a balanced data base, total demand for commodity i, DVCOM(i) 
   should equal DVCOST(i), the total cost of inputs to industry i !
![[!
! To check that total demand = total costs to industry i
   remove the strong comment markers ![[! ... !]]! around  this section   !
COEFFICIENT (all,i,SECT) DVCOST(i) # Total cost of inputs to industry i# ;
 FORMULA   (all,i,SECT)
     DVCOST(i) = SUM(u,SECT,DVCOMIN(u,i)) + SUM(f,FAC,DVFACIN(f,i)) ;
  ! Check that the values  of DVCOM and DVCOST are equal !
  DISPLAY DVCOM ;
  DISPLAY DVCOST ; !]]! 
!---------end of TABLO Input file--------------------------------------!

4.4.2    Noteworthy features in the linearized TABLO input file [gpd1.3.4.2]

1. DEFAULT statements

Notice that there are no DEFAULT statements at the start of the linearized file in section 4.4.1. This is because of the convention that all TABLO Input files are assumed to begin with defaults appropriate for linearized TABLO Input files11, namely as if there were the following statements at the start.

VARIABLE (DEFAULT = LINEAR) ; 
EQUATION (DEFAULT = LINEAR) ; 
VARIABLE (DEFAULT = PERCENT_CHANGE) ; 
COEFFICIENT (DEFAULT = NON_PARAMETER) ; 
FORMULA (DEFAULT = ALWAYS) ;  

The purpose of the last of these is discussed under the heading "FORMULAs" below.

2. VARIABLEs

The linear variables are declared explicitly. We have chosen to use the same names as are declared implicitly in the mixed TABLO Input file in section 4.3.3 above. (This makes results from the 2 files easier to compare.) But we could have chosen different names.

The (ORIG_LEVEL=...) qualifiers tell the software what to take as the pre-simulation values for the various levels variables. For example,

VARIABLE  (ORIG_LEVEL=Y)  p_Y  # Total nominal household expenditure # ;

indicates that the pre-simulation levels value of the variable p_Y is Y. Without this ORIG_LEVEL qualifier, you would not see the pre-simulation, post-simulation and changes results in Table 3.3 above when you run a simulation. Similarly

VARIABLE  (ORIG_LEVEL=1)  (all,i,SECT)  p_PC(i) # Price of commodities # ;

tells the software that it can take 1 as the pre-simulation levels values of the PC(i) for each commodity i. Starting with these prices equal to one explains why it is sensible to take the pre-simulation values of the supplies XCOM(i) to be equal to the pre-simulation dollar values DVCOM(i), as indicated in

VARIABLE  (ORIG_LEVEL=DVCOM)  (all,i,SECT)  p_XCOM(i) #...# ;

These ORIG_LEVEL qualifiers are not necessary in the mixed TABLO Input file SJ.TAB shown in section 4.3.3 above since there the linear variable p_Y is derived automatically from Y via the declaration of the levels variable Y, so the software knows the connection between Y and p_Y. [See section 10.4 for documentation about the ORIG_LEVEL qualifier.]

3. COEFFICIENTs

Many of the levels quantities which were declared as levels variables in the mixed TABLO Input file in section 4.3.3 are declared here as COEFFICIENTs. (For example, the dollar values DVHOUS and DVCOM. The first is READ from the data base and the second has its values assigned via a FORMULA.)

It may help to think of these COEFFICIENTs as holding pre-simulation values of the levels variables. However this is not entirely accurate in a multi-step simulation as we see below in the discussion of FORMULAs and UPDATEs.

4. FORMULAs

Most of the FORMULAs in the linearized file are re-evaluated at each step of a multi-step simulation. This is what the qualifier (ALWAYS) denotes in the DEFAULT statement shown in (1.) above. After each step of a multi-step simulation, the data base is updated and all FORMULA(ALWAYS)s are re-evaluated. For example, this ensures that DVCOM is always an accurate reflection of the DVCOMIN and DVHOUS values on the currently updated data base. [A numerical example is in section 4.4.7.]

However some FORMULAs, those with qualifier (INITIAL), are only evaluated on the first step of a multi-step simulation. FORMULAs giving the value of parameters (such as those for ALPHACOM and ALPHAFAC) should only be applied initially (that is, at the first step) since the value of a parameter should not be changed.

5. UPDATEs

The purpose of an UPDATE statement is to tell the software how a COEFFICIENT (that is, a levels variable) changes in response to the small changes in the linear VARIABLEs at each step of a multi-step simulation.

For example, consider DVHOUS(i), the dollar value of household consumption of commodity i.

(a) Suppose there were an explicit linear VARIABLE, say p_DVHOUS(i), declared giving the percentage change in DVHOUS(i). (In fact there is no such VARIABLE in the linearized TABLO Input file.) Then, in response to a change in this, the new value of DVHOUS(i) should be given by

new_DVHOUS(i) = old_DVHOUS(i)*[1 + p_DVHOUS(i)/100]

(On any step, the old value is the value before the step and the new value is the one put on the data base updated after the step.) We would need an UPDATE statement to indicate this. The statement could be

UPDATE (all,i,SECT) DVHOUS(i) = p_DVHOUS(i) ; .

(b) In fact there is no linear VARIABLE declared in the linearized TABLO Input file giving the percentage change in DVHOUS(i). However there are explicit linear VARIABLEs p_PC(i) and p_XH(i) showing the percentage changes in the relevant price and quantity. If p_DVHOUS(i) were declared, there would be a linear EQUATION connecting it to p_PC(i) and p_XH(i). This EQUATION would say that

p_DVHOUS(i) = p_PC(i) + p_XH(i)

Thus, the procedure for updating DVHOUS(i) is

new_DVHOUS(i) = old_DVHOUS(i)*[1 + {p_PC(i)+p_XH(i)}/100]

In fact the UPDATE statement is

UPDATE (all,i,SECT) DVHOUS(i) = p_PC(i) * p_XH(i) ;

This is interpreted by TABLO as having the correct effect (see section 4.4.6 for a numerical example). At first you may be puzzled by the multiplication sign "*" here since the percentage change in DVHOUS(i) is the SUM of p_PC(i) and p_XH(i). However, this form of UPDATE is called a PRODUCT UPDATE because it is used to update a COEFFICIENT (that is, a levels variable) which is the product of 2 or more levels variables whose percentage changes are explicit linear VARIABLEs. Here, in the levels,

DVHOUS(i) = PC(i) * XH(i)

and the "*" used in a PRODUCT UPDATE is to remind you of this levels12 formula.

6. Levels Prices and Quantities not Needed

Notice that no COEFFICIENTs have been declared to hold the levels values of prices or quantities. [For example, there is no COEFFICIENT XH(i) even though there is a VARIABLE p_XH(i).] This is a fairly common feature of linearized TABLO Input files. In such files,

7. Names for Levels and Linearized VARIABLEs

As you have seen above, the levels variables required in a linearized TABLO Input file appear as COEFFICIENTs while the percentage-change (or change) variables required appear as linear VARIABLEs.

It may happen that you need on the TABLO Input file a levels variable as a COEFFICIENT and its percentage change (or change) as a VARIABLE. In this case, since TABLO Input files are not case-sensitive, you cannot follow the convention of using upper case for the levels variables or COEFFICIENTs (for example, XHOUS) and the same name partly or wholly in lower case for the associated linear VARIABLEs (for example, xhous). The problem is most likely to occur for values, which often occur both as COEFFICIENTs and VARIABLEs.

We suggest 3 alternative ways around this problem.

1: Follow a convention that value coefficients start with "V", while the associated percentage change variable begins with "w".For example,

COEFFICIENT  VHOUTOT       VARIABLE  whoutot

2: Use the natural name for the COEFFICIENT version and attach 'p_' (for percentage change) or 'c_' (for change) at the start for the VARIABLE. For example,

COEFFICIENT  XHOUS(i)      VARIABLE  p_XHOUS(i)

3: Use the natural name for the VARIABLE version and attach '_L' (for levels) to the end for the COEFFICIENT. For example,

VARIABLE  xhous(i)         COEFFICIENT  XHOUS_L(i).

Although TABLO Input files are not case-sensitive (meaning that xhous and XHOUS are treated as being the same), we find it makes linearized TABLO Input files more readable if we consistently put linear VARIABLE names in lower case, or consistently put the first letter of all linear VARIABLE names in lower case and the rest in upper case.

4.4.3    Analysing simulation results [gpd1.3.4.3]

Now that you understand about TABLO Input files, you will want to begin learning how to analyse simulation results, ie, to explain them using the equations of the model (as in the TABLO Input file), and the base data.

In section 46.1 you can find a detailed hands-on analysis, using the AnalyseGE program, of the 10 percent labor increase simulation with Stylized Johansen (based on the linear TABLO Input file SJLN.TAB in section 4.4.1 above).

4.4.4    Writing UPDATE statements [gpd1.3.4.4]

The purpose of an UPDATE statement is to tell how much some part of data read changes in response to changes in the model's variables in the current step of a multi-step simulation. An introductory example was given in section 4.4.2 above.

Consider a COEFFICIENT V whose value(s) are read. There are three possibilities for the UPDATE statement for V.

1. If there is a linear VARIABLE, say w, in the TABLO Input file which represents the percentage change in V, then use an UPDATE statement of the form

UPDATE V = w ;

2. If, in the levels, V is equal to the product of two or more percentage-change variables, say p and q, use an UPDATE statement of the form

UPDATE V = p*q ;

This type of UPDATE statement is referred to as a PRODUCT UPDATE since it involves updating a Levels variable which is a product of other Levels quantities (often a value V is, in levels, the product of price P and quantity Q).

3. Otherwise work out an expression for the change in V in terms of linear VARIABLEs in the TABLO Input file and use a CHANGE UPDATE statement of the form

UPDATE (CHANGE)  V = <expression for change in V> ;

Of these, the second case is by far the most common and probably will cover over 90% of your UPDATE statements.13 All three UPDATE statements in the linearized TABLO Input file for Stylized Johansen are of this form (see section 4.4.1 above). Of course if COEFFICIENT V has one or more arguments, the UPDATE statements also contain the appropriate quantifiers, for example (all,i,SECT). Note also that only COEFFICIENTs whose values are READ or assigned via a FORMULA(INITIAL) in the TABLO Input file should be UPDATEd.

In case 3 above, the expression for the change in V is obtained by linearizing the levels equation connecting V to other levels variables whose associated linear variables have been declared in the TABLO Input file. See section 11.12.7 for a worked example.

More details about Updates, including examples, can be found in section 11.12.

4.4.5    Numerical versions of linearized equations [gpd1.3.4.5]

In this section we look at numerical versions of the linearized equations in SJLN.TAB. In two subsections below, we look at the numerical consequences of Update statements in SJLB.TAB (section 4.4.6) and at how the values of the Coefficients and the numerical equations are recalculated during each step of a multi-step calculation (section 4.4.7).

Some users are keen to have detailed information about these topics; others are not. Since a detailed knowledge about these topics is not essential for doing effective modelling, you should feel free to skip these sections. You can always refer back to them later on, if necessary.

Here we look at the numerical version of the linearized equation for market clearing of commodities Com_clear. The equation is

Equation Com_clear   (all,i,SECT) 
   p_XCOM(i) = BHOUS(i)*p_XH(i) + SUM(j,SECT,BCOM(i,j)*p_XC(i,j)) ;

There are really 2 equations here, one for each sector ("s1", "s2"). The BHOUS and BCOM Coefficients are shares. When evaluated at the base data values (see Table 3.1 above), they have the values

BHOUS("s1") = 2/8 = 0.25BHOUS("s2") = 4/12 = 0.333333
BCOM("s1","s1") = 4/8 = 0.5BCOM("s1","s2") = 2/8 = 0.25
BCOM("s2","s1") = 2/12 = 0.166667BCOM("s2","s2") = 6/12 = 0.5

At the start of the simulation (ie, on the first Euler step — see section 3.12.3 above), the two equations are

p_XCOM("s1") = 0.25 * p_XH("s1") + 0.5 * p_XC("s1","s1") + 0.25 * p_XC("s1","s2")
p_XCOM("s2") = 0.333333* p_XH("s2") + 0.1666667* p_XC("s2","s1") + 0.5 * p_XC("s2","s2")

This is why we call BHOUS and BCOM coefficients since their values are what are usually called the coefficients in the above equations14. The unknowns p_XCOM("s1"), p_XH("s1"), p_XC("s1","s1") and p_XC("s1","s2") are the Variables in the first of these equations.

When GEMPACK solves the equations above, all the variables are put onto one side so that the equation says that some expression is equal to zero. The equations above are rewritten as

1.0*p_XCOM("s1") - 0.25*p_XH("s1") - 0.5*p_XC("s1","s1") - 0.25*p_XC("s1","s2") = 0
1.0*p_XCOM("s2") - 0.333333*p_XH("s2") - 0.1666667*p_XC("s2","s1") - 0.5*p_XC("s2","s2") = 0

If you look at Table 3.4 above which represents the Equations Matrix for the linearized system, the equation Com_clear("s1") is one row of the Equations matrix. The coefficients of variable p_XH("s1") give the column for p_XH("s1") in the Equations matrix so that

4.4.6    Numerical examples of update statements [gpd1.3.4.6]

Here we consider the 4-step Euler calculation with Stylized Johansen in which the supply of labor is increased by 10 percent (and the supply of capital is fixed).

We look at the effect of the Update statements after the first step of this 4-step calculation.

During the first step, the supply of labor is only increased by 2.5 percent (one quarter of the total shock). The software solves the linear equations (those in section 4.4.5 above) to work out the consequential changes in the other quantities and prices. Some results from solving these equations are as follows:

p_PC("s1") = 0p_PC("s2") = -0.25p_XH("s1") = 1.5p_XH("s2") = 1.75

The Update statement for DVHOUS(i) is

UPDATE  (all,i,SECT)  DVHOUS(i) = p_PC(i) * p_XH(i) ;

which means (see point 5. in section 4.4.2 above) that

new_DVHOUS(i) = old_DVHOUS(i)*[1 + {p_PC(i)+p_XH(i)}/100] .

Hence the updated values for DVHOUS after the first step are

DVHOUS("s1") = 2*[1+{0+1.5}/100] = 2*1.015 = 2.03

DVHOUS("s2") = 4*[1+{-0.25+1.75}/100] = 4*1.015 = 4.06

Similarly the other percentage changes in prices and quantities during this first step are used to update the values of the other Coefficients DVCOMIN(i,j) and DVFACIN(f,j) which are read from the data base.15

4.4.7    How equations are recalculated in a multi-step calculation [gpd1.3.4.7]

As we indicated in section 3.12.1 above, the values of the Coefficients may change from step to step of a multi-step calculation.

Here we look at this for the second step of the 4-step Euler calculation discussed in section 4.4.6 above.

The values of all Coefficients read from the data base are updated at the end of the first step of this calculation. During the second step, these Coefficients take these updated values.

The values taken during step 2 of all other Coefficients which are not Coefficient(Parameter)s are inferred from the relevant Formulas.16 For example, the DVCOM(i) values during step 2 are calculated by applying the TABLO Input file

FORMULA (all,i,SECT) DVCOM(i) = SUM(j,SECT, DVCOMIN(i,j)) + DVHOUS(i);

The updated values for DVHOUS (see section 4.4.6 above) and DVCOMIN are put into the right-hand side of this Formula to give the values for DVHOUS(i) used during the second step. Similarly for all other Coefficients.

Thus, for example, the values of the BHOUS(i) are recalculated during this second step. These recalculated values are put into the relevant equations (namely the Com_clear equations).

Hence the numerical linear equations solved during step 2 may be different from those solved during step 1.

In fact, for the Stylized Johansen model, the Coefficients BHOUS, BCOM and BFAC, which look as if they may change from step to step, do not change.17 This behaviour (which is not typical of GE models) is a consequence of the fact that all behaviour in Stylized Johansen is Cobb-Douglas.

More details about the values used and calculated during the different steps of this 4-step calculation can be found in section 25.2.2.

4.5    Levels TABLO input files [gpd1.3.5]

We illustrate the construction of TABLO Input files containing only levels equations by looking at such a file for Stylized Johansen in section 4.5.1. The main difference in general from mixed TABLO Input files is in connection with behavioural equations (such as CES specifications). You should expect the levels files to contain explicit calibration FORMULAs of the kind familiar to levels modellers for calculating the values of the parameters of these functions.

A surprise with the Cobb-Douglas specification in Stylized Johansen is that, although such parameters appear in the levels equations, we do not need to calculate their values since these parameters do not appear in the linearized equations produced by TABLO. But this would not be the case if Cobb-Douglas were replaced by CES.

4.5.1    Levels TABLO input file for Stylized Johansen [gpd1.3.5.1]

The main difference from the mixed TABLO Input file shown in section 4.3.3 comes from using the levels version of the behavioural equations (the first three blocks in Table 4.1. These involve two parameters not present in the linearized versions of these equations, namely

ALPHAi0parameters in the consumer demand equations
Qjparameters in the intermediate demand equations.

These are called ALPHAH(i) and Q(j) respectively in the levels TABLO Input file given later in this section. As part of the calibration phase, you would expect to have to give FORMULAs for calculating the values of these. For example, using the TABLO Input file notation,

ALPHAH(i) = PC(i)*XH(i)/Y = DVHOUS(i)/SUM(ii,SECT,DVHOUS(ii))

and it would also be possible to write down a formula for the Q(j). However, in GEMPACK, the levels equations are only used as a means of writing down the linearized equations (TABLO does this by symbolically differentiating the levels equations — see section 4.6 below). Once this has been done, the levels equations are ignored. Thus, since the linearized versions of these equations no longer involve these ALPHAH and Q parameters, it is not necessary to give FORMULAs for them.18 Of course, in a more complicated model, you may not be sure if similar parameters are going to appear in the linearized system. When in doubt, you can write down the TABLO Input file leaving out calibration FORMULAs for such parameters and process the file by running TABLO. If the values are needed in the linearized system, TABLO will tell you and not allow you to proceed until you have supplied calibration FORMULAs.

Another noteworthy feature of the levels TABLO file shown below is in the EQUATION E_W for the quantity called W(j) there. Variable W(j) has been introduced to simplify the "intermediate demands" and "price formation" equations. The equation E_W uses the PROD operator to express W(j) as the product of the relevant quantities.19 The full levels TABLO Input file is shown below.

.!-------------------------------------------------------------------!
!                   Levels TABLO Input File for the                 !
!                      Stylized Johansen Model                      !
!                                                                   !
!      following the description in Chapter 3 of the text           !
!   "Notes and Problems in Applied General Equilibrium Economics"   !
!     by P.Dixon, B.Parmenter, A.Powell and P.Wilcoxen [DPPW]       !
!             published by North-Holland 1992                       !
!-------------------------------------------------------------------!

!   Text between exclamation marks is a comment                     !
!   Text between hashes (#) is labelling information                !

!-------------------------------------------------------------------!
!    Set defaults for Levels model                                  !
!-------------------------------------------------------------------!
EQUATION(DEFAULT=LEVELS) ;
VARIABLE(DEFAULT=LEVELS) ;
FORMULA(DEFAULT=INITIAL) ;
COEFFICIENT(DEFAULT=PARAMETER) ;

!-------------------------------------------------------------------!
!      Sets                                                         !
!-------------------------------------------------------------------!
! Index values i=1,2 in DPPW correspond to the sectors called s1,s2.
  Index values i=3,4 in DPPW correspond to the primary factors,
  labor and capital.   The set SECT below doubles as the set of 
  commodities  and the set of industries. !

SET SECT # Sectors # (s1-s2)  ;
SET FAC # Factors  # (labor, capital) ;

!-------------------------------------------------------------------!
!      Levels variables                                             !
!-------------------------------------------------------------------!
! In the DPPW names shown below, : denotes subscript.               !
! For example, x:j indicates that j is a subscript.                 !

Variable (GE 0)        Y    # Total nominal household expenditure # 
                            ! This is also Y in DPPW ! ;

Variable (GE 0) (all,i,SECT)  PC(i)   # Price of commodity i #
                               ! This is p:i (i=1,2) in DPPW ! ;
Variable (GE 0) (all,f,FAC)   PF(f)   # Price of factor f #
                               ! This is p:i (i=3,4) in DPPW ! ;
Variable (GE 0) (all,i,SECT)  XCOM(i) 
    # Total demand for (or supply of) commodity i #
                               ! This is x:i (i=1,2) in DPPW ! ;
Variable (GE 0) (all,f,FAC)   XFAC(f) 
    # Total demand for (or supply of) factor f    #
                               ! This is x:i (i=3,4) in DPPW ! ;

Variable (GE 0) (all,i,SECT)  XH(i)   # Household demand for commodity i #
                               ! This is x:i0 (i=1,2) in DPPW ! ;
Variable (GE 0) (all,i,SECT) (all,j,SECT)     XC(i,j) 
    # Intermediate inputs of commodity i to industry j #
    ! This is x:ij (i,j=1,2) in DPPW ! ;
Variable (GE 0) (all,f,FAC)(all,j,SECT)       XF(f,j) 
    # Factor inputs to industry j #
    ! This is x:ij (i=3,4; j=1,2) in DPPW ! ;
Variable (all,j,SECT)  W(j)    #Price expression#;

!-------------------------------------------------------------------!
!     Dollar values read in from database                           !
!-------------------------------------------------------------------!
Variable (GE 0) (all,i,SECT)(all,j,SECT)      DVCOMIN(i,j) 
    # Dollar value of inputs of commodity i to industry j # ;
Variable (GE 0) (all,f,FAC)(all,j,SECT)       DVFACIN(f,j)
    # Dollar value of factor f used in industry j # ;
Variable (GE 0) (all,i,SECT)                  DVHOUS(i) 
    # Dollar value of household use of commodity i # ;

!-------------------------------------------------------------------!
!     Parameters                                                    !
!-------------------------------------------------------------------!
COEFFICIENT (all,i,SECT)   ALPHAH(i)     #Household parameter#;
COEFFICIENT
 (all,i,SECT) (all,j,SECT) ALPHACOM(i,j) #Commodity parameter#;
COEFFICIENT
 (all,f,FAC) (all,j,SECT)  ALPHAFAC(f,j) #Factor parameter#;
COEFFICIENT (all,j,SECT)   Q(j)          #Scale parameter#;

!-------------------------------------------------------------------!
!      File                                                         !
!-------------------------------------------------------------------!
FILE iodata # input-output data for the model # ;

!-------------------------------------------------------------------!
!      Reads from the data base                                     !
!-------------------------------------------------------------------!
READ DVCOMIN from FILE iodata HEADER "CINP" ;
READ DVFACIN from FILE iodata HEADER "FINP" ;
READ DVHOUS  from FILE iodata HEADER "HCON" ;

!-------------------------------------------------------------------!
!     Formulas to calculate the Initial solution                    !
!-------------------------------------------------------------------!
! FORMULAs for Y, ALPHAH(i) and Q(j) are only needed if require
   change differentiation or add the Newton correction terms. !

!   1. Formulas for initial prices   !
!....................................!

FORMULA (all,i,SECT) PC(i) = 1 ;
FORMULA (all,f,FAC)  PF(f) = 1 ;
FORMULA (all,j,SECT) W(j) = 1 ;
FORMULA (all,j,SECT) Q(j) = 1 ;

.!   2. Formulas which are also equations   !
!..........................................!

FORMULA & EQUATION Comin 
# Intermediate input of commodity i in industry j #
 (all,i,SECT)(all,j,SECT)
 XC(i,j) = DVCOMIN(i,j) / PC(i) ;
! Quantity   = Dollar value / price !

FORMULA & EQUATION Facin # Factor input f in industry j #
 (all,f,FAC)(all,j,SECT)
 XF(f,j) = DVFACIN(f,j)/PF(f) ;

FORMULA & EQUATION House # Household demand for Commodity i #
 (all,i,SECT)
 XH(i) = DVHOUS(i)/PC(i) ;

FORMULA & EQUATION Com_clear #Commodity market clearing #
! (E3.1.6) in DPPW !
(all,i,SECT)   XCOM(i) = XH(i) + SUM(j,SECT, XC(i,j)) ;

FORMULA & EQUATION Factor_use # Aggregate primary factor usage #
! (E3.1.7) in DPPW ! 
(all,f,FAC)   XFAC(f) = SUM(j,SECT, XF(f,j)) ;

!  3. Formula for initial value of Y !
!....................................!
FORMULA Y = SUM(i,SECT,PC(i)*XH(i)) ;

!  4. Formulas for the parameters   !
!...................................!

FORMULA (all,i,SECT)(all,j,SECT)
 ALPHACOM(i,j) = XC(i,j)/XCOM(j) ;

FORMULA (all,f,FAC)(all,j,SECT)
 ALPHAFAC(f,j) = XF(f,j)/XCOM(j) ;

FORMULA (all,i,SECT)
 ALPHAH(i) = PC(i)*XH(i)/Y ;

!-------------------------------------------------------------!
!  Levels Equations    (Numbers refer to DPPW)                !
!-------------------------------------------------------------!
EQUATION Consumer_demands #Household expenditure functions #
! (E3.1.9) in DPPW ! 
 (all,i,SECT)  XH(i) = ALPHAH(i)*Y/PC(i)  ;

EQUATION Intermediate_com
 # Intermediate demand for commodity i by industry j # 
! (E3.1.10) in DPPW !
 (all,i,SECT) (all,j,SECT)
 XC(i,j) = ALPHACOM(i,j)*Q(j)*XCOM(j)*W(j)/PC(i) ;

EQUATION E_W # Define W(j) to simplify other equations #
 (all,j,SECT)
 W(j) = PROD(t,SECT,PC(t)^ALPHACOM(t,j)) *
                      PROD(u,FAC,PF(u)^ALPHAFAC(u,j)) ;

EQUATION Factor_inputs  # Factor input demand functions #
                                      !(E3.1.10) in DPPW ! 
 (all,f,FAC) (all,j,SECT)
 XF(f,j) = ALPHAFAC(f,j)*Q(j)*XCOM(j)*W(j)/PF(f) ;

EQUATION Price_formation # Unit cost index for industry j #
 (all,j,SECT)   PC(j) = Q(j)*W(j) ; ! (E3.1.12) in DPPW !

EQUATION Numeraire
 # Numeraire for the model is price of commodity 1 (E3.1.23)#
 PC("s1") = 1 ;              
!-------------end of TABLO Input file-------------------------!

4.6    TABLO linearizes levels equations automatically [gpd1.3.7]

When TABLO processes a TAB file containing levels EQUATIONs and VARIABLEs, it converts the file to a linearized file (we call it the associated linearized TABLO Input file). You can see the linearized equations on the INF file and evaluate them in AnalyseGE (see section 18.3).

The most important feature of this conversion is that, for each levels VARIABLE, say X, in your original TABLO Input file, there is an associated linear VARIABLE whose name is that of the original levels variable with "p_" added at the start.20 Also, for each levels VARIABLE in the original TABLO Input file, a COEFFICIENT with the same name as the levels VARIABLE is declared in the associated linearized TABLO Input file.

It is important to realise that the rest of TABLO (the last part of the CHECK and all of the CONDENSE and CODE stages) proceeds

as if the associated linearized TABLO Input file were the actual TABLO Input file.

This means that warnings and error messages given by TABLO may refer to statements in this associated linearized file rather than in your original TABLO Input file.21 Other features of this conversion are explained in section 9.2.

4.7    Creating the TABLO input file and command files for your own model [gpd1.3.9]

When you want to build your own model, you will usually construct the TABLO Input file by modifying one from an existing model. For example, you may wish to add some equations to an existing model.

Alternatively, you can create a TABLO Input file for your model from scratch. Suggestions about this can be found in section 8.3.

Whenever you are building or modifying a TABLO Input file, you will probably want to use the TABmate editor (see section 36.4) if you are working on a PC. TABmate assists you to identify and remove syntax or semantic errors from your TABLO Input file, as the examples in section 4.7.1 below show.

You will also need to write Command files for simulations. In section 4.7.2 below, we show you how you can identify and correct errors in Command files.

4.7.1    Correcting errors in TABLO input files [gpd1.3.9.1]

In the example below, we show you how to fix all errors in the TABLO Input file sjerror.tab which is supplied with the GEMPACK Examples.

TABmate can be a great help in finding errors. The example below shows you how to use TABmate to correct a TABLO Input file SJERROR.TAB which contains some typical errors.

Check how your WinGEM is configured by selecting

Options | Editor for TABLO Check Errors

and then slide your mouse across to click on Use TABmate.

Set your working directory to the subdirectory \SJ as described in section 3.4.2.

Now open a TABLO window via Simulation | TABLO Implement... and then, in this window, Select the TABLO Input file SJERROR.TAB. Click on Run to run TABLO. This run will find errors and so you should see a new window titled Error running TABLO In this window, click on Edit TABLO file.

This will cause TABmate display SJERROR.TAB. Indeed, TABmate will show you the first error, which occurs at the beginning of the declaration of variable XCOM. You should see a wriggly red line under the word VARIABLE at the start of this line (line number 55 of the file). To see the reason for this error, click on the word VARIABLE which is underlined in red. You will see the reason

Expected ;

shown (also in red) in the Error status panel in the bottom right-hand half of the TABmate's bottom panel. [After a few seconds the reason will go away, but you can get it back by clicking on the bottom panel or on the red-underlined word.]

You can see that a semi-colon is missing from the end of the previous line (the end of the declaration of variable PF). To remedy this error, insert a semi-colon at the end of that line. TABmate does not immediately realise that you have fixed this error. However you can ask TABmate to check the file by clicking on the TABLO Check button near the middle of the top part of TABmate. When you click on this Check button, TABmate first saves the TAB file and then runs TABLO to check the file.

This time it gets past the previous error but finds another error, underlining the word FACT in red and giving Unknown set as the reason for this error. A moment's reflection will tell you that the name of this set is just FAC (not FACT), so correct this error by removing the final "T". Then click on TABLO Check button again. This time TABmate tells you No error found (in "go-ahead" green rather than "stop" red).

Now that you have removed all errors, you can return to WinGEM to continue. To do this, close TABmate (for example, by selecting File | Exit from the main TABmate menu). You will see WinGEM's Error running TABLO window. In this window, click on Rerun. Then WinGEM will rerun TABLO. This time there should be no errors and TABLO will produce either a TABLO-generated program or else output for GEMSIM as usual.

This illustrates the procedure for removing errors from TABLO Input files.

TABLO Check: Behind the scenes

To understand what TABmate is doing when you click "TABLO Check", you could open a command prompt and type:

tablo -pgs sjerror

TABLO will check the file and report 1 syntax error and 10 semantic errors.

To identify the errors, view the Information file sjerror.inf:

tabmate sjerror.inf

Search for %% (two % signs with no space between them). At the first occurrence you should see something like:

     51   VARIABLE (all,i,SECT)  PC(i)   # Price of commodity i #
     52                                  ! This is p:i (i=1,2) in DPPW ! ;
     53   VARIABLE (all,f,FAC)   PF(f)   # Price of factor f #
     54                                  ! This is p:i (i=3,4) in DPPW !
     55   VARIABLE (all,i,SECT)  XCOM(i)
          ?
 %% Syntax error.
 Expected ;.
     56       # Total demand for (or supply of) commodity i #
     57                                  ! This is x:i (i=1,2) in DPPW ! ;

Note the ? which points to the first letter of VARIABLE in the declaration of XCOM. The reason "Expected ;." is shown. You can see that a semi-colon has been left out at the end of the previous declaration, namely the declaration of VARIABLE PF. To fix the error, you would need to add a semi-colon at the end of this statement in sjerror.tab. [There is no point in making any changes to the Information file sjerror.inf.]

Search again in sjerror.inf for %%. The next error shows something like:

     87   COEFFICIENT (all,f,FACT)(all,j,SECT)   ALPHAFAC(f,j)
                             ?
 %% Semantic problem.
 Unknown set.
     88    # Share of factor input f in costs of industry j # ;

Here the ? is pointing to the name FACT. The reason is "Unknown set". A moment's reflection will tell you that the name of this set is just FAC (not FACT). Again this needs to be corrected in sjerror.tab.

Search again in sjerror.inf for %%. The next error shows something like:

    109   FORMULA (all,i,FAC) PF(i) = 1.0 ;
                              ?
 %% Semantic problem.
 Unknown coefficient or variable.

The ? points to "PF" and the reason is "Unknown coefficient or variable". PF is unknown because of the first error above (where the semi-colon being omitted means that TABLO did not understand the statement declaring variable PF). We call this a consequential error since it is only an error because of an earlier error.

It turns out that all the other errors are consequential errors.

When you click "TABLO Check", TABmate

Occasionally TABmate cannot tell (from the INF file) where the error is located. In that case, the "INF See" button, lets you see the INF file yourself. Then you can use the "X Next" button to search for %% errors.

4.7.2    Correcting errors in command files [gpd1.3.9.2]

GEMSIM or the TABLO-generated program processes the Command file very early, checking that the statements are as expected. We refer to errors identified at this stage as syntax errors in the Command file. If you have a syntax error in the Command file (for example, do not spell one of the keywords correctly), the program stops with an error as soon as the whole Command file is processed in this way. When you have a syntax error in your Command file, the error will be marked in the Log file by %% to indicate where the error occurs. If you look in the Log file from the simulation, search for %% to find the error and the message indicating what the error is. Example 1 below is an example of a syntax error.

If there are no syntax errors, the program begins the simulation. Other errors in the Command file can be indicated later during the simulation. For example, you may not have a valid closure, or you may read shocks from a text file which does not have the expected form. In these cases, the error message may not refer explicitly to the Command file. Look at the Log file to identify the error. The error is usually indicated near the end of the Log file and is usually (but not always) marked with %%. You will need to read the error message and interpret it. Example 2 below is an example of this kind.

Example 1 - Syntax Error

Run GEMSIM or the TABLO-generated program for Stylized Johansen and take inputs from the Command file sjlberr1.cmf (which is supplied with the GEMPACK Examples).

The run should end with an error. To find the error, edit the Log file in your text editor and search for %%.22 You should see something like the following in the Log file:

 ! Solution method information
 ! Closure

 exogenous p_xfac ;
 rest endogenous ;

 ! Solution method information

 method = euler ;
 ! (Syntax error in next line)
 stps = 1 2 4 ;
  %% Unknown keyword 'stps'

 ! Simulation part

 ! Name of Solution file is inferred from name of Command file.
 ! (See section 20.5)

 shock p_xfac("labor") = 10 ;

 verbal description =
 Stylized Johansen model. Standard data and closure.
 10 per cent increase in amount of labor.
   (Capital remains unchanged.);

 ! Options
 extrapolation accuracy file = yes ;
 log file = yes ;

 ! End of Command file
  (Finished reading the command file.)

  There is at least one error in your Command file.

 (To see the error(s), look at the LOG file 'gpx60.log'.)
 (Search for %% in this LOG file.)

   (ERROR RETURN FROM ROUTINE: TGRCMF)
   (E-Error in command file input)
   (ERROR RETURN FROM ROUTINE: GEMSIM)
  (The program terminated with an error.)

You can see that the syntax error is the incorrect spelling of "steps".

To fix the problem, edit the Command file to fix this error and rerun the simulation.

If there are several syntax errors in the Command file, they will all be marked.

Example 2 - Error Discovered Later in the Run

Run GEMSIM or the TABLO-generated program for Stylized Johansen and take inputs from the Command file sjlberr2.cmf (which is supplied with the GEMPACK Examples).

The run should end with an error. To find the error, edit the Log file in your text editor and search for %%. You should see something like the following.

  --->  Beginning pass number 1 of 1-pass calculation.

  CHOICE OF ECONOMIC ENVIRONMENT

  (All components of 'p_XFAC' chosen to be exogenous.)
 %% Not all variables have been specified exogenous or endogenous.
  
   (ERROR RETURN FROM ROUTINE: ENINCF)
   (E-not all variables specified exogenous or endogenous)
   (ERROR RETURN FROM ROUTINE: ENINI )
   (ERROR RETURN FROM ROUTINE: TGEN  )
   (ERROR RETURN FROM ROUTINE: GEMSIM)
 (Incomplete new BCV file has been deleted.)
  
 Inputs have been taken from the Command file
 C:\SJ\sjlberr2.cmf
  
  (The program terminated with an error.)

The error in the example above is because the statement ."rest endogenous ;" has been commented out. To fix it remove the exclamation mark at the start of the line.

In general, once you have identified the source of the error, edit the Command file to fix this error and rerun the simulation.

Following the error, there is a trace-back string of subroutines. This trace-back string is probably of no use to you but can be helpful to the GEMPACK developers when tracing bugs in the GEMPACK code. If you need help with an error, it will be helpful if you save the Log file and send it to us when you report the problem.

5    Header Array files [harfiles]

Click here for detailed chapter contents

This chapter contains an introduction to Header Array files and to the programs which can be used to create or modify them (section 5.1).

Data for GEMPACK models (for example, input-output tables or parameters such as elasticities) are normally stored on files called Header Array (or HAR) files. Header Array files contain one or more arrays each containing data values. An individual array of data on a HAR file is accessed by supplying the unique 4-character identifier (or Header) for that array of values.

In addition to its header, each array of data has an associated long name (up to 70 characters long) which can contain a description of the data in the array.

Each array can have set and element labelling (which indicates, for example, the names of the commodities associated with each number) — see section 5.0.3 for details.

Header Array files are binary files that cannot be viewed or edited using normal text editors. The data is encoded in binary form to keep the size of the file small. You need to use a special program, such as ViewHAR, to examine or modify such files.

Header Array files are binary files so they cannot be printed or edited directly. Because of this, GEMPACK provides a number of utility programs for accessing them. These include

ViewHARFor viewing or modifying a HAR file
SEEHARFor translating HAR files to various text formats
MODHARFor modifying the data on a HAR file in batch or under Linux

ViewHAR has been introduced in chapter 3 above — further details can be found below. For SEEHAR, see chapter 37; for MODHAR, chapter 54.

5.0.1    Data on Header Array files [gpd4.3.1]

The data values held on an individual array can be either all real numbers, all integer numbers or all character strings. Depending on the type of data that is to be stored, the number of dimensions allowed varies.

The dimension limits for Header Arrays are :

Headers for arrays on any one file must be unique since the header acts as a label or primary key to identify the associated array.

Once written, an array contains not just the data for the array itself but also self-describing data, including the type of data values, dimensions of the array and a descriptive "long name" of up to 70 characters.

Header Array files have the advantage that you can access any array just by referring to the header which uniquely identifies the array in the file. There is no need to consider here the format1 of the arrays or any other details since they are all taken care of automatically by the software.

Headers consist of up to four characters which are usually letters (A to Z, a to z) or digits (0 to 9). Different arrays must have different headers. The case (upper or lower) of a header is not significant. (For example, you cannot have one array with header 'ABCD' and another on the same file with header 'AbCd'.). Headers starting with letters 'XX' are reserved for internal program use.

5.0.2    Array type [gpd4.3.1.1]

Each array on a Header Array file has an associated type. The type of each array is shown when ViewHAR lists the contents of a Header Array file.

Arrays of integers have type 2I, arrays of character strings have type 1C. Arrays of reals can have any of the types RE, 2R or RL2. The RE type includes set and element labelling (row and column labels) — see section 5.0.3.

5.0.3    Set and element labelling on header array files [gpd4.5a]

Arrays of real numbers on Header Array files usually contain set and element labelling information. This set and element labelling consists of

The set elements appear as row and column labels in the ViewHAR display.

TABLO-generated programs and GEMSIM automatically write this information to any arrays they write to a Header Array file. The information is also shown in various forms of SEEHAR and SLTOHT output.

Below is an example of labelled CSV output from SEEHAR (using the SES option; see section 37.1) showing the element names for the rows and columns. Such a CSV file could be read by Excel, Matlab or other programs.

Table 5.1 Example of labelled CSV output from SEEHAR
Coefficient DVFACIN(FAC:SECT)
 DVFACIN(FAC:SECT),s1        ,     s2    ,
 labor       ,  1.0000000    ,  3.0000000,
 capital     ,  1.0000000    ,  1.0000000,

We refer to this labelling information as set and element information on an array.

Set and element labelling information can only be attached to arrays of real numbers — not to arrays of integers or character strings.

5.0.4    Long names [gpd4.3.1.2]

Each header has an associated Long Name which can be up to 70 characters long. You can see these on the ViewHAR Contents page3.

When TABLO-generated programs and GEMSIM read and write header arrays, they may create new long names or transfer the long name from when the data was read (see section 11.11.7). Updated data files usually have the same long names as initial data (see section 22.2.4).

5.0.5    File history and creation information [gpd9.7.5.3]

When a GEMPACK program creates a Header Array file, it adds Creation Information to it, such as: the time and date on which the file was created; the program which created the file; and the GEMPACK Release from which the program EXE was built. See section 49.1 for more details.

A Header Array file can also contain what we call History Information (or simply History). This History consists of several lines of text (each line is limited to 60 characters) which are stored on the file. You can see (or edit) this History if you open the file in ViewHAR and click on the History menu item. You could make notes there about your file edits. The top part of the History form shows the file Creation Information.

The idea is that Creation Information and History help to remind you how, when and why you created the file. If you send the file to someone else, it could tell that person useful information.

When you carry out a simulation, the updated versions of any Header Array data files have History written on them, as does the Solution file.

5.1    Ways to create or modify header array files [gpd4.3.2]

5.1.1    Creating an initial HAR file of raw data [gpd4.3.2a]

The usual way to create header array files containing raw data is via ViewHAR. A blank (zero-filled) array is created in ViewHAR; then numbers from a spreadsheet are pasted into the array. ViewHAR can also modify single numbers (right-click on the value). These procedures are described briefly in section 6.1 below, and more fully in ViewHAR's Help. Some of the possibilities are illustrated in figure 5.1 below.

Figure 5.1 Ways to create an initial HAR file of raw data

On a non-Windows operating system, the (rather old-fashioned) program MODHAR can be used to turn raw text data into a HAR file — as described in Chapter 54.

5.1.2    Processing raw data to create a HAR file that model can use [gpd4.3.2b]

Usually the raw data requires considerable processing or manipulation before it can be used by a CGE model. The best way to do this processing is via one or more data-manipulation TABLO programs. These TAB files contain COEFFICIENT, READ, FORMULA, and WRITE statements (but do not contain VARIABLE or EQUATION statements).

Figure 5.2 below shows a possible procedure. RAWDATA.HAR is created interactively in ViewHAR, by copying raw data from a spreadsheet. Then the sequence of programs, STEP1.TAB, STEP2.TAB and STEP3.TAB are used to turn the raw data into MODEL.HAR — which is formatted and arranged to be used by the actual CGE model (in MODEL.TAB). If the raw data was changed or updated, you would edit RAWDATA.HAR interactively in ViewHAR, then rerun the three programs STEP1 to STEP3.

Figure 5.2 Steps in processing raw data

Clearly it would be risky or foolish to use ViewHAR to manually edit any of the files STEP1.HAR, STEP2.HAR or MODEL.HAR — any changes would be overwritten the next time you re-ran programs STEP1 to STEP3.

Using TABLO programs (rather than Excel) to process data offers three critical advantages:

See section 38.3 for more about data-manipulation TABLO programs.

6    Constructing HAR files [gpd1.4]

Click here for detailed chapter contents

When you prepare the TABLO Input file for a model, you work out how much data is required (see section 4.2 above) and what it must represent. Then comes the (often difficult and time-consuming) task of assembling the actual data (numbers); we say nothing about this here. Once that has been done, you must create files containing these numbers which can be read by the GEMPACK programs. These files are usually GEMPACK Header Array files1.

Header Array files are binary files which contain one or more arrays containing data values. An individual array of data on a Header Array file is accessed by referring to the unique 4-character identifier known as a Header for that array of values. See chapter 5 for more details.

ViewHAR makes it fairly easy for you to create, view, or modify these files The use of ViewHAR to create Header Array files, and to modify data on them, is introduced in sections 6.1 and 6.2 below2.

The usual way of creating a Header Array data file is to start with data from another program or source in XLS or some text format.

For XLS source, blank arrays of the correct size are created in ViewHAR — then the numbers are pasted from Excel into these arrays. We illustrate this for Stylized Johansen in section 6.1 below.

Text source can often be edited into a form that ViewHAR can read directly -- the so-called GEMPACK text file format. Otherwise, it may be possible to read it into a spreadsheet to create XLS source.

Section 6.2 below contains examples which show how ViewHAR can be used to modify data on Header Array files.

When you construct a data base for a model, it is important to check that it is balanced. We give some examples in section 6.3 below.

GEMSIM and TABLO-generated programs can be used to write Header Array or text data files. We give a hands-on example and some details in section 38.3 below.

We provide a table in section 6.4 which summarises the different programs you can use to convert data files of one type (for example, a text data file) to another type (for example, a Header Array file).

There are many techniques used in preparing and modifying data. In this chapter we only scratch the surface. We recommend sources of further information in section 6.5.

6.1    Constructing the header array data file for Stylized Johansen [sjmkdat]

You have looked at the Header Array data file SJ.HAR for Stylized Johansen in section 3.4.3 above. In this section we take you through the steps to construct that file SJ.HAR. We recommend that you carry out these steps on your own computer.

As you have seen in section 4.2.1 above, we need three arrays of data for DVCOMIN, DVFACIN and DVHOUS; these are of size 2 x 2, 2 x 2 and 2 respectively. The matrices of data required are as shown in the data base in Table 3.1 of section 3.1.1. We assume that you have data in an Excel sheet (SJDAT.XLS in the examples folder), as shown in the table below.

Table 6.1 Excel sheet of data for SJ model
Coefficient:DVCOMINHeader:CINP
Dimensions:SECT*SECTDescription:Use of commodities by industries
s1s2
s142
s226
 
Coefficient:DVFACINHeader:FINP
Dimensions:FAC*SECTDescription:Inputs of primary factors
s1s2
labor13
capital11
 
Coefficient:DVHOUSHeader:HCON
Dimensions:SECTDescription:Household use of commodities
s12
s24
Step 1 — Create a new HAR file in ViewHAR

Open ViewHAR and open the file SJDAT.XLS in Excel (or similar program).

In ViewHAR there are two modes: the simplest is Read Only mode where you can look at a Header Array file and are not allowed to change it. To get to this mode, select from the File menu Use simplified, read-only menu.

The second mode is Editing mode where you are allowed to modify data in the Header Array file. To get to this mode, select from the File menu Use advanced, editing menu. You must be in Editing mode to carry out the operations described below.

From the File menu, select Create New File.

Step 2 — Create the needed sets

We can see from the Excel file that sizes of needed data arrays are given by the 2 sets SECT and FAC. The first step is to create ViewHAR headers for these 2 sets.

Use the command Sets | Create New Set to open the Create Set dialog for the set SECT. Type in

Press the Check button to see if the data satisfies GEMPACK's rules. Press OK when you are done. You should see that the file now contains 1 header, "SEC".

Similarly use the Create Set dialog to make a header for the set FAC. Type in

For larger sets, it is easier to copy/paste the elements from Excel.

Now use File | Save as to save All headers in HAR format with the name MySJ.HAR.

Step 3 — Create the needed blank arrays

We can see from the Excel file that the needed data arrays are:

First use the Edit | Create new headercommand to make DVCOMIN. Fill in or choose the following options:

Press OK when you are done. You should see that the file now contains a new header, CINP. Examine the values of this header — they will be all zero, but at least you have an array of the right size with the right labels.

Leave this array (of zeros) in view in ViewHAR. Then, in Excel, select the 2x2 array of values3 for DVCOMIN, and Copy them to the clipboard.

Now go back to ViewHAR (still with the blank DVCOMIN array visible) and choose Import | Paste to screen from Clipboard. You should see the right numbers appear.

Now use File | Save to save your work4 so far.

Similarly, create and populate the DVFACIN and DVHOUS arrays.

Use Edit | Create new header to make DVFACIN by filling in or choosing: the Header type: Real; the header: FINP; the default value: 0; the Coefficient name: DVFACIN; the description: Inputs of primary factors; and the no. of dimensions: 2. For Choose Sets: select FAC in the first drop down list, and SECT in the second. Press OK when you are done.

Examine the values of the new FINP header — they will again be all zero. Then, in Excel, select the 2x2 array of values for DVFACIN, and Copy them to the clipboard. Then back in ViewHAR use Import | Paste to screen from Clipboard to bring the numbers into ViewHAR. And again File | Save .

For DVHOUS, similarly Edit | Create new header choose or fill in the Header type: Real; the header: HCON; the default value: 0; the Coefficient name: DVHOUS; the description: Household use of commodities; and the no. of dimensions: 1. For Choose Sets: select SECT in the drop down list. Press OK and view the new header HCON. Then, in Excel, select the 2 values for DVHOUS, and Copy them to the clipboard. Then back in ViewHAR use Import | Paste to screen from Clipboard to bring the numbers into ViewHAR. And yet again File | Save .

The task is complete !

6.1.0.1    Another way to attach set and element labelling information [sjmkdat2]

In the example above, we first created the sets, then used these to create blank labelled arrays. A more old-fashioned (but sometimes still useful) way is to first create blank un-labelled arrays, then create the sets, then attach sets to the arrays as row or column labels. You can do the latter with the menu item Edit | Apply/Change Set Labels . Use the Choose Dimension box in the bottom left-hand corner to select the first dimension. Then, with Choose Set drop-down list on the right-hand part of the form, select the right set. Then use the Choose Dimension box to select the second dimension, and the Choose Set drop-down list to select the right set for that. And so on, until all dimensions are labelled.

6.2    Editing the header array data file for Stylized Johansen [sjmoddat]

You can modify a number in ViewHAR by right-clicking that number (in the Data window) and typing in a new value.

To modify a whole array, it's usually easier to

Whether pasting numbers from Excel to ViewHAR, or from ViewHAR to Excel, you only get the number of decimal places that is visible in the source. Usually you need to increase the number of visible decimal places before you copy.

6.2.1    Other ViewHAR capabilities [gpd1.4.5.8]

ViewHAR offers many other capabilities. You can find more information in section 36.2, and complete details in the Help file supplied with ViewHAR.

6.3    Checking data is balanced [gpd1.4.7]

When you prepare the data file(s) for a model, you must be careful to check that all the different balancing conditions are satisfied.

For example, for Stylized Johansen, costs in each industry must equal the total demand for the corresponding commodity. In ORANI-G, which allows each industry to produce several commodities, there are two balancing conditions: costs in each industry must equal the value of all outputs from that industry; and output of each commodity (from several industries) must equal the total demand for that commodity.

The TAB file for a well-constructed model will contain code to check that such balance conditions hold, and even assertions (see section 25.3) that will stop the model running if they do not hold. Nonetheless, it is common (perhaps as part of a sequence of programs to produce a database) to write a self-contained TABLO Input file to read the data and carry out the calculations to check the balancing conditions. Such a TAB file will write the results of its calculations to a file you can look at to check that values are in balance.

When you are checking balance, you need to keep in mind that GEMPACK programs only produce about 6 figures of accuracy (see section 25.8).

6.3.1    SJCHK.TAB to check balance for Stylized Johansen [gpd1.4.7.1]

Supplied with GEMPACK is the file SJCHK.TAB which is used to check the balance of a data set for Stylized Johansen. View this file to see that the values of Coefficients DVCOM (value of output of each commodity) and DVCOSTS (costs in each industry) and the difference of these two (should be zero) are calculated and written to an output file. An Assertion statement (see section 25.3) is included so that the program will stop with an error if the difference is significant.

You will also see that a check is made to count the number of negative numbers in the data base (there should be none).

We encourage you to run SJCHK.TAB on SJ.HAR to check the balance.

If you prefer to use WinGEM, first make sure that both default directories point to the directory in which the Stylized Johansen files are located. First run TABLO on SJCHK.TAB and produce output for GEMSIM (for simplicity). Then run GEMSIM using Command file SJCHK.CMF. When GEMSIM has run, click on View Input/Output files and look at the values of DVCOM, DVCOSTS, and BALCHECK in the output file SJCHK.HAR. Also check that there are no negatives in the data base.

If you are working from the command prompt, change into the directory to which you copied the Stylized Johansen files. Then run TABLO on sjchk.tab to produce output for GEMSIM (for simplicity), ie, type:

TABLO -pgs sjchk

Then run GEMSIM taking inputs from the Command file sjchk.cmf, ie, type:

GEMSIM -cmf sjchk.cmf

When GEMSIM has run, look at the values of DVCOM, DVCOSTS, and BALCHECK in the output file sjchk.har, and also check for negative values.

6.3.2    SJCHK.TAB to check balance of updated data [gpd1.4.7.2]

Whenever you carry out a simulation, the updated data should satisfy the same balance checks as the original data — otherwise there is something wrong with the TAB file for your model.

It is easy to use SJCHK.TAB to check the balance of the updated data SJLB.UPD produced in the 10 percent labor increase simulation carried out via SJLB.CMF (see chapter 3). To do this, save the file SJCHK.CMF as SJLBCHK.CMF and alter the statement

file iodata = SJ.HAR ;

to read

file iodata = sjlb.upd ;

Then run GEMSIM taking inputs from Command file SJLBCHK.CMF. Look at the output file SJLBCHK.HAR produced and check that SJLB.UPD is still balanced.5

A more sophisticated, production-quality model should include such checking code in its main TAB file. That way, checking occurs every time the model runs — so alerting you early to potential problems.

6.3.3    GTAPVIEW for checking and summarising GTAP data [gpd1.4.7.3]

The standard GTAP TAB file referred to as GTAPVIEW provides a summary of any GTAP data set. We have provided GTPVEW61.TAB with the GEMPACK examples. You can see an example of the use of this TAB file in section 25.8.1.

The file GTPVEW61.TAB is an interesting example of a TAB file. For example, look at the set GDPEXPEND and how the values in Coefficient GDPEXP are built up via several Formulas. This shows a neat way of arranging summary data into headers on a Header Array file. You may be able to adapt some of these techniques in your own work.

6.3.4    Checking the balance of ORANIG data [gpd1.4.7.4]

See section 25.8.2 for details about this.

6.4    Which program to use in file conversion? [gpd1.4.8]

You need to convert between file formats

ViewHAR can be used interactively to do many conversions; but if a process is to be automated, command-line programs (if available) are preferred — they can be run from batch (BAT) scripts.

Table 6.2 below shows which programs to use in converting files from one type to another. The table rows (source) and columns (destinations) are labelled with 3-letter abbreviations, as follows:

HARGEMPACK Header array file
XLSExcel Speadsheet file
CSVtext file as saved or read by Excel; may be comma-, tab- or space-delimited
SQLtext file in "database" format; one number per row; zeros not shown
TXTGEMPACK text file: a special type of CSV, see chapter 38
GDXbinary data file used by GAMS
SL4GEMPACK solution file
Table 6.2 Programs to use in file conversion
↓In Out→HARXLSCSVSQLTXTGDX
HAR=har2xls
head2xls
head2csv
seehar
har2csvhar2txthar2gdx
XLS/Xxls2head=Excel-Excel-
CSV--=---
SQLcsv2har--=--
TXTmodhar
txt2har
ViewHAR-ViewHAR=ViewHAR
GDXgdx2harViewHAR-ViewHARViewHAR=
SL4sltohtViewHARsltohtViewHARViewHARViewHAR

In many cases alternative programs could be used; for example, ViewHAR can do most conversions. The table above shows the most appealing command-line program, if there is one — otherwise ViewHAR is shown. Note that from 2012 xls2head can read either XLS or XLSX files, but har2xls, head2xls and ViewHAR create only the older-format XLS files.

The programs gdx2har and har2gdx (see section 78.1) are command-line Windows-only programs distributed with GEMPACK. Slightly different versions are distributed with GAMS.

The programs har2csv, csv2har, har2txt, txt2har, har2xls, head2csv, head2xls and xls2head are command-line Windows-only programs. If they are not already included in your GEMPACK installation, you can download them from the GEMPACK website at http://www.copsmodels.com/gpmark9.htm. To obtain instructions for using, say, txt2har, you would simply type from the command line:

txt2har

In the table above "SQL" means, text files with lines like this:

"CitrusFruit","France","Germany","2005", 3974.2

meaning that, eg, 3974.2 tonnes of citrus was exported from France to Germany in 2005. Seehar's SQL option also offers a (fairly heavy-duty) way to turn HAR into SQL (see section 37.1.4).

For more about MODHAR, see chapter 54; for SEEHAR see chapter 37; and for SLTOHT see chapters 39 and 40.

To extract results from SL4 solution files, SLTOHT may be used to convert into one of two formats:

See also Running SLTOHT from the command line.

6.5    Further information [gpd1.4.9]

There are many techniques used in preparing and updating data files for models. This chapter is just a very brief introduction to the topic. Suggestions for finding out more are given below.

Aggregation: ViewHAR or, better, a command-line program AggHAR can be used to aggregate data. Both methods are described in the ViewHAR Help.

TABLO Input files: see example using mappings in section 11.9.

Disaggregation: can can be carried out using the (old-fashioned) command-line program DAGG downloadable from http://www.copsmodels.com/gpmark.htm. Alternatively, the newer command-line program DaggHAR (instructions in DaggHAR.doc) may be more convenient. In most cases, you will also need to write a TABLO program to do some of the job.

Periodic courses on the preparation of data for CGE models are listed at
http://www.copsmodels.com/pgemdata.htm

7    GEMPACK file types, names and suffixes [gpd1.5.8]

Click here for detailed chapter contents

GEMPACK programs use a number of different file types to communicate between themselves or to store results. Usually the file-name suffix (extension) indicates the file type.

7.0.1    Files with system-determined suffixes [gpd1.5.8.1]

Some types of files must be given system-determined suffixes. For example, GEMPACK requires that TABLO Input files have suffix .TAB. Below we list the most important type of files with system-determined suffixes (see also 3.14.1).

Table 7.1 File type with system-determined suffixes
File typeSuffixTypeSee
TABLO Input file.TABtextsection 4.3
TABLO Information file.INFtextsection 9.1.6
Solution file.SL4binarychapter 27
Equations file.EQ4binarychapter 59
GEMSIM Auxiliary Statement file.GSSbinarysection 3.14.2
GEMSIM Auxiliary Table file.GSTbinarysection 3.14.2
TABLO-generated Auxiliary Statement file.AXSbinarysection 3.14.2
TABLO-generated Auxiliary Table file.AXTbinarysection 3.14.2
TABLO-generated program.FORtextsection 3.14.2
Environment file.EN4binarysection 23.2.5
Model Information file.MINtextsection 21.4.1
Solution Coefficients file.SLCbinarysection 28.1
Extrapolation Accuracy file.XACtextsection 3.12.3
GEMPIE Print file.PI5textchapter 79

Whenever a program asks you for the name of any of these files with system-determined suffixes, you should never include the suffix in your input (since the program will add the suffix automatically). For example, in a Command file put

Solution file = sjlb ;     ! Correct

rather than

Solution file = sjlb.sl4 ;    ! Incorrect

Similar to the .SLC Solution Coefficients file, are .UDC, .AVC, and .CVL files -- see sections 28.2 and 28.3.

7.0.2    Suffixes of other files [gpd1.5.8.2]

Even though GEMPACK does not force you to use specific suffixes for other files, there are several different types of files where it has become customary amongst experienced GEMPACK users to use certain suffixes. Examples are in the table below.

Table 7.2 Commonly used suffixes for other files
File typeUsual Suffix(es)TypeSee
Header Array data file.HARbinarychapter 5
Text data file.TXTtextchapter 38
Updated Header Array file.UPD, .HARbinarysection 3.9
Command file.CMFtextchapter 20
Stored-input file.STI, .INPtextsection 48.3
Spreadsheet Mapping file.MAPtextsection 40.1
Solution file in HAR form.SOLbinarysection 39.1

In some cases there are considerable advantages from using these "usual" suffixes. For example,

Many of the GEMPACK programs suggest suffixes for output files they create. For example, SEEHAR often suggests suffix .SEE for its output files. We suggest that you go along with these suggestions unless you have good reasons to do otherwise.

7.0.3    Files — binary, header array or text? [gpd1.5.8.3]

There are two basic file types on all computers — text files (which are sometimes called ASCII files) and binary files. Text files are more portable — they can be viewed or printed using any text editor. Binary files are more compact and faster to process, but use one of a number of proprietary formats — so only special programs can read or create them. GEMPACK uses several files of each type, as indicated in tables 7.1 and 7.2.

Header Array (HAR) files (see chapter 6) are important binary files used often in GEMPACK to hold data for models. Although not recommended, you can also hold such data in text files: when used for this they must follow a standard format described in chapter 38.

7.0.4    Why so many files? [gpd1.5.8.4]

We have listed many of the important files, and discussed their roles, in section 3.14 above.

Some files are created to facilitate communication between different GEMPACK programs. [For example, GEMSIM Auxiliary files allow communication between TABLO and GEMSIM.]

Other files are created for users to look at or use. Some contain information which is important in reporting simulation results while others may allow experienced modellers to carry out tasks more efficiently. For example, when GEMSIM or a TABLO-generated program runs, it may produce various files listed below.

7.1    Allowed file and directory names [gpd1.5.9]

Both Windows1 and GEMPACK impose certain restrictions on file and directory names:

Directory names are restricted in the same way that file names are. Even if you are trying to create a file with a legal name, it may not be possible to create the file in a directory with an illegal name. For example, Chinese or Scandinavian characters in a directory name may cause problems.

Previous versions of GEMPACK and Fortran imposed tighter restrictions on file and directory names -- see section 5.9 of GPD-1. You might still be using a few older GEMPACK programs. To maintain compatibility with those:

Another virtue of of the above rule is that is simpler to remember than the more complex rules above.

7.1.1    File names containing spaces [gpd1.5.9.4]

To specify a file name containing spaces in a Command (CMF) file, enclose the name inside double quotes:

solution file = "my sj" ;

See section 20.4.2 for details.

If you are running a program interactively, you must not add quotes "" when specifying file names containing spaces. Similarly you should not add quotes when specifying such file names in Stored-input (STI) files.

If you are specifying a Command file name, STI file name or LOG file name on the Command line (see section 48.5), enclose the name in double quotes "" if it contains a space as in, for example,

gemsim  -cmf  "c:\my sj\my sjlb.cmf"

7.1.2    Characters in stored-input files and command files [gpd1.5.9.5]

TAB characters and other control characters (ASCII characters 0-31 and 127) can cause problems in Stored-input files and Command files. TAB characters are replaced by a single space. Most control characters are replaced by a single space but will cause a warning message. The program will stop with an error message if it finds a Control-Z character before the end of the file if there is text after it, or if there are two or more in the file.

There is no testing for other characters (ASCII characters 128-255) but these would cause problems if used in file names — see section 7.1.

8    Overview of running TABLO and the TABLO language [gpd2.1]

Click here for detailed chapter contents

TABLO is the GEMPACK program which translates the algebraic specification of an economic model into a form which is suitable for carrying out simulations with the model. The output from TABLO can be either GSS/GST files used to run the GEMPACK program GEMSIM or alternatively, a Fortran program, referred to as a TABLO-generated program. When TABLO writes a TABLO-generated program, you must then compile and link (LTG) the program to create the EXE file of the TABLO-generated program. Either GEMSIM or the EXE file can be run to carry out simulations.

This chapter contains an introduction to running TABLO, to compiling and linking TABLO-generated programs, and to writing TABLO Input files.

Chapters 9 to 18 provide complete user documentation of the TABLO program and the TABLO language. TABLO is the means by which economic models are implemented within GEMPACK, as described in the introductory chapters 3 to 7 (which you should read first).

Chapter 9 provides some of the fine print about running TABLO, including how it linearizes levels equations and about its Condensation stage.

Chapter 10 is a full description of the syntax required in TABLO Input files while chapter 11 contains a comprehensive description of the semantics (and a few points about the syntax which may not be clear from chapter 10) for the current version of TABLO.

Chapter 12 describes the TABLO statements for post-simulation processing; chapter 13 builds on this to shows how ranked sets can be used to present tables of winning and losing sectors in a simulation.

Chapter 15 provides some assistance with the important task of verifying that your model is actually carrying out the calculations you intend. Chapter 16 provides some details about intertemporal (that is, dynamic) modelling in GEMPACK. In chapter 17 we give examples of ways in which the TABLO language can be used to express relationships which at first sight are difficult to capture within the syntax and semantics of TABLO Input files.

Chapter 18 gives rules for linearizing levels equations, and indicates how the linearized equations are shown on the Information file.

We expect that chapters 9 to 18 will be used mainly as a reference document (rather than being read through in order). Use the Index to help find the relevant part whenever you need more information about TABLO.

Chapters 19 to 35 describe carrying out simulations on economic models after they have been implemented using TABLO.

8.1    Running TABLO on an existing model [gpd2.1.1]

Each of these examples assumes that you wish to run an existing model, or modify slightly an existing model.

You will find that TABmate (see section 8.4.1 below and section 36.4) provides an excellent interface for working with TABLO Input files, especially for identifying and eliminating syntax and semantic errors.

8.1.1    Example models ORANIG01 and GTAP61 [gpd2.1.1.1]

In chapter 3 the Stylized Johansen model SJ.TAB was used as the main example model. In following chapters the main example models are

(1) the ORANI-G model (May 2001) in the TABLO Input file ORANIG01.TAB written by Mark Horridge and colleagues from the Centre of Policy Studies, and

(2) the GTAP model Version 6.1 (August 2001) in the TABLO Input file GTAP61.TAB written by Tom Hertel and colleagues from the Center for Global Trade Analysis at Purdue University (see Hertel (1997) and McDougall (2002)).

The files for these models are amongst the Examples supplied with GEMPACK (see sections 60.5.1 and 60.7.1).

Running the ORANIG01 Model

View the ORANIG01 model in TABmate by opening ORANIG01.TAB from the GEMPACK Examples directory (usually C:\GP\EXAMPLES).

To run TABLO on the TABLO Input file ORANIG01.TAB, you should use the Stored-input file which carries out condensation.

(1) If you have a Source-code version of GEMPACK use the file OG01TG.STI to write a TABLO-generated program. At the Command prompt, the commands to use are

tablo -sti og01tg.sti            (creates TG-program ORANIG01.FOR).
ltg oranig01                     (compiles and links to produce ORANIG01.EXE).

Or you could click the TABLO STI button in TABmate (selecting og01tg.sti) to run both commands above.

(2) If you have the Executable-Image version of GEMPACK use the file OG01GS.STI. At the Command prompt, the command to use is

tablo -sti og01gs.sti            (produces output for GEMSIM)

Or you could click the TABLO STI button in TABmate (selecting og01gs.sti) to run the command above.

(3) If you are working in WinGEM, select the TABLO option Run from STI file and then select the STI file OG01GS.STI or OG01TG.STI and then click on the Run button.

Running the GTAP61 Model

Similarly you can view the GTAP61 model by opening the file GTAP61.TAB from the GEMPACK Examples subdirectory in your text editor. This model also needs a condensation STI file to run successfully. The Stored-input file called GTAP61TG.STI writes a TABLO-generated program and GTAP61GS.STI writes auxiliary files for GEMSIM.

(1) If you have a Source-code version of GEMPACK use the file GTAP61TG.STI. At the Command prompt, the commands to use are

tablo -sti gtap61tg.sti   (creates TG-program GTAP61.FOR)
ltg gtap61   (compiles and links to produce GTAP61.EXE).

Or you could click the TABLO STI button in TABmate (selecting gtap61tg.sti) to run both commands above.

(2) If you have the Executable-Image version of GEMPACK use the file GTAP61GS.STI. At the Command prompt, the command to use is

tablo -sti gtap61gs.sti   (produces output for GEMSIM)

Or you could click the TABLO STI button in TABmate (selecting gtap61gs.sti) to run the command above.

(3) If you are working in WinGEM, select the TABLO option Run from STI file and then select the STI file GTAP61GS.STI or GTAP61TG.STI and then click on the Run button.

Syntax and semantic examples from the TABLO Input files ORANIG01.TAB and GTAP61.TAB are used in throughout this chapter so that you can check a complete example of the relevant TABLO statements in a working model.

8.1.2    TAB file and WFP/PGS on command line [gpd5.10.1.2]

If you do not want to do any condensation actions not included in the TAB file, and you do not want to specify any options other than PGS or WFP at the Code stage, you can include the name of the TABLO Input file on the command line when you run TABLO. TABLO then runs in batch mode and does not expect any other input. If there are condensation actions in the TAB file, running with -pgs or -wfp will do those condensation actions (but give no opportunity for other condensation actions) and then go to Code stage.

Examples

1: To run TABLO to process SJ.TAB

tablo  sj

This will produce either a TABLO-generated program or output for GEMSIM, depending on which is the default action for the TABLO.EXE which is running. [The default is TABLO-generated program if TABLO.EXE is from a Source-code Version of GEMPACK or is GEMSIM if TABLO.EXE is from an Executable-Image Version of GEMPACK.]

2: To run TABLO to process SJ.TAB and produce output for GEMSIM

tablo -pgs  sj

3: To run TABLO to process SJ.TAB and produce output for GEMSIM and send all output to file SJGS.LOG

tablo  -pgs sj -log sjgs.log

4: To run TABLO to process SJ.TAB and produce the TABLO-generated program SJ.FOR

tablo  -wfp  sj

or

tablo sj  -wfp

the order is not important.

If you specify the TABLO Input file on the command line1, it is the same as running TABLO interactively and hitting carriage-return for every response (except the TAB file and WFP/PGS choices).

8.1.3    Running TABLO from TABmate with no STI file [tablocode]

Similar to the above, the TABLO Code button in TABmate runs TABLO without a STI file. The Options...Code and Other menu item is used to control whether TABLO produces a Fortran program or GEMSIM output.

8.1.4    Preliminary pass to count statements [gpd2.1.1.2]

TABLO carries out a preliminary pass of the TABLO Input file. On this pass, it just counts the numbers of the different types of statements and allocates memory for the checking which follows on the second pass.

If a line of your TABLO Input file is too long (see section 11.1.2), this error is pointed out on the preliminary pass. In that case, TABLO does no other checking. You must fix this long line and then run TABLO again. You may find that there are errors above this position in the TAB file, since TABLO has not really checked anything except line length on the preliminary pass.

8.2    Compiling and linking TABLO-generated programs [gpd2.1.2]

"Compiling and linking" a TABLO-generated program refers to what has been called Step 1(b) in sections 3.5.2 and 3.6.1.

If you are working at the command prompt, the command LTG as in

LTG <program-name> (for example, ltg oranig01 or ltg gtap61)

will compile and link a TABLO-generated program.

If you are using WinGEM, you can compile and link via menu item Compile & Link... under WinGEM's Simulation menu.

Within TABmate, when either of the TABLO Code or TABLO STI buttons is used to produce a Fortran program, LTG may be run automatically (or you may be prompted — see the Options...Code and Other menu item.

The input to the compile and link process is the TABLO-generated program (for example, ORANIG01.FOR). The output is an EXE file for the TABLO-generated program (for example, ORANIG01.EXE). You run the EXE file to carry out simulations with the model.

8.3    Writing a TABLO input file for a new model [gpd2.1.4]

If you wish to develop a TAB file for your own model without relying on an existing model, how do you go about it? Chapter 4 describes how to build a new model using Stylized Johansen as a simple example. To summarise, the steps are as follows.

Write down your equations in ordinary algebra. Choose whether to write a linearized, mixed or levels model. You may need to linearize your equations by hand (see section 18.2).

Compile a list of variables used in these equations.

Compile a list of data needed for the equations (levels values, parameters, other coefficients).

Work out what sets are involved for the equations, variables and data.

Construct your TAB file in TABmate (see section 8.4.1 below) and keep checking the syntax (clicking the "TABLO check" button) until you have removed all syntax errors. Section 4.7.1 contains a hands-on example showing how to correct errors in TABLO Input files. Consult chapters 10 and 11 for the TABLO syntax needed to write your TABLO statements. Use other models as extended examples of how to write TABLO code.

If your model is large, you may need to condense it — see section 8.5 below.

You can run your model within WinGEM or at the Command prompt.The simulation process is described in chapter 3 and in more detail in chapters 19 to 35.

8.4    Modern ways of writing TABLO input files (on a PC) [gpd2.1.5]

Although you can create TAB files with any text editor (such as emacs, NotePad or vi), we suggest that you use GEMPACK's TABMate text editor.

8.4.1    Using TABmate [gpd2.1.5.1]

Unless you have a firm preference for another text editor, we recommend that you use the TABmate editor because it has many in-built functions to assist you including the following.

More details about TABmate can be found in section 36.4.

8.4.2    Using TABmate to find a closure and suggest substitutions [autoclosure]

TABmate's Tools...Closure command helps you to find a standard closure for your GE model. It can also be used to find logical errors in your model, to suggest condensation actions, or to help construct a STI file. The results of the closure analysis are contained in a text report file suffixed CLO.

TABmate starts from the premise that there must be the same number of endogenous variables as equations in your model. By extension, we can usefully imagine that each equation explains a particular variable. Variables not explained by any equation are deemed to be exogenous in the standard closure.

In order for TABmate to know which variable is explained by a given equation, the modeller must follow a naming convention for equations. The convention is that the equation which explains variable "p1", say, is named "E_p1" (prefix E_). If you do not follow this convention, the Closure command will be no use to you, although the rest of TABmate will work normally.

Use the TABmate menu command Tools...Help on Tools to find out more about the Tools...Closure command.

8.4.3    Using TABmate to create a CMF file [autocmf]

TABmate's Tools...View/Create CMF will create a template CMF file for your model — you only need to add in the closure, shocks and actual filenames.

8.4.4    Using TABmate to reformat your code [beautyparlour]

TABLO is not case-sensitive: it will not complain if your TAB file refers to the same variable as "x1lab", "X1LAB" and "x1Lab". However, consistency is desirable, and can be enforced using TABmate's Tools...Beauty Parlour command. You can choose for, say, variables, to be rendered consistently in lower-case, or with the capitalization used when they first appeared in the TAB file.

8.4.5    Using ViewHAR to write TABLO code for data manipulation [gpd2.1.5.2]

If you have a Header Array data file containing set and element labelling (see section 5.0.3) and Coefficient names, ViewHAR can be used to write some of the TABLO code. To test this, run ViewHAR and open the file SJ.HAR from the GEMPACK Examples subdirectory. Select Export | Create TABLO Code from the main ViewHAR Menu. This will write some text to the Clipboard. In TABmate, create a new blank TAB file, and paste in text from the Clipboard. The following text will be created.

Example of TABLO code written by ViewHAR
Set SECT # description # (s1, s2);
Set FAC # description # (labor, capital);

Coefficient
(All,s,SECT)(All,a,SECT) DVCOMIN(s,a)
 # Intermediate inputs of commodities to industries - dollar values #;
(All,f,FAC)(All,s,SECT) DVFACIN(f,s)
 # Intermediate inputs of primary factors - dollar values #;
(All,s,SECT) DVHOUS(s) # Household use of commodities - dollar values #;.
Read
 DVCOMIN from file InFile header "CINP";
 DVFACIN from file InFile header "FINP";
 DVHOUS from file InFile header "HCON";

Update
(All,s,SECT)(All,a,SECT) DVCOMIN(s,a) = 0.0;
(All,f,FAC)(All,s,SECT) DVFACIN(f,s) = 0.0;
(All,s,SECT) DVHOUS(s) = 0.0;

Formula
(All,s,SECT)(All,a,SECT) DVCOMIN(s,a) = 0.0;
(All,f,FAC)(All,s,SECT) DVFACIN(f,s) = 0.0;
(All,s,SECT) DVHOUS(s) = 0.0;

Write
 DVCOMIN to file OutFile header "CINP" longname
 "Intermediate inputs of commodities to industries - dollar values";
 DVFACIN to file OutFile header "FINP" longname
 "Intermediate inputs of primary factors - dollar values";
 DVHOUS to file OutFile header "HCON" longname
 "Household use of commodities - dollar values";

ViewHAR has done all the dull part of code writing, and you can quickly edit the code by writing in appropriate filenames, formulas, updates etc to suit your model. This is very useful if you want to write a data manipulation TABLO Input file.

8.5    Condensing a large model [gpd2.1.6]

If your model is either too large to run on your computer, or too slow, you should consider condensation. See section 14.1 for an introduction to condensation, sections 14.1.2 and 14.1.4 for examples of condensation, and section 14.1.10 for further details. Basically you need to consider:

TABmate's Tools...Closure command (see section 8.4.2) is extremely useful in suggesting condensation possibilities. Also very useful is the Condensation Information file: see section 14.1.16.

Recent versions of GEMPACK allow you to specify condensation actions within the TAB files via OMIT, SUBSTITUTE and BACKSOLVE statements: see section 10.16. That is the recommended approach. TABmate's Tools...Closure command will produce condensation commands that you can paste into your TAB file.

8.5.1    Condensation in STI file: a legacy technique [oldsticond]

The older method was to specify condensation actions in a STI or Stored-input file. As mentioned above, nowadays you should instead place OMIT, SUBSTITUTE and BACKSOLVE statements within the TAB file. TABmate's Tools...Create in-TAB condensation from STI command will convert condensation commands from an older STI file into this modern form.

If you still need to work with the old STI file method, the examples in section 14.1.2 show an older way to create a STI file for condensation, suitable for small models: you could run TABLO interactively to carry out condensation and to create a Stored-input file which can be re-used to carry out this condensation.

TABmate's TABLO STI button can create a default STI file — which you could add to. The Tools...Closure command will produce condensation commands that you can paste into the STI file.

Using a basic STI file as a starting point, you can easily add, using your text editor, other variables to omit, substitute or backsolve. When this Stored-input file is complete, run TABLO with this Stored-input file, and continue in the usual way, either compiling, linking and running the TABLO-generated program, or running GEMSIM.

Example - Stored-input files for ORANIG

Use TABmate to look at the Condensation file for ORANIG01.TAB. There are two versions: OG01GS.STI which creates output for the GEMPACK program GEMSIM (using the pgs option), and OG01TG.STI which creates the TABLO-generated program ORANIG01.FOR and its Auxiliary files ORANIG01.AXS and ORANIG01.AXT (using the wfp option).

9    Additional information about running TABLO [gpd2.2]

Click here for detailed chapter contents

Most of the information about running TABLO is given in chapters 3 and 4. This chapter (which you could skip during a first reading) provides some additional, advanced information relating to:

9.1    TABLO options [gpd2.2.1]

This section gives details about Options that are available at the TABLO Check stage. Chapter 50 gives details about options available at the TABLO Code stage.

The TABLO program is divided into three distinct stages: CHECK, CONDENSE and CODE.

On starting TABLO, you make selections from the TABLO Options menu shown below. Standard Basic Options LOG, STI, SIF, ASI, BAT, BPR at the top of the screen are described in chapter 48.

You can choose which stages you carry out using the First Stage options (F1, F2, F3) and the Last Stage options (L1, L2, L3). The default choices for these options are F1 for the First Stage and L3 for the Last Stage. These mean that TABLO starts with the CHECK stage, then, if no errors are encountered during the CHECK, carries out CONDENSE (if requested), and then goes on to the CODE stage.

The option of carrying out some stages only is rarely used (except by GEMPACK developers doing debugging). There is more about it in section 64.1.

                  TABLO OPTIONS
             ( --> indicates those in effect )
 
     BAT Run in batch              STI Take inputs from a Stored-input file
     BPR Brief prompts             SIF Store inputs on a file
     LOG Output to log file        ASI Add to incomplete Stored-input file
 
     First Stage                   Last Stage
     -----------                   ----------
 --> F1 CHECK                      L1 CHECK
     F2 CONDENSATION               L2 CONDENSATION
     F3 CODE GENERATION        --> L3 CODE GENERATION
 
     RMS Require maximum set sizes to be specified
     NTX Dont store TAB file on Auxiliary file
     ICT Ignore Condensation statements on TAB file
     ASB All Substitutions treated as Backsolves
     NWT Add Newton-correction terms to levels equations
     ACD Always use Change Differentiation of levels equations
     SCO Specialized Check Options menu
 
 Select an option   :  <opt>      Deselect an option      : -<opt>
 Help for an option : ?<opt>      Help on all options     : ??
 Redisplay options  : /           Finish option selection:Carriage return
Your selection >

                    Main TABLO Options Menu

Option ACD is discussed in section 9.2.4 below. It affects the way TABLO linearizes any levels equations which, in turn, can affect the numerical properties of multi-step calculations.

Option RMS (Require Maximum Set Sizes) affects the CHECK stage of TABLO. When this option is selected the statement

SET REG # Regions # READ ELEMENTS FROM FILE GTAPSETS Header "H1";

would produce a semantic error. See section 11.7.2 for details.

Option NWT could be used with Newton's method to solve equations (see section 26.5). It causes TABLO to add the $del_newton term to all levels equations.

Option NTX is described in section 9.1.1 below. Option SCO leads to other options as described in section 9.1.3 below. Options ICT and ASB, which relate to the Condensation stage of TABLO (see section 14.1.10 below), are described in sections 14.1.15 and 14.1.13 respectively below.

9.1.1    TABLO input file written on the auxiliary files [gpd2.2.1.1]

The TABLO Input file for your model is written to the Auxiliary Table file (.AXT for a TABLO-generated program, .GST for GEMSIM) by default. These files are HAR files — but would only be meaningful to the GEMPACK developers. You can use the program TEXTBI (see chapter 70) to recover the Stored-input file from the Auxiliary Table file.

If, for reasons of confidentiality, you do not wish to send out your TABLO Input file on the Auxiliary files, you can turn off this default. At the first option screen in TABLO or at the top of your condensation Stored-input file, select the option

NTX Don't store the TAB file on Auxiliary file

then continue as usual with the TABLO input.

9.1.2    TABLO file and TABLO STI file stored on solution file [gpd2.2.1.2]

When the TABLO Input file is stored on the Auxiliary Table (.AXT or .GST) file (see section 9.1.1 above), this TABLO Input file is transferred from the Auxiliary Table file to the Solution file when you carry out a simulation using GEMSIM or a TABLO-generated program. This means that you can use the program TEXTBI (see chapter 70) to recover that TABLO Input file from the Solution file. This may assist in understanding simulation results.

Similarly, if you use a Stored-input file to run TABLO, this Stored-input file is transferred to the Auxiliary Table file produced by TABLO (unless TABLO option NTX is selected)

This Stored-input file is also transferred to the Solution file when you run a simulation using GEMSIM or a TABLO-generated program. You can use TEXTBI (see chapter 70) to recover the Stored-input file from the Solution file or from the Auxiliary Table file. [Strictly speaking, the Stored-input file put on the Auxiliary Table file is the one used for the CODE stage of TABLO. If you stopped and restarted TABLO (see section 64.1) condensation actions may not be on the Stored-input file put on the Auxiliary Table or Solution file.]

Note that the Stored-input file is only stored on the Auxiliary Table file if you use the STI option (see section 48.3) in TABLO by inputting

tablo.sti.sti-file-name

or the -STI option on the command line (see section 48.5) as in

tablo  -sti  sti-file-name

It does not happen if you use input redirection as in

tablo  <  sti-file-name          ! NOT recommended

since in this case TABLO is not aware that you are using a Stored-input file.

This means that it is usually possible to recover the TABLO file and any condensation actions from any Solution file.

Since the original data is stored on the SLC file (see section 28.1), this means that you can recover everything about a simulation from the Solution and SLC files.

9.1.3    Specialised check options [gpd2.2.1.3]

Choosing SCO gives access to the Specialised Check Options menu given below. However these options are rarely used so TABLO uses the default values for these unless you actively choose SCO and one or more of the Specialised Check options. You can find out more about these options from this menu. [For example, type ?SM5 to find out about option SM5.]

                Specialised Check Options 
              ( --> indicates those in effect )
  
       Semantic Check Options
       ----------------------
       SM2 Allow duplicate names
       SM3 Omit coefficient initialisation check
       SM4 Omit checking for warnings
       SM5 Do not display individual warnings
  
       Information File Options
       ------------------------
       IN1 Has the same name as the TABLO Input file
       IN2 Only show lines containing errors
       IN3 Omit the model summary in CHECK stage
  
Select an option   :  <opt>  Deselect an option      : -<opt>
Help for an option : ?<opt>  Help on all options     : ??
Redisplay options  : /       Return to TABLO Options : Carriage return
Your selection >

                  Specialised Check Options Menu

9.1.4    Doing condensation or going to code generation [gpd2.2.1.4]

After the CHECK stage is complete, if no syntax or semantic errors have been found, you are given the choice below:

  Do you want to see a SUMMARY of the model        [s], or
              perform CONDENSATION                 [c], or
              proceed to AUTOMATIC CODE GENERATION [a], or
              EXIT from TABLO                      [e] :

   (Enter a carriage return to proceed directly
      to AUTOMATIC CODE GENERATION)

If you select [a] (or if you type a carriage return), you will skip condensation and go directly to the Code stage of TABLO.

If you select [c], the following choice is presented. See section 14.1 and section 14.1.10 below for a description of Condensation.

 --> Starting CONDENSATION
  
  Do you want to SUBSTITUTE a variable             [s], or
      substitute a variable and BACKSOLVE for it   [b], or
                 OMIT one or more variables        [o], or
                 ABSORB one or more variables      [a], or
                 DISPLAY the model's status        [d], or
                 EXIT from CONDENSATION            [e] :

If you select [e] at either of the last two choices, the TABLO Record file (.TBR) and the Table file (.TBT) [see section 64.1] are written and the program TABLO ends.

9.1.5    TABLO code options [gpd2.2.1.5]

When you proceed to Automatic Code Generation, a Code Options Menu is presented. The main choice here is whether to produce output for GEMSIM (option PGS) or to write a TABLO-generated program (option WFP). Because the effect of the other options is intimately bound up with the way GEMSIM or the resulting TABLO-generated program will run, we postpone a discussion of these options until chapter 50.

9.1.6    Identifying and correcting syntax and semantic errors [gpd2.2.1.6]

If TABLO finds syntax or semantic errors during the CHECK stage, it reports them to the terminal and also, more usefully, to the Information (.INF) file.

To identify these errors, look at the Information file (via a text editor, or print it out). Syntax and semantic errors are marked by two percent signs %%, so you can search for them in an editor. The Information file usually shows the whole TABLO Input file (with line numbers added); lines with errors are repeated and a brief explanation is given of the reason for each error. (Also a question mark '?' in the line below the line with an error points to the part of the line where the error seems to be.)

Usually the change needed to correct the error will be clear from the explanation given. If not, you may need to consult the relevant parts of chapter 10 (for syntax errors) or chapter 11 (for semantic errors).

One syntax or semantic error may produce many more. If, for example, you incorrectly declare a COEFFICIENT A6, then every reference to A6 will produce a semantic problem ("Unknown coefficient"). In these cases, fixing the first error will remove all consequential errors.

TABmate (see section 8.4.1 above and section 36.4) provides an excellent interface for working with TABLO Input files, especially for identifying and eliminating syntax and semantic errors.

9.2    TABLO linearizes levels equations automatically [gpd2.2.2]

This section is only relevant for TABLO Input files which contain explicit levels EQUATIONs or explicit levels VARIABLEs.1 During the CHECK stage, when TABLO processes a TABLO Input file containing levels EQUATIONs and levels VARIABLEs, it converts the file to a linearized file; we refer to this as the associated linearized TABLO Input file. Although you may not see this associated linearized file (since the conversion is done internally by TABLO), you should be aware of some of its features.

The most important feature of this conversion is that, for each levels VARIABLE, say X, in your original TABLO Input file, there is an associated linear VARIABLE whose name is usually that of the original levels variable with "p_" added at the start.2 Also, for each levels VARIABLE in the original TABLO Input file, a COEFFICIENT with the same name as the levels VARIABLE is declared in the associated linearized TABLO Input file.

Other features of this conversion will be explained in sections 9.2.1 to 9.2.4 below.

It is important to realise that the rest of TABLO (the last part of the CHECK and all of the CONDENSE and CODE stages) proceeds

as if the associated linearized TABLO Input
file were the actual TABLO Input file.

This means that during CHECK and CONDENSE, warnings and error messages may refer to statements in this associated linearized file rather than in your original TABLO Input file.

During the CHECK stage, TABLO normally echoes the original TABLO Input file to the Information file (and flags any errors or warnings there). When there are levels EQUATIONs in the original file, in the Information file which TABLO writes to describe this model, each levels EQUATION is followed by its associated linearized EQUATION. So, if you wish to see the associated linearized EQUATIONs you can do so by looking at the CHECK part of the Information file. In section 18.3 we show part of the Information file obtained from processing the TABLO Input file SJ.TAB for the mixed version of Stylized Johansen. You can look there to see the linearized EQUATIONs associated with some of the levels EQUATIONs from this TABLO Input file, which is shown in full in section 4.3.3.

9.2.1    Change or percentage-change associated linear variables [gpd2.2.2.1]

When you declare a levels VARIABLE in your TABLO Input file, you must also decide which form of associated linear VARIABLE you wish to go in the associated linearized TABLO Input file. If you want it to be the corresponding percentage change, you don't need to take special action since this is usually the default. If however you wish it to be the corresponding change, you must notify TABLO of this by including the qualifier (CHANGE) in your VARIABLE statement. For example, the statement

VARIABLE (LEVELS,CHANGE) BT  # Balance of Trade # ;

in a TABLO Input file will give rise to a CHANGE variable c_BT in the associated linearized TABLO Input file.

As explained in section 4.3.5, there are some circumstances when a change linear variable is preferable to the percentage-change alternative. When you declare a levels VARIABLE we suggest the following guidelines.

VARIABLE (LEVELS,CHANGE) BT  # balance of trade # ;

9.2.2    How levels variable statements are converted [gpd2.2.2.2]

When you declare a levels VARIABLE or write down a levels EQUATION in a TABLO Input file, these give rise to associated statements in the associated linearized TABLO Input file created automatically by TABLO. After that, TABLO's processing proceeds as if you had actually written these associated statements rather than the levels statements actually written. We look at the different possibilities below.

Declaration of a Levels VARIABLE

Each declaration of a levels VARIABLE is automatically converted to three statements in the associated linearized TABLO Input file.3 These are

(1): the declaration of a COEFFICIENT(NON_PARAMETER) with the same name as the levels VARIABLE;

(2): the declaration of the associated linear VARIABLE if there is no LINEAR_VAR= qualifier. If there is a LINEAR_NAME= qualifier, that determines the name of this associated linear variable (see a few lines below). Otherwise the name of the associated linear variable has "p_" or "c_" added at the start depending on whether the corresponding percentage-change or change has been indicated by a qualifier PERCENT_CHANGE or CHANGE , or by the default statement currently in force if neither of these qualifiers is present;

(3): an UPDATE statement saying how the COEFFICIENT in (1) is to be updated during a multi-step simulation.

Example 1 The statement

VARIABLE (LEVELS,PERCENT_CHANGE) (all,c,COM) X(c) #label# ;

is converted to the 3 statements.

COEFFICIENT (NON_PARAMETER) (all,c,COM) X(c) ;
VARIABLE (LINEAR,PERCENT_CHANGE) (all,c,COM) p_X(c) #label# ;
UPDATE  (all,c,COM)  X(c) = p_X(c) ;

Example 2 The statement

VARIABLE (LEVELS,CHANGE) (all,i,IND) Y(i) #label# ;

is converted to the 3 statements

COEFFICIENT (NON_PARAMETER) (all,i,IND) Y(i) ;
VARIABLE (LINEAR,CHANGE) (all,i,IND) c_Y(i) #label# ;
UPDATE (CHANGE)   (all,i,IND)  Y(i) = c_Y(i) ;

Two Variable statement qualifiers LINEAR_NAME= and LINEAR_VAR= (see section 10.4) can alter the way in which a Levels Variable statement is converted.

Specifying the name of the linear variable (LINEAR_NAME)

You can use the qualifier LINEAR_NAME= if you want to specify the name of the associated linear variable (rather than letting TABLO determine the name by adding "p_" or "c_" to the front of the name of the Levels variable as described above).

For example

Variable(Levels, Linear_Name=xpc) (All,c,COM) X(c) ;

tells TABLO to use the name xpc (rather than p_X) for the linear variable associated with levels variable X. This statement is equivalent to the following three statements:

Coefficient (Non_parameter) (all,c,COM) X(c) ;
Variable (Linear,Percent_change) (all,c,COM) xpc(c);
Update  (all,c,COM)  X(c) = xpc(c) ;
Using a linear variable declared earlier (LINEAR_VAR)

You can use the qualifier LINEAR_VAR= if you want to indicate that the associated linear variable has been declared earlier in the TAB file. In this case TABLO adds the Coefficient and Update statements as indicated earlier but does not add a new Linear Variable. Instead TABLO associates the already declared Linear variable with this new Levels variable.

For example

Variable(Levels, Linear_Var=x) (All,c,COM) X_L(c) ;

tells TABLO that the linear variable to be associated with the levels variable X_L is the Linear Variable x declared earlier in the TAB file. This statement is equivalent to the following two statements:

COEFFICIENT (NON_PARAMETER) (all,c,COM) X_L(c) ;
UPDATE  (all,c,COM)  X_L(c) = x(c) ;

Use of the qualifier LINEAR_VAR= can reduce the proliferation of Variables and Equations when you add one or more Levels Variables at the bottom of a TAB file in which most equations are linearized ones.

For example, in ORANI-G there is a linear variable p0(c,s) giving the percentage change in the basic price of commodity c from source s (domestic or imported). Suppose that you need to add a Levels Equation involving this price. Then you need to add a levels version of this variable. Instead of using the qualifier LINEAR_VAR= you could add the following statements the end of the TAB file.

Variable(Levels) (All,c,COM)(All,s,SOURCE) P0_L(c,s) ;
Equation (Linear) E_p_P0_L  (All,c,COM)(All,s,SOURCE) p_P0_L(c,s) = p0(c,s) ;

Here the equation is needed to connect the two linear variables p_P0_L (created by the Levels Variable declaration) and the previously defined Linear Variable p0(c,s). But if you use the LINEAR_VAR= qualifier as in

Variable(Levels, LINEAR_VAR=p0) (All,c,COM)(All,s,SOURCE) P0_L(c,s) ;

no extra Linear Variable p_P0_L is needed and the Linear Equation E_p_P0_L is not needed.

Note that

9.2.3    How levels equation statements are converted [gpd2.2.2.3]

Each levels EQUATION is converted immediately to an appropriate linearized EQUATION. This linearized EQUATION has the same name as that used for the levels EQUATION. Exactly how the linearization is done depends on the types of associated linear VARIABLEs.

Example: The statement

EQUATION (LEVELS) House  (all,c,COM) DVH(c) = P(c) * QH(c) ;

may be converted to the linearized equation

EQUATION (LINEAR) House  (all,c,COM) p_DVH(c) = p_P(c) + p_QH(c) ;

if the levels VARIABLEs DVH, P and QH have percentage-change linear variables associated with them.

We describe the different linearizations in section 9.2.4 below.

9.2.4    Linearizing levels equations [gpd2.2.2.4]

In linearizing a levels equation, there are two methods of carrying out the differentiation. We illustrate these by considering the equation

G(X, Y, Z) = H(X, Y, Z)

where G and H are non-linear functions of the levels variables X,Y,Z.

If we take the percentage change of each side,

p_G(X, Y, Z) = p_H(X, Y, Z)

and apply the percentage-change differentiation rules which are given in detail in sections 18.1 and 18.2.2, the final result is a linear equation in terms of the percentage changes p_X, p_Y, p_Z of the levels variables X,Y,Z respectively,

R(X,Y,Z)*p_X + S(X,Y,Z)*p_Y + T(X,Y,Z)*p_Z = 0

where R, S, T are functions of the levels variables X,Y,Z.

If R, S, T are evaluated from the initial solution given by the (pre-simulation) database, a linear equation with constant coefficients results.

The alternative is to begin by taking the differential (or change) of both sides of the levels equation giving

d_G(X, Y, Z) = d_H(X, Y, Z)

and then using the change differentiation procedure in section 18.2.1.

If the levels variable X has a CHANGE linear variable c_X associated with it,

replace the differential dX by c_X.

If the levels variable X has a percent-change linear variable p_X associated with it,

replace the differential dX by (X/100)*p_X.

The result is an equation of the form

K(X,Y,Z)*p_X + L(X,Y,Z)*p_Y + M(X,Y,Z)*p_Z = 0

if X,Y,Z all have associated percent-change linear variables, or

D(X,Y,Z)*c_X + E(X,Y,Z)*c_Y + F(X,Y,Z)*c_Z = 0

if X,Y,Z all have associated change linear variables,

or some alternative if some of X,Y,Z have associated change linear variables and some have associated percent-change linear variables.

The linearization of levels equations is essentially transparent to you as a user. It happens automatically (without any intervention being required by you). In most, if not all, cases, you will not need to know how TABLO linearizes a particular equation. Accordingly you may prefer to ignore the rest of this section.

Note that, however the equation is linearized, and whether each variable has associated a change or percent-change linear variable, once the relevant functions (for example, the ones referred to above as R,S,T,K,L,M,D,E,F) are evaluated at the initial solution given by the initial database, the result is a system of linear equations

C . z = 0

as indicated in section 3.12.1.

To illustrate how individual levels equations are linearized, we look at some simple examples.

1: Consider the equation

Z = X * Y

where X, Y and Z are levels variables with associated percent-change linear variables p_X, p_Y and p_Z. If we use the percentage-change differentiation rules in section 18.1, we obtain the associated linear equation

p_Z = p_X + p_Y

Alternatively, if we use the change differentiation rules (see sections 18.1 and 18.2.1), we obtain the associated linear equation

Z/100*p_Z = Y*(X/100)*p_X + X*(Y/100)*p_Y.

2: Consider the same equation as in 1 but suppose that X,Y and Z have associated change linear variables c_X, c_Y and c_Z. Then, using the change differentiation rules in section 18.1, we obtain the linearization

c_Z = X*c_Y + Y*c_X

9.2.5    Linearizing a sum [gpd2.2.2.5]

Consider the equation

Z = X + Y

where X, Y and Z are levels variables with associated percent-change linear variables p_X, p_Y and p_Z. There are two ways of linearizing it.4

(a) Share Form. If we use the percentage-change differentiation rules in section 18.1, we obtain the associated linear equation

p_Z = X/(X+Y)*p_X + Y/(X+Y)*p_Y

The terms (X+Y) in the denominator can be replaced by Z to give a familiar form

p_Z = [X/Z]*p_X + [Y/Z]*p_Y

Here the expressions X/Z and Y/Z are the shares of X and Y in the initial values of Z.

(b) Changes Form. Alternatively, if we use the change differentiation rules in section 18.1, we obtain the associated linear equation

Z/100*p_Z = X/100*p_X + Y/100*p_Y

which can be simplified (by multiplying both sides by 100) to

Z*p_Z = X*p_X + Y*p_Y

Note that here the left-hand side can be interpreted as 100 times the change in Z. Similarly the terms X*p_X and Y*p_Y on the right-hand side are just 100 times the changes in X and Y respectively. This linearized version of the sum in the original levels equation is thus easy to understand: it says that 100 times the change in Z is equal to 100 times the change in X plus 100 times the change in Y.

TABLO would produce the second (Changes form) when linearizing this equation. [See, for example, the linearized version of the equation Factor_use in section 18.3.]

9.2.6    Algorithm used by TABLO [gpd2.2.2.6]

At present, if allowed to operate in its default mode, TABLO uses Change Differentiation (see section 18.2.1)

In all other cases TABLO uses percentage-change differentiation (see sections 18.1 and 18.2.2).

In some cases convergence of multi-step calculations may be hindered by percentage-change differentiation. In such a case you can force TABLO to use only change differentiation by selecting option

ACD       Always use Change Differentiation of levels equations

from the Options menu presented at the start of TABLO. (This menu is shown in section 9.1 above.)

9.2.7    TABLO can write a linearised TAB file [gpd9.7.19]

If your TAB file contains levels equations, TABLO is able to write a linearised version of the file - that is, a version in which all levels equations are replaced by the corresponding linear equation.

If you ask AnalyseGE (Version 2.88 or later) to load a Solution file which was produced from a TAB file which contains levels equations, by default AnalyseGE loads the linearised TAB file rather than the original one.

We think that the linearised TAB file gives you more scope for analysing the Equations parts of your results.

9.2.7.1    Fine print [gpd9.7.19.1]

If your TAB file contains levels equations, you can produce a linearised TAB file when you run TABLO interactively (as described in section 48.3). Give option LIN (not shown on the screen) when TABLO starts running and then continue the run as normal. The linearised TAB file written by TABLO has "-lin" added at the end of the name. For example, if you process SJ.TAB, the linearised TAB file will be called SJ-LIN.TAB.

The linearised TAB file is a proper TAB file in the sense that it satisfies all TABLO syntax and semantic rules.

In the linearised TAB file, the levels equations of the original TAB file are shown as linearised equations. The form of the linearised equations is the same as is shown in the Information file produced when TABLO runs.

If there is a Formula & Equation in the original TAB file, the Formula remains in the linearised TAB file and it is followed by a linearised version of the associated levels equation.

The linearised TAB file would produce exactly the same results as you obtained from the original TAB file. That is because TABLO works with only with the linearised versions of the equations after the Check stage.

Example

As an example, you might like to load the results from the standard 10% increase in labor supply with Stylized Johansen (SJLB.SL4) to see the differences. The standard TAB file SJ.TAB used to produce these results contains some levels and some linearised equations (see chapter 4).

9.3    Reporting Newton error terms in models with levels equations [gpd5.9.14]

If your model has all (or many) levels equations, you can report errors in these levels equations during and after a simulation. This provides an independent check as to the accuracy (or otherwise) of your simulation.

In order to be able to report the errors, you must select option NWT (see section 9.1) at the first option screen when you run TABLO. Then TABLO adds the Newton correction variable $del_Newton to your model and adds so-called Newton error terms (or Newton correction terms) to the linearised version of each levels equation.

The size of the Newton error term tells you how well each levels equation is satisfied.

As indicated in section 26.5.3, you can check the accuracy of the initial database by reporting the sizes of the Newton error terms as calculated from the initial data.

With the Command file statements described below, you can now report the sizes of all or selected Newton error terms as calculated from the final updated data or as calculated from any of the updated data sets produced during a multi-step calculation.

You do not need to be using Newton's method in order to be able to report these errors. You can also report them if you are using the traditional GEMPACK solution methods Euler, midpoint or Gragg (as the example in section 9.3.1 below makes clear).

Note that the Newton errors can only be calculated and reported for equations which are written as Levels equations in your TABLO Input file. They cannot be reported for linearised equations in the TABLO Input file.

Note also that you must include the Newton correction variable $del_Newton as an exogenous variable in your Command file (perhaps by including the statement "exogenous $del_newton ;").

We first describe an example in section 9.3.1 below. Then, in section 9.3.2 below, we fully document the Command file statements you can use to request reports about Newton error terms.

9.3.1    Example: reporting Newton errors with SJLVLBER.CMF [gpd5.9.14.1]

This is the usual Stylized Johansen simulation where the supply of labor is increased by 10% while the supply of capital is held fixed. It is run with the levels version SJLV.TAB (see section 4.5.1) of the Stylized Johansen model instead of the mixed version SJ.TAB (see section 4.3).

First run TABLO taking inputs from the Stored-input file sjlvnwgs.sti (which selects option NWT at the start and which produces output files for GEMSIM called sjlv-nwt.gss and sjlv-nwt.gst).

Then run GEMSIM taking inputs from the Command file sjlvlber.cmf. Notice that the Newton correction variable $del_Newton is declared as exogenous in this Command file. This simulation uses Euler 1,2,4 steps.

When this simulation has run, look at the LOG file SJLVLBER.LOG in TABmate.

First search for "based on initial data". You will see the lines

Newton error terms (based on initial data)
Sum of absolute values of the del_Newton terms is 0.0000000
 The norm of this del_Newton terms vector is 0.0000000.

This tells you that all the levels equations in the model are satisfied exactly (up to the precision used by the program) since the sum of the absolute values of the del_Newton terms (these are the Newton error terms) is zero.

Then search for "based on updated data". You will see lines like the following.

Final Newton error terms (based on updated data)
Newton error = -1.19209290E-05 in equation Comin("s2","s2")
Newton error = -8.34465027E-05 in equation Facin("labor","s1")
Newton error = -4.76837158E-05 in equation Facin("labor","s2")
Newton error = -2.38418579E-05 in equation House("s2")..<etc>.
Sum of absolute values of the del_Newton terms is 6.91890717E-04
 The norm of this del_Newton terms vector is 2.88324867E-04
Largest $del_Newton term is in equation Com_clear("s2")
The $del_newton term in this is -2.44140625E-04.

These are the values of the nonzero Newton error terms when calculated using the updated data. They show how accurately the levels equations are satisfied using the solution values reported by GEMSIM. Happily all of the errors are small so you can see that this is quite an accurate solution. The "Sum of absolute values of the del_Newton terms" value is the sum of all Newton errors. And the largest error is also reported (and the equation which produces it).

The Command file SJLVLBER.CMF contains the statement

Report newton errors = all ;

which asks GEMSIM to report the sizes of the Newton error terms at all steps.

Go back to the top of the LOG file SJLVLBER.LOG and search for "Newton error =". You will see something like the following.

--->  Beginning pass number 2 of 2-pass calculation
Newton error terms (as at the start of this simulation step)
Newton error = -1.69873238E-02 in equation Comin("s2","s1")
Newton error = -1.69873238E-02 in equation Comin("s2","s2")
Newton error = -9.71794128E-02 in equation Facin("labor","s1")..<etc>
Sum of absolute values of the del_Newton terms is 0.50708652
 The norm of this del_Newton terms vector is 0.19212985
Largest $del_Newton term is in equation Facin("labor","s1")
The $del_newton term in this is -9.71794128E-02.

These report the sizes of the Newton error terms after the first step of the 2-step Euler calculation. So these report the sizes after half of the full shock has been given in a single step. Notice that the errors are not inconsiderable. Notice also the value of the sum of all errors and of the largest one.

If you keep searching for "Newton error =" you will see similar reports which relate to the solution after 1, 2 or 3 of the 4 Euler steps carried out as the third multi-step calculation. Note that the sum of all errors keeps increasing. [It is about 0.13 after the first step, 0.25 after the second step and about 0.37 after the third step. Although the sum of all errors is not shown after the fourth step you can see that it would be about 0.5.]

Fortunately the extrapolation works well and (as you saw above when you searched for "based on updated data") the errors in the levels equations are very small after extrapolation.

As you will see in section 9.3.2 below, you can control how often these Newton error reports are given.

9.3.2    Command file statements for reporting Newton error terms [gpd5.9.14.2]

To generate reports about the Newton correction terms in the levels equations of your model, you must select the initial option NWT (see section 9.1) when running TABLO.

The following Command file statement allows you to see reports about the sizes of the Newton error terms at various stages during your simulation, including (most importantly) at the start and at the end. The sizes of these Newton error terms tell you how well the levels equations in your model are satisfied. In particular, if you report the values at the end of the simulation, you can tell whether or not you have solved the model sufficiently accurately.

Note that the Newton errors can only be calculated and reported for equations which are written as Levels equations in your TABLO Input file. They cannot be reported for linearised equations in the TABLO Input file.

Report newton errors = INITIAL | final | subinterval | all | none ; 
                   ! optional, default is "initial"

You can only choose one of the above alternatives (initial, final, subinterval, all or none).

Report newton errors = initial ;

prints out the Newton error terms based on the initial data.

Report newton errors = final ;

prints out the Newton error terms after the simulation has finished (based on the updated data and on the solution values in the Solution file).

Report newton errors = subinterval ;

prints out the Newton error terms after each subinterval and at the end.

Report newton errors = all ;

prints out the Newton error terms at the start (initial), at the start of each simulation step, at the start of each subinterval during the run, and after the simulation has finished.

By default, if there are Newton correction terms available (by running TABLO with the NWT option), the initial errors (those based on the initial data) will be reported in all the above cases. To turn off reporting Newton errors entirely, use the statement

Report newton errors = none ;

The following Command file statement allows you to include in these reports just the Newton errors greater than a specified number:

Report newton min_error = <r1> ; ! optional, default <r1> = 0

where r1 is a real number. For example if you include a statement in your Command file

Report newton min_error = 10 ;

the program will only print out information about equations for which the Newton correction term is greater than 10. It will also print out the name of the equation and components where the Newton correction term occurred.

The LOG file discussed in section 9.3.1 above should make the effect of these different statements clear.

Other Examples

Sections 26.5.5.2 and 26.5.5.3 describe simulations using Newton's method. The Command files include the statement

Report newton errors = all ;

so the sizes of the error terms are reported after every step (Euler or Newton). Look at the LOG files SJLVLBNW.LOG and SJLVLBNW2.LOG produced to see how the errors change after the different steps.

10    The TABLO language: basic syntax [gpd2.3]

Click here for detailed chapter contents

When implementing an economic model within GEMPACK, you prepare a TABLO Input file specifying the theory of the model. This specification uses the statements listed below. This chapter contains a full description of the syntax of these statements. Details about the semantics of these statements are given in chapter 11.

SETSUBSETCOEFFICIENTVARIABLEFILE
READWRITEFORMULAEQUATIONUPDATE
ZERODIVIDEDISPLAYMAPPINGASSERTIONTRANSFER
OMITSUBSTITUTEBACKSOLVECOMPLEMENTARITYPOSTSIM

In the following TABLO syntax specifications :

As an example of the general form of a TABLO statement, the following declares a variable PCOM.

VARIABLE(PERCENT_CHANGE) (all,i,COM) PCOM(i) #Price of commodity i# ;

In this statement

The syntax specification for VARIABLE is given below as:

VARIABLE [ (qualifier_list) ] [quantifier_list] 
    <variable_name> [ (index_1,... ,index_n) ]  [#<information># ] ;

10.1    SET [gpd2.3.1]

A list of categories (for example, the SET of commodities or the SET of industries).

A SET can be defined by

(1) listing all its elements :

SET [ (qualifier) ] <set_name> [#<information># ]
  (<element_1, . . . ,element_n>);

For example:

Set COM # Commodities # (wool, car, food) ;
Set IND # Industries # (ind1 - ind100) ;

The second example illustrates the way lists of element names can sometimes be abbreviated: see section 11.2.1 below for details.

(2) by saying where its elements can be read from :

SET [ (NON_INTERTEMPORAL) ] <set_name> [#<information># ]
  [ MAXIMUM SIZE <integer> ]  READ ELEMENTS FROM
 FILE <logical_name> HEADER "<header_name>" ;

For example:

Set IND # Industries # read elements from file INFILE header "INDE" ;

Alternatively, a SET can be defined by the following two obsolete or rarely-used forms:

(3) giving its size as an integer :

SET [ (NON_INTERTEMPORAL) ] <set_name> [#<information># ]
  SIZE <integer> ;

For example:

Set COM # Commodities # size 10 ; !not recommended ! ;

(4) by specifying its maximum size and giving its size as the value of an integer coefficient (one with no arguments).

SET [ (NON_INTERTEMPORAL) ] <set_name> [#<information># ]
  [ MAXIMUM SIZE <integer> ]  SIZE <integer_coefficient> ;

where <integer_coefficient> must have been declared as an integer coefficient which is a parameter (as described in section 10.3 below). For example:

Set COM # Commodities # maximum size 114  size NCOM ;  !not recommended !

Sets defined as in (3) and (4) above do not have elements defined at run time. That is, no names are given to the elements of the set when GEMSIM or the TABLO-generated program runs. For this reason, we encourage you not to use these types of sets in new models. Sets with named elements (such as those defined by (1) and (2) above and (5) below) are much easier1 to work with. We recommend that you only work with sets whose elements are named either in the TABLO Input file or at run time (the element names are read from a Header Array file).

The possible SET qualifiers are INTERTEMPORAL and NON_INTERTEMPORAL, of which NON_INTERTEMPORAL is the default (and so is usually omitted).

Of these four above, only (1) can be used for intertemporal sets.

In an intertemporal model, there are equations (and possibly formulas) in which coefficients and/or variables have arguments of the form 't+1', 't-3'. Argument t+1 refers to the value of the variable or coefficient at the time-point t+1 (1 interval after the current time t). The sets over which such arguments can range are called intertemporal sets: they are usually time-related. Intertemporal models are discussed in chapter 16.

(5) Intertemporal sets can also be declared using the following syntax (where the SET qualifier INTERTEMPORAL is used).

SET  (INTERTEMPORAL)  <set_name> [#<information># ]
  [ [MAXIMUM] SIZE <integer> ]
  ( <stem> [ <initial-element> ] - <stem> [ <end-element> ] ) ;

Both <initial-element> and <end-element> must each be either an integer or an expression of the form

<integer_coefficient> + <integer>OR<integer_coefficient> - <integer>

where <integer_coefficient> must have been declared as an integer coefficient which is a parameter (as described in section 10.3 below). For example:

Set (Intertemporal) FWDTIME (p[0] - p[NINTERVAL-1]) ;

We say that sets defined in this way have intertemporal elements. See section 16.2.1 below for more details.

The square brackets '[ ]' around "initial-element" and "end-element" in template (5) above do not indicate optional syntax in this case but are used for intertemporal sets whose actual sizes are read in at run time. These [] are used in the run-time names of the element (see section 11.7.1).

The second (SIZE)2 line in the syntax pattern above is optional and indeed obsolete. It was needed by GEMPACK Release 7.0 or earlier, but is now ignored, if present (see section 11.7.2).

See chapter 16 about INTERTEMPORAL models, and the definition of intertemporal sets.

10.1.1    Set expressions (includes unions, intersections and complements) [gpd2.3.1.0]

GEMPACK supports the following set union, intersection and complement statements:

SET <set_name> [#<information># ] = <setname1> + <setname2> ;
SET <set_name> [#<information># ] = <setname1> UNION <setname2> ;
SET <set_name> [#<information># ] = <setname1> INTERSECT <setname2> ;
SET <set_name> [#<information># ] = <setname1> - <setname2> ; 
SET <set_name> [#<information># ] = <setname1> \ <setname2> ;

The elements of the "+" joined set are those in <set-name1> followed by those in <set-name2>.

The elements of the UNION are those in <set-name1> followed by those in <set-name2> which are not in <set-name2>.

Both "+" and "UNION" can be used to specify set union. The difference is that "+" specifies that the two sets <setname1> and <setname2> must have no elements in common (that is, are disjoint). This is checked at run time. You should use the "UNION" form only if you intend that the two sets might share elements.

The elements of the INTERSECTion are those in <set-name1> which are also in <set-name2>. Elements are ordered as in <set-name1>.

Set operator "-" is used to denote the set complement. The elements of the complement are all the elements in <setname1> which are not in <setname2>. You can only use set operator "-" in the expression "<setname1> - <setname2>" if <setname2> is a subset of <setname1>.

The set complement operator "\" was introduced in GEMPACK Release 10.0-002. If
<setname> = <setname1> \ <setname2>
then, as with "-", the elements of <setname> are all elements of <setname1> which are not elements of <setname2>. However, there is no longer the requirement that every element of <setname2> is also an element of <setname1>. You should use this "\" form only if you think it possible that some elements of <setname2> are not elements of <setname1>.

Suppose, for example, that we have the two statements

SET SET1 (c1-c5) ;
SET SET2 (c3, c1, d5) ;

Notice that element "d5" is in set SET2 but not in SET1. Then the statement

SET3 = SET1 - SET2 ;

is not allowed while the statement

SET4 = SET1 \ SET2 ;

is valid and the elements of SET4 will be c2, c4 and c5.

We call "SET1 - SET2" the set complement of SET2 in SET1 while we call "SET3 \ SET4" the relative complement of SET4 in SET3. The word "relative" is used to indicate that not every element of the set after the operator needs to be an element of the set before the operator.

See section 11.7.3 for more details of set unions and intersections.

See section 11.7.4 for more details about set complements and relative complements.

Simple examples of union, intersection and complements
! given: !
Set DomCOM # Domestic Commodities# (Food, Manufact, Services) ;
Set ExportCOM #Export Commodities# (ExportFood, Manufact) ;
Set AggCOM # Agricultural Commodities# (Food, ExportFood) ;

! Union !
Set AllCOM2 # Domestic and Export Commodities UNION # = DomCOM UNION ExportCOM ;
! result: Food, Manufact, Services, ExportFood !

! Intersection !
Set CommonCOM # Commodities which are both Domestic and Export Commodities#
            = DomCOM INTERSECT ExportCOM ;
! result: Manufact !

! Complement !
Set NonExportCOM # Domestic commodities not exported #  = DomCOM - CommonCOM ;
! result: Food, Services !

! Relative Complement !
Set NonExpAggCOM # Agricultural commodities not exported #  = AggCOM \ ExportCOM ;
! result: Food !

! Disjoint Set Union !
Set ALLCOM # Domestic and Export Commodities + # =  ExportCOM + NonExportCOM ;
! result: ExportFood, Manufact, Food, Services!

10.1.1.1    Longer set expressions [gpd2.3.1.0b]

We also allow longer set expressions3 involving the set operators UNION, INTERSECT, "+", "-" and "\". You are also allowed to use brackets "(" or ")" to indicate the order of doing these operations. [But other types of brackets "[", "]", "{" and "}" are not allowed in set expressions.]

These operators can appear on the right-hand side of a SET statement (that is, after "="). Also on this right-hand side can be the names of sets already declared in the TAB file. And, as well as sets, you are allowed to give a name in quotes "" which indicates a single element. Examples should make this clear.

SET SET1 (c1-c5) ;
SET SET2 (c3, c1, d5) ;
SET SET3 (d1-d7) ;
SET SET4 (domestic, imported) ;
SET SetExp1 = SET1 UNION SET2 + "cars" ;
SET SetExp2 = SET1 - SET2 + "imports" ;
SET SetExp3 = SET1 \ (SET2 - "c1") ;
SET SetExp4 = "hous" + "gov" + "exp" ;
SET SetExp5 = SET4 UNION (SET2 INTERSECT SET3) + "wool" ; 

You should be able to figure out the elements of the sets SetExp1 to SetExp5 determined by the set expressions above, especially when we tell you that (in the absence of brackets indicating otherwise) operations are carried out from left to right. That is, for example, the expression
SET1 - SET2 - SET3
is evaluated as
(SET1 - SET2) - SET3.

See 11.7.5 for more details about these longer set expressions.

10.1.2    Equal sets [gpd2.3.1.2]

10.1.2.1    Non-Intertemporal sets [gpd2.3.1.2a]

A new set can be defined by indicating that it is equal to a previously defined set. The syntax is:

SET <set_name> [#<information># ] = <setname1> ;

Here <set_name1> must be a non-intertemporal set whose elements will be known at run time.

The set equality statement above automatically generates two subset statements, namely

SUBSET  <set_name> IS SUBSET OF <setname1> ;
SUBSET  <setname1> IS SUBSET OF <set_name> ;

See section 11.7.3 for details about the semantics of Set Equality statements.

10.1.2.2    Converting Non-Intertemporal Sets to Intertemporal Sets and vice versa [gpd2.3.1.2b]

You can also use a set equality statement to convert a non-intertemporal set to an intertemporal one, or vice versa. See 13.3.1 for details.

10.1.3    Data-dependent sets [gpd2.3.1.3]

Sets depending on data can be specified using the syntax:

SET <new_set> = (All, <index>, <old_set> : <condition>) ;

In the above, <old_set> is not allowed to be an intertemporal set.

The above SET statement automatically generates the following SUBSET statement:

SUBSET <new_set> IS SUBSET OF <old_set> ;

Example:

SET EXPIND # export-intensive industries #  = (all,i,IND : EXP(i) > 0.2*SALES(i)) ;

This defines the set of export-intensive industries to consist of all industries whose exports, EXP(i), are at least 20% of total sales, SALES(i).

See section 11.7.6 for more details.

10.1.4    Set examples from ORANIG model [gpd2.3.1.5]

We show below examples of sets used in the TABLO Input file ORANIG01.TAB. (ORANIG01 is one of our main example models — see section 8.1.1.) There are examples of run-time sets (COM, SRC, IND, OCC....), sets which are subsets of a larger set (MAR, DEST), set complements (NONMAR, NATCOM, NATIND), data-dependent sets (TRADEXP, LOCCOM) and an intersection (LOCIND).

File  BASEDATA  # Input data file #;
Set                                                                 ! index !
 COM # Commodities# read elements from file BASEDATA header "COM";   ! c !
 SRC # Source of commodities # (dom,imp);                            ! s !
 IND # Industries # read elements from file BASEDATA header "IND";   ! i !
 OCC # Occupations # read elements from file BASEDATA header "OCC";  ! o !
 MAR # Margin commodities # read elements from file BASEDATA header "MAR";
Subset MAR is subset of COM;
Set NONMAR   # Non-margin commodities # = COM - MAR;                 ! n !

Coefficient (parameter)(all,c,COM) IsIndivExp(c) 
      # >0.5 for individual export commodities#;
Read IsIndivExp from file BASEDATA header "ITEX";
! This way of defining a set facilitates aggregation of the data base ! 
Set TRADEXP # Individual export commodities # 
       = (all,c,COM: IsIndivExp(c)>0.5);
Write (Set) TRADEXP  to file SUMMARY header "TEXP";
Set NTRADEXP # Collective Export Commodities # = COM - TRADEXP;
Write (Set) NTRADEXP  to file SUMMARY header "NTXP";

Coefficient (parameter)(all,c,COM) IsLocCom(c) 
    # Flag, 1 for local coms, 0 for national #;
Read IsLocCom from file BASEDATA header "LCOM";
! nearly all of local commodities must be produced in region of use
  or, for exports to ROW, in source region !
Set LOCCOM      # Local Commodities (Set L, DPSV p.259) #
   = (all,c,COM: IsLocCom(c) > 0.5 );
Set NATCOM = COM - LOCCOM;
Set LOCIND # Local Industries # = LOCCOM intersect IND;
! This assumes that a local commodity in LOCCOM must have 
    the same name as the local unique-product industry in LOCIND
    which produces it !
Set NATIND = IND - LOCIND;

Set MARLOCCOM #Local margin commodities# = MAR intersect LOCCOM;
Set NONMARLOCCOM = LOCCOM - MARLOCCOM;

10.1.5    Set examples from GTAP model [gpd2.3.1.6]

This section contains examples of sets used in GTAP4 -- one of our main example models.

!    Aide-Memoire for Sets
    |--------------------------------------|
    |         DEMD_COMM                    |
    |----------------------------------------------------|
    | ENDW_COMM |       TRAD_COMM          |  CGDS_COMM  |
    |----------------------------------------------------|
    |        NSAV_COMM                                   |
    |----------------------------------------------------|
                |                     PROD_COMM          |
                |----------------------------------------| !
Set    
REG # regions in the model # read elements from file GTAPSETS header "H1";
TRAD_COMM # traded commodities # read elements from file GTAPSETS header "H2";
MARG_COMM # margin commodities # read elements from file GTAPSETS header "MARG";
CGDS_COMM # capital goods # read elements from file GTAPSETS header "H9";
ENDW_COMM # endowment commodities# read elements from file GTAPSETS header "H6";
PROD_COMM # produced commodities # = TRAD_COMM + CGDS_COMM;
DEMD_COMM # demanded commodities # = ENDW_COMM + TRAD_COMM;
NSAV_COMM # non-savings commodities # = DEMD_COMM + CGDS_COMM;
Subset
 PROD_COMM is subset of NSAV_COMM;
 MARG_COMM is subset of TRAD_COMM;
Set    NMRG_COMM # non-margin commodities # = TRAD_COMM - MARG_COMM;

Coefficient (Integer) (all,i,ENDW_COMM)
    SLUG(i) # binary flag, 1 for sluggish endowments, 0 for mobile #;
Read SLUG from file GTAPPARM header "SLUG";
Set
 ENDWS_COMM # sluggish endowment commodities # = (all,i,ENDW_COMM: SLUG(i)>0);
 ENDWM_COMM # mobile endowment commodities #   = ENDW_COMM - ENDWS_COMM;
 ENDWC_COMM # capital endowment commodity # (capital);
Subset ENDWC_COMM is subset of ENDW_COMM;

10.1.6    Set products [gpd2.3.1.4]

Set products (sometimes called Cartesian products) are allowed via a statement with syntax:

SET <new_setname> [#<information># ] = <setname1> X <setname2> ;

In this case we say that <new_setname> is the product of <setname1> and <setname2>.

Both <setname1> and <setname2> must be non-intertemporal sets.

Set product is allowed even when <setname1> or <setname2> does not have known elements. Then the product does not have known elements either.

Ideally, the elements of set1 are of the form xx_yyy where xx ranges over all elements of setname1 and yyy ranges over all elements of setname2 — essentially the product set consists of all ordered pairs (xx,yyy). However, since element names are limited to 12 characters (see section 11.2.1), some compromise must be made if the names from the constituent sets are too long.

The size of the product set is, of course, the product of the sizes of the two sets.

Examples:

SET COM (Food, Agric, Serv) ;
SET SOURCE (dom, imps) ; ! domestic or imports !
SET COM2 (Food, Agriculture, Services) ;
SET S4 = COM x SOURCE ;
SET S5 = SOURCE x COM ;
SET S6 = COM2 x SOURCE ;

The elements of S4 will be:

Food_dom, Agric_dom, Serv_dom, Food_imps, Agric_imps, Serv_imps

The elements of S5 will be:

dom_Food, imps_Food, dom_Agric, imps_Agric, dom_Serv, imps_Serv

Note that the elements of the first set vary faster and those of the second set vary slower. This is consistent with a variable X(i,j) where the "i" varies faster and the "j" slower in the component ordering — see section 66.4.

You cannot use the "x" set product operator to directly produce the set:

Food_dom, Food_imps, Agric_dom, Agric_imps, Serv_dom, Serv_imps

since in this case the elements of the second set vary faster. Instead you have to use the set S5, which is functionally identical.

Avoid long element names

Note the combined names of sets S4 and S5 still have no more than 12 characters.

GEMPACK must compromise for the elements of set S6 since "Agriculture" has 11 characters. The elements of S6 turn out to be:

C1Food_dom, C2Agric_dom, C3Servi_dom, C1Food_imps, C2Agric_imps, C3Servi_imps

This is explained in section 11.7.11 below.

You can prevent GEMPACK making up such names by ensuring that the (RHS) sets making up a set product have short elements (5 letters or less).

Mappings from product sets

The most useful feature of product sets is that if we define

SET S4 = COM x SOURCE ;

we can automatically generate a mapping from S4 to COM via

MAPPING (PROJECT)  S4toCOM from S4 to COM;

or a mapping from S4 to SOURCE via

MAPPING (PROJECT)  S4toSOURCE from S4 to SOURCE;

These projection mappings are explained in section 10.13.2.

10.1.7    Ranked sets [gpd2.3.1.6a]

You may wish to order set elements according to simulation results (for example, to identify the 5 industries which gain most and/or the five which lose most) or according to data or values of Coefficients (either pre-simulation or post-simulation values).

See chapter 13 for details of the syntax and semantics, and several examples.

10.2    SUBSET [gpd2.3.2]

The SUBSET statement states that one set is part of another. Section 11.8 below explains when SUBSET statements are required. The syntax is:

SUBSET  [ (BY_ELEMENTS) ] <set1_name>  IS SUBSET OF <set2_name> ;

For example:

Set AGRIC_COM # farm products # read elements from file BASEDATA header "AGRI";
Subset AGRIC_COM is subset of COM ;

Above, both of the sets AGRIC_COM and COM must be declared previously.

SUBSET (BY_NUMBERS)

The possible SUBSET qualifiers are BY_ELEMENTS or BY_NUMBERS, of which BY_ELEMENTS is the default (and so usually omitted). In the rare or obsolete SUBSET(BY_NUMBERS) form, the element numbers (ie, positions) in the big set of the elements in the small set can be given via the syntax:

SUBSET (BY_NUMBERS)  <set1_name>  IS SUBSET OF <set2_name> 
 READ ELEMENT NUMBERS FROM FILE <logical_name>
   HEADER  "<header_name>" ;

For example:

Set AGRIC_COM # farm products # size 6;
Subset (by_numbers) AGRIC_COM is subset of COM
  read element numbers from file BASEDATA header "AGRN";

The header "AGRI" would contain 6 integers showing the positions in set COM of the AGRIC_COM elements. In most cases, it would be better to use a more conventional SUBSET statement, as in the previous example.

10.2.1    Subset examples from ORANIG model [gpd2.3.2.1]

Some of the subsets of the ORANIG model are shown in section 10.1.4 above. Note that the set complement statement defining NONMAR requires that MAR is already declared to be a subset of COM

Subset MAR is subset of COM;
Set NONMAR   # Non-margin commodities # = COM - MAR;                 ! n !

However, it is not necessary to have a subset statement for the set NONMAR since NONMAR is automatically defined to be a subset of the set COM (see section 11.7.4).

10.2.2    Subset examples from GTAP model [gpd2.3.2.2]

Some SUBSET examples from GTAP are shown in the example section 10.1.5 above. There are many subsets in GTAP. Many of the sets are defined as unions of smaller sets. The union automatically defines the smaller sets as subsets of the union (see section 11.7.3).

For example, the set DEMD_COMM is defined by

Set DEMD_COMM = ENDW_COMM + TRAD_COMM;

This means that ENDW_COMM and TRAD_COMM are both subsets of DEMD_COMM. It is only in more complicated cases that you need to include the SUBSET statement, for example, for the set PROD_COMM.

10.3    COEFFICIENT [gpd2.3.3]

Coefficients represent real numbers (the default) or integers. They can occur as:

See section 11.6.1 for more details. The syntax is:

COEFFICIENT [ (qualifier_list) ] [quantifier_list]  <coefficient_name> [ (index_1,... ,index_n) ]
    [#<information># ]  ;

If there are n indices in the declaration, this defines an n-dimensional array. For REAL or INTEGER coefficients, n must be between 0 and 7 (inclusive). The number n is referred to as the dimension of the coefficient, or its number of arguments or indices. Examples

COEFFICIENT (all,i,COM) TOTSALES(i) # Total sales of commodities # ;
COEFFICIENT (all,i,COM)(all,j,IND) INTINP(i,j)  ;
COEFFICIENT (REAL)    GNP   # Gross National Product #   ;
COEFFICIENT (INTEGER) NCOM  # Size of set COM # ;
COEFFICIENT (PARAMETER) (all,j,COM) ALPHA(j) ;
COEFFICIENT (INTEGER, NON_PARAMETER) NCOUNT ;
COEFFICIENT (GE 20.0) (all,i,COM)  DVHOUS(i) ;

The possible COEFFICIENT qualifiers are:

See also section 11.6.3 for a description of "Integer Coefficients in Expressions and Elsewhere", section 11.11.1 for "How Data is Associated With Coefficients", section 11.4.10 for information about indices in coefficients and section 11.6.4 on "Where Coefficients and Levels Variables Can Occur".

Examples of coefficients from ORANIG model
Coefficient  ! Basic flows of commodities (excluding margin demands)!
(all,c,COM)(all,s,SRC)(all,i,IND) V1BAS(c,s,i) # Intermediate basic flows #;
(all,c,COM)(all,s,SRC)(all,i,IND) V2BAS(c,s,i) # Investment basic flows #;
(all,c,COM)(all,s,SRC)            V3BAS(c,s)   # Household basic flows #;
(all,c,COM)                       V4BAS(c)     # Export basic flows #;
(parameter)(all,i,IND) SIGMA1PRIM(i) # CES substitution, primary factors #;
                               V3TOT # Total purchases by households #;
(parameter)(all,c,COM) IsIndivExp(c) # >0.5 for individual export commodities#;
Read IsIndivExp from file BASEDATA header "ITEX";
Examples of coefficients from GTAP model
Coefficient SIZE_TRAD # size of TRAD_COMM set #;
Formula SIZE_TRAD = sum(i,TRAD_COMM,1);

Coefficient (Integer) (all,i,ENDW_COMM)
    SLUG(i) # binary flag, 1 for sluggish endowments, 0 for mobile #;

Coefficient (all,r,REG) SAVE(r) 
# expenditure on NET savings in region r valued at agent's prices #;

Coefficient (ge 0)(all,i,TRAD_COMM)(all,r,REG)
 VDGA(i,r) # government consumption expenditure on domestic i in r #;

Coefficient (all,i,DEMD_COMM)(all,j,PROD_COMM)(all,r,REG) 
VFA(i,j,r) # producer expenditure on i by j in r valued at agents' prices #;

10.4    VARIABLE [gpd2.3.4]

An economic variable (unknown) that occurs in one or more EQUATIONs. In a simulation, each variable must be specified to be exogenous or endogenous. The set of equations is solved to find the value of percentage changes (or ordinary changes) in the levels variables.

VARIABLE [ (qualifier_list) ] [quantifier_list] 
    <variable_name> [ (index_1,... ,index_n) ]  [#<information># ] ;

The number of indices must be between 0 and 7. This number is referred to as the dimension of the coefficient, or its number of arguments or indices.

The possible VARIABLE qualifiers are:

The last form of qualifier above can be used when declaring a LEVELS variable. It declares a specified range within which the value of the Levels Variable must stay5. [For example, if X(i) must be positive, you could use the qualifier (GT 0) when declaring the Levels Variable X.] These qualifiers request the program to check that the value of the levels variable stays within this range at run time. See sections 11.6.7 and 25.4 for details. Default ranges may apply — see section 10.19.1.

The declaration of a LEVELS variable X results in

in the associated linearized TABLO Input file (see section 9.2.2 above).

Example variable statements
Variable
 (all,i,COM)  p0(i)  #Basic price of commodities #;
 (percent_change)  (all,i,COM)(all,s,SRC)  xhous(i,s)
    # Household consumption of commodity i from source s #;
 phi  # exchange rate #  ;
 (change) delB # Change in Balance of Trade # ;
 (levels, change) (all,i,SECT) Q(i) ;
 (Levels, GE 0) (all,i,SECT) X(i) ;

Coefficient (all,i,IND) Y(i)  # Output #;
Variable (ORIG_LEVEL = Y)  (all,i,IND) yy(i)  
                     # yy is Percent change in Y # ; 
Variable (Orig_level=1)  (All,i,SECT)  p_PCOM(i) ; 

For more information see sections:

11.4.8for use of "Linear Variables in Expressions"
11.4.10for information about indices in variables
11.6.4on "Where Coefficients and Levels Variables Can Occur"
11.6.5for details of "Reporting Levels Values when Carrying Out Simulations"
11.6.7for details on "Specifying Acceptable Range of Coefficients Read or Updated".
Examples of variables from ORANIG01.TAB
Variable  
(all,c,COM)(all,s,SRC)(all,i,IND) x1(c,s,i)  # Intermediate basic demands #;
(all,c,COM)(all,s,SRC)(all,i,IND) x2(c,s,i)  # Investment basic demands #;
(all,c,COM)(all,s,SRC)            x3(c,s)    # Household basic demands #;
(all,c,COM)                       x4(c)      # Export basic demands #;
(all,c,COM)(all,s,SRC)            x5(c,s)    # Government basic demands #;
(change) (all,c,COM)(all,s,SRC)   delx6(c,s) # Inventories demands #;
(all,c,COM)(all,s,SRC)            p0(c,s)    # Basic prices for local users #;
(all,c,COM)                       pe(c)      # Basic price of exportables #;
(change)(all,c,COM)(all,s,SRC)    delV6(c,s) # Value of inventories #;

Variable
f5tot  # Overall shift term for government demands #;
f5tot2 # Ratio between f5tot and x3tot #;
x4tot  # Export volume index #;
p4tot  # Exports price index, local currency #;
w4tot  # Local currency border value of exports #;
Examples of variables from GTAP61.TAB
Variable (all, r, REG) psave(r) # price of savings in region r #;
Variable (all,r,REG)   qsave(r) # regional demand for NET savings #;
Coefficient (all,r,REG) SAVE(r) 
  # expenditure on NET savings in region r valued at agent's prices #;
Update (all,r,REG) SAVE(r) = psave(r) * qsave(r);

Variable (all,i,TRAD_COMM)(all,s,REG)
  pgd(i,s) # price of domestic i in government consumption in s #;

Coefficient (ge 0)(all,i,TRAD_COMM)(all,r,REG)
  VDGM(i,r) # government consumption expenditure on domestic i in r #;
Variable (orig_level=VDGM)(all,i,TRAD_COMM)(all,s,REG)
  qgd(i,s) # government hhld demand for domestic i in region s #;

Variable (orig_level = 1.0)(all,i,NSAV_COMM)(all,r,REG)
  pm(i,r) # market price of commodity i in region r #;

Variable (change) (all,r,REG) del_taxrgc(r) 
  # change in ratio of government consumption tax to INCOME #;

10.5    FILE [gpd2.3.5]

A file containing input data (for example, base data for the model), or output.

FILE [ (qualifier_list) ]  <logical_name>
  [ "<actual_name>" ]  [#<information># ]  ;

See sections 11.10 and 22.1 below for the connection between the logical file names in TABLO Input files and actual data files on your computer. Although this connection can be hard-wired by including the optional "<actual_name>" in the TAB file, we recommend that you avoid this — see section 11.10.

The possible FILE qualifiers are:

(1) OLD or NEW or FOR_UPDATES (OLD is the default).
OLD files are used for reading data from a pre-existing file, NEW files for writing data and creating a new file. Data cannot be written to an OLD file or read from a NEW file.
The FILE qualifier "FOR_UPDATES" is provided to declare a file which can have updated values written to it — see section 11.12.8.

(2) HEADER or TEXT (HEADER is the default).
Files can be GEMPACK Header Array files (as described in chapter 6 and in section 5.0.1) or TEXT data files (described in section 11.10.1 and also in chapter 38).

(3) ROW_ORDER or COL_ORDER or SSE or SPREADSHEET, SEPARATOR = "<character>"
These qualifiers are only relevant when you are writing a text file; that is, they must only be used after both of the qualifiers NEW, TEXT. The default is ROW_ORDER.

SPREADSHEET is similar to row order but there is a separator between data items. The default separator is a comma. To use a different separator, include the qualifier SEPARATOR = followed by the single-character separator surrounded by quotes. For example, SPREADSHEET, SEPARATOR = ";" would separate values with semicolons ;

SSE output is suitable for reading into a spreadsheet. Matrices in the output have row and column element labels. See section 10.5.1 for examples.

Other details about the syntax of text data files and row order, column order and spreadsheet data are given in chapter 38.

(4) GAMS as in FILE(NEW,GAMS). This is used when converting GEMPACK-style data to (old-fashioned) GAMS-style text data. See section 78.2 for details.

File examples
File IO  # Input-output data # ;
File (old) PARAMS  "PAR79.DAT" # parameters # ; ! not recommended !
File (New, Text) SUMMARY ;
File (New, Text, SSE)  OUTPUT1  # SSE output of coefficients # ;
File (Text, New, Spreadsheet, Separator=";") TABLE ;
File (For_updates) IO_UPDATED  #to contain updated prices# ;

See also section 11.10 on Files, section 11.10.1 on Text files and chapter 6 on HAR files.

Examples of files from ORANIG01.TAB
File  BASEDATA  # Input data file #;
File (new) SUMMARY  # Output for summary and checking data #;

Read V1BAS from file BASEDATA header "1BAS";

Write (Set) TRADEXP  to file SUMMARY header "TEXP";
Write SALE to file SUMMARY header "SALE";
Examples of files from GTAP61.TAB
File GTAPSETS # file with set specification #;
Set  REG # regions in the model #
    maximum size 10 read elements from file GTAPSETS header "H1";

File GTAPDATA # file containing all base data #;
Read  VDGA from file GTAPDATA header "VDGA";

File GTAPPARM # file containing behavioral parameters #;
Read  ESUBD from file GTAPPARM header "ESBD";

10.5.1    SSE output [gpd5.9.1]

A file might be declared via:

File (New, Text, SSE)  Output1  # SSE output of coefficients # ;

If "SSE" is specified, output to the file is suitable for reading into a spreadsheet. Matrices in the output have row and column elements labels. The relevant part of the Coefficient or Variable is shown in the top left-hand corner.

The output is similar to SSE output from SLTOHT (see section 40.3) and from SEEHAR (see the example in section 76.0.1.2).

Example of SSE Output from TG-program or GEMSIM
RegResults1(REG:RegVar1)uyEV
AUS0.0530.216157.499
NAM0.285-0.62816467.627
E_U0.207-0.44612159.798
JPN-0.051-0.119-1614.914
NIE-0.897-0.901-4505.593
ASN0.9932.4323540.311
................

10.6    READ [gpd2.3.6]

An instruction that the values of a given COEFFICIENT are to be read directly from a given FILE (or, rarely, from the terminal).

All the values can be read into a COEFFICIENT :

READ [qualifier_list] <coefficient_name> 
                   FROM <location>  [#<information># ]  ;

or, if just a part of the COEFFICIENT must be read :

READ [qualifier_list]  [quantifier_list]  
 <coefficient_name>  (argument_1,... ,argument_n) 
  FROM <location>  [#<information># ]  ;

In the above, <location> must be

(1) FILE <logical_name> HEADER "<header_name>     if the file is a Header Array file,

(2) FILE <logical_name>     if the file is a text file, or

(3) TERMINAL     if the data is to be read from the terminal.

There are two possible qualifiers making up [qualifier_list]. These are (BY_ELEMENTS) and (IfHeaderExists).

The qualifier (BY_ELEMENTS) is only allowed when reading a list of set elements to define a set mapping (see section 10.13 below).

The qualifier (IfHeaderExists) is only allowed for a read from a Header Array file. Then the read is only done if the specified header exists on the relevant file. See section 11.11.8 for details.

An argument is either an index or the element of a SET. Index offsets are not allowed. See 11.2.4 for more details.

A levels variable can be given as the name of the coefficient being read. (This is because the declaration of a VARIABLE(LEVELS) produces a COEFFICIENT of the same name in the associated linearized TABLO Input file, as explained in section 9.2.2 above.)

Examples

READ TOTSALES FROM FILE io HEADER "TSAL" ;
READ (all,i,COM) INTINP(i,"wool") FROM FILE params ; ! a partial read !
READ INTINP FROM TERMINAL ;

See also section 11.11 on "Reads, Writes and Displays".

At present, data cannot be read into an integer coefficient with more than 2 dimensions (but values can be assigned via a formula).

Examples of reads from ORANIG model
File  BASEDATA  # Input data file #;
Coefficient  
 (all,c,COM)(all,s,SRC)(all,i,IND)  V1BAS(c,s,i)  # Intermediate basic flows #;
Read   V1BAS from file BASEDATA header "1BAS";
Examples of reads from GTAP model
Read  SAVE from file GTAPDATA header "SAVE";
      VDGA from file GTAPDATA header "VDGA";
Coefficient (all,i,TRAD_COMM) ESUBD(i)
  # region-generic el.of sub domestic/imported in Armington for all agents #;
Read ESUBD from file GTAPPARM header "ESBD";

10.7    WRITE [gpd2.3.7]

An instruction that the values of a given COEFFICIENT are to be written to a given FILE or (rarely) to the terminal.

All the values of a COEFFICIENT can be written via the syntax:

WRITE [qualifier_list] <coefficient_name> TO <location> [#<information># ]  ;

or, just a part of the COEFFICIENT can be written :

WRITE [qualifier_list] [quantifier_list]  
 <coefficient_name>  (argument_1,... ,argument_n) 
  TO <location>  [#<information># ]  ;

The # information # field in Write statetements is optional and ignored — so is rarely used in practice.

In the above, <location> must be

(1) if the file is a Header Array file:

FILE <logical_name> HEADER "<header_name>" [LONGNAME "<long_name>"]  

The LONGNAME "<long_name>" is optional; if omitted, the long name written on the file is determined as described in section 11.11.7.]

(2) if the file is a text file: FILE <logical_name> ;

or (3) if the data is to be written to the terminal (ie, the log file): TERMINAL

There are two possible qualifiers making up [qualifier_list]:

An argument is either an index or the element of a SET. Index offsets are not allowed. See 11.2.4 for more details.

A levels variable can be given as the name of the coefficient being written. (This is because the declaration of a VARIABLE(LEVELS) produces a COEFFICIENT of the same name in the associated linearized TABLO Input file, as explained in section 9.2.2 above.)

There are two qualifiers used for writing the elements of sets to text or Header array files:

WRITE (SET) <setname> TO FILE <logical-file> [ HEADER "<header>"]  ;

or, to write all sets to a Header Array file (you do not specify Header names):.

WRITE (ALLSETS) TO FILE <hafile> ;
Examples
Write TOTSALES to file IO header "TSAL" ;
Write COMPROD  to file BASEDATA header "COMP" 
       longname "Production of commodity i by industry j" ;
Write (all,i,COM) INTINP(i,"wool") to file PARAMS ; ! partial write to text !
Write INTINP to terminal ;
Write (set)  COM  to  file  OUTFILE header  "COMS" ;
File (new) manysets ;
Write (Allsets) to FILE  manysets ;

At present, data cannot be written from all or part of an integer coefficient with more than 2 dimensions.

See also sections:

11.11on "Reads, Writes and Displays"
11.7.7 and 11.7.8for details on writing one (or all) sets to file
10.13for details about writing mappings.
Example of writes from ORANIG01.TAB
File (new) SUMMARY  # Output for summary and checking data #;
Write(set) TRADEXP  to file SUMMARY header "TEXP";
Write SALE to file SUMMARY header "SALE";

10.8    FORMULA [gpd2.3.8]

An algebraic specification of how the values of a given COEFFICIENT are to be calculated from those of other COEFFICIENTs.

FORMULA [ (qualifier) ] [#<information>#] [quantifier_list]  
 <coefficient_name>  (argument_1,... ,argument_n) = expression ;

Possible qualifiers are INITIAL or ALWAYS. The default is ALWAYS for formulas with a real coefficient on the left-hand side and is INITIAL for formulas with an integer coefficient on the left-hand side. In the former case (real coefficient on the LHS), the default can be reset by use of a Default statement (see section 10.19).

FORMULA(INITIAL)s are only calculated during the first step in a multi-step simulation, while FORMULA(ALWAYS)s are calculated at every step.

A levels variable can be given as the <coefficient_name> being calculated on the left hand side of a FORMULA(INITIAL). However a levels variable can not be given on the left hand side of a FORMULA(ALWAYS) because a levels variable is automatically updated using its associated percentage change or change at later steps.

A FORMULA(INITIAL) produces a READ statement in the associated linearized TABLO Input file. The FORMULA is used in step 1 of a multi-step calculation while the READ is used in subsequent steps. (See section 11.11.4 below.)

Another possible qualifier is BY_ELEMENTS. This qualifier is only allowed if <coefficient_name> is a set mapping (see section 10.13) - that is, if Coefficient <coefficient_name> has been declared as a set mapping.

Index offsets (see sections 11.2.4) are not allowed in the arguments of the left-hand side of a FORMULA(INITIAL) since they are not allowed in a READ statement (see section 11.11.4)

See section 11.4 for the syntax of expressions used in FORMULAs.

An argument is either an index or the element of a SET, as described in section 11.2.4.

See section 10.13 for details about special formulas for mappings.

The qualifier "WRITE UPDATED ..." used for FORMULA(INITIAL) has the syntax:

FORMULA (INITIAL,
   WRITE UPDATED VALUE TO FILE <logical_filename> 
     [HEADER "<headername>"] [LONGNAME "<words>"])  
 [#<information>#] [quantifier_list]  
 <coefficient_name>  (argument_1,... ,argument_n) = expression ;

In this case, GEMSIM or the TABLO-generated program will write the updated (ie post-simulation) values of the coefficient to the specified logical file at the specified header with the specified long name. See section 11.12.8 for details.

The logical file <logical_filename> can be a text file or a Header Array file.

The HEADER "<headername>" part is required if the file <logical_filename> is a Header Array file but is not allowed if the file <logical_filename> is a text file.

The LONGNAME "<words>" part is optional if the file <logical_filename> is a Header Array file but is not allowed if the file <logical_filename> is a text file.

Formula examples
FORMULA  (all,i,COM)  HOUSSH(i) = HOUSCONS(i)/TOTCONS ;
FORMULA  (all,i,COM) TOTSALES(i)= SUM(j,IND, INTINP(i,j) ) ;
FORMULA  NIND = 10 ;
FORMULA (INITIAL) (all,i,SECT) PCOM(i) = 1.0 ;
FORMULA (INITIAL,   WRITE UPDATED VALUE TO FILE upd_prices
    HEADER "ABCD" LONGNAME "<words>" ) 
      (all,c,COM) PHOUS(c) = 1 ;
Examples of formulas from ORANIG model
Formula
 (all,c,COM)(all,s,SRC)(all,i,IND)
  V1PUR(c,s,i)  = V1BAS(c,s,i) + V1TAX(c,s,i) + sum{m,MAR, V1MAR(c,s,i,m)};
Formula
 (all,i,IND) V1LAB_O(i) = sum{o,OCC, V1LAB(i,o)};
             TINY       = 0.000000000001;
Coefficient (all,c,COM)(all,s,SRC) LEVP0(c,s) # Levels basic prices #;
Formula (initial) (all,c,COM)(all,s,SRC) LEVP0(c,s) = 1; ! arbitrary setting !
Formula
 (all,n,NONMAR) MARSALES(n) = 0.0;
 (all,m,MAR)    MARSALES(m) = sum{c,COM, V4MAR(c,m) +
                           sum{s,SRC, V3MAR(c,s,m) + V5MAR(c,s,m) +
                           sum{i,IND, V1MAR(c,s,i,m) + V2MAR(c,s,i,m)}}};
Coefficient
 (all,c,COM) INITSALES(c) # Initial volume of SALES at current prices #;
Formula
 (initial) (all,c,COM) INITSALES(c) = SALES(c);
Update (all,c,COM) INITSALES(c) = p0com(c);

Set EXPMAC # Expenditure Aggregates #
 (Consumption, Investment, Government, Stocks, Exports, Imports);
Coefficient (all,e,EXPMAC)  EXPGDP(e) # Expenditure Aggregates #;
Formula
 EXPGDP("Consumption") = V3TOT;
 EXPGDP("Investment")  = V2TOT_I;
 EXPGDP("Government")  = V5TOT;
 EXPGDP("Stocks")      = V6TOT;
 EXPGDP("Exports")     = V4TOT;
 EXPGDP("Imports")     =-V0CIF_C;
Write EXPGDP to file SUMMARY header "EMAC";
Examples of formulas from GTAP model
Coefficient (all,i,DEMD_COMM)(all,j,PROD_COMM)(all,r,REG)
VFA(i,j,r) # producer expenditure on i by j in r valued at agents' prices #;
Formula (all,i,ENDW_COMM)(all,j,PROD_COMM)(all,r,REG)
    VFA(i,j,r) = EVFA(i,j,r);
Formula (all,i,TRAD_COMM)(all,j,PROD_COMM)(all,s,REG)
    VFA(i,j,s) = VDFA(i,j,s) + VIFA(i,j,s);

Formula (all,r,REG) GOVEXP(r) = sum(i,TRAD_COMM, VGA(i,r));

Formula (all,r,REG)
TIU(r) = sum(j,PROD_COMM, sum(i,TRAD_COMM, DFTAX(i,j,r) + IFTAX(i,j,r)));

Coefficient (all,i,TRAD_COMM)(all,r,REG) CONSHR(i,r) 
# share of private hhld consumption devoted to good i in r #;
Formula (all,i,TRAD_COMM)(all,r,REG)
    CONSHR(i,r) = VPA(i,r) / sum(k, TRAD_COMM, VPA(k,r));

Coefficient (all,m,MARG_COMM)(all,i,TRAD_COMM)(all,r,REG)(all,s,REG)
    VTMUSESHR(m,i,r,s) # share of i,r,s usage in global demand for m #;
Formula (all,m,MARG_COMM)(all,i,TRAD_COMM)(all,r,REG)(all,s,REG)
    VTMUSESHR(m,i,r,s) = VTFSD(i,r,s) / VT; ! default share !
Formula  
(all,m,MARG_COMM: VTMUSE(m) <> 0.0)(all,i,TRAD_COMM)(all,r,REG)(all,s,REG)
    VTMUSESHR(m,i,r,s) = VTMFSD(m,i,r,s) / VTMUSE(m);

10.9    EQUATION [gpd2.3.9]

An algebraic specification of some part of the economic behaviour of the model using COEFFICIENTs and VARIABLEs.

EQUATION [ (qualifier) ] <equation_name> [#<information># ]
     [quantifier_list]  expression_1 = expression_2 ;

Either expression_1 or expression_2 can be just the single character 0 (zero). That is, you can have "0" as either LHS or RHS, but not "0.0".

The possible qualifiers are:

Both defaults can be reset by use of a Default statement (see section 10.19).

The terms in a Levels EQUATION can be constants (eg, 3.1), Coefficient(Parameter)s [see section 10.3] or Levels Variables [see section 10.4]. Linear variables cannot appear in a Levels Equation, nor can Coefficients which are not Parameters. [See also the table in section 11.6.4]

TABLO converts an EQUATION(LEVELS) to an equivalent associated linear equation as described in sections 9.2.2 and 9.2.4.

See section 11.4 for the syntax of expressions used in EQUATIONs.

Examples of equations
EQUATION  HOUSCONS  # Household consumption #
          (all,i,COM) xh(i) = SUM{s,SOURCE, A6(i)*xhous(i,s)} ;
EQUATION   BALTRADE      -100.0 * delB + E*e - M*m = 0 ;
EQUATION(LEVELS)  eq1  0 = X1 + X2 - A3*X3 ;
EQUATION(Levels, Add_Homotopy) EQ1 (All,c,COM) X1(c) = A*X2(c) ;

The following equations from ORANIG illustrate the convention of naming each equation as "E_+varname" where varname is the name of the variable determined by that equation. Although optional, the convention is strongly recommended: it allows TABmate to check your model for logical consistency, suggest a possible closure, and suggest possible condensation actions — see section 8.4.2.

Examples of equations from ORANIG model
Equation
 E_x1lab   # Demand for labour by industry and skill group #
  (all,i,IND)(all,o,OCC)
   x1lab(i,o) = x1lab_o(i) - SIGMA1LAB(i)*[p1lab(i,o) - p1lab_o(i)];
Equation
 E_p1lab_o # Price to each industry of labour composite #
  (all,i,IND) [TINY+V1LAB_O(i)]*p1lab_o(i) 
                    = sum{o,OCC, V1LAB(i,o)*p1lab(i,o)};
Equation E_p0com  # Zero pure profits in transformation #
 (all,c,COM) p0com(c) = [1.0-EXPSHR(c)]*p0dom(c) + EXPSHR(c)*pe(c);

Equation E_x4tot    V4TOT*x4tot = sum{c,COM, V4PUR(c)*x4(c)};
Examples of equations from GTAP model
Equation GPRICEINDEX
# definition of price index for aggregate gov't purchases (HT 40) #
(all,r,REG)
    pgov(r) = sum(i,TRAD_COMM, [VGA(i,r)/GOVEXP(r)] * pg(i,r));

Coefficient (all,i,TRAD_COMM)(all,j,PROD_COMM)(all,s,REG) FMSHR(i,j,s) 
# share of firms' imports in dom. composite, agents' prices #;
Formula (all,i,TRAD_COMM)(all,j,PROD_COMM)(all,s,REG)
    FMSHR(i,j,s) = VIFA(i,j,s) / VFA(i,j,s);

Equation ICOMPRICE 
# industry price for composite commodities (HT 30) #
(all,i,TRAD_COMM)(all,j,PROD_COMM)(all,r,REG)
    pf(i,j,r) = FMSHR(i,j,r)*pfm(i,j,r) + [1 - FMSHR(i,j,r)]*pfd(i,j,r);

Equation INDIMP
# industry j demands for composite import i (HT 31) #
(all,i,TRAD_COMM)(all,j,PROD_COMM)(all,s,REG)
    qfm(i,j,s) = qf(i,j,s) - ESUBD(i) * [pfm(i,j,s) - pf(i,j,s)];

Equation INDDOM
# industry j demands for domestic good i. (HT 32) #
(all,i,TRAD_COMM)(all,j,PROD_COMM)(all,s,REG)
    qfd(i,j,s) = qf(i,j,s) - ESUBD(i) * [pfd(i,j,s) - pf(i,j,s)];

Equation RORGLOBAL
# global supply of cap. goods, or global rental rate on investment (HT 59) #
(all,r,REG)
RORDELTA*rore(r) + [1 - RORDELTA] * {[REGINV(r)/NETINV(r)] * qcgds(r)
                                       - [VDEP(r)/NETINV(r)] * kb(r)}
= RORDELTA * rorg + [1 - RORDELTA] * globalcgds + cgdslack(r);

!  This equation computes alternatively the global supply of capital goods
    or the global rental rate on investment, depending on the setting for
    the binary RORDELTA parameter (either 0 or 1). !

10.9.1    FORMULA & EQUATION [gpd2.3.9.1]

As a shorthand way of defining both a FORMULA and an EQUATION at the same time, you can use the ampersand & between the keywords FORMULA and EQUATION.

The ampersand & indicates that there is a double statement equivalent to both a FORMULA and an EQUATION at the same time.

FORMULA [ (qualifier) & EQUATION [ (qualifier) ] 
  <equation_name> [#<information># ] [quantifier_list]
 <coefficient_name> (argument_1,...,argument_n) = expression ;

This is only possible with a FORMULA(INITIAL) and an EQUATION(LEVELS). If the qualifiers are omitted, it is assumed that these are the qualifiers for this double statement, even if the defaults for the TABLO Input file are set differently.

The double statement must obey the syntax rules for both a FORMULA(INITIAL) and an EQUATION(LEVELS). The conditions on a FORMULA(INITIAL) are quite strict — see section 10.8.

The keyword for the next statement after the double statement FORMULA & EQUATION must be included; it cannot be omitted (see section 11.1.1 below).

FORMULA & EQUATION example
FORMULA & EQUATION E_XHOUS   # Commodity i - household use #
  (all,i,SECT) XHOUS(i) = DVHOUS(i)/PCOM(i) ;

This is equivalent to the two statements:

FORMULA(INITIAL)  (all,i,SECT) XHOUS(i) = DVHOUS(i)/PCOM(i) ;
EQUATION(LEVELS) E_XHOUS   # Commodity i - household use #
  (all,i,SECT) XHOUS(i) = DVHOUS(i)/PCOM(i) ;

10.10    UPDATE [gpd2.3.10]

An algebraic specification of how the values of a given COEFFICIENT are to be updated after each step of a multi-step simulation.

UPDATE [ (qualifier) ] [quantifier_list]
 <coefficient_name> (argument_1,...,argument_n) = expression ;

The possible UPDATE qualifiers are PRODUCT6, CHANGE or EXPLICIT 7, of which PRODUCT is the default.

The PRODUCT qualifier is used to update a coefficient (usually a value) which, in the levels, is a product of one or more variables. In this case, the expression on the right hand side of the UPDATE equation is the product of the associated percentage change variables (usually a price and a quantity).

CHANGE updates are used in all other cases. The expression on the right hand side of the UPDATE equation is the change in the updated coefficient expressed in terms of other coefficients and variables.

An argument is either an index or the element of a SET, as described in section 11.2.4.

UPDATE examples

Examples

UPDATE (all,i,COM)  VHOUSCONS(i) = pCOM(i)*xHOUS(i) ;
UPDATE (CHANGE) (all,i,COM) TAXREV(i) = delTAXREV(i);
UPDATE (PRODUCT) (all,i,SECT) VOLUME(i) = p_HEIGHT(i)*p_WIDTH(i)*p_DEPTH(i);

Point 5 in section 4.4.2 includes an explanation as to why update statements are necessary for obtaining accurate solutions of the levels equations of a model.

More details on Updates can be found in sections 4.4.4 and 11.12.

Examples of updates from ORANIG model
Coefficient  ! Basic flows of commodities (excluding margin demands)!
(all,c,COM)(all,s,SRC)(all,i,IND) V1BAS(c,s,i) # Intermediate basic flows #;
(all,c,COM)(all,s,SRC)            V6BAS(c,s)   # Inventories basic flows #;
Read
 V1BAS from file BASEDATA header "1BAS";
 V6BAS from file BASEDATA header "6BAS";

Variable  ! Variables used to update above flows !
(all,c,COM)(all,s,SRC)(all,i,IND) x1(c,s,i)  # Intermediate basic demands #;
(change) (all,c,COM)(all,s,SRC)   delx6(c,s) # Inventories demands #;
(all,c,COM)(all,s,SRC)            p0(c,s)    # Basic prices for local users #;
(change)(all,c,COM)(all,s,SRC)    delV6(c,s) # Value of inventories #;
Update
 (all,c,COM)(all,s,SRC)(all,i,IND)  V1BAS(c,s,i) = p0(c,s)*x1(c,s,i);
 (change)(all,c,COM)(all,s,SRC)     V6BAS(c,s)   = delV6(c,s);
 (change)    FRISCH = FRISCH*[w3tot - w3lux]/100.0;
Coefficient
 (all,c,COM) INITSALES(c) # Initial volume of SALES at current prices #;
Formula  (initial) (all,c,COM) INITSALES(c) = SALES(c);
Update (all,c,COM) INITSALES(c) = p0com(c);
Examples of updates from GTAP model
Update
 (all,r,REG)     SAVE(r) = psave(r) * qsave(r);
 (all,r,REG) GOVEXPEV(r) = ygev(r);
 (all,i,TRAD_COMM)(all,r,REG)     VDGA(i,r) = pgd(i,r) * qgd(i,r);

The explicit style of Update has some occasional, rather technical, uses. For example:

Coefficient STEPNUM # counting steps in simulation #;
Formula (initial) STEPNUM = 1;
Update (explicit) STEPNUM = STEPNUM + 1;

10.11    ZERODIVIDE [gpd2.3.11]

By default TABLO allows zero divided by zero in FORMULAs, and returns zero as the result. The ZERODIVIDE statement allows you to control this behaviour.

The ZERODIVIDE statement specifies the default value to be used in a FORMULA when the denominator of a division operation is equal to zero. The default can be either the value of a scalar coefficient (that is, one which is declared without any indices) :

ZERODIVIDE [ (qualifier) ] DEFAULT <coefficient_name> ;

or a real constant:

ZERODIVIDE [ (qualifier) ] DEFAULT <real_constant> ;

Alternatively, the particular default value can be turned off to indicate that this kind of division by zero is not allowed :

ZERODIVIDE [ (qualifier) ] OFF ;

The possible ZERODIVIDE qualifiers are ZERO_BY_ZERO (the default) or NONZERO_BY_ZERO.

ZERO_BY_ZERO applies when the numerator in the division is zero (zero divided by zero) while NONZERO_BY_ZERO applies when the numerator in the division is a nonzero number (nonzero divided by zero).

ZERODIVIDE examples
ZERODIVIDE DEFAULT  A1 ;
ZERODIVIDE (ZERO_BY_ZERO) DEFAULT  1.0 ;
ZERODIVIDE (NONZERO_BY_ZERO) OFF ;
Examples from ORANI-G
Zerodivide default 0.5;
Formula
 (all,c,COM)(all,i,IND)            V1PUR_S(c,i) = sum{s,SRC, V1PUR(c,s,i)};
 (all,c,COM)(all,s,SRC)(all,i,IND) S1(c,s,i)    = V1PUR(c,s,i) / V1PUR_S(c,i);
 (all,i,IND)                       V1MAT(i)     = sum{c,COM, V1PUR_S(c,i)};
Zerodivide off;
Zerodivide default 999;
Formula     (all,i,IND) SUPPLYELAST(i) =
    SIGMA1PRIM(i)*V1LAB_O(i)*V1CST(i)/[V1PRIM(i)*{V1CAP(i)+V1LND(i)}];
Zerodivide off;
Examples from GTAP
Zerodivide (zero_by_zero) default 0;
Coefficient (all,i,TRAD_COMM)(all,r,REG)(all,s,REG)
    SX_IRS(i,r,s) # share of exports of good i from region r to s #;
Formula (all,m,MARG_COMM)(all,r,REG)(all,s,REG)
    SX_IRS(m,r,s) = VXWD(m,r,s) / [ sum{k, REG, VXWD(m,r,k)} + VST(m,r) ];
Formula (all,i,NMRG_COMM)(all,r,REG)(all,s,REG)
    SX_IRS(i,r,s) = VXWD(i,r,s) / [ sum{k, REG, VXWD(i,r,k)}];
Zerodivide (zero_by_zero) off;

10.11.1    More about zerodivides [gpd2.4.13]

Division by zero is never allowed in EQUATIONs or UPDATEs. ZERODIVIDE statements only affect calculations carried out in FORMULAs.

Often, because the equations solved by TABLO are linearized, some of the coefficients are shares (or proportions) of various aggregates. Naturally, these shares should sum to unity. In some specific instances, however, the aggregate may be zero and the shares of this aggregate will amount to a zero proportion of a zero sum. So that simulations turn out as expected, it may nevertheless be important that the share values used do still add to one. Consider, for example,

FORMULA (ALL,i,COM)(ALL,j,IND) S(i,j) = A(i,j)/SUM(k,IND,A(i,k)) ;

Here S(i,j) is the share of A(i,j) in the sum across all industries k of A(i,k), and we would expect that, for all commodities i,

SUM(k,IND,S(i,k))

equals one. If, for commodity "boots", A("boots",j) is zero for all industries j, then each S("boots",j) would be calculated as zero divided by zero. TABLO allows zero divided by zero in formulas, and uses a default value of zero for their results. However, then the shares S("boots",j) would not add to one over all industries (indeed, SUM(j,IND,S("boots",j)) would be zero). This can be rectified using a ZERODIVIDE instruction which changes the default value that is used whenever a division of zero by zero is encountered during formula calculations. In the above example, by changing the default to 1/NIND (where NIND is the number of industries), the shares S("boots",j) can be made to sum, over all industries, to one. This can be done by the TABLO input shown below.

COEFFICIENT NIND # number of industries # ;
COEFFICIENT RECIP_NIND # reciprocal of the number of industries # ;
FORMULA NIND = SUM(i, IND, 1) ; ! Counts number of things in IND !
FORMULA RECIP_NIND = 1/NIND ;
ZERODIVIDE DEFAULT RECIP_NIND ;
FORMULA (ALL,c,COM)(ALL,i,IND) S(c,i) = A(c,i)/SUM(k,IND,A(c,k)) ;
ZERODIVIDE OFF ;

Note the formula for NIND (see section 17.1). This use of SUM saves you having to hard-wire the size of IND in your code.

Two types of division by zero are distinguished, division of zero by zero and division of a nonzero number by zero. Different default values can be set for these two cases and one can be allowed while the other is not. The second of these two cases is controlled by statements beginning ZERODIVIDE (NONZERO_BY_ZERO) while the first of these is controlled by statements beginning ZERODIVIDE (ZERO_BY_ZERO) (where the qualifier (ZERO_BY_ZERO) can be omitted since it is the default).

After one of these two zerodivide default values has been set to a particular value by a ZERODIVIDE instruction, that value will be used as the zerodivide default for all calculations involving formulas that appear after that ZERODIVIDE statement in the TABLO Input file. This default will remain in effect until the zerodivide default is changed by another ZERODIVIDE statement of the same type or until it is turned off by a statement of the form

ZERODIVIDE [(<qualifier>)] OFF ;

When either type of zero divide is turned off, if that type of division is encountered in a formula, GEMSIM or the TABLO-generated program will stop running with an error message which indicates where the division has occurred (see section 34.3 for details).

By convention, at the start of each TABLO Input file, division of zero by zero is allowed and the default result is zero, while division of a nonzero number by zero is not allowed. This is as if there were the following two statements at the start of every TABLO Input file.

ZERODIVIDE DEFAULT 0.0 ;
ZERODIVIDE (NONZERO_BY_ZERO) OFF ;

10.11.1.1    Programs report zerodivides [gpd2.4.13.1]

After any formula in which ZERODIVIDE default values have been used, GEMSIM and TABLO-generated programs usually reports during step 1 of a multi-step calculation the number of occurrences and the default value used. Separate reports are given for zero-divided-by-zero and nonzero-divided-by-zero. Round brackets () enclose the former, while angle brackets <> enclose the latter. When such division occurs, we suggest that you check the data and formulas to make sure you understand why it is happening and that the default value being given is acceptable. (If you don't want your TABLO-generated program to be able to report these, you can select option NRZ in the Code stage of TABLO, as explained in section 50.0.1 below.)

10.11.1.2    Good practice for zerodivides [gpd2.4.13.2]

We recommend that you turn off ZERODIVIDE defaults in all places except those where your knowledge of the data leads you to expect division by zero. In this way, you will not get unintended results as a result of ZERODIVIDE default values operating. At the start of your TAB file, insert

ZERODIVIDE OFF;

When you know a zero denominator may plausibly occur, temporarily activate an appropriate default:

ZERODIVIDE DEFAULT RECIP_NIND ;
FORMULA (ALL,c,COM)(ALL,i,IND) S(c,i) = A(c,i)/SUM(k,IND,A(c,k)) ;
ZERODIVIDE OFF ;

ID01 and ID0V functions (see section 11.5.1) can mostly replace use of the ZERODIVIDE statement. While ZERODIVIDE affects only Formulas, ID01 and ID0V can be used both in Formulas and Equations.

10.12    DISPLAY [gpd2.3.12]

An instruction that the values of a given COEFFICIENT are to be displayed (that is, written to a text file called the Display file) for examination by the user.

Note: DISPLAY statements are a rather old-fashioned way to check the values of coefficients. Usually, the SLC file (see section 28.1) produced when you run a simulation is easier to use. For Data Manipulation TAB Files (ie, those without equations and variables) you can use the similar CVL file — see 28.3. However, DISPLAYS may still be useful if you wish to see values at all steps of a multi-step simulation — see DWS option in section 25.1.10.

All the values of a COEFFICIENT can be displayed :

DISPLAY [(POSTSIM)] <coefficient_name> # <information> # ;

or just a part of the COEFFICIENT can be displayed :

DISPLAY [(POSTSIM)] [quantifier_list]
 <coefficient_name> (argument_1,...,argument_n) # <information> # ;

A levels variable can be given as the name of the coefficient being displayed. (This is because the declaration of a VARIABLE(LEVELS) produces a COEFFICIENT of the same name in the associated linearized TABLO Input file, as explained in section 9.2.2 above.)

The qualifier (POSTSIM) means that the DISPLAY statement is done during post-simulation processing (see chapter 12). In this case, post-simulation values of the Coefficient are written to the Display file.

DISPLAYs of both real and integer coefficients are allowed.

DISPLAY examples
DISPLAY  TOTSALES;
DISPLAY (all,i,COM) INTINP(i,"wool") # Intermediate inputs of wool # ;

See also sections:

11.11on "Reads, Writes and Displays"
11.11.2for information about partial displays
22.3for details about Displays, Display files and Command files.

10.13    MAPPING [gpd2.3.13]

This statement is used to define Mappings between sets.

MAPPING [(ONTO)] <set_mapping>  FROM  <set1>  TO  <set2> ;

The optional (but usually advisable) MAPPING qualifier ONTO means that every element in the codomain (<set2>) is mapped to by at least one element in the domain set (<set1>). If the qualifier ONTO is not present, the mapping need not be onto in the mathematical sense — see sections 11.9.2 and 11.9.3 for details.

For example:

MAPPING (onto) Producer  from  COM  to  IND  ;

means that each COM is produced by just one IND, and that each IND produces at least one COM.

Further examples and details are given in section 11.9.

10.13.1    Formulas for mappings, and reading and writing mappings [gpd2.3.13.1]

Set mapping values can be read in or assigned by formulae and can be written to a file. In each case the syntax is as already described above for Reads, Writes or Formulas.

Statements especially relevant to set mappings are:

READ (BY_ELEMENTS) [quantifier_list] <set_mapping> FROM FILE .... ;
READ <set_mapping>  FROM FILE ... ;

WRITE <set_mapping> TO FILE ... ;
WRITE (BY_ELEMENTS) <set_mapping> TO FILE ... ;

FORMULA (BY_ELEMENTS) [quantifier_list] <set_mapping> = ... ;

The qualifier BY_ELEMENTS means the element names are read or written or assigned by formula rather than the position number in the set. This qualifier BY_ELEMENTS is optional for Formulas — see section 11.9.11.

Examples

READ (BY_ELEMENTS)  (all,i1,S1)  MAP1(i1)  from file ... ;
FORMULA (BY_ELEMENTS)  MAP1("food") = "aggfood" ;

Further examples and details are given in section 11.9.

10.13.2    Projection mappings from a set product [gpd2.3.13.2]

Projection mappings from a set product to one of the sets making the product are allowed via statements of the form

MAPPING (PROJECT) <set_mapping>  FROM  <set1>  TO  <set2> ;

where set1 has been defined earlier to be the product (see section 10.1.6) of set2 with another set. This MAPPING statement both declares the mapping and sets its values. PROJECT is a Mapping statement qualifier. This qualifier is only allowed when the set being mapped from has been defined as the product of two sets and the set being mapped to is one of these two sets.

MAPPING (PROJECT) example

Consider sets COM, SOURCE and BOTH = COM x SOURCE as below.

SET COM (Food, Agriculture, Services) ;
SET SOURCE (dom, imp) ; ! domestic or imports !
SET BOTH = COM x SOURCE ;

The elements of BOTH are

C1Food_dom, C2Agric_dom, C3Servi_dom, C1Food_imp, C2Agric_imp, C3Servi_imp .

(see section 10.1.6).

Suppose that mapping BOTH2COM is defined via

MAPPING (PROJECT)  BOTH2COM from BOTH to COM ;

Then BOTH2COM maps

C1Food_dom to FoodC2Agric_dom to AgricultureC3Servi_dom to Services
C1Food_imp to FoodC2Agric_imp to AgricultureC3Servi_imp to Services

Suppose that BOTH2SOURCE is defined via

MAPPING (PROJECT)  BOTH2SOURCE from BOTH to SOURCE ;

Then BOTH2SOURCE maps

C1Food_dom to domC2Agric_dom to domC3Servi_dom to dom,
C1Food_imp to impC2Agric_imp to impC3Servi_imp to imp.

10.14    ASSERTION [gpd2.3.14]

An ASSERTION statement is used to check conditions that are expected to hold. The syntax is:

ASSERTION  [<qualifiers>] [ # message # ] [quantifier_list] <condition> ;

Here <condition> is a logical expression, the optional message between hashes '#' is the message that will be shown (at the terminal or in a LOG file) if the condition is not satisfied, and <quantifier-list> (optional) can be one or more quantifiers. If the condition is not satisfied, the run of GEMSIM or the TABLO-generated program is terminated prematurely (that is, just after checking this assertion) and an error message is given.

ASSERTION examples
Assertion # Check X3 values not too large # (all,c,COM) X3(c) <= 20 ;
 (initial) # Check X is not negative # (all,c,COM) (all,i,IND) X(c,i) >= 0 ;

Allowed qualifiers are ALWAYS or INITIAL (of which ALWAYS is the default).

With qualifier ALWAYS, the assertion is checked at every step of a multi-step calculation. With qualifier INITIAL the assertion is checked only on the first step.

Include a unique message (between #'s) with each assertion — the message will be echoed if the assertion fails — so you will know which assertion is failing.

If an assertion is not satisfied, the software tells you the element names (or numbers if names are not available) each time it fails. For example, if the assertion

ASSERTION # Check no negative DVHOUS values # (all,c,COM) DVHOUS(c) >= 0 ;

fails for commodity "wool" you will see the message

%% Assertion 'Check no negative DVHOUS values' does not hold 
 (quantifier number 1 is 'wool')

(and once for each other such commodity 'c' where the assertion fails) and then the message

Assertion 'Check no negative DVHOUS values' does not hold.

A wise Irishman observed that everything that can possibly go wrong will go wrong . To help identify the possible cause of problems, a well-written TAB file should contain many assertions, perhaps checking that:

If absolutely necessary, you can temporarily suppress the testing of assertions, or convert them to warnings, by including statements "Assertions=no;" or "Assertions=warn;" in your Command file.

See section 25.3 for more about assertions.

ASSERTION examples from ORANIG model
Coefficient                    ! coefficients for checking !
 (all,i,IND) DIFFIND(i)  # COSTS-MAKE_C : should be zero #;
 (all,c,COM) DIFFCOM(c)  # SALES-MAKE_I : should be zero #;
             EPSTOT      # Average Engel elasticity: should = 1 #;
Formula
 (all,i,IND) DIFFIND(i)  = V1TOT(i) - MAKE_C(i);
 (all,c,COM) DIFFCOM(c)  = SALES(c) - MAKE_I(c);
             EPSTOT      = sum{c,COM, S3_S(c)*EPS(c)};

Write ! we file these numbers BEFORE the assertions below !
 DIFFIND to file SUMMARY header "DIND";
 DIFFCOM to file SUMMARY header "DCOM";
 EPSTOT  to file SUMMARY header "ETOT";

Assertion ! if below not true, program will stop with message !
 # DIFFIND = V1TOT-MAKE_C = tiny # (all,i,IND) ABS(DIFFIND(i)/V1TOT(i)) <0.001;
 # DIFFCOM = SALES-MAKE_I = tiny # (all,c,COM) ABS(DIFFCOM(c)/SALES(c)) <0.001;
 (initial) # Average Engel elasticity = 1 #  
ABS(1-EPSTOT) <0.01;

10.15    TRANSFER [gpd2.3.15]

TRANSFER statements can be used for transferring data from an old Header Array file to a new or updated header Array file. The syntax is:

TRANSFER <header> FROM FILE <logical-file1> TO FILE <logical-file2> ;
TRANSFER (IfHeaderExists) <header> FROM FILE <logical-file1> TO FILE <logical-file2> ;
TRANSFER UNREAD FROM FILE <logical-file1> TO FILE <logical-file2> ;
TRANSFER UNWRITTEN FROM FILE <logical-file1> TO FILE <logical-file2> ;
TRANSFER <header> FROM FILE <logical-file1> TO UPDATED FILE ;
TRANSFER UNREAD FROM FILE <logical-file1> TO UPDATED FILE ;

Here <header> is a Header Array on the file called <logical-file1> in your TABLO Input file. It will be transferred unchanged to the file called <logical-file2> or to the updated version of <logical-file1>.

Both files must be Header Array files.

If the statement begins "TRANSFER UNREAD", all Headers on file 1 which have not been read in the TABLO Input file are transferred to the new file 2 or to the updated version of file 1.

If the statement begins "TRANSFER UNWRITTEN", all Headers on file 1 which have not been written onto file 2 are transferred to the new file 2.

Note that

Transfer Unwritten from file <logical-file1> to Updated File ; ! not allowed !

is not allowed — instead use "Transfer Unread".

TRANSFER examples
Transfer "EXT1" from File IODATA to updated file ;
Transfer Unread from File IODATA to file OUT2 ;

See section 11.13 for the motivation behind these statements and for further details and examples.

10.16    OMIT, SUBSTITUTE and BACKSOLVE [gpd2.3.16_17_18]

As described in section 14.1, condensation is a vital tool to reduce the numbers of variables and equations, so that larger models can be solved quickly. You can OMIT, SUBSTITUTE or BACKSOLVE variables to condense your model.

The traditional method has been to list the omit, substitute and backsolve actions in a STI (stored input) file — see section 14.1.2 for an example of this older method. Here we describe the modern alternative: specifying these actions within your TAB (TABLO input) file.

An OMIT statement can be placed in your TAB file with the syntax:

OMIT  <variable_1> <variable_2> ...  <variable_n>   ;

where the variable names listed <variable_1> <variable_2> ... are separated by spaces, and are any linear variables defined previously in the TABLO Input file. For example:

OMIT examples
OMIT  a1  a1oct  a1mar  a1_s  a2  a2mar  ;

Similarly SUBSTITUTE and BACKSOLVE statements can be placed in your TAB file with the syntax:

SUBSTITUTE  <variable_name>  USING  <equation_name>  ;
BACKSOLVE  <variable_name>  USING  <equation_name>  ;

where <variable_name> is the name of the variable to substitute or backsolve for, and <equation_name> is the name of the equation to use. For example:

SUBSTITUTE and BACKSOLVE examples (linear variables)
SUBSTITUTE  p1  USING  E_Price1 ;
BACKSOLVE p1lab USING E_p1lab ;

These are equivalent to STI file lines:

s
p1
E_Price1
b
p1lab
E_p1lab

The Tools menu in TABmate contains an item Create in-TAB condensation from STI which can help you move from the old STI-file way of specifying condensation to the new TAB-file way.

If you wish to omit or substitute a Levels variable X, you can use either the levels name X or the name of the associated linear variable (which is usually either c_X for an ordinary change or p_X for a percentage change variable — see section 9.2.2).

Levels variable examples
VARIABLE (CHANGE,LEVELS) XYZ ;
OMIT c_XYZ ;
VARIABLE (LEVELS) X ;
VARIABLE (LEVELS) Y ;
EQUATION(LEVELS) Eqn_HOUSE  A*X + B*Y = C ;
SUBSTITUTE p_X USING Eqn_HOUSE ;   ! using the linear name p_X !

or you can use the levels name:

SUBSTITUTE X USING Eqn_HOUSE ;   ! using the levels name X !

If you specify omissions in your TABLO Input file, these omissions are done first, followed by the substitutions and backsolves in the order they appear in the TABLO Input file.

Further details about TABLO condensation and condensation statements in the TAB file are given in sections 14.1.10 and 14.1.14.

10.16.1    Example - condensation in the TABLO input file for model ORANIG [gpd2.3.18.1]

This section of a TABLO Input file can be added to the TABLO Input file ORANIG01.TAB. It contains some of the standard condensation for the model. Usually these condensation actions are carried out by running TABLO using the condensation Stored-input file (either OG01GS.STI or OG01TG.STI). However if all the condensation actions are in the TABLO Input file, condensation is carried out by running TABLO with just the TABLO Input file.

Condensation actions in TABLO Input file (could be added to TAB file ORANIG01.TAB)

OMIT a1 a1oct a1mar a1_s a2 a2mar a2_s a3 a3mar a4mar a5mar ;
OMIT f1lab f1lab_o f1lab_i ;

SUBSTITUTE p1 using E_p1 ;
BACKSOLVE p1lab using E_p1lab ;
SUBSTITUTE p1_s using E_p1_s ;
SUBSTITUTE p2 using E_p2 ;
SUBSTITUTE p2_s using E_p2_s ;
SUBSTITUTE p3 using E_p3 ;
SUBSTITUTE p5 using E_p5 ;
... etc

BACKSOLVE regemploy using E_regemploy ;
BACKSOLVE regadvantage using E_regadvantage ;
BACKSOLVE regemploycon using E_regemploycon ;
BACKSOLVE regx1primcon using E_regx1primcon ;

The above excerpt follows the convention of naming each equation as "E_+varname" where varname is the name of the variable determined by that equation. Although optional, the convention allows TABmate to check your model for logical consistency, suggest a possible closure, and automatically generate statements like the above — see section 8.4.2.

10.17    COMPLEMENTARITY [gpd2.3.19]

Chapter 51 describes complementarities in detail. The TABLO syntax is summarized below.

A complementarity is a relation between a (levels) variable and an expression. If X is a levels variable and EXP is an expression, a simple complementarity is often written

X >= 0   ⊥   EXP

which is notation for :

EitherX > 0andEXP = 0
orX = 0andEXP >= 0

A more general complementarity is

L< = X < = U   ⊥   EXP

which is notation for :

EitherX = LandEXP>0
orL<=X<=UandEXP=0
orX=UandEXP < 0

The syntax is:

COMPLEMENTARITY (VARIABLE = <variable-name> , 
                 LOWER_BOUND = <lower-bound name / value> ,
                 UPPER_BOUND = <upper-bound name / value ) 
          <complementarity_name> [#<information># ] 
 [quantifier_list]  Expression  ;

The qualifier VARIABLE must be present. <variable-name> is the name of a levels variable previously defined in the model.

At least one of the qualifiers UPPER_BOUND or LOWER_BOUND is required. Both are allowed.

<lower-bound name / value> , <upper-bound name / value> is either a real constant or the name of a levels variable or a coefficient (parameter).

The <complementarity_name> must be present and is limited to 10 characters.

The syntax of the Expression is the same as for an expression on one side of a levels equation.

The above syntax means :

EitherVariable = Lower boundandExpression >= 0
orLower bound <= Variable <= Upper boundandExpression = 0
orVariable = Upper boundandExpression <= 0.
Special Cases (Only One Bound)

1. Only a Lower Bound

Here the Complementarity statement is of the form

COMPLEMENTARITY (VARIABLE = X, LOWER_BOUND = L) C_name Expression ;

This means that:

EitherX = LandEXP > 0
orL <= XandEXP = 0.

2. Only an Upper Bound

Here the Complementarity statement is of the form

COMPLEMENTARITY (VARIABLE = X, UPPER_BOUND = U) C_name Expression ;

This means that:

EitherX <= UandEXP = 0
orX = UandEXP < 0.

We give two examples below. Further details and examples of complementarities are given in chapter 51. See also section 11.14.

Import quota example

XIMP_QUOTA(i) is the volume import quota and XIMP(i) is the volume of imports.

TIMP_QUOTA(i) is the extra power of the import tariff due to the import volume quota.

If the quota is not binding,

TIMP_QUOTA(i) = 1 and XIMP(i) <= XIMP_QUOTA(i)

or, if the quota is binding,

TIMP_QUOTA(i) >= 1 and XIMP(i) = XIMP_QUOTA(i) .

The TABLO notation for this is as follows:

COMPLEMENTARITY  (Variable = TIMP_QUOTA, Lower_Bound = 1)  IMPQUOTA
    (all,i,COM)   XIMP_QUOTA(i) - XIMP(i) ;

which means :

EitherTIMP_QUOTA(i) = 1andXIMP_QUOTA(i) - XIMP(i) >= 0
orTIMP_QUOTA(i) >= 1andXIMP_QUOTA(i) - XIMP(i) = 0 .

An alternative way of writing this complementarity is to introduce a variable XIMP_RATIO(i), where

XIMP_RATIO(i)=XIMP(i)/XIMP_QUOTA(i)

is the ratio between the current volume of imports XIMP(i) and the quota volume XIMP_QUOTA(i). It is easy to see when the quota has been reached since then XIMP_RATIO is 1.0.

The complementarity expression can be written as 1-XIMP_RATIO(i).

COMPLEMENTARITY  (Variable=TIMP_QUOTA, Lower_Bound=1) IMPQUOTA
    (all,i,COM)   1-XIMP_RATIO(i);

This COMPLEMENTARITY statement is included in the MOIQ.TAB example explored in section 51.3.2.

GTAP tariff-rate quota example

QMS_TRQ(i) is the TRQ import volume quota on imports QXS and the ratio QXSTRQ_RATIO is

QXSTRQ_RATIO = QXS/QMS_TRQ .

TMSTRQ is the additional TRQ import tax in s on an imported commodity.

The complementarity for the Tariff-Rate Quota in TABLO notation is

COMPLEMENTARITY  (Variable = TMSTRQ,  Lower_Bound = 1,  Upper_Bound = TMSTRQOVQ) TRQ
  (All,i,TRAD_COMM)(All,r,REG)(All,s,REG)    1 - QXSTRQ_RATIO(i,r,s) ;

Here the lower bound on the complementarity variable TMSTRQ is a real number (1) and the upper bound is a (levels) variable TMSTRQOVQ.

This means:

EitherTMSTRQ = 1and1 - QXSTRQ_RATIO >= 0[in quota]
or1 <= TMSTRQ <= TMSTRQOVQand1 - QXSTRQ_RATIO = 0[on quota]
orTMSTRQ = TMSTQOVQand1 - QXSTRQ_RATIO <= 0[over quota]

This COMPLEMENTARITY statement is included in the G5BTRQ.TAB example explored in section 51.8.4.

10.18    POSTSIM [gpd2.3.19a]

The statement

POSTSIM (BEGIN) ;

begins a post-sim section in a TAB file while the statement

POSTSIM (END) ;

ends a post-sim section in a TAB file.

For details see chapter 12. There are several examples of post-sim sections in a TAB file in section 53.2.

10.19    Setting default values of qualifiers [gpd2.3.20]

It is possible to reset the default values for some of the qualifiers in some of the statements described above. Although we refer to these statements as Default statements, note that DEFAULT is not a keyword but a qualifier which follows the keyword of the statement where the default is being reset.

Keyword ( DEFAULT = qualifier) ;

Keyword can be any of COEFFICIENT, VARIABLE, FORMULA, EQUATION.

For real COEFFICIENTs, the default can be set to PARAMETER or NON_PARAMETER. (This does not affect the default for integer coefficients, which is always PARAMETER.)

For VARIABLE, the default can be set to LINEAR or LEVELS, and also to PERCENT_CHANGE or CHANGE.

For FORMULAs with a real coefficient on the left-hand side, the default can be set to INITIAL or ALWAYS. (This does not affect the default for formulas with an integer coefficient on the left-hand side; for these the default is INITIAL.)

For EQUATION, the default can be set to LINEAR or LEVELS and also to ADD_HOMOTOPY or NOT_ADD_HOMOTOPY. In the ADD_HOMOTOPY case, the default name of the homotopy variable can be specified -- see section 26.6.5 for details.

DEFAULT examples
EQUATION (DEFAULT = LEVELS) ;
FORMULA (DEFAULT = INITIAL) ;
COEFFICIENT (DEFAULT = PARAMETER) ;
VARIABLE (DEFAULT = CHANGE) ;
VARIABLE (DEFAULT = LEVELS) ;
EQUATION (DEFAULT = ADD_HOMOTOPY = Homotopy2) ;

The two VARIABLE defaults can both be set simultaneously, so after the VARIABLE defaults were set as in the previous two examples, a "VARIABLE X ;" statement without qualifiers would define a LEVELS variable X with an associated CHANGE differential c_X.

If no Default statements are included, the following defaults apply:

Statement Default
COEFFICIENTNON_PARAMETER
VARIABLELINEAR and PERCENT_CHANGE
FORMULAALWAYS
EQUATIONLINEAR and NOT_ADD_HOMOTOPY

These defaults are the ones that naturally apply in a linearized TABLO Input file so no Default statements are needed in this case.

See sections 4.3.3 and 4.3.4 for the Default statements often put at the start of a mixed or levels TABLO Input file.

Default statements can be put anywhere in the TABLO Input file. For example, if you have a group of levels equations followed by a group of linearized equations, you can put

EQUATION (Default = Levels) ;

before the group of levels equations and then

EQUATION (Default = Linear) ;

before the group of linearized equations.

10.19.1    Default statements for bounds on coefficients [gpd5.8.2]

Coefficient and levels Variable declaration statements can have qualifiers that specify acceptable ranges of values for the coefficient and levels variable (see sections 10.3 and 10.4). For example,

COEFFICIENT (GE 0.0) (All,c,COM)  V4BAS(c) ;
VARIABLE (LEVELS, > 0.0, < 10.0) (All,c,COM) V5BAS(c) ;

There are now two DEFAULT statements which allow you to set the range restrictions for many COEFFICIENTs at once.

COEFFICIENT (DEFAULT=LOWER_BOUND  <condition>) ;
COEFFICIENT (DEFAULT=UPPER_BOUND  <condition>) ;

For the LOWER_BOUND, the conditions allowed are:

GT real-numberorGE real-number,egGT 0.0or>= -1.0

For the UPPER_BOUND, the conditions allowed are:

LT real-numberorLE real-number,egLT 100.0or<= 1.0

These defaults can be turned off by using:

COEFFICIENT (DEFAULT=LOWER_BOUND OFF) ;
COEFFICIENT (DEFAULT=UPPER_BOUND OFF) ;

The default statements also apply to the Coefficients defined by a levels variable declaration.

DEFAULT=LOWER_BOUND example
COEFFICIENT (DEFAULT=LOWER_BOUND   GT 0.0) ;
COEFFICIENT  X ; .(all,i,IND) Y(i); 
COEFFICIENT (GT  -1.0) Z ;
VARIABLE(LEVELS) (all,i,IND) V(i) ;
COEFFICIENT (DEFAULT=LOWER_BOUND OFF) ;
COEFFICIENT W ;

Here Coefficients X, Y and Coefficient V (defined via the levels variable declaration) have the range restriction "GT 0.0". .Z has its own LOWER_BOUND range restriction of "GT -1.0" .W has no LOWER_BOUND (or UPPER_BOUND) range restriction.

The two range restrictions UPPER_BOUND and LOWER_BOUND are independent of one another in the sense that they must be turned on and off separately.

10.20    TABLO statement qualifiers - a summary [gpd2.3.21]

Table 10.1 below lists the different statement qualifiers currently in use. Qualifiers are put in round brackets after the key word they qualify. If there are two or more qualifiers, they can appear in any order, separated by commas, as, for example, in

FILE (OLD, TEXT) .....

The defaults (which apply if no relevant qualifier is given) are indicated. However those marked with an asterisk (*) can be changed as explained in section 10.19 above.

10.20.1    Spaces and qualifier syntax [gpd2.3.21.1]

In TABLO Input files, a space after the keyword before a qualifier is not necessary. For example, either of the following is allowed.

File  (New)  output   # Summary output # ;
File(New)  output   # Summary output # ;

But, in "extra" TABLO-like statements on Command files (see section 25.6), at least one space is required after the keyword before the qualifier. Thus, for example,

Xfile  (New)  output   # Summary output # ;

is allowed but

Xfile(New)  output   # Summary output # ;

will result in an error.

Table 10.1 Qualifier defaults
Set qualifiers
INTERTEMPORAL or NON_INTERTEMPORALdefault is NON_INTERTEMPORAL
Subset qualifiers
BY_ELEMENTS or BY_NUMBERSdefault is BY_ELEMENTS
Coefficient qualifiers
REAL or INTEGERdefault is REAL
NON_PARAMETER or PARAMETERdefault is NON_PARAMETER(*) for real coefficients
and PARAMETER for integer coefficients
<operator> <real_number>where operator is GE,GT,LE or LT (see section 11.6.7)
Variable qualifiers
PERCENT_CHANGE or CHANGEdefault is PERCENT_CHANGE(*)
LINEAR or LEVELSdefault is LINEAR(*)
LINEAR_NAME or LINEAR_VARsee section 9.2.2
ORIG_LEVEL = <coefficient> or <real>(for linear variables only — see section 11.6.5)
<operator> <real_number>where operator is GE,GT,LE or LT (see section 11.6.7)
File qualifiers
HEADER or TEXT or GAMSdefault is HEADER
OLD or NEW or FOR_UPDATESdefault is OLD
ROW_ORDER or COL_ORDER ordefault is ROW_ORDER
SPREADSHEET,
SEPARATOR ="<character>"
Comma is the default separator
Read qualifiers
BY_ELEMENTS(for reading character data to a set mapping)
IfHeaderExists(read only done if specified header exists on the file)
Write qualifiers
BY_ELEMENTS(for writing a set mapping as character strings)
POSTSIM(for writing postsim values)
SET or ALLSETS(for writing sets)
Formula qualifiers
ALWAYS or INITIALdefault is ALWAYS(*) when a real coefficient is on LHS
INITIAL when an integer coefficient is on LHS
BY_ELEMENTS(see sections 10.8 and 10.13)
WRITE UPDATED ...(see section 10.8)
Equation qualifiers
LINEAR or LEVELSdefault is LINEAR(*)
ADD_HOMOTOPY or NOT_ADD_HOMOTOPYdefault is NOT_ADD_HOMOTOPY (see 26.6.6)
Update qualifiers
PRODUCT or CHANGEdefault is PRODUCT
Zerodivide qualifiers
ZERO_BY_ZERO or NONZERO_BY_ZEROdefault is ZERO_BY_ZERO
Display qualifiers
POSTSIM(for displaying postsim values)
Mapping qualifiers
ONTOThis is not the default
PROJECTSee section 10.13.2
Assertion qualifiers
ALWAYS or INITIALdefault is ALWAYS
Complementarity qualifiers
VARIABLE= , LOWER_BOUND= ,
UPPER_BOUND
see section 10.17

11    Syntax and semantic details [gpd2.4]

Click here for detailed chapter contents

This section contains a comprehensive description of the semantics of the TABLO language (and any points of syntax not covered in the previous chapter).

11.1    General notes on the TABLO syntax and semantics [gpd2.4.1]

11.1.1    TABLO statements [gpd2.4.1.1]

A TABLO Input file consists of a collection of separate TABLO Statements. Each input statement must usually begin with its keyword such as: SET, SUBSET,COEFFICIENT, VARIABLE, FILE, READ, WRITE, FORMULA, EQUATION, UPDATE, DISPLAY, ZERODIVIDE, MAPPING, ASSERTION, TRANSFER, OMIT, SUBSTITUTE, BACKSOLVE or COMPLEMENTARITY and must end with a semicolon ";". The keyword can be omitted if the previous statement on the file is of the same type, as in, for example, the following three VARIABLE declarations:

Variable (all,i,COM) x(i);
         (all,i,COM) x2(i);
                     y;

However, if the previous statement begins with the two keywords FORMULA & EQUATION (see section 10.9.1 above), the keyword must be included.

Although a statement can inherit its keyword from the previous statement as described just above, it is very important to realise that a statement never inherits qualifiers from the previous statement. Thus, for example, if you define 3 linear VARIABLEs via the following statements:

Variable (change) c_X;
                  c_Y;
                  c_Z;

although the first is declared to be a CHANGE variable, the second and third (c_Y and c_Z) will be PERCENT_CHANGE variables (assuming the usual default values for qualifiers are in place). If you want to make them all CHANGE variables, you must explicitly include this qualifier for them all, even if you leave out the keyword in the declarations of the last two, as in;

Variable (change) c_X;
         (change) c_Y;
         (change) c_Z;

11.1.2    Lines of the TABLO input file [gpd2.4.1.2]

Input is in free format. Multiple spaces, tabs and new lines are ignored by TABLO.

Lines are limited to 255 characters (since GEMPACK release 11.2, May 2013). Longer lines will result in an error on the preliminary pass and no other checking will be done until you fix the lines which are too long.

Previously lines were limited to 80 characters. Labelling information (see 11.2.3) is limited to 80 characters. Long names (see 5.0.4) are limited to 70 characters.

Older versions of TABLO will raise a syntax error if lines longer than 80 characters are found. See section 2.9.7 to identify which version of TABLO (or any GEMPACK program) you are running.

If you want to distribute a TAB file to others, who may have an older Release of GEMPACK, you could use the TABmate command Tools...Wrap TAB lines at 80 to rearrange lines to suit older TABLO versions.

11.1.3    Upper and lower case [gpd2.4.1.3]

Upper case letters (A to Z) and lower case letters (a to z) are not distinguished by TABLO, and can be freely intermixed. A suggested, consistent usage of different cases in linearized TABLO Input files is to use:

For example:

Equation E_xdomexp_c (all,r,REG)
  ID01[VDOMEXP_C(r)]*xdomexp_c(r) = sum{c,COM,VDOMEXP(c,r)*xdomexp(c,r)};

The TABmate command Tools...Beauty Parlour allows you to enforce case consistency within your TAB file.

11.1.4    Comments [gpd2.4.1.4]

Comments begin and end with an exclamation mark " ! ". Such comments, which are ignored by TABLO, can go anywhere in the file. TABmate displays such comments in blue italic letters, by default.

11.1.5    Strong comment markers [gpd2.4.1.5]

Strong comment markers, ![[! at the start and !]]! at the end, can be used to comment out longer sections of text which already contain ordinary comments indicated by '!' or even other strong comment markers. An example follows:

![[! Strong comment includes ordinary comments and previously active text
 ! ordinary comment !
  previously active text 
 ! old comment!   Strong comment ends with !]]!

These strong comment markers may be nested, so that one !]]! cancels out one previously active ![[!. Note that the start of a strong comment should not usually be made in the middle of an existing ordinary comment, as the next example shows.

! ordinary comment starts ![[! strong comment - ends with !]]!
   But this text is still inside the ordinary comment which
   needs another exclamation mark to end it !

TABmate displays these strong comments with a light blue background, by default.

11.1.6    Reserved (special) characters [gpd2.4.1.6]

There are three reserved characters, namely

;which terminates an input statement
#the delimiter for labelling information
!the delimiter for comments

We recommend that you do not use any of these reserved characters except for their defined function. For example, even though TABLO ignores the content of comments, you should still not include semicolons (;) within them.

11.1.7    Chinese and accented characters [nonascii]

Strictly, these are not allowed in a TAB file, but some people have found that TABmate often will display them correctly, if they appear within comments. However, the practice is risky: these non-ASCII characters may be stored as PAIRs of ASCII characters — which might include such characters as ! or ;. If TABLO thinks that a comment ends (with !) somewhere within 北京 or São Paulo, error messages can be hard to interpret.

11.2    User defined input [gpd2.4.2]

The syntax descriptions in chapter 10 referred to the following types of user-defined input.

11.2.1    Names [gpd2.4.2.1]

All names of COEFFICIENTs, VARIABLEs, SETs, set elements, indices, EQUATIONs and logical FILEs consist of letters (A to Z, a to z), digits (0 to 9), underscores '_' and the character '@'. Names must commence with a letter. Asian or other non-English letters are not allowed.

Examples are SALES, X3, X, TOT_SALES, p_XH, c_abc, Focc, xcom, X3@Y2.

The case (upper or lower) is not significant so XYZ is the same as xyz.

Headers must be four (or fewer) characters, either letters A-Z or digits 0-9. Headers starting with XX are reserved for internal program use. Headers on any one file must be unique. Examples are ABCD, 1234, ESUB, H1, COM. We suggest you use uppercase, but case (upper or lower) is ignored, so 'abcd' is the same as 'ABCD'.

The maximum lengths of names are as follows:

Table 11.1 Maximum name lengths
Name of objectMaximum length
(characters)
Header4
COEFFICIENT12
SET12
Index12
VARIABLE(LINEAR)15
VARIABLE(LEVELS)12
EQUATION20
COMPLEMENTARITY10
Logical FILE20
Set element12
Intertemporal element stem6 (see section 16.2.1)
Actual file name40
Real constant20
Integer constant18
Integer set size9

Duplication of a name for two different purposes is not allowed. For example, you cannot use 'X1' to denote a coefficient and 'x1' to be a variable. (Remember that input is case-independent.)

Certain names (SUM, IF, function names and operators used in conditionals) are reserved, which means that they cannot be used as the names of coefficients, variables, sets or files (but they can be used as set element names and inside quotes in Formulas and Equations — for example, SALES("prod")). These reserved words are listed below.

Table 11.2 Reserved words
Reserved WordDescriptionSee section
ALLquantifier11.3
SUM PRODsum, product11.4.3
IFconditional expressions11.4.6
LE GE LT GT EQ NEcomparison operators11.4.5
NOT AND ORlogical operators11.4.5
ABS MAX MIN SQRT EXP LOGE LOG10functions11.5
ID01 ID0V RANDOM NORMAL CUMNORMALfunctions11.5
LOGNORMAL CUMLOGNORMAL GPERF GPERFCfunctions11.5
ROUND TRUNC0 TRUNCBfunctions11.5
RAS_MATRIXspecial function11.15
$POSspecial function11.5
MAXS MINSMax,min over set11.4.3
HOMOTOPYvariable26.6.4
$del_Newtonvariable26.5

11.2.2    Abbreviating lists of set elements [gpd2.4.2.0]

Lists of set elements such as

ind1, ind2, ind3, ind4, ind5, ind6, ind7, ind8

can be abbreviated using a dash. For example, the above could be abbreviated to

ind1 - ind8

Such abbreviations can be mixed with other element names to give lists such as

(cattle, grain1 - grain4, services1 - services12, banking)

There are two ways of implying a list of element names. The first is illustrated above. The second has the number parts expanded with leading zeros such as

ind008 - ind112

which is an abbreviation for

ind008, ind009, ind010, ind011, (and so on up to) ind112.

In this second case, the number of digits at the end must be the same before and after the dash. For example, the following are allowed

ind01 - ind35, com0001 - com0123,

while

ind01 - ind123

is not allowed.

11.2.3    Labelling information (text between hashes #) [gpd2.4.2.2]

Text between delimiting hashes ('#') is labelling information. It must be contained on a single input line in the TABLO Input file, and is limited to 80 characters.

We recommend that you include labelling information wherever possible in your TABLO Input file, to make model output more intelligible. COEFFICIENT, VARIABLE and SET labelling information is used for displaying data and results in many GEMPACK programs. As well:

At present, labelling information on READ or WRITE statements is not used.

11.2.4    Arguments: indices, set elements or index expressions [gpd2.4.2.3]

An argument can be an index:

X2(i)

or a set element name inside double quotes:

X2("wool")

Most generally, an argument can be any index expression.

Arguments of variables and coefficients are separated by commas and enclosed in round brackets. They follow immediately after the variable or coefficient name. When a variable or coefficient is declared in a VARIABLE or COEFFICIENT input statement, all arguments will be (dummy) indices.

In all other occurrences of arguments, they could be indices or elements (enclosed in double quotes) from the relevant set or indeed, any appropriate index expression. Examples of coefficients followed by arguments are:

X3(i,j)     INTINP(i,"wool")

The arguments must range over the appropriate sets, in the order specified in the coefficient or variable declaration. For example, if variable x3 is declared via

Variable  (all,i,S) (ALL,j,T) x3(i,j) ;

then, in every occurrence of x3,

Mappings in index expressions

Arguments can also involve set mappings. For example, in

AGGX2(COMtoAGGCOM(c))

the argument is COMtoAGGCOM(c) where COMtoAGGCOM is a mapping (from the set COM to the set AGGCOM) and c is an index ranging over the set COM (we assume AGGX2 is dimensioned AGGCOM). A set mapping can be applied to any index expression to form another index expression, eg:

MAP1(i)   MAP1(MAP2(c))

When an argument involves one or more set mappings, a little care is required to check that the argument is in the appropriate set. Details can be found in section 11.9.7.

Intertemporal set indices

An argument can also be of the form index + <integer> or index -<integer> if the set in question is an intertemporal set (see section 16.2). For example:

X(t+1)    X(t-1).

Here the "+/-<integer>" part is called the index offset.

If an argument involves an index offset, usually the index in question must range over a subset of the relevant set. For example, if Coefficient X2 is declared via

Coefficient  (all,i,S) X2(i) ;

then for the occurrence X2(t+1) to be allowed, the set S must be an intertemporal set and usually the index t must be ranging over a subset of S. However, this requirement can be relaxed in some circumstances — see section 16.4.

When the set involved is intertemporal, an index offset can be added to MAPped indices. For example:

 MAP1(t)+2   MAP1("t2")-3   MAP2(MAP1(t)+2)-3

Elements from intertemporal sets with intertemporal elements are not allowed as arguments. For example, the Formula below is not allowed since the argument of Coef2 must be from an intertemporal set with intertemporal elements.

Set (Intertemporal) alltime (p[0] - p[10]) ;
Coefficient (all,t,alltime)  Coef2(t) ;
Formula Coef2("p[6]") = 3 ;   ! not allowed !

11.2.5    Index expressions with elements from run-time sets [gpd2.4.2.4]

Sets whose elements are specified in the TAB file are said to have fixed elements, while sets whose elements are read or inferred at run-time are said to have run-time elements -- see section 11.7.1 for more details.

Before GEMPACK Release 8, set element names in index expressions, eg:

Formula COEF1("food") = 23 ;

were only allowed if the underlying set had fixed elements.

Since then TABLO also allows the underlying set to have runtime elements. TABLO does this by inventing a synthetic set, prefixed S@, as illustrated in the following example.

Example

File Setinfo ;
Set COM # Commodities #  
   Read Elements from File Setinfo header "COM" ;
Set MAR # Margins commodity # ("transport") ;
Subset MAR is subset of COM ;
Set NONMAR # Non-margins commodities # = COM - MAR ;
Coefficient (all,c,NONMAR)  COEF1(c) ;
Formula COEF1("food") = 23 ;

The elements of COM are read at run time, while those of MAR are fixed. The elements of NONMAR are inferred at run time (once the elements of COM have been read). See section 11.7.1 for more details about run-time elements.

TABLO creates a new set called S@food containing the single element "food" and TABLO adds information to indicate that this set is a subset of the set NONMAR.1

Whether or not "food" is actually an element of NONMAR can only be checked when GEMSIM or the TABLO-generated program runs to carry out the statements in this TABLO Input file. At runtime the program checks that "food" is an element of NONMAR when it checks the SUBSET statement (S@food is subset of NONMAR) introduced by TABLO. If "food" is not in NONMAR, the error message will say that S@food is not a subset of NONMAR since "food" is not in NONMAR.

11.3    Quantifiers and quantifier lists [gpd2.4.3]

A quantifier is of the form

(All,<index_name>,<set_name> [:<condition>] )

For example:

(ALL, i, COM)
(all,i,COM: TPROD(i) > 0)

A quantifier list consists of one or more quantifiers, concatenated together in the input. For example:

(all,i,COM)
(all,i,COM)(all,j,IND)
(all,i,COM: TPROD(i) > 0)(all,s,SOURCE)(all,j,IND)

Quantifier lists occur in many TABLO statements: COEFFICIENT, VARIABLE, READ, WRITE, FORMULA, EQUATION, UPDATE, DISPLAY, ASSERTION and COMPLEMENTARITY.

Conditions are only allowed in quantifiers in FORMULA(ALWAYS) and UPDATE statements. (They are not allowed in quantifiers in READs, FORMULA(INITIAL)s, EQUATIONs, WRITEs, DISPLAYs or declarations of VARIABLEs or COEFFICIENTs.)

See section 11.4.5 for more details about conditions in quantifiers.

Examples of quantifier lists from ORANIG01.TAB
Coefficient  ! Basic flows of commodities (excluding margin demands)!
(all,c,COM)(all,s,SRC)(all,i,IND) V1BAS(c,s,i) # Intermediate basic flows #;
Variable  ! Variables used to update above flows !
(all,c,COM)(all,s,SRC)(all,i,IND)  x1(c,s,i) # Intermediate basic demands #;
Update (all,c,COM)(all,s,SRC)(all,i,IND)  V1BAS(c,s,i)  = p0(c,s)*x1(c,s,i);
Formula  (all,c,COM)(all,s,SRC)(all,i,IND)
   V1PUR(c,s,i)  = V1BAS(c,s,i) + V1TAX(c,s,i) + sum{m,MAR, V1MAR(c,s,i,m)};

11.4    Expressions used in equations, formulas and updates [gpd2.4.4]

Expressions occur in equations, formulas, updates and complementarities.

11.4.1    Operations used in expressions [gpd2.4.4.1]

The following operators can be used in expressions.

+Addition
-Subtraction
*Multiplication
/Division
^Power

Note that ^ means "to the power of". For example, X^3 means X to the power of 3 (that is, X cubed) while X^Y means X to the power Y. The "Y" in Z^Y is referred to as the exponent.

A multiplication operation MUST be shown explicitly whenever it is implied -- for example A6(i)SALES(i) is incorrect and must be written as A6(i)*SALES(i).

Order of precedence in evaluation

GEMPACK processes expressions in the following order:
parts within brackets are done first,
then unary2 + or - , ie, expressions like '-3' or '+2.0',
then the ^ power operation,
then multiplication and division (* and /), which have the same precedence,
then binary addition and subtraction (eg: '2+1' and '4-2'), which have the same precedence.

Operators with the same precedence (ie, */ or +-) are processed left to right.

With these rules:

-A+B^C/Dis processed as( (-A) + ((B^C)/D) )
E*F/Gis processed as(E*F)/G
E/F*Gis processed as(E/F)*G not E/(F*G)

You should assume that some other reader of your code has not memorized the above rules. Always use additional brackets to convey your intention if there could be any ambiguity.

Note that while in normal arithmetic, (E*F)/G and E*(F/G) have the same values, these expressions can lead to different results when evaluated in a TAB file if F=G=0 and there is a nonzero ZERODIVIDE DEFAULT value in place.3

Examples of expressions from ORANIG01.TAB
Update (all,c,COM)(all,s,SRC)(all,i,IND)  
   V1BAS(c,s,i)  = p0(c,s)*x1(c,s,i);
Formula  (all,c,COM)(all,s,SRC)(all,i,IND)
   V1PUR(c,s,i)  = V1BAS(c,s,i) + V1TAX(c,s,i) 
                      + sum{m,MAR, V1MAR(c,s,i,m)};
Update
 (change)(all,c,COM)(all,s,SRC)(all,i,IND)  V1TAX(c,s,i) = delV1TAX(c,s,i);
Formula     (all,i,IND) SUPPLYELAST(i) =
    SIGMA1PRIM(i)*V1LAB_O(i)*V1CST(i)/[V1PRIM(i)*{V1CAP(i)+V1LND(i)}];
Equation
 E_x1lab   # Demand for labour by industry and skill group #
  (all,i,IND)(all,o,OCC)
  x1lab(i,o)    =  x1lab_o(i) - SIGMA1LAB(i)*[p1lab(i,o) - p1lab_o(i)];
 !expression 1 !  !   expression 2                                    !

11.4.2    Brackets in expressions [gpd2.4.4.3]

Pairs of brackets ( ), [ ] or { } can be used to express grouping in expressions. They can also be used with SUMs (see section 11.4.3), IFs (section 11.4.6) and to surround function arguments (section 11.5).

In quantifiers (using the ALL syntax in section 11.3), round brackets ( ) are required; [ ] and { } cannot be used. Also, keyword qualifiers must be surrounded by round brackets ( ), as in

Formula (initial) (all,i,COM) B(i)=3;     ! only ( ) allowed here     !

Complicated expressions are more readable when different types of bracket are used. Because you must use round brackets in the above cases, it makes sense to prefer the other styles, [ ] and { } where they are allowed, as in

Formula C = sum{i,COM, ABS[B(i)]};        ! [ ] or { } or ( ) allowed !

For example, the "Beauty Parlour" in TABmate (see 8.4.4) will use { } for SUMs and [ ] to group terms.

Square brackets in intertemporal sets [ ] indicate flexible set sizes where the set size is read in at run time -- see chapter 16.

11.4.3    Sums over sets in expressions [gpd2.4.4.2]

Sums over sets or subsets can be used in expressions, using the following syntax:

SUM { <index_name>,<set_name> [:<condition>], expression }

If, for example the set IND has two elements "car" and "food" then

Sum{i,IND, A6(i)*SALES(i)}

means

A6("car")*SALES("car") + A6("food")*SALES("food").

As for quantifiers, the optional condition is a logical expression which may restrict the number of things summed. For example, with IND as just above, if A6("car") is -1 and A6("food") is 2 then

Sum{i,IND: A6(i) > 0, A6(i)*SALES(i) }

will be equal to just A6("food")*SALES("food"). See section 11.4.5 for more details about conditions in SUMs.

Pairs of brackets [ ] or ( ) can be used as alternatives to the pair { } in Sum{ }, as in, for example,

 Sum[i,IND, A6(i)*SALES(i) ]
 Sum(i,IND: A6(i) > 0, A6(i)*SALES(i) )
Example from ORANI-G

The ORANI-G model contains the following code to work out the average price received by an industry that produces several commodities:

Coefficient
 (all,c,COM)(all,i,IND) MAKE(c,i) # Output of commodity c by industry i #;
 (all,i,IND)            MAKE_C(i) # All production by industry i #;
Formula     (all,i,IND) MAKE_C(i) = sum{c,COM, MAKE(c,i)};
Equation E_x1tot # Average price received by industries #
 (all,i,IND) p1tot(i) = sum{c,COM, [MAKE(c,i)/MAKE_C(i)]*pq1(c,i)};

Above, the average price p1tot is a share-weighted average of the prices pq1 where the shares are [MAKE(c,i)/MAKE_C(i)] and the denominator MAKE_C(i) is the sum over commodities c of MAKE(c,i).

You might be tempted to express the same idea in a more compact way by writing:

Coefficient
 (all,c,COM)(all,i,IND) MAKE(c,i) # Output of commodity c by industry i #;
Equation E_x1totAlt # Average price received by industries #
 (all,i,IND) p1tot(i) = sum{c,COM, [MAKE(c,i)/sum{cc,COM,MAKE(cc,i)}]*pq1(c,i)};

but that would be a bad idea because the sum:

sum{cc,COM,MAKE(cc,i)}

would be evaluated once for each COM*IND combination (rather than, as previously, once for each IND). This type of unnecessary repeated SUMming can increase simulation times.

Good Practice Recommendation: Avoid putting SUMs in denominators

11.4.4    MaxS, MinS and Prod operators [gpd2.4.4.2a]

Operators MAXS, MINS and PROD over sets or subsets have a similar syntax to SUM. They can be used in expressions, using the following syntax:

MAXS, MINS, PROD syntax

MAXS(<index_name>,<set_name> [:<condition>], expression )
MINS(<index_name>,<set_name> [:<condition>], expression )
PROD(<index_name>,<set_name> [:<condition>], expression )

PROD means the product over the set. MAXS is the maximum over a set. MINS is the minimum over the set.
Some examples:

MAXS(c,COM,V4BAS(c))

is the maximum value of V4BAS(c) where c is in the set COM.

FORMULA (All,i,COM)(All,j,IND) Z(i,j) = MINS(s,SOURCE, X(i,s,j))  ;

Z(i,j) are the minimum values of X(i,s,j) where s is in the set SOURCE

PROD(i,IND,A6(i)*SALES(i))

is the product of terms A6(i)*SALES(i) over the set IND.

If, for example the set IND has two elements "car" and "food" then

PROD(i,IND,A6(i)*SALES(i))

means

A6("car")*SALES("car") * A6("food")*SALES("food").

As for SUMs, the optional condition is a logical expression which may restrict the number of things in the set. For example, with IND as just above, if A6("car") is -1 and A6("food") is 2 then

PROD(i,IND: A6(i) > 0, A6(i)*SALES(i) )

will be equal to just A6("food")*SALES("food"). See section 11.4.5 for more details about conditions in SUMs, PRODs, MAXS, MINS.

Empty sets

If EMPTY is an empty set containing no elements, then

Expressions permitted

Linear variables are not permitted inside a PROD, MAXS or MINS. However levels variables are allowed inside PROD in a FORMULA or EQUATION.

For example, in the levels form of Stylized Johansen in the TAB file SJLV.TAB

EQUATION  Extra  (all,j,SECT)
LOGE(W(j)) = SUM{t,SECT, ALPHACOM(t,j)*LOGE(PC(t))}
           + SUM{u,FAC,  ALPHAFAC(u,j)*LOGE(PF(u))};

could be rewritten as

EQUATION  Extra  (all,j,SECT)
  W(j) = PROD(t,SECT,PC(t) ^ALPHACOM(t,j)) * PROD(u,FAC,PF(u)^ALPHAFAC(u,j)) ;

In this equation PC and PF are levels variables and ALPHACOM and ALPHAFAC are COEFFICIENT(PARAMETER)s.

11.4.5    Conditional quantifiers and SUMs, PRODs, MAXS and MINS [gpd2.4.4.5]

Conditions can be specified to restrict SUMs, PRODs, MAXS and MINS (see section 11.4.3) and ALLs (see section 11.3). The condition is specified after a colon ':' as in

SUM{j,IND: XINP(j) > 0, XINP(j)*y(j) }

or

(ALL,j,IND: XINP(j) > 0 )

Read the colon ':' as 'such that' (just as in set notation in mathematics).

The judicious use of conditionals may result in GEMSIM or TABLO-generated programs running much more quickly. Conditionals may also help to specify complicated scenarios such as taxes applied at increasing rates depending on income (though, in such cases, care must be taken to use this only in situations where the underlying function is continuous — that is, does not make discrete jumps as inputs vary).

Examples of the use of conditional SUMs can be found in section 11.9 below.

At present conditional SUMs are allowed everywhere that SUMs are allowed. Conditional ALLs are allowed in FORMULA(ALWAYS)s and UPDATEs, but not in EQUATIONs, READs, WRITEs, DISPLAYs or FORMULA(INITIAL)s.

Conditional PRODs are allowed everywhere that PRODs are allowed. Similarly, conditional MAXS and MINS are allowed everywhere that MAXS and MINS are allowed.

The syntax for conditional SUMs, PRODs, MAXS, MINS and ALLs is as follows.

SUM{ <index>, <set> : <condition> , <expression to sum> }
ALL( <index>, <set> : <condition> )
PROD( <index>, <set> : <condition> , <expression to multiply> )
MAXS( <index>, <set> : <condition> , <expression> )
MINS( <index>, <set> : <condition> , <expression> )

where you want to find the maximum or minimum of the <expression> for MAXS and MINS.

Conditions specified in ALLs or SUMs or PRODS or MAXS or MINS can depend on the data of the model but not on the changes or percentage changes in the data. That is, conditions can involve coefficients or levels variables (but not linear variables) of the model. The operations in the conditions may involve comparing real numbers using the operations below. In each case there is a choice of the syntax to be used in TABLO Input files to express these: either a letter version or a symbol version is available, as indicated below.

Comparison OperatorLetter VersionSymbol Version
less thanLT<
less than or equal toLE<=
greater thanGT>
greater than or equal toGE>=
equalsEQ=
not equal toNE<>

You can also use index-expression conditions (see 11.4.11) in ALLs, SUMs, PRODS, MAXS or MINS.

Note that no space is allowed between the two characters in the symbol versions <=, >=, <> of LE, GE and NE. When using the letter versions, it is often obligatory to leave a space before the operator and best to leave one after it, such as in "X(i) GT Y(j)".

The logical operators AND, OR and NOT can also be used. Thus compound conditions are possible such as

[X(i) > 0] AND [Y(i) LT (Z(i) + W(i)) ]

Note that the operations +, -, *, / and ^ can be used in the numerical part of these conditions. For example,

 [ {X(i)+Y(i)} * Z(i) > 10.0 ]

The precedence rules for AND, OR and NOT are that

NOT behaves like '-' in arithmetic, while

AND and OR behave like '*' and '+' respectively. For example,

NOT A(i) > B(i) AND C(i) < 1 OR D(i) GT 5.3

really means

[ { NOT [A(i) > B(i)] } AND {C(i) < 1} ] OR {D(i) GT 5.3} .

Use brackets liberally to make your meaning clear to TABLO or to any reader.

11.4.6    Conditional expressions [gpd2.4.4.6]

The IF syntax shown below can be used as part of any expression, including expressions in equations and on the right hand side of formulas and updates.

IF ( <condition>, <expression> )

The value of the above conditional expression is equal to the value of <expression> if <condition> is true, otherwise the value is zero. For example,

FORMULA (all,i,COM) A(i) = B(i) + IF( C(i) >= 0, D(i) ) ;

sets

A(i) = B(i) + D(i)if C(i) is positive or zero, or
A(i) = B(i)if C(i) < 0.

For other examples, see section 17.3 and the comment after Example 2 in section 14.1.11.

The <condition> part is as described for conditions in 11.4.5. Conditions must be logical expressions which can be evaluated to be either true or false. Typically they involve comparison operators LT, LE, GT, GE, EQ or NE (see the table in section 11.4.5).

Pairs of brackets [ ] or { } can be used as alternatives to the pair ( ) in IF( ), as in, for example,

IF[ C(i) >= 0, D(i) ].

Logical expressions of the form "<index> IN <set>" are also allowed, as described next.

11.4.7    Index-IN-Set condition for IF expressions [gpd2.4.4.6b]

GEMPACK allows4 operator IF for expressions of the form IF(<index>IN<set>, <expression>). Note the important fine print, section 11.4.7.1, which follows the examples.

Example 1

Suppose that we have a set COM with a subset MARGCOM with MARGCOM being a subset of COM. Then consider the statements

Coefficient (all,c,COM) Coef1(c) ;
Coefficient (all,m,MARGCOM) Coef2m(m) ;
Formula (all,c,COM) 
       Coef1(c) = IF[c in MARGCOM, Coef2m(c)] ;

The IF on the RHS of the Formula has condition "c in MARGCOM". The effect of this Formula is to set Coef1(c)=Coef2m(c) is c is in MARGCOM, otherwise to set Coef1(c)=0.

Semantic rules for IF(<index> IN <set>, <expression>)

1. The <index> must be active before the IF. [This "active" status can come from an ALL quantifier (all,<index>,<set2>) or from a SUM index.] Before the IF, <index> ranges over the set in the ALL quantifier or in the SUM.

2. Inside the <expression> part of

IF(<index> IN <set>, <expression>)

checking is done AS IF <index> were ranging over <set> rather than the set <index> was ranging over before this IF. This rule is applied when TABLO checks that indexes range over appropriate sets (see section 11.8).

3. Both the set <set> and the set over which <index> was ranging before the IF must have known elements at run time. (See section 11.7.1 for what it means to have "elements known at run time".)

4. However, the set <set> is NOT required to be a subset of the set over which <index> was ranging before the IF. [See Example 2 below.]

5. A condition "<index> in <set>" cannot be combined with other conditions using AND, OR, NOT.

Examples will make these rules clear.

Example 1 (continued)

Firstly look again at Example 1 above. In the Formula

Formula (all,c,COM) 
      Coef1(c) = IF[c in MARGCOM, Coef2m(c)] ;

index "c" begins ranging over the set COM because of "(all,c,COM)". But when it comes to Coef2m(c) (the <expression> part) it is ranging over the set MARGCOM. Since Coef2m is defined to have one argument which ranges over the set MARGCOM, you would not normally be allowed to write coef2m(c) if c is ranging over COM. That is, you are not allowed to write

(all,c,COM) Coef2m(c) 

(see section 11.8).

In Example 1, index c ranges over COM at the start of the Formula. However, because of semantic rule 2 above, while inside the <expression> part of IF[c in MARGCOM, Coef2m(c)], checking is done as if index c were ranging over the set MARGCOM (rather than the set COM). So Coef2m(c) is ok there, just as it would be in the statement

(all,c,MARGCOM) Coef2m(c) = 1 ;

Semantic rule 3 above means that both sets COM and MARGCOM must have known elements at run time.

Example 2

Suppose that we have sets COM, MARGCOM (margins commodities) and EXPCOM (exported commodities) and that both MARGCOM and EXPCOM are subsets of COM but that neither is a subset of the other. For example, MARGCOM may have elements (air, rail, road) while EXPCOM has elements (coal, air). Consider the statements

Coefficient (all,c,COM) Coef1(c) ;
Coefficient (all,c,COM) Coef1b(c) ;
Coefficient (all,m,MARGCOM) Coef2m(m) ;
Coefficient (all,e,EXPCOM) Coef3e(e) ;
Formula (all,m,MARGCOM) Coef2m(m) = 
  Coef1(m) +IF[m in EXPCOM, Coef1b(m) + Coef3e(m)] ;

Here <expression> is "Coef1b(m) + Coef3e(m)". This is only relevant for those m in MARGCOM which are also in EXPCOM, namely just "air" for the elements given above. Hence, the Formula above gives values

Coef2m("air")  = Coef1("air") + [Coef1b("air") + Coef3e("air")]
Coef2m("rail") = Coef1("rail")  
Coef2m("road") = Coef1("road")

This illustrates Rule 4 above.

Notice however that the Formula

(all,c,COM) Coef1(c) = IF[c in EXPCOM, Coef2m(c)]    ! not valid

is NOT valid. By rule 2 above, when checking Coef2m(c), index c is ranging over the set EXPCOM. But Coef2m has been defined to have one argument ranging over the set MARGCOM. For Coef2m(c) to be valid, the index checking procedure used in TABLO (see section 11.8) then requires that c is ranging over either MARGCOM or a Subset of MARGCOM. Since EXPCOM is not a subset of MARGCOM, the above statement is not valid.

Example 3

Suppose that sets and Coefficients are as in Example 2 above. Consider the Formula

Formula (all,c,COM) Coef1(c) = 
IF[c in MARGCOM, IF{c in EXPCOM, Coef2m(c)} ; ! invalid

When checking Coef2m(c), c is deemed to be ranging over EXPCOM (by Rule 2 above). That means that the Formula above is not valid (since the argument of Coef2m must range over MARGCOM or a subset of MARGCOM). As a human reader of the Formula above, you are probably inclined to protest since surely c is also in MARGCOM when Coef2m(c) is evaluated, because IF{c in EXPCOM, Coef2m(c)} is inside IF[c in MARGCOM, ]. But, while you know that, TABLO follows Rule 2 explicitly (and perhaps simple mindedly). TABLO makes no attempt to remember that c must also be in MARGCOM above. If you want such a Formula, you can easily make a valid one by defining a new set which is the intersection of MARGCOM and EXPCOM. For example

Set MARGEXP = MARGCOM Intersect EXPCOM ;
Formula (all,c,COM) Coef1(c) = 
IF[c in MARGCOM, IF{c in MARGEXP, Coef2m(c)}] ;  ! valid

This has the same effect as was presumably intended by the invalid Formula above. And it is legal as far as TABLO is concerned; when Coef2m(c) is being checked, c is ranging over the set MARGEXP (by Rule 2) and this is ok since MARGEXP is a subset of MARGCOM . Notice also that

Formula (all,c,COM) Coef1(c) = 
IF[(c in MARGCOM) AND (Coef1b(c) > 0), 
                     Coef2m(c)] ;   ! invalid

is invalid by Rule 5 above.

Example 5: Market clearing in GTAP

The 2 equations MKTCLTRD_MARG and MKTCLTRD_NMRG below are taken from the standard GTAP.TAB. These could be amalgamated into the single equation shown below. Then the new equation could be used to substitute out or backsolve for qo.

The current 2 equations:

Equation MKTCLTRD_MARG
# eq'n assures market clearing for margins commodities (HT 1) #
(all,m,MARG_COMM)(all,r,REG)
qo(m,r) = SHRDM(m,r) * qds(m,r)
        + SHRST(m,r) * qst(m,r)
        + sum(s,REG, SHRXMD(m,r,s) * qxs(m,r,s))
        + tradslack(m,r);
Equation MKTCLTRD_NMRG
# eq'n assures market clearing for the non-margins commodities (HT 1) #
(all,i,NMRG_COMM)(all,r,REG)
qo(i,r) = SHRDM(i,r) * qds(i,r)
        + sum(s,REG, SHRXMD(i,r,s) * qxs(i,r,s))
        + tradslack(i,r);

could be replaced by the single equation:

Equation MKTCLTRD
# eq'n assures market clearing for all commodities (HT 1) #
(all,i,TRAD_COMM)(all,r,REG)
qo(i,r) = SHRDM(i,r) * qds(i,r)
        + IF[i IN MARG_COMM, SHRST(i,r) * qst(i,r)]
        + sum(s,REG, SHRXMD(i,r,s) * qxs(i,r,s))
        + tradslack(i,r);

Note that qst(i,r) and SHRST(i,r) are only declared if i is in MARG_COMM. That is why we need to use the Index-IN-Set approach.

Example 6: Combining two related equation blocks

The ORANI-G model has different export demand equations for "Individual" export commodities (where price determines world demand) and for the remaining "Collective" export commodities (which move en bloc):

Set
 TRADEXP  # Individual export commodities # = (all,c,COM: IsIndivExp(c)>0.5);
 NTRADEXP # Collective export commodities # = COM - TRADEXP;
Equation
 E_x4A  # Individual export demand functions #
   (all,c,TRADEXP)  x4(c) - f4q(c) = -ABS[EXP_ELAST(c)]*[pf4(c) - f4p(c)];
 E_x4B  # Collective export demand functions #
   (all,c,NTRADEXP) x4(c) - f4q(c) = x4_ntrad;

The form of the equation names (E_x4A and E_x4B) tells TABmate that the two equations together determine the variable x4 — this helps TABmate construct an "automatic closure" (see section 8.4.2). However, we cannot substitute or backsolve for x4 (which would reduce model size) because substitution requires that one equation explains all elements of the associated variable.

Using the Index-IN-Set approach, we could combine the two equations thus:

Equation E_x4  # Export demands #  (all,c,TRADEXP)  x4(c) - f4q(c) =
   IF[c in TRADEXP,  -ABS[EXP_ELAST(c)]*{pf4(c) - f4p(c)}]
 + IF[c in NTRADEXP, x4_ntrad];

We could use equation E_x4 to substitute or backsolve for x4. In addition, E_x4 makes the "automatic closure" clearer.

Example 7: Emission rules in MMRF-GREEN

MMRF-GREEN models CO2 emissions (xgas) with a set of six rules, different for industries (IND) and residential fuel users, and different too according to whether emissions arise from burning a fuel (coal, gas, or petroleum products) or in some other way (termed "Activity"). The equations are:

Variable (all,f,FUELX)(all,u,FUELUSER)(all,q,REGDST)
xgas(f,u,q) # All emissions #;
Equation
E_xgasA (all,i,IND)(all,q,REGDST)             
  xgas("Coal",i,q) = xprimen("Coal",i,q) + agas("Coal",i,q) + agas2("Coal",i,q);
E_xgasB (all,i,IND)(all,q,REGDST)             
  xgas("Gas",i,q) = xprimen("Gas",i,q) + agas("Gas",i,q) + agas2("Gas",i,q);
E_xgasC (all,p,PETPROD)(all,i,IND)(all,q,REGDST)
  xgas(p,i,q) = xfinalen(p,i,q) + agas(p,i,q) + agas2(p,i,q);
E_xgasD (all,i,IND)(all,q,REGDST)             
  xgas("Activity",i,q) = [actdrive(i,q) + agasact(i,q)];
E_xgasE (all,f,FUEL)(all,q,REGDST)            
  xgas(f,"Residential",q) = x3o(f,q)
        + agas(f,"Residential",q) + agas2(f,"Residential",q);
E_xgasF (all,q,REGDST)                        
  xgas("Activity","Residential",q) = x3tot(q);

The equations explain all elements of xgas because of previous set definitions which imply that:

FUEL  = "Coal" + "Gas" + PETPROD 
FUELX = FUEL + "Activity" 
FUELUSER = IND + "Residential" 

Unfortunately, because xgas is explained by 6 equations (rather than 1) it is not possible to backsolve or substitute it. Since xgas is a large variable, this must impose a performance penalty.

Using the Index-IN-Set approach, we could formulate the 6 rules as a single equation:

Set CoalGas = FUEL - PETPROD; ! ie: Coal,Gas ! 
Subset CoalGas is subset of PrimFuel; 
Equation E_xgas
(all,f,FUELX)(all,u,FUELUSER)(all,q,REGDST)
xgas(f,u,q) = if [u in IND, 
  if [f in CoalGas,  xprimen(f,u,q)  + agas(f,u,q) + agas2(f,u,q)]
+ if [f in PetProd,  xfinalen(f,u,q) + agas(f,u,q) + agas2(f,u,q)] 
+ if [f ="Activity", actdrive(u,q) + agasact(u,q)]]
           +  if [u = "Residential",
  if [f in FUEL,     x3o(f,q) + agas(f,u,q) + agas2(f,u,q)]
+ if [f ="Activity", x3tot(q) ]];
Backsolve xgas using E_xgas; 

This enables us to backsolve xgas (to speed up solving) and arguably is clearer. It suggests a further improvement: making the term [agas(f,u,q) + agas2(f,u,q)] common to all 6 cases.

11.4.7.1    Fine print [iinsfineprint]

Note that "<index> IN <set>" is NOT allowed as a condition for a SUM, PROD, MAXS, MINS or for an ALL (see section 11.4.5).

Errors in the Release 11.0 implementation of index-in-set could produce errors either at the TABLO stage or at run-time. In rare cases, wrong results might be generated without warning. That was more likely to occur with GEMSIM than with a TABLO generated program. These bugs were fixed in Release 11.1.

From Release 11.1 TABLO always translates, during the CHECK stage, index-in-set to conditional SUMs. Subsequent error or warning messages may refer to these SUMs (even though they are not present in the original TAB file, see example (i) in section 14.1.10).

The Release 11.0 implementation of index-in-set also took longer to run than it should have. The conditional SUM implementation seems quite efficient.

11.4.8    Linear variables in expressions [gpd2.4.4.7]

In the following section, a linear variable is a variable representing the change or percentage change of a levels quantity. A linear variable can be declared using VARIABLE(LINEAR) or as the change (c_...) or percentage change (p_...) associated with a VARIABLE(LEVELS).

Linear variables cannot occur in a formula or in the conditional part of an ALL, IF or SUM. Division by an expression involving linear variables is not allowed in an equation.

In the following, a linear equation is one declared by a statement EQUATION (LINEAR) or just by EQUATION if the default for equations is not reset (as described in section 10.19). Similarly a levels equation is one declared by EQUATION (LEVELS).

In a linear equation, coefficients (or levels variables) must multiply linear variables, and, in such a multiplication, coefficients must go on the left and linear variables must go on the right.

For example, if xind and xcom are linear variables and A6, SALES are coefficients, then

A6(i)*xcom(i) + (SALES(i)/A6(i))*xind(i)

is correct. But

xcom(i)*A6(i)

is incorrect, and

SUM(i,S,A6(i)*xcom(i)) * SALES(j)

is incorrect.

A coefficient and a linear variable cannot be added. For example,

xcom(i) + A6(i)

is incorrect. Similarly a levels variable and a linear variable cannot be added.

Every term in a linear equation must contain a linear variable part. For example

A6(i)*xcom(i) + SALES(i) = 0

is incorrect. It is not a sensible equation because the second term, SALES(i), contains no linear variable.

The right-hand-side of a CHANGE UPDATE can contain any legal expression involving coefficients and variables. However, the right-hand-side of a PRODUCT UPDATE statement can only contain PERCENT_CHANGE linear variables multiplied (via '*') together (see section 11.12.4). Each PRODUCT update statement is translated automatically by TABLO into the appropriate algebraic expression. For example,

UPDATE  (all,i,COM) DVHOUS(i) = p_PC(i)*p_XH(i) ;

(which by default is a PRODUCT update) is the same as

UPDATE (CHANGE) (all,i,COM) DVHOUS(i) =DVHOUS(i)*[ p_PC(i)/100 + p_XH(i)/100 ] ;

In algebraic terms, both these updates are the same as the algebraic expression:

DVHOUS(i)_Updated=DVHOUS(i)*[1 + p_PC(i)/100 + p_XH(i)/100]

Linear variables and COEFFICIENT(NON_PARAMETER)s are not allowed in levels equations. Expressions in levels equations can only contain levels variables, parameters and constants (and of course operators).

11.4.9    Constants in expressions [gpd2.4.4.8]

As well as using coefficients and variables in expressions, you can use ordinary numbers (real or integer) written as decimals if necessary.

Examples are

16.54    -23 1   0.0

Real numbers should not be written using exponent notation. Don't use, for example, 1.3E12.

Especially when used as an exponent (that is, in the "B" part of an expression of the form A^B), it may be best to write integers without a decimal point.5 For example, write A^(C-2) rather than A^(C-2.0)

11.4.10    Indices in expressions [gpd2.4.4.9]

When used as arguments of a coefficient or variable, each index must be active — that is, be an ALL index or a SUM index still inside the scope of that ALL or SUM. No index which is still active can be re-used as an ALL or SUM index. If these rules are not followed, semantic problems will result. The examples below should make this clear.

Examples

(a) The index 'j' in A7(i,j) below is not active.

FORMULA  (all,i,IND)  A6(i) = A7(i,j);
                                   ^    ! incorrect:j not active !

(b) The SUM index 'j' below is already active.

FORMULA (all,j,IND) A6(j) = SUM(j, IND, B7(i,j) ) ;
                                ^    ! incorrect:j already active !

(c) The index 'j' in A8(j) below is not active because it does not fall within the scope of the SUM.

FORMULA   T1 = SUM{ j, COM, A6(j) } + A8(j)  ;
                                         ^    ! incorrect:j not active !

Every index quantified at the beginning of a formula must be used as an index of the coefficient on the left hand side of the formula. For example,

FORMULA (all,i,COM)(all,j,IND) A6(i) = 28 ;    ! incorrect: no j on LHS !

is not allowed.

The same coefficient does not usually occur on both sides of a formula. If the same coefficient does occur on both sides, then there must be NO overlap between its components or parts on each side. For example,

FORMULA (all,i,COM)
 SH1(i,"domestic") = 1.0 - SH1(i,"imported") ;  !correct!

is allowed, but

FORMULA (all,i,COM) 
 SH2("cars",i) = 1.0 - SH2(i,"shops")*A6 ;     !incorrect!

is not allowed because the component SH2("cars","shops") of SH2 occurs on both sides.

Exception: you may put exactly the same expression on both LHS and RHS, as in:

FORMULA (all,i,COM) x(i) = x(i) + y(i) ;    !correct!

11.4.11    Index-expression conditions [gpd2.4.4.10]

An index expression is an expression built up from indices and set MAPPINGs (see section 11.2.4). For example, COMTOAGGCOM(c) is an index expression.

11.4.11.1    Comparing indices [gpd2.4.4.10.1]

Conditions for SUMs and IFs can involve comparisons of indices and index expressions. You can also use index comparisons for conditions in ALLs in the cases where conditions on ALLs are allowed (see section 11.3). You can test if an index is equal to EQ or not equal to NE another index, as in the formula:

FORMULA (all,c,COM)(all,i,COM)   X(c,i) = IF( c EQ i , Y(i)) ;

The expression c EQ i is a comparison of two indices. The IF condition c EQ i is true if the element names of the set elements c and i are the same.
This would set X(i,i) = Y(i) and X(c,i) = 0 when c is not equal to i. Similarly,

FORMULA (all,c,COM) Y(c) = SUM(i,COM : i NE c , X(c,i) ) ;

will, for each c in COM, sum all X(c,i) except for X(c,c).

11.4.11.2    Index expression comparison [gpd2.4.4.10.2]

Conditions of the form

<index-expression-1> <comparison-operator> <index-expression-2>

are allowed when <comparison-operator> is EQ (equals) or NE (not equal to).

The expression "COMTOAGGCOM(c) EQ aggc" in the formula

AGGDHOUS(aggc) = SUM(c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c) ) ;

is an index-expression comparison.

In the general form of the condition above, the set in which <index-expression-1> lies must be either equal to, or else a SUBSET of, the set in which <index-expression-2> lies, or vice versa. [An index by itself lies in the set over which it ranges. When a set MAPPING from <set1> to <set2> is applied to an index ranging over <set1> or a subset of <set1>, the resulting expression is in the set <set2>. See section 11.9.6 for details.]

For example you cannot compare c with i when c belongs to the set of commodities COM and i belongs to the set of industries IND. But using the mapping PRODUCER defined:

MAPPING PRODUCER from COM to IND ;

you can compare the mapping of c, PRODUCER(c), with industry i as in "PRODUCER(c) EQ i" since PRODUCER(c) ranges over the set of industries IND.

When indices are ranging over intertemporal sets, index offsets can be used. For example,

MAP1(t+2)-3

is legal if index "t" is ranging over intertemporal set S1 and MAP1 is a MAPPING from S1 to an intertemporal set S2.

Again if indices range over intertemporal sets, <comparison-operator> can be replaced by any of:

LEor<=(less than or equal to)
LTor<(less than)
GEor>=(greater than or equal to)
GTor>(greater than)
EQor=(equal to)
NEor<>(not equal to).

This is because the elements of an intertemporal set are ordered. Consider for example,

SET alltime (p[0] - p[10]) ;

Here p[1] LT p[3] etc.

As an example, if TIME is an intertemporal set, you could write:

Formula (all,t,TIME) CUM(t) = Sum{u,TIME:u <=t, FLOW(u)};

To achieve a similar effect by comparing elements of non-intertemporal sets, you could use the $POS function described in section 11.5.6. For example, if SEC is a non-intertemporal set, then:

Formula (all,i,SEC)(all,j,SEC) LOW(i,j) = if( $POS(i)>=$POS(j), X(i,j) );

sets LOW cells on or below the diagonal to X(i,j), while setting cells above the diagonal to zero.

11.5    Functions [gpd2.4.4.4]

Certain functions can be used in expressions. Those recognised at present are

Table 11.3 Functions
FunctionDescriptionSee
ABS(x)the absolute value of x51.12
MAX(x1,x2,..)maximum value — can take 2 or more arguments51.9
MIN(x1,x2,..)minimum value — can take 2 or more arguments51.10
SQRT(X)square root of x
EXP(x)e raised to the power x where e=base of natural logarithms
LOGE(x)log to the base e of x (natural log)
LOG10(x)log to the base 10 of x
ID01(x)x if x is not equal to 0, or is 1 if x=011.5.1
ID0V(x,v)x if x is not equal to 0, or is v if x=011.5.1
RANDOM(a,b)random number between a and b11.5.2
NORMAL(x)normal distribution with mean 0 and standard deviation 111.5.4
CUMNORMAL(x)probability that a normally distributed variable is ≤ x11.5.4
LOGNORMAL(x)log-normal distribution function11.5.5
CUMLOGNORMALcumulative log-normal distribution function11.5.5
GPERF(x)Error Function erf(x)11.5.5
GPERFC(x)Complementary Error Function erfc(x)11.5.5
$POS(i)position of i in set over which i is ranging11.5.6
$POS(i,S)position of i in set S11.5.6
$POS("food",S)position of "food" in set S11.5.6
ROUND(x)nearest integer to real number x11.5.7
TRUNC0(x)truncates the real number x to the nearest integer towards 011.5.7
TRUNCB(x)truncates the real number x to the nearest integer ≤ x11.5.7
RAS_MATRIXSpecial function for carrying out RAS of data11.15

Below we give details about some of these.

The names of all these functions are reserved words — see section 11.2.

Function arguments must be surrounded by pairs of brackets (), [] or {} as in, for example, ABS[X], MIN{X1,X2+1}.

The arguments of these functions can be expressions involving COEFFICIENTs, levels VARIABLEs and/or real numbers, but cannot include linear VARIABLEs. For example, SQRT(C1+5) is accepted if C1 is a COEFFICIENT or levels VARIABLE but not if it is a linear VARIABLE.

Only a limited list of functions can be used in levels EQUATIONs, namely

SQRT, EXP, LOGE, LOG10.

However you can accurately model functions MAX, MIN and ABS using a Complementarity — see section 51.9 for details.

Real or Integer result ?

Consequently only some functions can be used in a Formula which has an integer Coefficient on the left-hand side, namely $POS, ROUND, TRUNC0, TRUNCB (and sometimes ABS, MAX or MIN).

See section 63.1.2 for more details of real and integer arithmetic.

11.5.1    ID01 and ID0V functions [gpd2.4.4.4.1]

ID01 stands for "IDentity function except that 0 (zero) maps to 1 (one)".
ID0V stands for "IDentity function except that 0 maps to a specified Value".
They are defined:

if x=0ID01(x)=1otherwiseID01(x)=x
if x=0ID0V(x,v)=votherwiseID0V(x,v)=x

Note that there is a zero '0' in these names, not a letter 'o'.

These functions ID01 and ID0V can be used to guard against division by zero in equations or formulas. For example, consider the formulas:

(all,i,IND) V1LAB_O(i) = SUM{o,OCC,V1LAB(i,o)};
(all,i,IND)(all,o,OCC) OCCSHR(i,o) = V1LAB(i,o)/ID01[V1LAB_O(i)];

Here the ID01 in the second formula guards against the possibility that, for some industry i, V1LAB(i,o) is zero for all occupations and hence V1LAB_O(i) is zero.

Again, consider the ORANI-G equation:

(all,i,IND)  V1LAB_O(i)*p1lab_o(i) = sum{o,OCC, V1LAB(i,o)*p1lab(i,o)};

If, for some industry i, all V1LAB(i,o) [and hence V1LAB_O(i)] were zero, the equation would have all zero coefficients — giving rise to a "structurally singular matrix" solution error. Instead we should write:

(all,i,IND)  ID01[V1LAB_O(i)]*p1lab_o(i) = sum{o,OCC, V1LAB(i,o)*p1lab(i,o)};

ID01 converts the coefficient on the left-hand side to 1, so that the equation can be used to solve for p1lab_o(i) (which is then equal to zero for this industry i). ID01 can replace the use of "TINY" coefficients often seen in older code, eg:

(all,i,IND)  [TINY + V1LAB_O(i)]*p1lab_o(i) = sum{o,OCC, V1LAB(i,o)*p1lab(i,o)};

An advantage of using ID01 rather than TINY is that ID01 only changes the coefficient on the left-hand side when it would otherwise be zero, whereas the use of TINY changes the value of that coefficient in every case (though only by a very small amount).

ID01 and ID0V functions can mostly replace the facilities offered by the ZERODIVIDE statement described in section 10.11. However, ZERODIVIDE affects only Formulas; ID01 and ID0V can be used both in Formulas and Equations.

11.5.2    RANDOM function [gpd2.4.4.4.2]

The function RANDOM can be used to generate random numbers in a specified range. Successive calls to RANDOM(a,b) with the same values of a and b produce numbers which are uniformly distributed between a and b. RANDOM(a,b) is allowed whether a <= b or a > b.

Each time you run the program, you may wish to get a new sequence of such random numbers, or you may wish to get the same sequence each time. If you wish to get the same sequence each time, you should put the statement

 randomize = no ;

in your Command file. The default is to randomize each time, which corresponds to the statement "randomize = yes ;".6

Avoid creating data-dependent sets whose membership depends, directly or indirectly, on numbers generated via the RANDOM function (details).

11.5.3    Statistical functions [statistical]

To assist you with statistical tasks, GEMPACK provides several functions, described below, related to the normal probability distribution. The following table shows some values of these functions:

x-3-2-1-0.500.0010.5123
GPERF(x)-1.00-0.99-0.84-0.5200.0010.520.840.991.00
GPERFC(x)2.001.991.841.5210.9990.480.160.000.00
LOGNORMAL(x)N.A.N.A.N.A.N.A.N.A.0.0000.6270.3990.160.07
CUMLOGNORMAL(x)N.A.N.A.N.A.N.A.N.A.0.0000.2440.5000.760.86
NORMAL(x)0.000.050.240.350.400.400.350.240.050.00
CUMNORMAL(x)0.000.020.160.310.50.5000.690.840.980.99

11.5.4    NORMAL and CUMNORMAL functions [gpd2.4.4.4.3]

The functions NORMAL and CUMNORMAL describe the normal probability distribution7.

The NORMAL function defines the standard normal (bell-shaped) curve with mean 0 and standard deviation 1. Its formula is:

NORMAL(x) = [1.0/SQRT(2*π)]*EXP(-X*X/2)

where π is (approximately) 3.141592.

CUMNORMAL(X) is equal to the integral of the above normal curve from negative infinity to X (that is, to the area of the left tail from negative infinity up to X). CUMNORMAL(X) values range from 0 (when X is negative infinity) through 0.5 (when X=0) up to 1 (when X is plus infinity)8.

Suppose that you are considering a variable T which is normally distributed with mean 3 and with standard deviation 0.5. You can use the CUMNORMAL function to find the probability that T lies between two specified values. For example, suppose you wish to calculate the probability that T lies between 3.6 and 4.0. This is between 1.2 and 2.0 standard deviations away from the mean, so that the probability is

CUMNORMAL(2.0) - CUMNORMAL(1.2) = 0.97725 - 0.88493 = 0.09232.

11.5.5    Functions for log-normal distribution [gpd9.7.9]

A random variable X is said to have a log-normal distribution if its logarithm LOG(X) is normally distributed. See, for example, http://en.wikipedia.org/wiki/Log-normal for information about the log-normal distribution9.

The GEMPACK functions are

LOGNORMAL(X) is the probability density function for a positive variable X for which the natural logarithm LN(X) [that is, LOGE(X) in TABLO notation — see section 11.5] is normally distributed with mean 0 and standard deviation 1. Note that

LOGNORMAL(x) = [1.0/(x*SQRT(2*π))]*EXP(-LN(x)*LN(x)/2)

where π is (approximately) 3.141592. Note also that LOGNORMAL(X) is only valid for values of X > 0.

CUMLOGNORMAL(X) is the cumulative distribution function for a positive variable X for which the natural logarithm LN(X) is normally distributed with mean 0 and standard deviation 1. That is, CUMLOGNORMAL(X) is the probability that such a log-normally distributed variable is less than or equal to X (X>0). Note also that CUMLOGNORMAL(X) is only valid for values of X > 0.

GPERF(X) is the value of the so-called Error Function [usually denoted by ERF(X)]:

[2/SQRT(π)] ∫0X EXP(-T*T) dT

where SQRT denotes square root. Note that GPERF(X) is valid for any X and that

GPERF(-X) = -GPERF(X).

GPERFC(X) is the value of the so-called Complementary Error Function [usually denoted by ERFC(X)]:

[2/SQRT(π)] ∫X EXP(-T*T) dT

where SQRT denotes square root. Note also that for any X ,10

GPERFC(X) = 1 - GPERF(X)

The Error Functions ERF and ERFC are useful for calculating values of the cumulative log-normal and cumulative normal functions — see, for example, the Wikipedia reference above, or section 6.2 of Press et al. (1986). In particular,

CUMLOGNORMAL(X) = 0.5*[1 + GPERF(LN(X)/√2)]

and,

CUMNORMAL(X) = 0.5*[1+ GPERF(X/√2)]

11.5.6    $POS function [gpd2.4.4.4.4]

The function $POS is used to determine the position number in a set from the index or element name. It can be used in the following three ways:

1: $POS(<index>) indicates the position number of <index> in the set over which this index is ranging.

For example, suppose that COM is the set (c1-c5). The formula

 FORMULA (all,c,COM) X(c) = $POS(c) ;

puts X("c1") equal to 1, X("c2") = 2, X("c3") = 3, X("c4") = 4 and X("c5") = 5.

2: $POS(<index>,<set2>) indicates the position of <index> in the set <set2>. In this case, <index> must be ranging over a set which is a subset of <set2>.

For example, consider COM as above and suppose that MAR is the set (c3,c4) and that MARCOM has been declared as a subset of COM. The formula

  FORMULA (all,m,MAR) X(m) = $POS(m,COM) ;

puts X("c3") equal to 3 and X("c4") = 4 (their position numbers in COM). But the formula

 FORMULA (all,m,MAR) X(m) = $POS(m) ;

puts X("c3") equal to 1 and X("c4") = 2 (their position numbers in MAR).

$POS(<element>,<set>) is also allowed. This gives the position number of the element <element> in the set <set>. So, with the sets above, $POS("c3",MAR) = 1 and $POS("c3",COM) = 3.

In fact the first argument of $POS can be an index expression (see section 11.9.5). For example, $POS(COMTOAGGCOM(c)) and $POS(COMTOAGGCOM(c),AGGCOM) are legal if index "c" is ranging over set COM (or over a subset of it) and COMTOAGGCOM is a mapping from the set COM to some other set.

The $POS function returns an INTEGER value, so it can be used in formulas whose LHS coefficient is an integer coefficient (see section 11.6.3).

The example below shows how we can make a new set, COM, by inserting a new element, "PipeLine" into an existing set COM0. The new element is inserted just after the existing "RailTransprt" element.

Set
PART1 = (all,c,COM0:$pos(c)<=$pos("RailTransprt",COM0));
PART2 = COM0 - PART1;
COM = PART1 + "PipeLine" + PART2; 

11.5.7    ROUND, TRUNC0 and TRUNCB functions [gpd2.4.4.4.5]

ROUND(x) is the nearest integer to the real number x, eg:

ROUND(3.1)=3ROUND(3.6)=4ROUND(-3.1)=-3ROUND(-3.6)=-4

TRUNC0(x) truncates the real number x to the nearest integer towards 0, eg:

TRUNC0(3.1)=3TRUNC0(3.0)=3TRUNC0(3.6)=3TRUNC0(-3.1)=-3TRUNC0(-3.6)=-3

TRUNCB(x) truncates the real number x to the nearest integer which is below (that is, less than or equal to) x, eg:

TRUNCB(3.1)=3TRUNCB(3.0)=3TRUNCB(3.6)=3TRUNCB(-3.1)=-4TRUNCB(-3.6)=-4

The ROUND, TRUNC0 and TRUNCB functions return INTEGER values, so they can be used in formulas whose LHS coefficient is an integer coefficient (see section 11.6.3).

11.6    Coefficients and levels variables [gpd2.4.5]

11.6.1    Coefficients — what are they ? [gpd2.4.5.1]

In the linear equation 3x + 4y = 7, the 3 and the 4 are usually called the coefficients. This explains why the name COEFFICIENT is used in GEMPACK. In a linear EQUATION in a TABLO Input file, a typical term is of the form C*x where C is a COEFFICIENT and x is a linear VARIABLE.

However, COEFFICIENTs can occur and be used in other ways in TABLO Input files, as we now describe.

In a model (that is, a TABLO Input file containing EQUATIONs), COEFFICIENTs can be used to hold base data or consequences of the base data (for example, totals or shares). They can also be used to hold the values of model parameters (such as elasticities).

For example, in the linearized TABLO Input file SJLN.TAB for Stylized Johansen shown in section 4.4.1, DVHOUS holds base data, DVCOM and BHOUS hold consequences of the base data and ALPHACOM holds the values of model parameters. Of these, BHOUS and ALPHACOM appear as coefficients in the linear EQUATIONs Price_formation and Com_clear respectively.11

In a data-manipulation TABLO Input file (that is, a TABLO Input file containing no EQUATIONs), COEFFICIENTs can be used to hold base data or consequences of the base data.

For example, in the data-manipulation TABLO Input file SJCHK.TAB usually distributed with GEMPACK (see section 6.3.1), DVHOUS holds base data, and DVCOM and DVCOSTS hold consequences of the base data.

In a model, COEFFICIENTs which are not parameters might represent the current value of levels variables. For example, in Stylized Johansen:

11.6.2    Model parameters [gpd2.4.5.2]

In GEMPACK, a parameter of a model is a COEFFICIENT whose values do not change between the steps of a multi-step calculation (for example, elasticities). Such COEFFICIENTs can (and often should) be declared as COEFFICIENT(PARAMETER)s.

Non-parameter coefficients are used to carry the current values of levels variables. Their values can change between the steps of a multi-step calculation. [See section 11.6.1.]

11.6.3    Integer coefficients in expressions and elsewhere [gpd2.4.5.3]

Integer coefficients can be used in formulas and equations much like real coefficients. When used in an equation, or in a formula whose left-hand side (LHS) is a real coefficient, integer coefficients are treated exactly like real ones.

In formulas whose LHS coefficient is an integer coefficient, the following restrictions hold.

[Inside the condition part of a SUM, PROD, MAXS, MINS or IF (see sections 11.4.5 and 11.4.6), arithmetic is done as if all coefficients were real coefficients.]

Only a limited list of functions can be used in a Formula which has an integer Coefficient on the left-hand side, namely

$POS, ROUND, TRUNC0, TRUNCB (and sometimes ABS, MAX or MIN).

Integer coefficients may be involved in the equations of a model. If so, these coefficients cannot change their values between the steps of a multi-step simulation,12 and so must be parameters of the model. Hence

To make it easy for you to satisfy (1) of the previous point,

On occasions, it may be useful to have integer coefficients which are not parameters but which can change their values between steps of a multi-step calculation. (You can perhaps use such coefficients to report information such as the number of entries in an array which exceed some specified value at each step.)

Such coefficients cannot occur in an equation (as explained above) but can be written to the terminal (ie, log file) at each step if you put the statement "DWS = yes ;" in your Command file (see section 25.1.10) when you run GEMSIM or the TABLO-generated program.

To overcome the defaults set, as described above, you will need to include an explicit NON_PARAMETER qualifier when you declare such a coefficient, and will need to include an explicit ALWAYS qualifier with any FORMULA having such a coefficient on the left-hand side.

Integer coefficients used in setting sizes of sets must be parameters (see sections 10.1 and 11.7.1).

Integer coefficients used in specifying the elements of an intertemporal set must be parameters (see section 10.1).

If coefficients with integer values occur as exponents in an expression, there may be some advantage in declaring them as COEFFICIENT(INTEGER)s, for the reason explained in section 16.3 below.

Using integer coefficients in formulas can be quite useful in setting ZERODIVIDE defaults. For example consider any set IND. After the statements

Coefficient NO_IND # Number elements in the set IND # ;
Formula  NO_IND = SUM(j,IND, 1) ;

the Coefficient NO_IND is equal to the number of elements in the set IND (see section 17.1). Hence the following sets a ZERODIVIDE default which adjusts sensibly for any set IND:

Coefficient RECIP_NIND ;
Formula RECIP_NIND = 1/NO_IND ;
Zerodivide Default RECIP_NIND ;
Coefficient (all,i,IND) SHAREY(i) # Share of Y(i) in total of all Y(j) # ;
Formula (all,i,IND) SHAREY(i) = Y(i)/SUM(j,IND,Y(j)) ;
Zerodivide Off ;

(If all the Y(j) are zero then each SHAREY(i) will be set equal to RECIP_NIND. For example, if NO_IND=10 and all Y(j) are zero then SHAREY(i) will be equal to 0.1 for all i in IND, so that these values add to 1 as expected since they are shares.)

Note that the functions to round or truncate real numbers (ROUND, TRUNC0 and TRUNCB) return INTEGER values. In particular, they can be used in formulas whose LHS coefficient is an integer coefficient (see section 11.5).

11.6.4    Where coefficients and levels variables can occur [gpd2.4.5.4]

Some details of the syntax of levels variables and levels equations have been given in the preceding sections.

In the following section, a brief summary is given of different ways of representing levels quantities in the model using real COEFFICIENTs and VARIABLE(LEVELS).

In a linearized representation of a model, a COEFFICIENT represents the current value of a levels variable. This is why, as explained in section 9.2.2 above, every VARIABLE(LEVELS) statement gives rise to a COEFFICIENT with the same name in the associated linearized TABLO Input file automatically produced by TABLO. (The associated linear variable has a different name, often one with "p_" or "c_" added, see section 9.2.2.) Thus there are three types of COEFFICIENTs.

All three types can be initialised at the first step of a multi-step calculation by reading from a file via a READ statement or by a formula given in a FORMULA(INITIAL) statement. COEFFICIENT(NON_PARAMETER)s of type (1) above can also be initialised at the first step (and every subsequent step) via a FORMULA(ALWAYS).

At subsequent steps,

After the final step, the data files are updated to reflect the final values of any COEFFICIENTs or levels variables whose values were read initially, but final values of COEFFICIENTs or levels variables initialised via a FORMULA(INITIAL) are not usually shown on these updated data files. [However, values initialised via a FORMULA(INITIAL) will be shown on the relevant updated data file if the qualifier "WRITE UPDATED VALUE TO ... " is included in the FORMULA statement — see section 10.8.]

All three types of coefficients can be used in conditions (that is, the condition of a SUM, PROD, MAXS, MINS, IF or ALL — see sections 11.4.5 and 11.4.6) in situations where these are allowed.

The following table summarises which quantities can occur in which types of statements, and also which ones are illegal.

Table 11.4 Statement types in which variables and coefficients are legal
StatementPermittedIllegal
EQUATION(LINEAR)Linear variables
Coefficients
Levels variables
Constants
Operators
 
Non-parameter int coeff.
EQUATION(LEVELS)Levels variables
Parameter coeff.
Constants
Operators
Linear variables
Non_parameter coeff.
FORMULA(ALWAYS)
Left-hand side
Non_parameter coeff.Levels variables
Parameter coeff.
Linear variables
FORMULA(ALWAYS)
Right-hand side
Coefficients
Levels variables
Constants
Operators
 
Linear variables
FORMULA(INITIAL)
Left-hand side
Coefficients
Levels variables
 
Linear variables
FORMULA(INITIAL)
Right-hand side
Coefficients
Levels variables
Constants
Operators
Linear variables
UPDATE(PRODUCT)or(CHANGE)
Left-hand side
Non_parameter coeff.Parameter coeff.
Levels variables
Linear variables
Integer coeff.
 
UPDATE(PRODUCT)
Right-hand side
Linear variables
Operator '*' for
multiplication
Coefficients
Levels variables
Constants
Other operators
UPDATE(CHANGE)
Right-hand side
Coefficients
Linear variables
Levels variables
Constants
Operators
 
SUM etc conditions in
FORMULAs, EQUATIONs
ALL conditions
for FORMULAs
Coefficients
Levels variables
Constants
Comparison operators
 
Linear variables
SUM etc ALL conditions
for UPDATE(CHANGE)
as above plus
Linear variables

11.6.5    Reporting levels values when carrying out simulations [gpd2.4.5.5]

It is possible to ask GEMSIM or a TABLO-generated program to calculate and report pre-simulation and post-simulation levels values as well as the usual percentage change results, even if your TABLO Input file has only linear variables and linearized equations. To do this, you may need to add appropriate information in your TABLO Input file to tell TABLO what are the pre-simulation levels values of selected linear variables.

For example, in the linearized TABLO Input file SJLN.TAB for the Stylized Johansen model (see section 4.4.1), we have included the qualifier "(ORIG_LEVEL=DVCOM)" when declaring the variable p_XCOM, as in

Variable (ORIG_LEVEL=DVCOM)  (All,i,SECT)  p_XCOM(i) ;

[Here DVCOM(i) is a dollar value for each commodity i. But its original (that is, pre-simulation) value can be thought of as a quantity, where one unit of volume is whatever amount can be purchased for one dollar at pre-simulation prices.]

Also we have included the qualifier (ORIG_LEVEL=1) when declaring the variable p_PCOM, as in

Variable  (ORIG_LEVEL=1)  (All,i,SECT)  p_PCOM(i) ;

to indicate that the original levels value of the commodity prices are being taken as 1.

When you run a simulation, GEMSIM or the TABLO-generated program will report the pre- simulation, post-simulation levels values of XCOM and PCOM, also the change in them, as well as the percentage change p_XCOM in XCOM and p_PCOM in PCOM, for each commodity.

The syntax for these variable qualifiers is

(ORIG_LEVEL=<coefficient-name>)

or

(ORIG_LEVEL=<real-number>)

Qualifiers "ORIG_LEVEL=" are only needed when you define linear variables (percentage changes or changes).

In a levels or mixed model, you do not need such qualifiers when declaring levels variables (since the correspondence is clear). [When you declare a levels variable X, TABLO does not need to be told that the pre-simulation values of the associated linear variable p_X or c_X are given by the coefficient X.] Thus, for example, no ORIG_LEVEL statements are needed in the mixed TABLO Input file SJ.TAB for Stylized Johansen (see section 4.3.3) in order to get levels values reported when you carry out a simulation.

Note that no indices need to be shown (nor will TABLO allow them to be shown) in a "ORIG_LEVEL=" qualifier. Simply specify the name of the coefficient. TABLO automatically checks that the coefficient and variable have the same numbers of indices and that these indices range over exactly the same sets; a semantic error will be reported otherwise. The coefficient referred to in a qualifier

(ORIG_LEVEL=<coefficient-name>)

must be a real coefficient (not an integer one).

To make it easier to add "ORIG_LEVEL=" qualifiers to existing TABLO Input files, we have made an exception to the usual rule that everything must be defined before it is referenced. In the qualifier

(ORIG_LEVEL=<coefficient-name>)

the Coefficient in <coefficient-name> is allowed to be declared later in the TABLO Input file. For example, in SJLN.TAB (see section 4.4.1), it is correct to include the qualifier "(ORIG_LEVEL=DVHOUS)" in the declaration of variable p_XCOM even though coefficient DVHOUS is not declared until several lines later.

Note that the values of <coefficient-name> must, of course, be available (via a Read or Formula). The values needed are just the pre-simulation values — the values are not needed (for this purpose, at least) at subsequent steps. Thus, if you are adding Formulas just to give the values in question (and not also for other purposes), you can make them Formula(Initial)s. For example, in SJLN.TAB it is natural to include the qualifier (ORIG_LEVEL=Y) in the declaration of linear variable p_Y. Coefficient Y (value of household expenditure) was not available in the Release 5.2 version of SJLN.TAB. In the Release 6.0 version we added it via

Coefficient  Y  # Total nominal household expenditure # ;
Formula (Initial)  Y = SUM(i, SECT, DVHOUS(i) ) ;

[Had we not done so, we could not have included the (ORIG_LEVEL=Y) qualifier when declaring variable p_Y.]

11.6.6    How do you see the pre-simulation and post-simulation levels values? [gpd2.4.5.6]

If you don't want to include these levels results on a Solution file, you can add the statement

levels results = no ;

to your Command file.

Note that levels values are not necessarily available for all variables. [In a linearized TABLO Input file, they are only available for those variables for which you add an "ORIG_LEVEL=" qualifier when you declare the variable.]

ViewSOL can also show any levels results available on the Solution file. These are shown as 4 separate solutions in 4 columns. Suppose the main solution file was called MySim. Then

Note that you can suppress levels results via the Options menu item under the File menu of ViewSOL.

SLTOHT processes levels results (if present) if you specify the SLTOHT option SHL - Show levels results, if available. The default is not to show levels results so that the new SLTOHT is still compatible with old Stored-input files or batch programs written for Release 5.2. See chapters 39 and 40 for more details about SLTOHT.

If you run GEMPIE (see chapter 79) and select the totals solution, you will see the levels values reported unless you select GEMPIE option "NLV" (No levels values) . Then, for each component of each variable whose pre-simulation levels values are known (e.g., via an ORIG_VALUE= qualifier), you will see 4 numbers underneath each other, as in, for example,

3.000(the percent change)
500.0(the pre-simulation levels value)
515.0(the post-simulation levels value)
15.0(the change from pre-simulation to post-simulation)

The linearized result (percentage-change or change) is always first, then below it are the pre-simulation, post-simulation and change results.

Levels results are not shown if you select GEMPIE option SNA (Single solution not across the page) since levels results are only shown when the results go across the page.

11.6.7    Specifying acceptable range of coefficients read or updated [gpd2.4.5.7]

Qualifiers such as (GE 0) can be used to specify acceptable ranges of values for coefficients and levels variables (see sections 10.3, 10.4 and 10.19.1). These can be used to report errors if a simulation takes the values out of the acceptable range. They can also be used in conjunction with user-specified accuracy (26.4). See section 25.4 for details.

11.7    Sets [gpd2.4.6]

11.7.1    Set size and set elements [gpd2.4.6.1]

The size of a set, and its elements, can be specified in the TABLO Input file, or may be determined at run time. For example, the set

SET  COM  (c1-c10) ;

has fixed size 10 (that is, the size is specified in the TABLO Input file) whereas the set

SET COM  Read Elements from File Setinfo Header "COM" ;

has its size determined at run time. In the first of these examples, the element names are fixed in the TABLO Input file whereas in the second example, the element names are defined at run time (when the Setinfo file is read).13

In a multi-step calculation, the size and elements of each set are determined during the first step, and do not vary in subsequent steps.

Sets may have named elements. If so, these element names may be fixed or only defined at run time.

If element names are read at run time as in, for example,

SET COM Read Elements from File Setinfo Header "COM" ;

[see set declaration numbered (2) in section 10.1], the data at the relevant position of the relevant file must be strings of length no more than 12. [Shorter lengths are ok.] This is because element names are limited to at most 12 characters (see section 11.2.1). See section 11.7.10 for more details about reading element names from a Header Array file.

For example, if you are preparing a header to contain the names of the 20 commodities in your model, the data at the relevant header should be 20 strings of length 12 (or it could be 20 strings of length 8 if all element names were this short).

The elements of intertemporal sets defined using style (5) in section 10.1 are based on the intertemporal element stem. For example, if the set fwdtime is defined via

SET (INTERTEMPORAL) fwdtime MAXIMUM SIZE 100 (p[0] - p[NINTERVAL-1]) ;

and if coefficient NINTERVAL has the value 6 at run time, then the elements of fwdtime are
p[0], p[1], p[2], p[3], p[4] and p[5].

As indicated earlier, we say that the intertemporal set fwdtime has intertemporal elements. See section 16.2.1 for more details about intertemporal sets and elements.

Sets defined as Unions, Intersections (see section 11.7.3), Complements (see section 11.7.4) or depending on data (see section 11.7.6) may have fixed elements or run-time elements. For details, see the relevant sections below.

11.7.2    Obsolete "maximum size" in SET statements [gpd2.4.6.2]

In older TABLO code, you may see statements like

Set REG # Regions # Maximum size 10 Read elements from file GTAPSETS Header "H1";

TABLO will ignore the "Maximum size 10".14 The modern style is simply

Set REG # Regions # Read elements from file GTAPSETS Header "H1";

11.7.3    Set unions, intersections and equality [gpd2.4.6.3]

Unions and intersections of sets are allowed in TABLO Input files (see section 10.1.1). For example, in GTAP (see section 10.1.5), once the sets ENDW_COMM (endowment commodities) and TRAD_COMM (tradeable commodities) are defined, the set DEMD_COMM (demanded commodities) can be defined via the statement

Set DEMD_COMM # Demanded Commodities # = ENDW_COMM + TRAD_COMM ;

As DEMD_COMM is defined above, an error will be raised if ENDW_COMM and TRAD_COMM have any common elements. In the unlikely case that you wished to allow common elements, you would write:

Set DEMD_COMM # Demanded Commodities # = ENDW_COMM union TRAD_COMM ;

The syntax for set union and intersection is

SET <set-name> [#<label-information>#] = <set-name1> + <set-name2>;
SET <set-name> [#<label-information>#] = <set-name1> UNION <set-name2>;
SET <set-name> [#<label-information>#] = <set-name1> INTERSECT <set-name2>;

(see section 10.1.1). Here both <set-name1> and <set-name2> must be previously defined sets whose elements are either fixed or known at run-time (see section 11.7.1).

The elements of the "+" joined set are those in <set-name1> followed by those in <set-name2>.

The elements of the UNION are those in <set-name1> followed by those in <set-name2> which are not in <set-name2>.

The elements of the INTERSECTion are those in <set-name1> which are also in <set-name2>.

For example, if
SET1 has elements (e1, e2, e3, e4) and
SET2 has elements (e2, e6, e1), and if

SET3 = SET1 UNION SET2 ;
SET4 = SET1 INTERSECT SET2 ;
SET5 = SET2 UNION SET1 ;

then
SET3 has elements (e1, e2, e3, e4, e6),
SET4 has elements (e1, e2), and
SET5 has elements (e2, e6, e1, e3, e4).

Note that, although the elements of SET3 and SET5 are the same, their order is different. The order is, of course, important in associating data with indices (see section 11.11.1).

Note also that, with SET1 and SET2 as above, the elements of

SET1 INTERSECT SET2

and

SET2 INTERSECT SET1

are in a different order.

Thus, as far as TABLO is concerned, the order of the sets in a UNION or INTERSECT statement can affect the sets so defined.

Intertemporal sets are not allowed in Set Union or Intersection statements.

Unions and intersections can be used in XSET extra statements in Command files (see section 25.6).

As well as defining a new set, a set union or intersect statement automatically generates the obvious SUBSET statements, namely

SUBSET <set-name1> IS SUBSET of <union set-name> ; 
SUBSET <set-name2> IS SUBSET of <union set-name> ; 
SUBSET <intersect set-name> IS SUBSET of <set-name1> ; 
SUBSET <intersect set-name> IS SUBSET of <set-name2> ; 

In a disjoint set union (see section 10.1.1)

SET <set_name> [#<information># ]=<setname1> + <setname2> ;

both <set-name1> and <set-name2> must be previously defined non-intertemporal sets whose elements are either fixed or known at run-time (see section 10.1.1).

In a set equality statement (see section 10.1.2)

SET <set_name> [#<information># ]=<setname1> ;

<set-name1> must be a previously defined non-intertemporal set whose elements are either fixed or known at run-time (see section 11.7.1). A set equality statement automatically generates the obvious two SUBSET statements.

NOTE. Set unions and intersections can be used in longer expressions — see 10.1.1.1 and 11.7.5.

11.7.4    Set complements and relative complements [gpd2.4.6.4]

As indicated in 10.1.1, there are two kinds of set complement allowed. The two operators are "-" and "/". The latter is for relative complement.

The syntax is

SET  <new-setname>  =  <bigset>  -  <smallset>  ;  ! set complement !

or

SET  <new-setname>  =  <bigset>  \  <smallset>  ; ! relative complement !

(see section 10.1.1). Here <bigset> and <smallset> must have already been defined in earlier SET statements. In the first case, <smallset> must have been declared as a SUBSET of <bigset> (but that is not required in the second case). The elements of <bigset> and <smallset> must be either fixed or known at run-time (see section 11.7.1).

These statements mean that the elements of <new-setname> are all the elements in <bigset> which are not in <smallset>.

You can find simple examples in 10.1.1.

As well as defining a new set, each set complement statement automatically generates the obvious SUBSET statement, namely SUBSET <new-setname> IS SUBSET of <bigset> ;

For example, in ORANI-G (see section 10.1.4) COM is the set of all commodities and MAR is the set of all margins commodities, and the statement

SET NONMAR = COM - MAR ;

says that NONMAR consists of all commodities which are not in MAR. That statement also means that NONMAR is a subset of COM.

If both <smallset> and <bigset> have fixed elements (that is, those defined explicitly in the TABLO Input file), then the complement set (or relative complement set) <new-setname> has fixed elements.

For example, with the statements

SET COM (c1,c2,c3,c4,c5) ;
SET MARCOM (c3, c4) ; 
SUBSET MARCOM is subset of COM ; 
SET NONMARCOM = COM - MARCOM ;

the set NONMARCOM has fixed elements c1,c2,c5.

If <bigset> has run-time elements (for example, read from a file), then <new-setname> also inherits the appropriate run-time elements.

If <smallset> and <bigset> have fixed sizes, so does the set complement, but not the relative complement. Otherwise <new-setname> has its size determined at run time.

Intertemporal sets are not allowed in set complement statements. That is, <bigset> and <smallset> are not allowed to be intertemporal sets and the set qualifier (INTERTEMPORAL) is not allowed in a set complement statement.

Set complements and relative complements can be used in XSET extra statements in Command files (see section 25.6).

Set complements and relative complements can be used in longer expressions — see 10.1.1.1 and 11.7.5.

11.7.5    Longer set expressions [gpd2.4.6.4b]

As indicated in 10.1.1.1, you can use longer set expressions involving the set operators UNION, INTERSECT, "+", "-" and "\". You are also allowed to use brackets "(" or ")" to indicate the order of doing these operations. [But other types of brackets "[", "]", "{" and "}" are not allowed in set expressions.]

Some simple examples are given in 10.1.1.1. Below we give more formal rules for such expressions.

Set expressions can involve

In order for "+" to be valid, the two sets whose elements are being "+"ed must be disjoint.

In order for "-" to be valid, every element of the set whose elements are being "-"ed must be in the set doing the "-"ing.

Consider the following examples.

SET NewSet1 = Set1 UNION Set2 + Set3 - Set4 ;
SET NewSet2 = Set5 - (Set6 + Set7) ; 

For the first of these statements to be valid, Set3 must have no elements which are also in (Set1 UNION Set2) and every element in Set4 must be in (Set1 UNION Set2 + Set3).

For the second of these statements to be valid, Set7 must have no elements which are also in Set6 and every element in (Set6 + Set7) must also be in Set5.

Of course if you use brackets, they must make sense. For example

SET NewSet1 = (NewSet2 - NewSet3) + (NewSet5 ;

is not valid since the brackets do not make sense.

In general you can have a set expression on the RHS of a SET statment as in

SET <set_name> [#<information># ] = <set-expression>  ;

Special Rule
As with Release 10 and earlier, if you specify a simple set complement

SET <set_name> = <setname1> - <setname2> ;

then set <setname2> must have been already declared as a SUBSET of <setname1> (in a SUBSET statement).

Subsets Implied by Set Expressions

Consider the statement

SET NewSet1 = Set2 UNION Set3 UNION Set4 ;

Clearly Set2, Set3 and Set4 will all be subsets of NewSet1. TABLO adds these SUBSET statements in this case.

There are several other cases where TABLO adds the "obvious" SUBSET statements.

Rules for Implied Subset Statements

  1. If all operators are UNION and/or + then every RHS set is subset of LHS set. [This is true even if there are some brackets on the RHS.]
  2. If all operators are INTERSECT then LHS set is subset of every RHS set. [This is true even if there are some brackets on the RHS.]
  3. If RHS ends <expression> UNION Set2 then Set2 is subset of LHS set.
  4. If RHS ends <expression> INTERSECT Set2 then LHS is subset of Set2.
  5. Simple complement. If just one "-" or "\" operation between two sets Set1 = Set2 - Set3 [or Set1 = Set2 \ Set3], then Set1 is Subset of Set2.

There may be other cases when you know that your set expression implies a SUBSET relationship.15 But TABLO may not be as clever as you are. So, if in doubt, add the SUBSET statement yourself. If TABLO also figured it out, you will be told that your SUBSET statement is redundant. But if you leave it out and TABLO does not figure it out, you may get an error later in your TAB file. That is why you should include the statement if in doubt.

11.7.6    Sets whose elements depend on data [gpd2.4.6.5]

Sets can be defined in TABLO Input files in ways which depend on data, as in for example,

SET SPCOM = (all,c,COM: TOTX(c) > TOTY(c)/5 ) ;

which says that the set SPCOM consists of all commodities c in COM for which TOTX(c) is greater than one-fifth of TOTY(c). (This set is defined during the first step of a multi-step simulation using initial values of TOTX and TOTY read in or calculated by initial formulas. It will not change at subsequent steps for updated values of TOTX and TOTY).

Other examples are the set TRADEXP in ORANI-G (see section 10.1.4) and the set ENDWS_COMM in GTAP (see section 10.2.2).

The required syntax is

SET  <new-set> = (All, <index> , <old-set>: <condition> );

which says that <new-set> consists of the elements of <old-set> which satisfy the given condition. (see section 10.1.3.)

Such a set definition automatically implies the obvious SUBSET statement (namely that <new-set> is a subset of <old-set>).

If the old set <old-set> has element names defined, then names for the elements of the new set <new-set> are inherited at run time.

Only one quantifier (ALL,<index>,<set>) is allowed. The condition follows the colon ':' in this quantifier. [The condition can contain operators like AND, OR.]

Note that the resulting set can be empty (since empty sets are allowed - see section 11.7.9).

At present, set statements of the kind described in this section which depend on data cannot be included as "extra" statements in Command files (see section 25.6).

The old set here (this is called <old-set> above and is COM in the example at the start of this section) is not allowed to be an intertemporal set. This is because subsets of intertemporal sets cannot have "gaps" in them — see section 11.8.

11.7.6.1    Avoid defining sets depending on random numbers [randsetbug]

Up to and including GEMPACK 11.3.001, a bug affected sets whose membership depended, directly or indirectly, on numbers generated via the RANDOM function. Membership of such sets might change during the course of a simulation. The bug was fixed in GEMPACK 11.3.002.

11.7.7    Writing the elements of one set [gpd2.4.6.6]

An example of a TABLO statement to do this is

Set DEST # Sale Categories # 
    (Interm, Invest, HouseH, Export, GovGE, Stocks, Margins);
Write (Set) DEST to file OUTFILE Header "DST";

(see section 10.7). Here the HEADER part is required if OUTFILE has been previously declared to be a new Header Array file, but is not allowed if OUTFILE is a text file. For Header Array files, the output is written as strings of length 12 (the length of set element names — see section 11.2.1). In the Text file case the output is written using the standard GEMPACK syntax for character strings (see 38).

Following the example above, header DST on the output file would be given the automatically generated description "Set DEST Sale Categories". This form of 'long name' (see section 5.0.4) works well with the set/element labelling capabilities in ViewHAR, and with the 'ds' option in MODHAR (see section 54.4.2). But you can override this useful default behaviour, by writing, for example:

Write (Set) DEST to file OUTFILE Header "DST" Longname "Demanders";

XWrite (set) statements can be added to your Command file as an "extra" statement.

11.7.8    Writing the elements of all (or many) sets [gpd2.4.6.7]

The syntax is

WRITE (ALLSETS) to file <hafile> ;

(see section 10.7). This writes the elements all sets whose elements are specified (either in the TABLO Input file or at run time).

The file in question must be (the logical name of) a Header Array file. No other writes are allowed to this same file (in order for us to be able to ensure relatively easily that the resulting file will not have duplicate headers).

If the elements of a set have been read from a Header Array file, they will be written to the same header (where possible); otherwise the program makes up a header. Do not include a header name in the WRITE(ALLSETS) statement.

The long name (see section 5.0.4) written with the elements of each set is of the form

Set <setname> <labelling information>

as described in the previous subsection.

Note that this statement can be added to your Command file as an "extra" statement. For example, the following statements in a Command file will write out all (or most) sets to the file somesets.har.

xfile (new) manysets ;
file manysets = somesets.har ;
xwrite (allsets) to file manysets ;

11.7.9    Empty sets [gpd2.4.6.8]

TABLO, TABLO-generated programs and GEMSIM allow empty sets.

For example, GTAP contains a set ENDWS_COMM of sluggish endowment commodities which is a subset of the set of all the endowment commodities (see section 10.2.2). It may be convenient to have no endowment commodities sluggish for some simulations, which means that the set of sluggish endowment commodities is empty.

In particular, empty sets can be used in SUBSET and Set Complement, Set Union and Set Intersection statements.

You can define an empty set in various ways.

1. The simplest is to use the "listing elements" style [see (1) in section 10.1], indicating no elements between the brackets as in, for example,

SET  EMPTY1   # Empty set #   ( ) ;

2. Alternatively you can read the elements from a file. If there are zero strings at this header in the file, the resulting set will be empty. For example,

SET EMPTY2  Read Elements from File Setinfo  Header  "EMP2" ;

3. You could also use a set complement:

SET EMPTY3 = IND - IND ;

4. You could use a condition (provided COEF1 has been defined and assigned values all less than 5000):

SET EMPTY4 = (All, i, IND : COEF1(i) > 5000) ;

11.7.10    Reading set elements from a file [gpd2.4.6.9]

Element names can be read in at run time when GEMSIM or a TABLO-generated program runs.

The file from which they are read must be a Header Array file.

The type of TABLO statement used is given in set declaration numbered (2) in section 10.1. For example,

 SET COM  Read Elements from File Setinfo Header "COM" ;

The data at the relevant position of the relevant file must be strings of length no more than 12. [Shorter lengths are ok.] This is because element names are limited to at most 12 characters (see section 11.2.1).

For example, if you are preparing header "COM" to contain the names of the 20 commodities in your model, the data at the relevant header should be 20 strings of length 12 (or it could be 20 strings of length 8 if all element names were this short).

11.7.10.1    TABLO style of set element names [gpd2.4.6.9.1]

In TABLO Input files, set element names follow the rule given in section 11.2.1, so that

We refer to this style of element names as TABLO style.

11.7.10.2    Flexible style of set element names [gpd2.4.6.9.2]

When you are reading element names from a Header Array file, you can also use Flexible style for element names. In flexible style the restrictions are relaxed to be

There is a statement for Command files in GEMSIM or TABLO-generated programs:

set elements read style = TABLO | flexible ;

where TABLO is the default. In order to use this flexible style of set element names you must include in your Command file the statement

set elements read style = flexible ;

We have included the flexible style of set element names for backwards compatibly with Release 6.0 of GEMPACK. However we encourage you to use the stricter form of TABLO style in new models.

11.7.11    Creating element names for set products [gpd2.4.6.10]

As indicated in section 10.1.6, set products are allowed via a statement of the form

SET  <set1> = <set2> X <set3> ;

Ideally, the elements of set1 are of the form xx_yyy where xx ranges over all elements of set2 and yyy ranges over all elements of set3. [Essentially set1 consists of ordered all pairs (xx,yyy).] However, since element names are limited to 12 characters, some compromise must be made if the names from the constituent sets are too long.

Assuming:

SET COM (Food, Agric, Serv) ;
SET SOURCE (dom, imp) ; ! domestic or imports !
SET COM2 (Food, Agriculture, Services) ;
SET S4 = COM x SOURCE ;
SET S5 = COM2 x SOURCE ;

The elements of S4 are

Food_dom, Agric_dom, Serv_dom, Food_imp, Agric_imp, Serv_imp

Here the combined names have no more than 12 characters.

A compromise is required in the case of the elements of set S5 since "Agriculture" has 11 characters. The elements of S5 are

C1Food_dom, C2Agric_dom, C3Servi_dom, C1Food_imp, C2Agric_imp, C3Servi_imp .

Because at least one name (Agriculture) in the first set COM2 must be truncated, all truncated names begin with the first letter "C" of this set followed by the element number. Because the longer name in SOURCE has 4 characters, and the joining "_" makes one more, at most 7 characters are allowed for the truncated elements of set COM2. This results in "C2Agric_dom" and "C2Agric_imp".

It may happen (though it is extremely unlikely if the elements of the original sets have sensible names) that the product set ends up with two or more elements with the same name. If so, an error occurs and you should change the names of the elements of the original sets to avoid the problem.

The algorithm for assigning names is as follows. Consider:

SET3 = SET1 x SET2 ;

Work out the maximum lengths MXELT1 and MXELT2 of elements from SET1 and SET2.

1. If MXELT1+MXELT2 <= 11, no truncation is necessary and the elements have the desired names of the form xx_yyy where xx ranges over SET1 and yyy ranges over SET2.

2. Otherwise, if MXELT1 <= 5, do not truncate elements from SET1 but truncate elements from SET2 to at most 11-MXELT1 characters.

3. Ditto if MXELT2 <= 5, do not truncate elements from SET2 but truncate elements from SET1 to at most 11-MXELT2 characters

4. Finally, if not yet resolved, truncate elements from both sets. Use up to 6 characters for elements of SET1 and up to 5 for elements of SET2.

Whenever an element name is truncated, the truncated name begins with the first letter of the set followed by the element number from that set. Then come as many characters from the original element name as there is room for.16

If the two sets have fixed elements (see section 11.7.1), the names of the elements of the product are worked out by TABLO and are available in other TAB file statements. If the elements of either or both of the sets are defined at run time, GEMSIM or the TABLO-generated program works out the names of the elements of the product.

11.8    Subsets [gpd2.4.7]

TABLO checks that indices range over appropriate sets, as described in section 11.2.4 above. SUBSET statements may be necessary for this to be done correctly. Suppose, for example, that you need the formula

(all,i,MARGCOM) X(i) = C1(i) + Y(i) ;

where coefficients X, C1, Y have been declared via

COEFFICIENT  (all,i,COM) C1(i) ;
COEFFICIENT  (all,i,MARGCOM) X(i) ;
             (all,i,MARGCOM) Y(i) ;

in which the sets COM (all commodities) and MARGCOM (the margins commodities) are defined by

SET COM (wool, road, rail, banking) ;
SET MARGCOM (road, rail) ;

In the formula above, i ranges only over MARGCOM but C1 has been defined to have one index which must be in COM. When MARGCOM is declared to be a subset of COM via the SUBSET statement

SUBSET MARGCOM IS SUBSET OF COM ;

TABLO can tell that i in MARGCOM is therefore also in COM. Otherwise TABLO will think that the index i in C1(i) is not in the expected set and an error will result.

The two sets must already have been defined in separate SET statements which assign elements to the sets (either fixed or run time elements — see section 11.7.1).

Not all subset relations need to be declared explicitly. If you have declared set A to be a subset of set B and have declared set B to be a subset of set C, you do not need to declare that set A is a subset of set C. This will be inferred from the other two subset declarations. Subset relations are also inferred from set unions, intersections, complements, equality and data-dependent set statements (see section 11.7 for details).

The two sets in a SUBSET statement must be of the same type — INTERTEMPORAL or NON_INTERTEMPORAL.

For intertemporal sets with fixed elements, the small set cannot have "gaps" in it. For example, the following would cause an error.

SET (INTERTEMPORAL) time0 ( p0 - p10 ) ;
SET (INTERTEMPORAL) time3 ( p0, p2, p4, p6, p8, p10 ) ;
SUBSET time3 IS SUBSET OF time0 ;       !incorrect!

[This is because arguments such as 't+1' must have an unambiguous meaning. In the example above, if 't' were in 'time3' and t equals 'p0', we would not know if 't+1' refers to 'p2' (the next element in 'time3') or to 'p1' (the next element in 'time0').]

11.8.0.1    SUBSET(BY_NUMBERS) statement (very rare) [gpd2.4.7.1]

The default form of SUBSET statement just described is the SUBSET(BY_ELEMENTS). Above, we omitted the qualifier (BY_ELEMENTS) since it is the default. As stated above, (BY_ELEMENTS) requires that set elements are known at or before run time.

However, there are occasionally sets whose elements are unknown (types 3 and 4 in section 10.1). How can we make subsets of those? Enter the SUBSET(BY_NUMBERS) statement. We might have:

Set TOWNS size 1000; 
Set CAPITALS size 8;
Subset(by_numbers) CAPITALS is subset of TOWNS
 read element numbers from file INFILE header "CAPS";

Data read in a SUBSET (BY_NUMBERS) statement must be integer (not real) data. Integer 1 refers to the first set element in the original SET, integer 2 refers to the second and so on. So if the data read in is 1 2 5 the subset contains the 1st, 2nd and 5th elements of the set. At run time, GEMSIM or the TABLO-generated program checks that the number of integers at this header on the data file matches the size of the small set in the SUBSET statement. (If the small set has size 4, exactly 4 integers are expected on the data file at the specified header.) It also checks that all the integers at the specified header are in the right range and are distinct.

11.9    Mappings between sets [gpd2.4.8]

As set out in section 10.13, mappings between sets can be defined via statements following the syntax

MAPPING [(ONTO)] <set-mapping>  FROM  <set1>  TO <set2>  ;

Here <set1> and <set2> must have already been declared as sets. The mapping called <set-mapping> is a function which takes an element of set <set1> as input and produces as output an element of set <set2>. The optional (but strongly recommended) qualifier (ONTO) requests the software to check that every element of set2 is mapped to by at least one element of set1 — see section 11.9.3 for details.

Usually the source set <set1> is bigger (has more elements) than the target set <set2>.17 Each element of the source set <set1> maps to just one of the target set <set2>. In general, several members of <set1> may map to the same element of <set2>. We call this a many-to-one mapping.

Many GEMPACK users find mappings confusing, partly because they think of mappings in the wrong way. The GEMPACK many-to-one concept of mapping might be illustrated as follows:

Table 11.5 The right way to think of a mapping
Commodity (COM)maps to: Broad group (AGGCOM)
RiceCereals
WheatCereals
OtherCerealsCereals
CattleLivestock
SheepLivestock
OtherAnimalsLivestock
FruitFruitVeg
VegetablesFruitVeg
....etc....etc

You could show the same information as a one-to-many relation, as follows:

Table 11.6 The WRONG way to think of a mapping
Broad group (AGGCOM)includes: Commodities (COM)
CerealsRice Wheat OtherCereals
LivestockCattle Sheep OtherAnimals
FruitVegFruit Vegetables
....etc....etc

But this second idea of mapping (called in ViewHAR, 'reverse mapping') is NOT the GEMPACK idea. Notice also that in table 11.6 it is possible that 'Fruit' might mistakenly appear in two categories — the format of table 11.5 precludes such an error.

In GEMPACK you can not use as a mapping a many-to-many relation or a one-to-many relation where one element of the first set corresponds to more than one element of the second set.

Example 1 - Multiple Outputs

Suppose that some industries produce several commodities, but that each commodity in the set COM is produced by only one industry in the set IND. We can declare a mapping called PRODUCER from COM to IND as follows.

MAPPING PRODUCER from COM to IND ;

Then PRODUCER("Com1") would be an element of set IND, namely the industry in IND which produces "Com1".

Example 2 - Aggregating Data

Imagine a data manipulation TABLO Input file which is aggregating some data set with commodities in set COM to an aggregated set of AGGCOM commodities.18 The following statement could be useful.

MAPPING (ONTO) COMTOAGGCOM from COM to AGGCOM ;

With this, for each "c" in COM, COMTOAGGCOM(c) is the aggregated commodity to which "c" is mapped. The formula for aggregating domestic household consumption could then be written as follows.

COEFFICIENT (all,aggc,AGGCOM) AGGDHOUS(aggc) ; 
COEFFICIENT (all,c,COM) DHOUS(c) ; 
FORMULA (all,aggc,AGGCOM) 
AGGDHOUS(aggc) = SUM(c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c) ); 

This uses an "index expression comparison" (see section 11.4.11) to compare COMTOAGGCOM(c) with "aggc". The right-hand side of the formula uses the conditional sum:

SUM(c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c) )

to scan through all members c of COM, looking for those that map to the broad group aggc.

You can also use mappings to aggregate data in ViewHAR. ViewHAR makes it easy to set up (or read in) the set mappings for the aggregation you want. You can view the aggregated data and/or save it to a new Header Array file. See the chapter "Aggregating or Remapping Data" in the ViewHAR Help file.

The command-line program AggHAR can also be used to aggregate data, in a similar manner to ViewHAR. In addition it allows for weighted aggregation of, eg, elasticities. AggHAR instructions are contained in the ViewHAR Help file.

Example 3 - Aggregating Simulation Results

With COM, AGGCOM and the mapping COMTOAGGCOM as in Example 2 above, it is a simple matter to report simulation results for the aggregated commodities. For example, consider the variable xhous(c) which reports the percentage change in household consumption of commodity c in COM. Suppose that you wished to aggregate these (and possibly other similar results) to report the percentage change in household consumption of each of the aggregated commodities. Then you might use the mapping COMTOAGGCOM and the TABLO statements:

VARIABLE (all,c,COM) xhous(c) ;  
VARIABLE (all,aggc,AGGCOM) agg_xhous(aggc) ; 
EQUATION E_agg_xhous (all,aggc,AGGCOM)  
   SUM{c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c)} * agg_xhous(aggc)
 = SUM{c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c) * xhous(c) }; 

The equation above could alternatively be more concisely written:

EQUATION E_agg_xhous (all,aggc,AGGCOM)  
 SUM{c,COM:COMTOAGGCOM(c)=aggc, DHOUS(c) *[agg_xhous(aggc)-xhous(c)]}=0; 

Here the DHOUS(c) (as in Example 2 above) are suitable weights to use to aggregate the xhous results.19

The procedure in Example 3 is perfectly general and can be used with any model to report aggregated results (calculated while the rest of the model solves); this is easier than aggregating percentage changes after the simulation has been run. Of course you need to choose or construct suitable weights.

Example 4 - Unnecessary sums in mapping expression

Again with COM, AGGCOM and the mapping COMTOAGGCOM as in examples above, we might wish to express the idea that the rate of a new tax rate applies to blocks of commodities. We could do this with a direct mapping:

Variable (all,c,COM) thous(c) # new tax on commodity c #;  
Variable (all,aggc,AGGCOM) agg_thous(aggc) # new tax on broad com group aggc #; 
Equation E_thous (all,c,COM) 
  thous(c) = agg_thous(COMTOAGGCOM(c)); 

For example, suppose "Beef" and "Chicken" in the set COM both mapped to the broad group "Meat" in AGGCOM. Then we would be ensuring that the same "Meat" tax applied to both "Beef" and "Chicken".

Another, bad, way to write the equation above might be:

Equation E_thousBad (all,c,COM) 
  thous(c) = SUM{aggc,AGGCOM:COMTOAGGCOM(c)=aggc, agg_thous(COMTOAGGCOM(c)); 

Careful analysis of equation E_thousBad shows that it does the same thing as equation E_thous — but is inefficient and confusing. In E_thousBad the right-hand side of the equation uses the conditional sum:

SUM{aggc,AGGCOM:COMTOAGGCOM(c)=aggc, agg_thous(COMTOAGGCOM(c))

to scan through all members of AGGCOM, looking for the one that commodity c maps to. However, COMTOAGGCOM(c) tells us directly to which AGGCOM each c in COM corresponds. The sum involves wasteful computation, which could slow down your simulation.

Usually,

Equation E_thous (all,c,COM) thous(c) = agg_thous(COMTOAGGCOM(c));

A sum with index comparison would be wasteful here.

Formula (all,aggc,AGGCOM) AGGDHOUS(aggc)
       = SUM(c,COM: COMTOAGGCOM(c) EQ aggc, DHOUS(c) ); 

Example 5 - One-to-one mappings for reordering sets

A special case of the many-to-one mapping used by GEMPACK is the one-to-one mapping. For example, we might have:

Set HEIGHT(tall,short); Set STATUS(higher,lower);
Mapping (onto) A from HEIGHT to STATUS; 
Formula A("tall")="higher"; A("short")="lower"; 

Commonly the two sets involved have the same elements, but in a different order. For example, Australia includes 6 states and 2 'territories' (ACT and NT). Not all data sources order the territories in the same way. So we might see code like the following:

Set REG # Oz states # (NSW, VIC, QLD, SA, WA, TAS, NT, ACT);
Set REG1 # Oz states (odd ordering) # (NSW, VIC, QLD, SA, WA, TAS, ACT, NT);
Subset REG is subset of REG1;
Coefficient (all,r,REG) POPULATION(r) # total population #; 
Read POPULATION from file DAT header "POP";
Coefficient (all,q,REG1) ELDERLY(q) # number over 70 years old #; 
Read ELDERLY from file DAT header "OLD";
Coefficient (all,r,REG) OLDRATIO(r) # 70+ share of total population #; 
Formula (all,r,REG) OLDRATIO(r) = ELDERLY(r)/POPULATION(r); 

Here, the data at header "OLD" is stored in the odd REG1 order. Because of the subset statement, no explicit mapping is necessary.

11.9.1    Defining set mapping values [gpd2.4.8.1]

Of course MAPPINGs must be defined. That is, the TABLO Input file must give a way of specifying <set-mapping>(s) for all s in <set1>. And the values of <set-mapping>(s) must be in the set <set2> for each s in <set1>.20

Values for set mappings can be established in any of the following ways:

(a) by reading the element NAMEs in <set2> where each element of <set1> is mapped.

An example is

READ (BY_ELEMENTS) COMTOAGGCOM from File setinfo ;

The qualifier "(BY_ELEMENTS)" is required. The file setinfo can be a text file or a Header Array file (in which case a HEADER must also be specified). The data on the file at the relevant place must be CHARACTER data giving, for each c in COM, an element name in AGGCOM. Since element names are limited to at most 12 characters (see section 11.2.1), the data on the file should be strings of length no more than 12. [Shorter lengths are ok.]

(b) by formula(s) assigning the element NAMEs in <set2> to which the different elements of <set1> are mapped. For example:

FORMULA COMTOAGGCOM("C10TCF") = "AC5Manuf" ;

where the RHS is an element of AGGCOM. This uses element NAMEs on the RHS. Another example of this type is

FORMULA (all,c1,COM1) COMTOAGGCOM(c1) = "AC5Manuf" ;

where COM1 is a subset of COM.

(c) by reading the element NUMBERs in <set2> to which each element of <set1> is mapped. An example is

READ COMTOAGGCOM from File setinfo ;

The file setinfo can be a text file or a Header Array file (in which case a HEADER must also be specified). The data on the file at the relevant place must be INTEGER data giving, for each c in COM, an element number in AGGCOM. It is also possible to read as integers just some of the values of a mapping, as in the example

READ (all,c1,COM1) COMTOAGGCOM(c1) from File setinfo ;

where the set COM1 is a subset of the domain COM of the mapping COMTOAGGCOM. [Note that the qualifier "(BY_ELEMENTS)" is not present when integer data is read; this qualifier indicates character data.]

(d) by formula(s) assigning the element NUMBERs in <set2> to which each element of <set1> is mapped. An example is

FORMULA  COMTOAGGCOM("C10TCF") = 5 ;

where the RHS is the element number in AGGCOM. This uses element NUMBERs on the RHS. [Indeed, in this case, the RHS can be any expression allowed on the RHS of FORMULAs whose LHS is an Integer Coefficient — see section 11.6.3 for details. For example, the RHS could be ICOEF+2 in the example above if ICOEF had been declared as an Integer Coefficient.]

(e) by formula(s) of the type FORMULA(BY_ELEMENTS) assigning the element NAMEs as in

Formula(By_Elements) (All,m,MAR) MAR2AGGMAR(m)=COM2AGGCOM(m) ;

Here the RHS is another mapping, or it could be an index. See section 11.9.11 for more details.

(f) as the projection mapping from a set product to one of the sets making up the product. See section 10.13.2 for details.

Example — Aggregating Data or Results

Consider the following statements

SET  COM (wool, wheat, banking, hotels) ; 
SET  AGGCOM (agriculture, services) ; 
MAPPING COMTOAGGCOM from COM to AGGCOM ;

The mapping COMTOAGGCOM could be defined in one of the following ways.

(1) Via the following formulas with element NAMEs on the RHS

Formula  COMTOAGGCOM("wool") = "agriculture" ; 
Formula  COMTOAGGCOM("wheat") = "agriculture" ; 
Formula  COMTOAGGCOM("banking") = "services" ; 
Formula  COMTOAGGCOM("hotels") = "services" ;

(2) Via the following formulas with element NUMBERs on the RHS

Formula  COMTOAGGCOM("wool") = 1 ; 
Formula  COMTOAGGCOM("wheat") = 1 ; 
Formula  COMTOAGGCOM("banking") = 2 ; 
Formula  COMTOAGGCOM("hotels") = 2 ;

(3) Via the following file and read statements

File (text)  setinfo ; 
Read (BY_ELEMENTS) COMTOAGGCOM from file setinfo ;

In this case, the text file SETINFO should have the following array on it.

4 strings length 12 ; 
agriculture 
agriculture 
services
services

(4) Via the following file and read statements21

File (text)  setinfo ; 
Read COMTOAGGCOM from file setinfo ;

In this case, the text file SETINFO should have the following array on it.

4 integer ; 
1  1  2  2

(5) Via a FORMULA(BY_ELEMENTS)

Formula(By_Elements) (All,m,MAR) MAR2AGGMAR(m)=COM2AGGCOM(m) ;

See full details in section 11.9.11 below.

Note the general form of defining statements for COMTOAGGCOM:
COMTOAGGCOM("element from COM") is equal to either an "element of set AGGCOM" or else to an element number of set AGGCOM.

11.9.2    Checking values of a mapping [gpd2.4.8.2]

When you assign values to a set mapping, GEMSIM and TABLO-generated programs check that the values are sensible. For example, with COM, AGGCOM and COMTOAGGCOM as above, the formulas

COMTOAGGCOM("wool") = "steel" ;
COMTOAGGCOM("wool") = 15 ;

would lead to errors at run time since "steel" is not an element of AGGCOM and AGGCOM does not have 15 elements.

The values assigned to a set mapping are not checked after each assignment.22 Rather they are checked just before the set mapping is used (in a formula) or at the end of the preliminary pass (once all sets and set mappings have been set up).

The values of all set mappings are checked, even if the set mapping is not used in any formula, equation or update.23

11.9.3    Insisting that a set mapping be onto [gpd2.4.8.3]

As far as GEMPACK is concerned, set mappings do not need to be "onto" in the mathematical sense. That is, for a mapping from SET1 to SET2, it need not be the case that every element in SET2 is mapped to by some element in SET1.24

For example, if mapping MAP3 maps the set EXPIND of export industries to the set IND of all industries, there may be industries in IND which are not mapped to by anything in EXPIND.

In most cases, however, you will want the mapping to be onto.

If you use the qualifier (ONTO) when defining the mapping, the software will check that the every element of the codomain is mapped to by at least one element of the domain. If you use this qualifier when declaring the mapping and the mapping is not onto, the program will stop with an error.

The check that the mapping is onto is done at the same time as the check that the values are in range (see section 11.9.2).

11.9.4    Using set mappings [gpd2.4.8.4]

Set MAPPINGs can be used in arguments of VARIABLEs and COEFFICIENTs.

For example, continuing on the aggregation example, we could write

COEFFICIENT (all,c,COM) SHARE(c) # Share of com c in aggregate com # ;   
FORMULA (all,c,COM)    
SHARE(c)= DHOUS(c) / AGGDHOUS( COMTOAGGCOM(c)) ;

We can write "AGGDHOUS(COMTOAGGCOM(c))" since AGGDHOUS requires one argument which is in the set AGGCOM and "COMTOAGGCOM(c)" is in AGGCOM since "c" is in COM.

But it would be an error to write "DHOUS(COMTOAGGCOM(c))" because DHOUS requires one argument which is in the set COM yet COMTOAGGCOM(c) is an element of the set AGGCOM (so is not in the set COM since AGGCOM is not a subset of COM).

11.9.5    Set Mappings can only be used in index expressions [gpd2.4.8.5]

The term "index expression" was defined in section 11.2.4. An index expression is either an index or an element or an expression involving indices, element, index offsets and set mappings. Index expressions can be used as the arguments of coefficients or variables (see section 11.2.4), or in index-expression comparisons (see section 11.4.11).

Set MAPPINGs can ONLY be used in index expressions -- that is, in arguments of VARIABLEs or COEFFICIENTs as in

AGGDHOUS(COMTOAGGCOM(c))

or in index-expression-comparisons such as

COMTOAGGCOM(c) EQ aggc

in the aggregation example given earlier.

11.9.6    Two or more set mappings in an index expression [gpd2.4.8.6]

Set mappings can be applied to expressions which themselves involve one or more set mappings. In mathematical parlance, this is composition of functions. For example, suppose that MAP1 and MAP2 are set mappings.

MAPPING MAP1 FROM S1 TO S2 ; 
MAPPING MAP2 FROM S3 TO S4 ; 

Since MAP1 maps set S1 into set S2 and MAP2 maps set S3 into set S4, then the expressions

MAP1(MAP2(i)) 
MAP1(MAP2("element")) 

are legal provided that

[For example, then MAP2(i) is in the set S4 because "i" is in S3 and so MAP2(i) is also in the set S1 since S4=S1 or S4 is a subset of S1; hence MAP1(MAP2(i)) makes sense since the argument "MAP2(i)" of MAP1 is in the set S1, as required.] The resulting expressions are thought of as being in set S2 (since this is where the outer mapping MAP1 maps things).

If intertemporal sets and index offsets are involved, similar rules apply. Basically the index offset does not affect the set in which the expression is thought to be. For example, if set S1 is an intertemporal set, then the expression MAP1(MAP2(i) + 2) is legal precisely when MAP1(MAP2(i)) is. This is because MAP2(i)+2 lies in the same set as MAP2(i).

11.9.7    Set mappings in arguments [gpd2.4.8.7]

When an argument of a coefficient or variable involves a set mapping, the argument must be in the appropriate set.

For example, suppose that MAP1 and MAP2 are as in the section above and consider Coefficients X4 and X5 defined by

COEFFICIENT  (All,c,S2)  X4(c) ;
COEFFICIENT  (All,c,S5)  X5(c) ;

Suppose that i is an index ranging over the set S3 or a subset of S3. Recall from the section above that the index expression MAP1(MAP2(i)) is thought of as being in the set S2 (the codomain of MAP1). Hence

11.9.8    Other semantics for mappings [gpd2.4.8.8]

Several READs and/or FORMULAs can be used to set up the values of each set mapping. But, once a set mapping is used (for example, in a Formula or in a Write, or in an index expression in a condition as in section 11.4.11), its values cannot be changed (that is, it cannot appear in a READ statement or on the LHS of a Formula).

Set mappings are not allowed in index expressions on the LHS of a formula or of an update. For example, the following is not allowed.

FORMULA (all,c,COM) C1(COMTOAGGCOM(c)) = C2(c) ;  ! Wrong !

[If several different "c"s in COM were mapped to the same place in AGGCOM, the results would be ambiguous since it would depend on the order of processing the elements "c" in COM.]

Set mappings are not allowed in the declaration of coefficients or variables. Nor are they allowed in displays.

11.9.9    Writing the values of set mappings [gpd2.4.8.9]

The correct method is:

Write (by_elements) COMTOAGGCOM to file OUTFILE header "C2AC";

This will write the values of the set mapping as character strings (to a header of type '1C') which contain the names of the elements to which the elements of the domain set are mapped.

The qualifier BY_ELEMENTS is, of course, not allowed if the elements of the codomain set (the set which is being mapped to) are not known. Then you could write:

Write COMTOAGGCOM to file OUTFILE header "C2AC";

and the values of the set mapping COMTOAGGCOM will be written as integers (showing the position number in AGGCOM of COMTOAGGCOM(c) for each c in COM).

11.9.10    Reading part of a set mapping BY_ELEMENTS [gpd2.4.8.10]

It is possible to read just some of the values of a set mapping by elements. That is, statements of the form

READ (by_elements)  (all,i1,S1)  MAP1(i1)  from file  ;

are allowed. [Above, if MAP1 is a mapping from set S2 to set S3, then S1 must be a subset of S2.]

For the above to be valid, the data on the file (at the relevant header if it is a Header Array file, or in the relevant position if it is a text file) must be character data. [It cannot be integer data as would be required if the qualifier (BY_ELEMENTS) were omitted.]

11.9.11    Mapping values can be given by values of other mapping or index [gpd2.4.8.11]

Mapping Example 1 An example will make this clear. Suppose that you are aggregating some data. You have defined the set COM of commodities and the set AGGCOM of aggregated commodities, and have defined a set mapping COM2AGGCOM from COM to AGGCOM. [For each c in COM, COM2AGGCOM(c) is the aggregated commodity c belongs to.] Suppose also that MAR is the set of margins commodities (MAR is a subset of COM) and that AGGMAR is the set of aggregated margins commodities. You want to define a mapping MAR2AGGMAR from MAR to AGGMAR. Indeed, for each m in MAR, the value of MAR2AGGMAR(m) should just be the commodity in AGGCOM to which m maps under the mapping COM2AGGCOM already set up. So you want a formula of the form

FORMULA   (All,m,MAR)   MAR2AGGMAR(m) = COM2AGGCOM(m) ;

That is, you define the mapping and give it values via the 2 statements

MAPPING  MAR2AGGMAR  from  MAR  to  AGGMAR ;
FORMULA (All,m,MAR) MAR2AGGMAR(m) = COM2AGGCOM(m) ;

To make this concrete, suppose for simplicity that COM is the set (c1-c10), that MAR is the subset (c6-c9), that AGGCOM is the set (agc1-aggc5) and that COM2AGGCOM maps each of c1,c2,c3 to aggcom1, each of c4,c5 to agcom2, each of c6,c7 to aggcom3, each of c8,c9 to aggcom4 and c10 to aggcom5. Suppose also that AGGMAR is the set (aggomc3,aggcom4).

Then COM2AGGCOM("c6") is equal to "aggcom3" and so the formula above will set MAR2AGGMAR("c6") equal to "aggcom3" as you would expect. Similarly for the other elements of MAR. You can see that MAR2AGGMAR will map c5 and c6 to aggcom3 and each of c7,c8 to aggcom4.

In General

Suppose that set mapping MAP1 has been declared via the statement

MAPPING   MAP1  from S1  to  S2 ;

(where S1 and S2 are sets which have already been defined). You are allowed to use the following kinds of formulas to define some or all the values of a set mapping.

FORMULA  (All,i1,S3)  MAP1(i1) = <index-expression> ;
FORMULA    MAP1("e1") = <index-expression> ;

Above S3 must be equal to S1 or else a subset of it, and "e1" must be an element of the set S1.

Above, <index-expression> can begin with a set mapping (as in the example above) or can be simply an index. [Index expressions are defined in section 11.2.4.]

For the first formula above to be valid,

If either of the first two conditions above is false, TABLO will report an error. The third condition can only be checked when the TABLO-generated program or GEMSIM runs. If it fails, the details will be reported when that program runs.

Suppose that in the example above COM2AGGCOM("c9") were equal to "aggcom5" instead of "aggcom4". Then the formula

FORMULA   (All,m,MAR)   MAR2AGGMAR(m) = COM2AGGCOM(m) ;

would produce an error when m is equal to c9 since then the RHS is equal to aggcom5 which is not an element of the set AGGMAR.

Note that no subset relationship is required between the set in which the values of <index-expression> lies and the set S2 which is to contain the values of MAP1.

Note that <index-expression> cannot be an index followed by an index offset. This is because, even if the index is ranging over an intertemporal set, the offset would take one value of the index expression out of the set over which the index is ranging.

When the right-hand side is an element or an index-expression (see section 36.3), the qualifier (BY_ELEMENTS) is allowed (but is not required). So the Formula in Example 1 above could be written

FORMULA (BY_ELEMENTS) (All,m,MAR) MAR2AGGMAR(m) = COM2AGGCOM(m) ;

This qualifier can be helpful since, in order to understand the formula above for MAR2AGGMAR, you must think of the element names. [However the qualifier (BY_ELEMENTS) is not allowed if the right-hand side is not an element or an index-expression.]

Mapping Example 2

Suppose that a model has sets COM of commodities and IND of industries. Suppose that some industries produce several commodities and that other industries (those in the subset UPIND of IND) produce only one commodity. Suppose also that for the names of the industries in UPIND are the same as the names of the commodities they produce. Then you can define a set mapping from UPIND to COM via the statements

MAPPING   UPIND2COM  from UPIND to COM ;
FORMULA (BY_ELEMENTS)  (all,i,UPIND)  UPIND2COM(i) = i ;

This is an example where the <index-expression> on the RHS is just an index. Note that the formula above is valid even if UPIND has not been declared to be a subset of COM.

11.9.12    Writing a set mapping to a text file [gpd2.4.8.12]

When a set mapping is written to a text file via a "simple" write (that is, one with no ALL quantifiers), comments are added after each value which indicate the names of the elements in question. These comments indicate the name of the element being mapped and the name of the element to which it is mapped. For example,

Write COM2AGGCOM to terminal ;

might produce the output (in the log file)

3 integer header "Mapping COM2AGGCOM from COM(3) to AGGCOM(2)" ;
1                !  c1            maps to aggc1
1                !  c2            maps to aggc1
2                !  c3            maps to aggc2

11.9.13    Long name when a set mapping is written to a header array file [gpd2.4.8.14]

When all elements of a set mapping are written to a Header Array file via a "simple" Write (that is, no with no ALL quantifiers), if a long name is not specified in the Write statement, the software writes a special form of long name. The long name is of the form

Mapping <mapping-name> from <domain-set>(<size>) to <codomain-set>(<size>)

For example, consider the mapping COM2AGGCOM which maps a set COM of size 23 to the set AGGCOM of size 14. The long name used would be

Mapping COM2AGGCOM from COM(23) to AGGCOM(14)

This form of long name is used by the aggregation functions in ViewHAR to recognise set mappings. See the ViewHAR Help file for details.

Note that, for simple writes of a set mapping, the convention described above replaces that described in section 11.11.7 (which still applies to other writes).

11.9.14    ViewHAR and set mappings [gpd2.4.8.15]

ViewHAR allows you to save set mappings as Header Array or text files, or to paste them into spreadsheets or TAB files. [It has similar capabilities for sets.] See the ViewHAR Help file for details.

11.10    Files [gpd2.4.9]

A logical filename is always required in a FILE statement, since all references to files in READ and WRITE statements use logical names, never actual file names. When no actual file name is given, GEMSIM or the TABLO-generated program expect the actual filename to be specified on the Command file (see section 22.1). This has the great advantage of allowing you to use different base data without needing to rerun TABLO. If you include an actual filename in your FILE declaration then

We recommend that you do not specify actual file names in FILE statements, unless you have good reason to do so.

See section 22.1 to find out how to make the connection between a logical file name and the associated actual file when GEMSIM and TABLO-generated programs run.

Files can be GEMPACK Header Array files (see chapter 5) or GEMPACK text data files (see chapter 38 for more details). Real and integer data can be read from, or written to, these files by GEMSIM or TABLO-generated programs. These programs can only read character data

However, TRANSFER statements (see section 11.13) can be used to copy any character data (or indeed any header) from one HAR file to another.

11.10.1    Text files [gpd2.4.9.1]

You should avoid using text files to store numbers which are input to your model (although text file output [CSV] is useful for taking results into Excel). You might encounter the use of text files in older models. GEMSIM and TABLO-generated programs can read real or integer (but not character) data from such files or write to them. In a TAB file, the default file type is Header Array. Thus, whenever you want a particular file to be a text file, you must indicate this by using the 'TEXT' file qualifier when declaring the file, such as in the example below.

FILE (TEXT) input1 ;
FILE (TEXT, NEW) output1 ;

Then you can read data from file 'input1' and write data to file 'output1'. (The qualifier 'NEW' is required to indicate a file to be written to.) Data on text files has no 4-character header associated with it, so the READ/WRITE instructions in the TABLO Input file do not mention a header either, as in the next two examples.25

READ A1 FROM FILE input1 ;
WRITE A2 TO FILE output1 ;

Partial READs/WRITEs to/from text files are also allowed. Use the same syntax as for Header files except that 'HEADER "xxxx"' is omitted. For example,

READ (all,i,COM) A3(i,"imp") FROM FILE input1 ;

You can also read data from the terminal or write it to the terminal. The syntax is as shown below.

READ A1 FROM TERMINAL ;
WRITE A2 TO TERMINAL ;

Details of the preparation of data for text files are given in chapter 38, with an example given in section 54.10.

When preparing text data for a partial read, such as

(all,i,COM)(all,j,IND) A1(i,"dom",j),

the first line indicating how much data follows should refer to the part to be read, not the full array. In the example just above, if COM and IND have sizes 3 and 20 respectively, the first line should be

3  20  row_order ;

to indicate a 2-dimensional array of size 3 x 20. Then the data (3 rows each of 20 numbers) should follow, each row starting on a new line. Note also that long "rows" can be spread over more than one line. (For example, the 20 numbers here can be put say 8 on each of two lines and the 4 on a third line.)

In preparing the "how much data" information at the start of each array, you can omit any sizes equal to 1.

For example, when preparing data to be read (via a partial read) into the (3, 1-4, 5, 1-7) part of some coefficient, regard this as a 2-dimensional array of size 4 x 7 (not a 4-dimensional array of size 1 x 4 x 1 x 7). The only time a size equal to one need be used is for a single number, when the "how much data" line will be "1 ;" meaning a 1-dimensional array of size 1.

Several different arrays of data can appear consecutively on a text file. GEMSIM or the TABLO-generated program reads them in order. Of course you must be careful to prepare the data file so that the order corresponds with the order or the READ statements in your TABLO Input file. Indeed, this question of order is one reason why using text files can introduce errors that would not occur if you were using Header Array files.

Two READs from the same TEXT file must not be separated by READs from other files. Otherwise GEMSIM or the TABLO-generated program would close the TEXT file when it comes to the read from the other file; then, when it re-opens the TEXT file for the next read from it, it would start reading at the beginning of the TEXT file again. (That is, it would lose its place in the TEXT file.)

When reading data from the terminal, GEMSIM and TABLO-generated programs ask if you wish to input the data in row order (the default) or column order. You are then prompted for it one row or column at a time. [If you want to prepare a Stored-input file for this, follow the instructions above as if preparing a text file except that the first line showing amount of data should be omitted.]

Note that, at present, GEMSIM and TABLO-generated programs can only read set elements and subsets-by-number from Header Array files, not from text files (see sections 10.1 and 10.2). But these programs can read the values of a set mapping from a text file (see section 11.9.1).

11.11    Reads, writes and displays [gpd2.4.10]

11.11.1    How data is associated with coefficients [gpd2.4.10.1]

The order of the elements of a set (as declared in a SET declaration) determines the association of data on a Header Array file or text file with actual parts of a coefficient.

For example, if the set IND has elements "car", "wool" and "food" and the set FAC has elements "labor" and "capital", and if coefficients A3, A4, B3 and A5 are declared via

COEFFICIENT (ALL,i,IND)(ALL,f,FAC)      A3(i,f) ;
COEFFICIENT (ALL,i,IND)                 A4(i)   ;
COEFFICIENT                             B3      ;
COEFFICIENT (ALL,i,IND)(ALL,j,IND)(ALL,f,FAC)  A5(i,j,f) ;

then, for the purposes of associating them with data on a file, A3 should be thought of as a 3 x 2 matrix (where the rows are indexed by the set IND and the columns by the set FAC), A4 should be thought of as vector (that is, a one-dimensional array) of length 3, B3 as a single number and A5 as a 3 x 3 x 2 array. For example:

READ A3 FROM FILE cid HEADER "C003" ;

to succeed, the data on the file at header 'C003' must be a 3 x 2 matrix. A3("car","capital") gets the value of the entry in row 1 and column 2 of the matrix on the file while A3("food","labor") is assigned the value of the entry in row 3 and column 1 of the matrix on the file. Again, for

READ A4 FROM FILE cid HEADER "C103" ;

to succeed, the data on the file at header 'C103' must be exactly 3 numbers. A4("wool") gets the value of the 2nd number on the file. For

READ B3 FROM FILE cid HEADER "C113" ;

to succeed, the data on the file at header 'C113' must be a single number. B3 gets the value of this number on the file.

GEMSIM and TABLO-generated programs can check the order of the elements of a set, as defined in the TABLO Input file or read at run time when the set is defined, against the element names which may be stored on a Header Array file from which data is being read. This allows you to guard against errors that would occur if a data item were assigned to the wrong part of a Coefficient. You can control how much of this checking is carried out. See section 22.4 for details.

Sets of size 1 and single elements are ignored when checking if the data on a file is of the right size for a Read or partial Read. For example, with Coefficient A3 being declared as in the example at the start of this section, the data on a file for a "READ A3" statement can be of size 3x2 or 3x1x2 or 1x3x2x1.

11.11.2    Partial reads, writes and displays [gpd2.4.10.2]

In a partial read, the whole of some header (or text data) on file is used to assign values to part of some coefficient.26

In a partial write, part of some coefficient is written to file.

With A5 declared as above and IND having elements as above, for the partial read of the coefficient A5

READ (ALL,i,IND)(ALL,j,IND) A5(i,j,"capital")
                     FROM FILE cid HEADER "C032" ;

to succeed, the data on the file at header 'C032' must be a 3 x 3 matrix. A3("car","food","capital") gets the value of the entry in row 1 and column 3 of the matrix on the file.

In checking that the amount of data at the appropriate place on the file is as expected, any 1's in the size are ignored. For example, if a 3 x 2 matrix of data is required, an array of size 3 x 1 x 2 on the file is considered to match this (in the obvious way).

In READ, WRITE or DISPLAY statements which only transfer some of the values of the relevant coefficient (so that quantifiers occur explicitly),

1. all indices associated with the coefficient must be different. For example,

READ (all,i,COM) A6(i,i) FROM ....      !incorrect!

is not allowed.

2. every index quantified must appear as an index of the coefficient. For example,

READ (all,i,COM)(all,j,COM) A7(i) FROM ...   !incorrect!

is not allowed.

3. indices can range over subsets of the sets over which the coefficient is defined. For example, if coefficient A is defined by

COEFFICIENT (all,c,COM) A(c) ;

and MARGCOM has been defined as a SUBSET of COM, the statement

READ (all,c,MARGCOM) A(c) ;        !correct!

is allowed.

Similar rules apply to partial writes and displays.

Index offsets (see section 11.2.4) are not allowed in READs, WRITEs or DISPLAYs. Eg:

READ (all,t,fwdtime) X(t+1) From File (etc) ; ! NOT allowed !

Good Practice Recommendation: Avoid writing code like:

 Coefficient (all,i,COM)(all,j,COM) MAT(i,j) # some data #;
 Read        (all,i,COM)(all,j,COM) MAT(i,j) from file Infile header "A1";

since the Read statement may suggest to the casual reader that this is a partial read. In fact the whole of MAT is read in, so you should write:

 Coefficient (all,i,COM)(all,j,COM) MAT(i,j) # some data #;
 Read MAT from file Infile header "A1";

11.11.3    Seeing the values of integer coefficients of dimension 3 or higher [gpd5.8.5]

Any Display statement will work for Integer Coefficients of dimension 3 or higher. This includes simple Display statements such as

Display COEF1 ; ! quantifiers and elements are also allowed in this case !

or complicated ones involving quantifiers, elements and or subsets. You will see the values displayed as integers, as you would expect. You can see the element names associated with each entry of the array since Display output is labelled output — see the example output on the first page in chapter 5.0.3.

You can include simple Write statements in your TAB file to write all the values of an integer Coefficient with 3 or more dimensions to a Header Array file or to a text file or to the terminal. These simple write statements must be of the form

Write COEF1 to file ... ; ! no quantifiers or elements are allowed !

In each case, the output values will be written not as integers, but as real numbers. [This is because we do not support 3 or higher dimensional integer arrays on Header Array files or on GEMPACK text data files.]

AnalyseGE can show the values of integer Coefficients of dimension 3 or more.

11.11.4    FORMULA(INITIAL)s [gpd2.4.10.3]

Each FORMULA(INITIAL) statement in a TABLO Input file produces an additional READ statement in the associated linearized TABLO Input file. For example, the statement

FORMULA(INITIAL)  (all,c,COM)  A(c) = ... ;

also gives rise to the statement

READ (all,c,COM) A(c) FROM FILE ... ;

A temporary file (the "intermediate extra data" file — see section 22.2.3) is used to hold the values of the coefficient in this case. The FORMULA is implemented during step 1 of a multi-step calculation while the READ is applied during subsequent steps.

Because of this, the restrictions in section 11.11.2 above for partial reads apply also to FORMULA(INITIAL)s. That is, the quantifiers and LHS coefficient occurrence of a FORMULA(INITIAL) must satisfy the rules for partial READs. For example,

FORMULA(INITIAL) (all,i,COM) A6(i,i) = ... ;    !incorrect!

would produce a semantic error.

Index offsets (see section 11.2.4) are not allowed in the left-hand side of a FORMULA(INITIAL) since they are not allowed in a READ statement. For example, the statement

Formula (Initial) (all,t,fwdtime)  X(t+1) = Y(t) ;

is not allowed.

11.11.5    Coefficient initialisation [gpd2.4.10.4]

Part of the semantic check is to ensure that all coefficients have their values initialised (that is, assigned) via reads and/or formulas. You should note that the check done by TABLO is not complete, as explained below.

Consider, for example, a coefficient A6 declared via

COEFFICIENT (ALL,i,COM)(ALL,j,IND) A6(i,j) ;

TABLO can tell that a read such as

READ A6 FROM FILE cid HEADER "ABCD" ;

initialises all parts of A6 (that is, initialises A6(i,j) for all relevant i and j), as does a formula such as

FORMULA (ALL,i,COM)(ALL,j,IND) A6(i,j) = A4(i) + A5(j) ;

provided A4 and A5 have been fully initialised. TABLO can also tell that a partial read such as

READ (ALL,i,COM) A6(i,"sheep") FROM FILE cid HEADER "ABCD" ;

or a formula such as

FORMULA (ALL,i,COM) A6(i,"sheep") = A4(i) ;

only initialises some parts of A6 (since A6(i,j) for j different from "sheep" is not affected).

At present TABLO gives no warning about possibly uninitialised coefficients if two or more partial initialisations are made. You should note that, depending on the actual details, there may still be parts of the coefficient not initialised. If, for example, the set IND in the examples above has just two elements "sheep" and "cars" then the two reads

READ (ALL,i,COM) A6(i,"sheep") FROM FILE cid HEADER "ABC1" ;
READ (ALL,i,COM) A6(i,"cars")  FROM FILE cid HEADER "ABC2" ;

would fully initialise A6, but the two reads

READ (ALL,i,COM) A6(i,"sheep") FROM FILE cid HEADER "ABC1" ;
READ         A6("tin","cars")  FROM FILE cid HEADER "ABC2" ;

would leave some parts of A6 uninitialised (if COM has elements different from "tin"). See section 25.7 for an example of this. There a coefficient is written even if some of its values have not been initialised.

Since Release 8, GEMSIM and TABLO-generated programs initialise all values of all Coefficients to zero by default. You can change this if you wish. See section 25.7 for details.

11.11.6    Display files [gpd2.4.10.5]

All DISPLAYs are written to a single text file called the Display file. Details can be found in section 22.3.

11.11.7    Transferring long names when executing write statements [gpd2.4.10.6]

Suppose you wrote a data-manipulation TAB file that contained the code fragment:

Coefficient (all,c,COM)(all,s,SRC) V5BAS(c,s) # Household Demands #;
READ V5BAS from file INFILE header "5BAS"; 
Formula (all,c,COM)(all,s,SRC:V5BAS(c,s)=0) V5BAS(c,s) = 0.001;
Write V5BAS to file OUTFILE header "5BAS"; 

and suppose that on the input file the 5BAS header had the long name "Hou Bas". What long name would you expect to see for the 5BAS header on the output file?

The answer is that the output file will show long name "Hou Bas", not "Household Demands". This behaviour (sometimes handy, sometimes irritating) is further explained below.

Case 1: Write statement uses long name from input file

This is the case shown above. If the input header has a non-blank long name, and the Write statement gives no long name, the input long name will be used, not the long name in the coefficient declaration.

Case 2: Longname in Write statement is always used.

If instead the Write statement above had been

Write V5BAS to file OUTFILE header "5BAS" longname "Household Use";

the output file would show long name "Household Use", overriding any long name on the input file or in the coefficient declaration.

Case 3: If no Longname in input file or Write statement, Coefficient declaration is used

Suppose we used the same code as in the first example, but the 5BAS header on the input file had no (or a blank) long name. Then the output file would show "Household Demands" — the long name used in the Coefficient declaration.

Case 4: Partial writes create a special long name

If instead the Write statement above had been

Write (all,c,COM) V5BAS(c,"dom")to file OUTFILE header "5BAS";

the output file would show long name: V5BAS(COM,"dom") Household Demands
appending the long name from the coefficient declaration.

Good Practice Recommendation: The data file used by a CGE model should always be produced by a TABLO program. Usually this formats data as the model requires, check that accounts are initially balanced, and perhaps summarizes the data. In that TABLO program, each Write statement should explictly include the Longname — giving you full control of the long names displayed on your model's input file.

11.11.8    Reads only if header exists — read qualifier ifheaderexists [gpd5.8.1]

You can use the Read qualifier IfHeaderExists to ensure that a read statement is carried out only if the specified header exists on the file. If the header is present, the data is read from it. Otherwise no error occurs. This may be useful in a number of circumstances.

Example 1: You may have a general-purpose model which often runs with default elasticity values of 1 (or zero). But, in some cases you may want to be able to provide more specific elasticity values. The same TAB file can be used for the two cases if you set the elasticity values to their default value and then read in the more explicit values only if the relevant header exists on the input data file. The TAB file statements might be as follows.

Coefficient (All,c,COM) ELAST(c) ;
Formula (All,c,COM) ELAST(c) = 1 ;  ! the default value !
Read (IfHeaderExists) ELAST from File INPUT Header "ELAS" ;

The "IfHeaderExists" is a Read qualifier allowed for Release 9.0 and later. The read is carried out only when the relevant header exists on the Header Array file. If the header is there, the values are read from it. Otherwise the values already set up are used.

Example 2: Consider a recursive dynamic model in which you wish to keep track of price changes across a number of years. It is often ok to consider all basic prices being equal to one in the first year of a sequence of linked simulations.

You can avoid having to add lots of price headers (with all values equal to 1) to the data for the first year if you use Read(IfHeaderExists) to read the prices. For each relevant price, put a Formula setting the prices to 1 and then put a Read(IfHeaderExists) statement after. In the simulation for the first year, the header will not exist so all prices will be set to one, but the updated prices will be written to the updated data file (even though the header is not present on the input data — see section 11.11.8.1 below). In year 2, the updated prices from the simulation for year 1 will be on the updated data from that year, and these price values will be read at the start of year 2. Similarly for subsequent years.

11.11.8.1    Syntax and semantic rules [gpd5.8.1.1]

11.12    Updates [gpd2.4.11]

Update statements have been introduced in sections 4.4.2 and 4.4.4. Here we give extra information about them.

11.12.1    Purpose of updates [gpd2.4.11.1]

The purpose of the update statements is to give instructions for calculating the new values for all data (that is, coefficients whose values are read) as a result of the changes in the variables of the model in one step of a multi-step simulation. In the expression on the right-hand side of an update statement,

These values are use