5. Developers Installation

5.1. Python Language Installation

If you already have a suitable python-3 installation with all scientific packages updated to their latest versions, you may skip this 1st stage.

Note

Installing Python under Windows:

The program requires CPython-3, and depends on numpy, scipy, pandas, sklearn and matplotlib packages, which depend on C-native backends and need a C-compiler to install from sources.

In Windows it is strongly suggested NOT to install the standard CPython distribution that comes up first(!) when you google for “python windows”, unless you are an experienced python-developer, and you know how to hunt down pre-compiled dependencies from the PyPi repository and/or from the Unofficial Windows Binaries for Python Extension Packages.

Therefore we suggest that you download one of the following two scientific-python distributions:

5.1.1. Install WinPython

  1. Install the latest python-3.6+ 64 bit from WinPython Prefer an installation-folder without any spaces leading to it.

  2. Open the WinPython’s command-prompt console, by locating the folder where you just installed it and run (double-click) the following file:

    <winpython-folder>\"WinPython Command Prompt.exe"
    
  3. In the console-window check that you have the correct version of WinPython installed, and expect a similar response:

    > python -V
    Python 3.6.1
    
    REM Check your python is indeed where you installed it.
    > where python
    ....
    
  4. Use this console and follow Install CO2MPAS python packages instructions, below.

5.1.2. Install Anaconda

The Anaconda distribution is a non-standard Python environment that for Windows containing all the scientific packages we need, and much more. It is not update-able, and has a semi-regular release-cycle of 3 months.

  1. Install Anaconda python-3.6+ 64 bit from http://continuum.io/downloads. Prefer an installation-folder without any spaces leading to it.

    Note

    When asked by the installation wizard, ensure that Anaconda gets to be registered as the default python-environment for the user’s account.

  2. Open a Windows command-prompt console:

    "windows start button" --> `cmd.exe`
    
  3. In the console-window check that you have the correct version of Anaconda-python installed, by typing:

    > python -V
    Python 3.6.1 :: Anaconda 2.3.0 (64-bit)
    
    REM Check your python is indeed where you installed it.
    > where python
    ....
    
  4. Use this console and follow Install CO2MPAS python packages instructions, below.

5.2. Install CO2MPAS python packages

Note

Since co2mpas-2.0.0 the python code of CO2MPAS had been splitted in 4 packages depicted below with their dependencies:

co2sim[io,plot]
    /\
   / co2dice
  /  /
co2gui
   |
co2mpas

