<< Click to Display Table of Contents >> Navigation:  »No topics above this level« Introduction - Gekko Source Code Documentation

March 2021

 

 

This is the Gekko 3.0 source code documentation (for the excact Gekko version 3.1.12), building upon the prior version of the source code documentation from 2014. That version was written for Gekko 2.0, and there are so many source code changes between Gekko 2.0 and 3.0 that a new version of the source code documenation is warranted. The Gekko 2.0 source code documentation can be found here.

 

Together with the API (application programming interface, detailing the structure of what goes in and out of different classes/objects and their methods), this should enable persons with a reasonable understanding of programming and .NET to alter the source code of Gekko, and for instance alter an existing component or develop new components.

 

Beware that this documentation (or the API) is different from a help system explaining how to use Gekko, including how to use Gekko commands and command files. The material here is for programmers and people who would like to look into the inner workings of Gekko. Normal users should consult the Gekko help system that comes pre-installed with Gekko (type F1 in Gekko), or can be found here.

 

 

What is Gekko?

 

Gekko is a free open-source software package for timeseries management and for solving and analyzing large-scale economic models. Gekko started out being primarily focused on solving models, but in later years the focus has also been oriented towards creating a user-friendly environment for the general handling and "wrangling" of timeseries data.

 

The software runs under Windows (.NET), and is open source (GNU GPL). It is written in C#, which is a modern object-oriented language with automatic garbage-collection. C# was chosen because it on the one hand offers the necessary raw speed to make the software run reasonably fast, and on the other hand is a language with high programmer productivity, because the object orientation makes it possible to keep the C# code well-structured. C# does not allow so-called pointers, and is in this sense a managed language. This adds stability to the program, but there is a small overhead to such managed code (which is well worth the price). There are faster languages in existence, such as for instance Fortran, C or C++, but C# keeps itself pretty speedy via dynamic just-in-time compilation (JIT). In some cases the C# JIT may even outperform statically compiled languages like Fortran, C or C++, but in general C# is somewhat but not dramatically slower.

 

Gekko programs are compiled before they are run. That is, the Gekko commands are first translated into corresponding C# code, and then executed (this preserves speed and is in contrast to so-called interpreted languages).

 

C# and .NET also provides easy and seamless building of the graphical interface (GUI). The user interface is mostly WPF, cf. this Gekko blog post.

 

 

About priorities in this documentation

 

When writing this documentation it became clear that not all components could be explained with the same level of details (within the allocated resources). Some prioritization had to be made, and it was decided to focus much of the attention on those basic Gekko components that are most vital for running Gekko command files. These components are primarily variables of different kinds (timeseries, scalars and collections), forming expressions when combined with mathematical operators and functions, for subsequent use in statements. In addition, a lot of effort has gone into explaining the parser that converts Gekko programs into first a tree structure (AST tree), and next into corresponding C# code that mirrors the Gekko command (file). This level of detail has to do with the fact that for new users of the source code, the parser part of Gekko is probably the most challenging.

 

Other "difficult" components are also explained in depth, cf. this page. Regarding the "easier" parts of the Gekko source code, these are not (yet) explained in depth in the present source code documentation, but the methods still contain quite a lot of comments, and the purpose of these methods is typically quite clear.

 

 

Results/benefits

 

The current rewrite of the source code documentation (in 2020) was financed by Statistics Denmark. As mentioned, there was an older source code documentation available (from 2014), but this documentation targeted Gekko 2.0.

 

When Gekko transferred from version 2.0 (or to be precise: version 2.4) to Gekko 3.0, at least half of the source code was completely rewritten. This rewrite was done in order to clean up the syntax, and -- among other things -- make it possible to operate on databanks and variables in a much more flexible and modern way.

 

So when assembling the Gekko 3.0 version, there was a lot of translation of C# code taking place, and a lot of code was run simultaneously in two versions concurrently (compatible to Gekko 2.0, and compatible to Gekko 3.0) for testing purposes. As Gekko 3.0 matured and was ultimately released, there was still a lot of "debris" left: that is, C# code that corresponded to syntax and components in Gekko 2.0, but was now obsolete.

 

A lot of the work regarding the current source code documentation has also revolved around cleaning up the C# code itself. Removing all the obsolete debris, and organizing the code in more isolated components (classes). In addition to this, a lot of methods have been cleaned up and annotated, so that an API documentation can be produced.

 

There is still work to do regarding the C# source code. But dramatic changes like the change from Gekko 2.0 to 3.0 are not expected anytime soon, and it is the intention to gradually annotate all C# methods in the source code (that have not already been annotated), and to keep the source code itself and the current source code documentation in sync.

 

All in all, the C# source code is much, much more organized now (March 2021), compared to how it was in 2020 and before. This, combined with the upgraded source code documentation, also affects the developing speed when the programmer adds new components or adjusting existing code. The whole code is simply much more transparent now.