MODEL

<< Click to Display Table of Contents >>

Navigation:  Gekko User Manual > Gekko statements >

MODEL

Previous pageReturn to chapter overviewNext page

The MODEL statement is used in one of two ways:

 

Load Gekko equations contained in a .frm file

Load GAMS equations stored in a GAMS file. GAMS models are not solved, but their equations can be displayed or decomposed. GAMS equations can either be loaded as raw equations or unrolled equations, cf. the GAMS section below.

 

A MODEL statement loading a Gekko model is best put before READ statements: in that way all model variables not found in the databank will be auto-created when issuing the READ statement.

 

Failsafe note: if you experience problems solving the model (SIM), try using the Gauss-Seidel method (default) together with the setting option solve failsafe = yes. Gekko model equations may be executed individually (one by one) with the PREDICT statement.

 


 

Syntax

 

model < DEP=...  DUMP  GMS > filename ;

 

DEP=

(Optional). Together with the <gms> option, the user can provide a list that identifies what variables individual equations determine. For instance, in a GAMS equation e_1 specified like e_1[i, t] .. p[i, t] * q[i, t] =E= v[i, t]; there is the question of which variable is determined in the e_1 equation? In a system of simultaneous equations, what is determined is a complicated question, but in many cases it makes sense to designate a "dependent" variable. In the e_1 equation, we would expect the dependent variable to appear on the left-hand side of the equation, but then there is the question of whether this is p or q?

 

Gekko can try to find the dependent variable in two ways, controlled by option model gams dep method = ... .  Either it will look for the first variable that is not inside a []-bracket or $-condition; in the above case p. Alternatively, it will look at the equation name, and if this is for instance e_p, it will assume that p is the dependent variable. If these rules do not designate the "right" variable, you may use the <dep> local option like this: model <gms dep=#(listfile dep)> model.gms;In the listfile (you may alternatively use  a normal list), you can state lines like this:

 

p; e3; e10;

q; e2;

 

This tells Gekko that equations e_3 and e_10 designate p as dependent variable, whereas equation e_2 designates q as dependent variable. These designations overrule the above-mentioned logic (either picking the first variable on the left-hand side, or using the equation name), so only the special cases that do not follow that rule need to be stated. For instance, if e_1 was determining q instead of p, the q-line of the listfile could be q; e_1; e_2. instead of just q; e_2.

 

When using the first variable on the left-hand side, Gekko will allow lagged or leaded variables to be dependents. This can be switched off with option model gams dep current = yes, after which only current (non-lagged and non-leaded) variables can be identified as dependents.

 

Note: The identification of "dependents" is only used in the DISP and DECOMP statements, not elsewhere. [New in 3.0.2]

 

DUMP

(Optional). With this option together with the <gms> option, a GAMS model will be dumped in Gekko form, as the file dump.gcm. This file can be used to inspect how Gekko translates GAMS-equations, and which variables are indentified as dependents in each equation (and if they are identified via a DEP list). These equations may not run in Gekko, at the moment <dump> is only for debugging. [New in 3.0.2]

GMS

(Optional). With this option, Gekko will read GAMS equations from a .gms file (extension .gms will be added if missing). Gekko will search the .gms file for equations which can be shown with the DISP statement. A MODEL<gms> statement, will set option model type = gams; automatically.

filename

Filenames may contain an absolute path like c:\projects\gekko\bank.gbk, or a relative path \gekko\bank.gbk. Filenames containing blanks and special characters should be put inside quotes. Regarding reading of files, files in libraries can be referred to with colon (for instance lib1:bank.gbk), and "zip paths" are allowed too (for instance c:\projects\data.zip\bank.gbk). See more on filenames here.

If the filename is set to '*', you will be asked to choose the file in Windows Explorer.

The extension .frm is automatically added, if it is missing.

 

 

 


 

Gekko models

 

Model equations may be decorated with formula codes, and there are also some special markers to indicate different parts of the model:

 

Equation types

 

_

These formula codes begin with the character _, and the following codes may follow:

 

position 2: an arbitrary character to indicate the type of equation, for instance I for identity, G for 'guessed' equation, S for stochastic, etc. The chosen characters are completely ignored in simulations etc. and can be thought of as meta information.

position 3 and 4: add-factor, either J_ or JD for additive add-factors, or JR for relative add-factors.

position 5: indicate exogenization dummy, D.

position 6: not used

position 7: a Z for damping in the Gauss-Seidel algorithm

 