So everything depends on co2sim, and co2mpas is now a virtua; package, which does not contain any python-code.

  1. Assuming you have unhindered connection to the internet, first ensure that you have the latest pip installed. Follow the standard instructions on other platforms: https://pip.pypa.io/en/stable/installing/#upgrading-pip

    Tip

    From the AIO CONSOLE, run this script:

    Warning

    Installation failures:

    The previous step require http-connectivity for pip command to Python’s “standard” repository (https://pypi.python.org/). In case you are behind a corporate proxy, you may try one of the methods described in section Alternative installation methods, below.

    If all methods to install CO2MPAS fail, re-run pip command adding extra verbose flags -vv, copy-paste the console-output, and report it to JRC.

  2. Uninstall any old CO2MPAS package(s):

    pip uninstall -y co2sim co2dice co2gui co2mpas
    
  3. Re-install (or upgrade) all CO2MPAS packages:

    pip install co2mpas -U
    

    You may optionally install just the simulation-model:

    pip install co2sim[io,plot] -U
    

    …or install it without the io and plot “extras”, if you want to use just the simulation core:

    pip install co2sim -U
    
  4. Check that when you run CO2MPAS, the version executed is indeed the one installed above (check both version-identifiers and paths):

    > co2mpas -vV
    co2mpas_version: ...
    co2mpas_rel_date: ...
    co2mpas_path: d:\co2mpas_AIO\Apps\WinPython\python-3.6.1\lib\site-packages\co2mpas
    python_path: D:\co2mpas_AIO\WinPython\python-3.6.1
    python_version: 3.6.1 (v3.6.1:9b73f1c3e601, Feb 24 2015, 22:44:40) [MSC v.1600 XXX]
    PATH: D:\co2mpas_AIO\WinPython...
    
    > co2dice config paths
    APP:
      co2dice_path: co2mpas_AIO\apps\winpython\python-3.6.1.amd64\lib\site-packages\co2dice
      python_path: co2mpas_AIO\apps\winpython\python-3.6.1.amd64
    VERSIONS:
      co2dice_release: ...
      co2dice_updated: ...
      dice_report_ver: 1.0.2
      python_version: 3.6.1 (v3.6.1:69c0db5, Mar 21 2017, 18:41:36) [MSC v.1900 64 bit (AMD64)]
    CONFIG:
      config_paths:
        - D:\Work\ALLINONE\co2mpas_AIO-1.7.3\CO2MPAS\.co2dice\co2dice_config.py
      persist_path: D:\Work\ALLINONE\co2mpas_AIO-1.7.3\CO2MPAS\.co2dice\co2dice_persist.json
      LOADED_CONFIGS:
        - D:\Work\ALLINONE\co2mpas_AIO-1.7.3\CO2MPAS\.co2dice\:
    ENV_VARS:
      AIODIR: D:\Work\ALLINONE\co2mpas_AIO-1.7.3\
    

    Note

    The above procedure installs the latest CO2MPAS, which might be more up-to-date than the version described here!

    In that case you can either:

    1. Visit the documents for the newer version actually installed.
    2. “Pin” the exact version you wish to install with a pip command (see section below).

5.2.1. Upgrade CO2MPAS (with internet connectivity)

  1. Uninstall (see below) and re-install it or use the pip install -U option.

5.2.2. Uninstall CO2MPAS

To uninstall CO2MPAS type the following command, and confirm it with y:

> pip uninstall co2sim co2dice co2gui co2mpas
Uninstalling co2mpas-<installed-version>
...
Proceed (y/n)?

Re-run the command again, to make sure that no dangling installations are left over; disregard any errors this time.

5.2.3. Alternative installation methods

You can install multiple versions of CO2MPAS, from various places, but all require the use of pip command from a console to install:

Tip

In all cases below, remember to uninstall CO2MPAS if it’s already installed.

Remember also to store the installation logs with the -v --log options, particularly if you install a specific version from GitHub

  • Latest STABLE: use the default pip described command above.

  • Latest PRE-RELEASE: append the --pre option in the pip command.

  • Specific version: modify the pip command like that, with optionally appending --pre:

    pip install co2mpas==1.0.1 ... # Other options, like above.
    
  • Specific branch from the GitHub-sources:

    pip install -v log pip.log git+https://github.com/JRCSTU/co2mpas.git@dev
    
  • Specific commit from the GitHub-sources:

    pip install -v log pip.log git+https://github.com/JRCSTU/co2mpas.git@2927346f4c513a
    
  • Speed-up download: append the --use-mirrors option in the pip command.

  • (for all of the above) When you are behind an http-proxy: append an appropriately adapted option --proxy http://user:password@yourProxyUrl:yourProxyPort.

    Important

    To avert any security deliberations for this http-proxy “tunnel”, JRC cryptographically signs all final releases with one of those keys: - GPG key ID: 9CF277C40A8A1B08 form @ankostis - GPG key ID: 1831F9C2294A33CC for @vinci1it2000

    Your IT staff may validate their authenticity and detect man-in-the-middle attacks, however impossible.

  • (for all of the above) Without internet connectivity or when the above proxy cmd fails:

    1. Use an existing Python-3.6 environment; that might be an older ALLINONE, WinPython, Anaconda or Linux’s standard python environment.

    2. With with a “regular” browser and when connected to the Internet, pre-download locally and unzip the respective co2mpas_DEPENDENCIES-vX.X.XXX.7z file from the latest ALLINONE release (e.g. http://github.com/JRCSTU/CO2MPAS-TA/releases/). This archive contains all the dependent packages of CO2MPAS.

    3. Install CO2MPAS, referencing the above folder. Assuming that you unzipped the packages in the folder path/to/co2mpas_packages, use a console-command like this:

      pip install co2mpas  --no-index  -f path/to/co2mpas_packages
      

5.2.4. Install Multiple versions in parallel

In order to run and compare results from different CO2MPAS versions, you may use virtualenv command.

The virtualenv command creates isolated python-environments (“children-venvs”) where in each one you can install a different versions of CO2MPAS.

Note

The virtualenv command does NOT run under the conda python-environment. Use the conda command in similar manner to create child conda-environments instead.

5.2.5. Install as a Docker

New in v2.0.x releases, there is the pCO2SIM/docker/ folder that contains the dockerfile to build a working CO2MPAS environment for Linux + Anaconda.

5.3. Autocompletion

In order to press [Tab] and get completions, do the following in your environment (ALLINONE is pre-configured with them):

  • For the Clink environment, on cmd.exe, add the following lua script inside clink’s profile folder: clink/profile/co2mpas_autocompletion.lua

    --[[ clink-autocompletion for CO2MPAS
    --]]
    local handle = io.popen('co2mpas-autocompletions')
    words_str = handle:read("*a")
    handle:close()
    
    function words_generator(prefix, first, last)
        local cmd = 'co2mpas'
        local prefix_len = #prefix
    
        --print('P:'..prefix..', F:'..first..', L:'..last..', l:'..rl_state.line_buffer)
        if prefix_len == 0 or rl_state.line_buffer:sub(1, cmd:len()) ~= cmd then
            return false
        end
    
        for w in string.gmatch(words_str, "%S+") do
            -- Add matching app-words.
            --
            if w:sub(1, prefix_len) == prefix then
                clink.add_match(w)
            end
    
            -- Add matching files & dirs.
            --
            full_path = true
            nf = clink.match_files(prefix..'*', full_path)
            if nf > 0 then
                clink.matches_are_files()
            end
        end
        return clink.match_count() > 0
    end
    
    sort_id = 100
    clink.register_match_generator(words_generator)