Introduction > A quick primer on parsing

Gekko offers its own programming environment, via so-called command files (or interactive typing of commands into the user interface). The command files contain Gekko commands to be executed, and the syntax of these commands suits the time-series oriented nature of Gekko. When a command file is run in Gekko, the command file is translated into a correspond C# statements (which are dynamically compiled and run). The same applies to equations in models: these are also translated into C# code (albeit somewhat simpler code).

So in this sense, the core part of Gekko can be thought of as two components:

1.A translator that translates Gekko commands (or models) into corresponding C# code

2.A C# library of classes and methods to handle models, timeseries, scalars, lists, databanks etc.

Below is an example of how the translation is done. Much more details on this can be found in the section on parser and object structures.

Example

Consider this Gekko command (setting the timeseries x1 to the value 150 for the period 2010-15):

x1 <2010 2015> = 150;

The command would be translated into the following C# code (simplified a lot to just provide a rough idea):

O.Lookup("x1", 2010, 2015, "=", 150);

In the Gekko C# library, there is a corresponding Lookup() method, which could look a bit like the following:

Lookup(string name, int per1, int per2, string operator, double value) {
  //simplified lookup code to deal with an annual timeseries
  for (int per = per1; per <= per2; per = per + 1) {
    GekkoTime t = new GekkoTime(EFreq.A, per, 1);
    GetDatabank("Work").GetIVariable(name + "!a").SetData(t, value);
  }
}

(Above, we skipped an if statement regarding the operator, which can be for instance =, *=, +=, etc.). The above code loops the integer per from 2010 to 2015, and for each per, a corresponding GekkoTime t is created. Next, the variable x1!a is fetched from the Work databank, and the value for each t is set to 150.

The actual Gekko code for doing this is a bit more complicated, but the structure is the same. The above code relies heavily upon Gekko-specific components (classes/methods), such as Databanks (the hierarchical list of databanks), Databank (a particular databank object), and Series (the actual storage of sequential timeseries data).

The translation of Gekko code into C# is done by means of a parser, more specifically the open-source ANTLR parser (ANTLR version 3). In order to do the translation, a parser grammar must be defined, and the ANTLR grammar corresponding to the series statement looks a bit like this:

assignment: type? name ('<' dates '>')? '=' expression;

The ? indicates that the type and the <> brackets are optional. A statement x1 <2010 2015> = 150; may include type indicator, for instance series x1 <2010 2015> = 150; , and it may omit dates, for instance x1 = 150;. In the rule above, dates is another rule that expects two consecutive dates (or expressions). Besides, a variable name must be stated, and a = must be present before the right-hand side expression. (expression matches the value 150). In this way, the parser splits up the Gekko commands, and the "real" grammar also includes code that transform the rules into a tree structure (AST tree).

The library part of Gekko uses pretty basic C#, with classes and methods etc. Some of the classes and methods are of course relatively complicated, but not more so than code in any other large and complicated project. For instance, databanks are really just C# Dictionaries referring a given string (for instance "Work") to another Dictionary (databank), containing the variables. A bit more complicated is how a timeseries object stores the individual data points (this is done by means of an auto-resizing array, much more on this here).

In reality, the parser is more complicated than that, and hence the parser and the way dynamic C# code is emitted via the parser is described pretty thoroughly on subsequent pages, so that these components hopefully do not evolve into some kind of black box that looks intimidating from the outside.