Example: _SJRD_Z means S for stochastic, JR for relative add-factor, D for exogenization dummy, and Z for damping.

Y

An equation with code Y means that the equation is run after the simulation (for each period). Such Y-type equations are often of technical character, calculating different kinds of add-factors (J-variables) etc.

T

Equations with code T are run exactly like Y-type equations. The only difference is that the T indicates that such equations are "interesting" and should be part of documentation systems, etc. T can be read as "table variables".

P

Equations with code P are not run at all in SIM, since they are not considered part of the model. P-type equations can be used to store mathematical relationships in frm files, together with the normal equations. P-type equations can only be run via the PREDICT statement, and can therefore be thought of as "predict equations". Examples may be an equation like FRML P   ye = (y[-1] + y + y[+1])/3;, calculating a moving average of y, including leads. Such an equation will trigger a forward-looking algorithm unless stated as a P-type equation. (The equation may still be run as part of a SIM statement, if the RUNAFTER$ part of the model contains a PREDICT of the equation, cf. example below).

 

 

Model parts (tags)

 

Note: The AFTER$ and AFTER2$ tags are placed between normal model equations (which are located at the top of the file). The RUNBEFORE$,  RUNAFTER$ and VARLIST$ tags must be placed after the normal model equations, and these tags separate each other, so they do not need an ending tag.

 

AFTER$

This tag indicates that the following variables are to be understood af part of the 'AFTER$' equations. The AFTER$ distinction is only used in the special SIM<after> statement, not anywhere else (a normal SIM statement ignores the tag). See the note above.

AFTER2$

This tag indicates that the following variables are to be understood af part of the 'AFTER2$' equations. In Gekko, there is no difference between AFTER$ and AFTER2$. The AFTER2$ distinction is only used in the SIM<after> statement, not anywhere else (a normal SIM statement ignores the tag). See the note above.

RUNBEFORE$

After a RUNBEFORE$ tag, you may put normal Gekko statements that are to be executed just before the model is simulated (SIM).  In these statements, you may refer to the dates %__simt1 and %__simt2 which indicate the start and end of the simulation period. See the note above.

RUNAFTER$

After a RUNAFTER$ tag, you may put normal Gekko statements that are to be executed just after the model is simulated (SIM). In these statements, you may refer to the dates %__simt1 and %__simt2 which indicate the start and end of the simulation period. The RUNAFTER$ tag must be placed after the normal model equations. See the note above.

VARLIST$

You may put a variable list after a VARLIST$ tag, instead of using a separate file for this. See the note above.

 

 

The MODEL statement automatically analyzes and splits the model into three internal parts: the prologue (pre-model), the simultaneous part, and the epilogue (post-model). So Gekko will automatically detect any pre- and post-model and will use this information to speed up simulations (hence, for SIM purposes, AFTER$ and AFTER2$ tags are ignored). The simultaneous part of the model is sub-divided into two parts: the feedback variables, and the simultaneous recursive variables. This information is used to speed up the Newton algorithm, by reducing the dimensionality of the simultaneous equations.

 

The MODEL statement used on a Gekko model emits some files containing lists of exogenous, endogenous, and DJZ-type variables (that is, add-factors and variables used for exogenization). It also emits a file with ordering information. These files are assembled into a .zip-file with the name [model]__info.zip, where [model] is the name of the model. Gekko also creates the lists #all, #endo, #exo, #exod, #exodjz, #exoj, #exotrue and #exoz with lists of different kinds of variables. The lists are located in the Global databank, so that they survive READ statements.

 

The Gekko model equations have the following syntax:

 

FRML code  variable =  expression;

 

code

See the above table regarding equation types

variable

A variable, or an expression on a variable: log(x), dlog(x), dif(x) or pch(x)

expression

Mathematical expression

 

As an example to illustrate, we will consider a particularly simple equation:

 

FRML _SJ_D  c  = 0.* y + 0.* y[-1];

 

The equation code is _SJ_D, which means that an absolute add factor (Jc) will be added to the equation. So our equation is augmented into

 

c  = 0.* y + 0.* y[-1] + Jc;

 

Last, exogenization dummies are added, too (the D in the fifth position of the equation code). This is done in order to ease exogenization of the equation, if needed. In general, such variables are implemented in the following way:

 

c  = (- Dc) * (0.* y + 0.* y[-1] + Jc) + Dc * Zc;

 

