Developers’ section¶

Folders organization¶

GAMS code and scripts are included within the “GAMS-files” folder. The code should only be modified in that folder!
Python code and scripts are included within the “dispaset” folder.
DispaSET configuration files are included within the “ConfigFiles” folder (one file per simulation).
Input files for each country are stored in the “Database” folder
Simulation directories can be written into the “Simulations” folder, which is not tracked by git

A sample Simulation Environment Folder is available at SimulationReferenceTestCase. The files in this folders are generated automatically by the pre-processing scripts. They should not be modified. The folder should be replaced and updated at every major Dispa-SET release.

By default, the pre-processing scripts are set to generate the simulation environment within the “Simulations” folder. This folder is excluded in .gitignore and can therefore be used for testing purposes.

Math equations in the Docs¶

To use online mathjax (default), there is nothing to do but displaying the equation requires an internet connection. In linux, the Makefile call to build with mathjax is written:
```
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

In conf.py, the only math equation should be: 'sphinx.ext.mathjax'
```

To use pngmath (for Linux):

sudo apt-get install dvipng

In conf.py, add 'sphinx.ext.pngmath' in the extensions

in Makefile: $(SPHINXBUILD) -D pngmath_latex=latex -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

To use mathjax in offline mode, download the latest release from the mathjax github, copy it to Docs/_static/, and include it in the conf.py:
```
mathjax_path = "Mathjax/MathJax.js"
```

Using Autodoc¶

The “API” section of the Docs uses uses the sphinx autodoc extension to scan the source code of Dispa-SET and display the relevant functions together with their description, parameters and outputs. In the Sphinx “conf.py”, the path to the source file must be added:

sys.path.insert(0, os.path.abspath('../dispaset'))

If the API documentation is generated with sphinx-apidoc, from the Docs folder, use:

sphinx-apidoc -o . ../dispaset/

Add a link to “DispaSET” in the table of content of index.rst and include the root folder in conf.py:

sys.path.insert(0, os.path.abspath('../'))

Clone git repository to svn¶

Install git svn
```
sudo apt-get install git-svn
```
Create svn branch
```
git branch svn
```

Connect to svn repository

git svn init -s --prefix=svn/ --username <user> https://joinup.ec.europa.eu/svn/dispaset

Checkout svn banch
```
git checkout svn
```
Fetch remote content
```
git svn fetch
```
Reset repository
```
git reset --hard remotes/svn/trunk
```
Merge master into svn
```
git merge master
```
Commit to the remote repository
```
git svn dcommit
```

The folder can finally optionally be deleted to avoid any confusion.

Issue with the compilation of the GAMS API¶

First, check that the installed version of GAMS is the 64 bit. 32 bit versions tend to generated compatibility issues.

When the pre-compiled libraries do not work, they must be re-compiled from the GAMS apifile folder. In Windows, this generally raises the issue of the missing vcvarsall.bat file. If the issue persists after installing the Microsoft C++ compiler for Python 2.7, try the following:

Enter MSVC for Python command prompt
SET DISTUTILS_USE_SDK=1
SET MSSdk=1
python.exe gdxsetup.py install

Public version of Dispa-SET¶

Because some input files are subject to intellectual property and copyrights, some folders available on the private repository cannot by uploaded to the public GitHub repository. The script DispaSync.sh in the root folder has been written to synchronize the subset of publicly available folders and files with an external folder. This folder can then be committed and pushed to the public repository.

By default, all file and folders are synchronized. In order to add a private path (to a file or to a folder), edit the DispaSync.sh file and add an entry to the “–exclude” argument.

The “rsync” software is required for the synchronization and must be installed on the local machine. The script can be run in any UNIX terminal (i.e. it cannot be run in Windows).