2. Installation

2.1. Introduction

LIAM2 is cross-platform. It has been reported to run on Windows, Mac OS X and Linux. Installation is easier on Windows because we provide a self-contained bundle containing an executable (which includes all dependencies), a text editor, documentation and a demonstration model. If you want to install LIAM2 on other platforms (Mac OS X or Linux) or change the framework itself, you have to install from source.

2.2. Install using the Windows bundle

Extract the contents of the bundle in a directory on your disk (let us call it <BUNDLEPATH>). The name of this directory and the path leading to it should not contain any “special” (non-ASCII) characters.
Create a shortcut to <BUNDLEPATH>\editor\Notepad++Portable.exe, for example by right-clicking on it and using “Send to” -> “Desktop (create shortcut)”.
You are ready to run your first model.

2.3. Install from source

To install LIAM2 from source, you first need to install LIAM2 dependencies then install LIAM2 itself from source.

2.3.1. Install LIAM2 dependencies

LIAM2 is built on top of a number of other open-source packages. See below for the different ways to install them.

Required dependencies:

Python 3.10+ (64b) - http://www.python.org/
Numpy 1.8.0 or later - http://www.numpy.org/
PyTables 3 or later - http://www.pytables.org
Numexpr 2.0 or later - https://github.com/pydata/numexpr
PyYAML 3.0.8 or later - http://pyyaml.org
Cython 0.16 or later - http://www.cython.org/

Optional dependencies:

to view hdf5 files: vitables 2.1 or later - http://vitables.org

It requires PyQt
to generate plots and charts: matplotlib 1.2 or later - http://matplotlib.org/
to build the documentation to html (other formats need additional packages):

Sphinx 1.0 or later - http://www.sphinx-doc.org/
to import data with interpolation/data with missing data points (eg several time series with different dates for the same individual):

bcolz 0.7 or later - https://github.com/Blosc/bcolz
to create standalone executables:

Nuitka

There are several options to install all those packages. In order of increasing difficulty:

Using Miniconda (all platforms)
Getting binary packages using apt-get (GNU/linux debian-based distributions)

2.3.1.1. Using Miniconda (all platforms)

Install Miniconda for your platform (Python 3.X). We recommend using the 64-bit version if you have a 64bit OS. https://conda.io/miniconda.html
Install required dependencies by typing in a command prompt:
```
conda install numpy pytables numexpr pyyaml cython
```
You can also install the optional dependencies:
- to generate plots and charts:
```
conda install matplotlib qtpy pyqt
```
- to view hdf5 files via vitables:
```
pip install vitables
```
- to build the documentation to html (other formats need additional packages):
```
conda install sphinx
```
- to import data with interpolation/data with missing data points (e.g. several time series with different dates for the same individual):
```
conda install bcolz
```

2.3.1.2. Getting binary packages using apt-get (GNU/linux debian-based distributions)

Install the required dependencies:

sudo apt-get install python python-numpy python-tables python-numexpr python-yaml cython

You can also install the optional dependencies:

to view hdf5 files via vitables:
```
sudo apt-get install python-vitables
```

to generate plots and charts:

sudo apt-get install python-matplotlib python-dateutil python-pyparsing

to build the documentation to html (other formats need additional packages):
```
sudo apt-get install python-sphinx
```
to import data with interpolation/data with missing data points (e.g. several time series with different dates for the same individual):
```
pip install bcolz
```

2.3.2. Install LIAM2 itself from source

Download the zip file (e.g. LIAM2-0.13.0-src.zip) from LIAM2 website.
Unzip into a directory of your choice. Let us call that directory <SOURCEPATH>. For example
```
Programs/LIAM2-0.13.0-src/
```
Open a terminal (Mac Terminal, gnome-terminal, konsole, xterm, …)
Change into the directory into which LIAM2 has been unzipped (<SOURCEPATH>). For example:
```
cd Programs/LIAM2-0.13.0-src/
```
Run installation of LIAM2
```
python setup.py install
```
You are ready to run your first model.

2.3.2.1. Building the C extensions manually

Additionally, if you want to get maximum performance, you need to have the C extensions built and compiled. If all goes well, this was done automatically in the “python setup.py install” step above but in case it failed for some reason, you might need to do it manually.

For that you need to have Cython (see above) and a C compiler installed, then go to the root directory of LIAM2 and type:

python setup.py build_ext --inplace

If all goes according to plan, you should then be up and running.

2.3.2.2. Building the documentation

make sure both <PYTHONDIR> and <PYTHONDIR>/Scripts are in your system PATH where <PYTHONDIR> is the directory where you installed Python
Install sphinx
Open a command prompt
Go to the documentation directory. For example:
```
cd liam2/doc/usersguide/
```
Launch the build:
```
make html
```
Open the result in your favourite web browser. It is located in:
```
build/html/index.html
```