Two more variables are added, Dc and Zc. If Dc = 0, the variables Dc and Zc have no effect, but if Dc = 1, the equation reduces to = Zc. In that case, the equation is controlled by the exogenous variable Zc. In addition to this equation, Gekko adds two more 'reverted' equations regarding Jc and Zc. These equations are of Y-type, run after the simulation.

 

FRML Y      Jc = c - (0.* y + 0.* y[-1]);
FRML Y      Zc = c;

 

If Dc = 0, it is easy to see that Jc will not change its value via its Y-type equation. But if Dc = 1, Jc will attain the value that corresponds to what Zc has been set to, or Jc = Zc - (0.* y + 0.* y[-1]). Therefore, you may set Dc = 1, and Zc to some chosen value. When you simulate, c will attain that value. Later on, if you reset Dc = 0 and simulate, you will notice that c still assumes the chosen value (but is otherwise free to change if variables on the right-hand side change). So these exogenization dummies can be used to change the levels of endogenous variables, in a sense performing an implicit goals-means analysis, where c is the goal, and Jc is the means.

 

The same functionality is often used for log-linear equations. Such an equation would look like:

 

FRML _GJRD Dlog(y) = Dlog(x);

 

The add-factor (J-variable) is now relative (code JR), and the resulting equations are as follows:

 

= y[-1] * exp(log(x) - log(x[-1])) * (+ JRy);

 

This equation is the 'unfolded' equation used in the simulations (try taking log() on both sides of the equation). In general, a JR-variable is always implemented by multiplying the unfolded equation with (+ JR). Note that in this equation, the relative add-factor corresponds to Dlog(y) = Dlog(x) + log(+ JRy), so the relative add-factor can be interpreted as an additive add-factor in logarithms (also note that log(+ JRy) ≈ JRy for small values of JRy).

 

If in doubt about how a particular equation unfolds, including how D-, J- and Z-variables are implemented, you may DISP it and click the link "Show detailed equation".

 

You may use parameter values instead of numerical values, for instance:

 

val %= 0.758812;  //Note: you must use the VAL keyword in frml files
FRML _i Y = %c*X1 + (1-%c)*X2;

 

The parameter value must be located inside the model file itself, either before or after the FRML statement(s) using it.

 

 


 

Gekko models: supported functions

 

In addition to the normal functions like log(), exp(), abs(), pow(), the following functions are possible:

 

Name

Description

Possible on left-hand side

dif(x) or

diff(x)

Absolute time-difference

yes

dify(x) or diffy(x)

Yearly absolute time-difference

yes

dlog(x)

Logarithmic time-differences

yes

dlogy(x)

Yearly logarithmic time-differences

yes

lag(x, lag)

Lags x a number of periods. Note the sign of the lag: lag(x, 2) = x[-2]. Can be used if x is an expression.

no

max(x1, x2)

Max of the two values

no

min(x1, x2)

Min of the two values

no

movavg(x, lags)

Moving average

no

movsum(x, lags)

Moving sum

no

pch(x)

Percent time-difference

yes

pchy(x)

Yearly percent time-difference

yes

 

 

 


 

Gekko models: variable list

 

You may add a variable list with variable explanations at the end of the model file (.frm), after a VARLIST$ (or VARLIST;) tag. The list can be 'folded', using indices like qJ{j}{i}. The list must be in UTF-8-format, if for instance 'æ', 'ø' and 'å' or other special characters are to be shown correctly. In Notepad, you can choose encoding UTF-8 under 'Save as'. These variable explanations show up in for instance DISP or DECOMP.

 

An example:

 

FRML Qu = ......... ;
FRML fMz01 = ......... ;
 
VARLIST$
----------
Qu
Antal beskæftigede i alle erhverv ekskl. landbrug mv.
(1000 pers.)
Kilde: Statistikbanken, NAT18, branche: jf. fX{j}
 
----------
fMz{i}     i=01,2,3q,59,s
Den del af importgruppe {i}, der har en generel substitutionselasticitet til dansk produktion
(mio.kr., 2005-priser, kædede værdier)
Kilde: Nationalregnskabet
Beregning: fMz{i} = Mz{i}/pm{i}
----------

 

Note that each variable has a section delimited by '------'. The rules are as follows:

 

Every variable section must end with a line with "---" (at least three of these). The variable list as a whole must end with such a line in order to get the last variable section read.

