Setup and compliance with IT policies

General

Our framework is, in principle, platform independent. The components are:

• Python 3 (64 bit), including packages such as SciPy, Matplotlib, and Sphinx
• C++ compiler(s): g++ and possibly others
• C++ libraries: Boost, possibly others
• LaTeX

Details

• It is preferable to download a Python 3 distribution rather than Python from http://www.python.org, as distributions come with several packages we use. Otherwise, you will have to install the packages yourself. There are several Python distributions for Windows. A good distribution for Mac OSX and Linux is Anaconda. (On Linux, you could also use your Linux distribution’s package manager instead of downloading a Python distribution.)
• Sphinx, if it does not already come with your Python distribution. (This document is written in Sphinx.)
• MatplotLib, if it does not already come with your Python distribution. (The plots in this document were produced by Matplotlib.)
• SciPy, if it does not already come with your Python distribution.
• On Mac OSX and Linux, g++ comes with the system (on OSX, g++ is actually clang++). On Windows, we use MinGW, from http://www.mingw.org or http://mingw-w64.org/doku.php. In addition, we use MSYS on top of MinGW so that we can enter Unix-like shell commands. Alternatively, you should be able to use Cygwin.
• Download a LaTeX distribution, such as MiKTeX for Windows or MacTeX for Mac OSX. This is used to render math equations in Sphinx or write stand-alone LaTeX documents. It should come with a package manager.

Once you have downloaded and installed everything, you will need to make sure it all works as expected. You may need to set a few environment variables.

1. When you enter “python” at the command line, you should end up using the Python you just installed. You can also enter “which python”. If the command is not recognized or points to a different Python installation, you will need to add the location of your Python installation to your PATH environment variable.
2. The following commands should be also recognized: g++, make, sphinx-quickstart, and latex.
3. In order to be able to build C++ Python extensions (i.e., invoke C++ libraries from Python), you will need to find the location of the include directory (that contains the file “Python.h”) in your Python installation. This can vary widely between distributions. You can follow this https://en.wikibooks.org/wiki/Python_Programming/Extending_with_C, or simply search for the file “Python.h”. Then set an environment variable pointing to that directory.
4. Your Python session must know where to look for the Python modules and C++ libraries you import in your scripts. This is done via the PYTHONPATH environment variable.

Streamlined processes

There are two kinds of processes we streamline:

1. Building C++ libraries from the C++ source. They work just like the proof of concept library we demonstrated: C++ library implementation. Of course, in order to build large libraries you should write a makefile system.
2. Building any documents similar to this one (documentation, studies, reports, etc). This is done by entering “build html” at the command line. This will build the document from Sphinx source files and run all the Python scripts (invoked from within the Sphinx source files) responsible for producing the displayed results.

This is just a framework; many variations are possible. For example, parts of the results can be precomputed by running the Python scripts in advance. Instead of using the plot directive (see rst source file), one can edit the defauft Makefile generated by Sphinx (the makefile used to build this document).

Build this document

1. Choose your platform (Mac OSX, Linux, or Windows) and packages, as explained above.

2. Download the source code (please contact).

3. Set up the environment variables. There are many ways to do this, depending on the platform. The following .bash_profile file was tested on MacOSX and Linux, with Anaconda Python installed in the home directory, and the source code from GitHub also in the home directory. It should work fine on Windows, if you use Bash/MSYS, not cmd.exe. Alternatively, you can set the environment variables from the Windows control panel.

   # added by Anaconda3 2.5.0 installer
   export PATH="~/anaconda/bin:$PATH"
   
   # This is different for different Python distributions.
   # Path to directory containing Python.h
   export PYTHONINCLUDE="~/anaconda/include/python3.5m/"
   
   # This tells Python where to look for the Python modules and C++ libraries used in the script.
   export PYTHONPATH=... enter path to the directory containing this documentation
   export PYTHONPATH="$PYTHONPATH/LibCPPExample/build/:$PYTHONPATH"
   

4. Build the C++ library. Go to the directory LibCPPExample and execute (the commands in) the file commands... - depending on your platform.

5. Build the document. Go to the directory Documentation and enter “build html” at the command line.

Compliance with IT policies

Our framework does not require any special arrangements or exceptions other than be allowed to dowload the software and tools locally.

We use well-known, widely-used open source packages that are self-contained “bubbles”. Unless we have no choice, we do not write to the windows registry (in case we have to build our framework under windows).