You may use {}-placeholders that are auto-unfolded. If you need more than one list in one section, the lists can be delimited by blanks or ';'. Example: qJ{j}{i} j=t,e;i=a,b (compact) or qJ{j}{i} j = t, e   i = a, b (more spacing).

The index inside the {}-placeholder can be an arbitrary letter, but only one letter.

The lists can be of arbitrary depth/dimension, for instance: qJ{i}{j}{k}{m} i=a,b;j=1,2;k=x,y;m=nm,nk.

The lines following the first line (with the variable name) are descriptions. All {}-placeholders are in-substituted in the descriptions, too.

You can use an arbitrary number of description lines. For instance, (1) description, (2) unit, (3) source, (4) calculation. You may use empty description lines.

 

Instead of putting the variable list in a model (.frm) file, it can instead exist in a stand-alone file called varlist.dat (without the VARLIST$ line).

 


 

Gekko models: examples

 

If the model file name is simple.frm, you may load the file as follows:

 

model simple;

 

Note that extension '.frm' is automatically added if it is missing (you may alternatively use model *; to choose the model in Windows Explorer).

 

Consider the following model file (called simple.frm):

 

FRML _I     y  = c + i + g;
FRML _S     c  = (- Dc) * (0.* y + 0.* y[-1] + Jc) + Dc * Zc;
FRML Y      Jc = c - (0.* y + 0.* y[-1]);
FRML Y      Zc = c;
FRML T      cy = c/y;
FRML P      ye = (y2[-1] + y2 + y2[+1])/3;  //y2 can be read as y
 
// --------------------------------------------------------
RUNAFTER$  
series  <%__simt1 - 2 %__simt2    >   y2 = y;
series  <%__simt2 + 1 %__simt2 + 1>   y2 %= 0;
predict <%__simt1 - 1 %__simt2    >   ye;
 
// --------------------------------------------------------
VARLIST$
----------
y
Gross domestic product
(US dollars)
Source: Eurostat
 
----------
c
Consumption
(US dollars)
Source: Eurostat
----------

 

The two first equations are the 'real' equations which are simultaneous and are simulated in a SIM statement. The two next Y-type equations are technical, making it possible to use Dc = 1 to exogenize c via Jc (cf. descriptions above, and see below how to autogenerate these Y-type equations via equation codes). These equations are not part of the simulation, but are run after each simulated period. The T-type equation calculates a table variable that is not part of the simultaneous part of the model. Like the two Y-type equations, this equation is run after each simulated period (the equation calculates a simple consumption share for later tabelling).

 

The P-type equation calculates a variable ye (expected y) from another variable y2. This variable is essentially just y, but extended with a constant value after the simulation period. This equation is ignored by SIM, and can only be used together with the PREDICT statement. In the RUNAFTER$ part of the model, the ye equation is called via such a PREDICT statement, and the equation is calculated one year before the simulation start, because ye it depends on leaded y-values and therefore must be updated before simulation start.

 

Instead of the two manually constructed Y-type equations above, you may instead use this equation for c:

 

FRML _SJ_D  c  = 0.* y + 0.* y[-1];

 

This equation code automatically emits the two Y-type equations in the above example.

 


 

Gekko models: note

 

You cannot use broken lags, for instance x[-0.3]. This will perhaps be added later on (would be translated into 0.7*+ 0.3*x[-1]). Leads like x[+1] are allowed.

 

For exponents, please use either a^b or a**b (in addition, pow(a,b) is also possible).

 

Comments: use // to out-comment the rest of the line or /* ... */ to comment out several lines.

 

You may put meta-information into the model file (.frm). As of now, Info, Date, Freq, and Signature fields are supported. Example (to be put in the top of the model (.frm) file):

 

// Info: Model used for forecasting 2012-2030
// Date: 7-11-2012 15:37:00

// Freq: q
// Signature: fp88RzyZfJNaoTi3I4X3Ww

 

Gekko will complain if this format deviates, for instance the Info field is to be written with capital 'I', with no blank before the colon, and one blank after the colon. This rigorousness regarding form is to make it easy to spot the information in different .frm files.

 

The Info, Date and Freq (if q or m) fields will be displayed when loading the model (MODEL statement), and the Signature field is used for verifying that .frm files have not been changed relative to an 'official' version. The signature for a particular .frm file can be obtained with the SIGN statement. For quarterly or monthly models it can be an advantage to state the frequency explicitly, else Gekko may complain that an option freq = ... ; should be set before the MODEL statement.

 

If you have a variable that is defined implicity, for instance as f(x) = 0, but where the x cannot be isolated, you may use the following pattern:

 

FRML _d   x = x + f(x);

 

where f(x) is an expression where x cannot be isolated. If you choose option solve method = newton, an equation like the above should solve just fine with SIM.

 


 

GAMS models

 

You may load a GAMS model in two ways: either as "raw" GAMS equations, or as "unrolled" GAMS equations.

 

Raw: or instance, the raw GAMS equation E_y .. y[i, t] =E= sum(j, x[i, j, t]); could be translated into the corresponding Gekko statement y[#i] = sum(#j, x[#i, #j]);, and Gekko can use such translated "raw" equations in the DISP statement and other places.

Unrolled: Gekko also supports the use of "unrolled" scalar GAMS euations. If in the above GAMS equation i runs over a and b, and j runs over x and y, the raw equation can be unrolled into the following (for the year 2020 here): y[a, 2020] = x[a, x, 2020] + x[a, y, 2020]; and y[b, 2020] = x[b, x, 2020] + x[b, y, 2020]; These equations are in a sense "atomic", and Gekko uses them for the DECOMP statement, because they are precise and unequivocal.

 

To load raw GAMS equations, use for instance MODEL <gms> eqs.gms;, where the equations are contained inside the .gms file. Gekko will search for .. inside the .gms file to locate the equations.

 

To load unrolled equations, you need to construct a .zip file with suitable unrolled equations. Per default, you may use the following file names inside the .zip:

 

gams.gms: Unrolled equations

dict.txt: Dictionary with real variable names

raw.gms: Raw GAMS equations (optional)

 

The unrolled equations and the dictionary can be produced by GAMS' convert statement. A simple example:

 

raw.gms

 

set t / 2000, 2001, 2002, 2003 /;
set t0[t] / 2001, 2002 /;
variable y[t], c[t], g[t];
y.l['2001']  = 499; y.l['2002']  = 531;
c.l['2001']  = 459; c.l['2002']  = 471;
g.fx['2001'] = 40;  g.fx['2002'] = 60;
y.fx['2000'] = 500; y.fx['2003'] = 540;
equation e1[t], e2[t];
e1[t] $ t0[t] ..  y[t] =E= c[t] + g[t];
e2[t] $ t0[t] ..  c[t] =E= 0.* y[t-1] + 0.* y[t] + 0.* y[t+1];
model m /all/ ;
option mcp=convert;
solve m using mcp;

 

Run this file in GAMS, for instance with the Windows DOS call /...gams_path/gams.exe raw.gms, which produces the two files gams.gms and dict.txt. If you do not want to set option mcp=convert; inside your GAMS file, drop the line and instead use the call /...gams_path/gams.exe raw.gms solver=convert. Zip gams.gms, dict.txt and raw.gms into simple.zip (or download here if you like). Put simple.zip in your Gekko working folder, and try this (in Gekko):

 

model<gms>simple.zip;
<2000 2003> = 500, 499, 531, 540;
<2001 2002> = 459, 471;
<2001 2002> = 40, 60;
decomp <2002 2002> y;

 

This fires up DECOMP, using the equations inside simple.zip. Because there are no Ref databank values, the decomp cannot show multiplier decompositions.

 

Inside the .zip file you may optionally put a ModelInfo.json file describing file names, for instance:

 

ModelInfo.json
 

{
   "unrolledModel": "gams.gms",     //GAMS scalar model, with variables x1, x2, x3, ... (GAMS output)
   "unrolledNames": "dict.txt"      //Translation of x1, x2, x3, ... into "normal" variable names (GAMS output)

   "rawModel":      "raw.gms",      //Raw model eqs (optional)
}

 

Default values are gams.gms, dict.txt and raw.gms as shown above, so if you are using these names inside your .zip file, you do not need a .json file. You may put other helper files in the .zip file if you wish (for instance databanks etc.). If your equations are scattered inside a system of GAMS files, you have to assemble these files into a single .gms file, but Gekko does not care about extraneous code inside such a file (it only locates the equations, searching for ..).

 

Gekko does not (at the moment) offer to solve a full GAMS model with the SIM statement, but residuals can be computed with SIM<res>.

 

 


 

Related options

 

OPTION folder model = [empty];

OPTION model type = default;  //default | gams

OPTION model gams dep current = no; //yes | no

 

 


 

Related statements

 

SIM, SERIES, READ