.. index:: install

.. _install:

Installation
============

principia-materia (PM) consists of Python codes with C++ and Fortran
extensions. There will soon be a variety of options for installing PM, but we
presently recommend cloning the git repository, creating a virtual environment,
installing the required dependencies, and compiling the source code. 
We also provide the option of having auto-completion at the Bash shell using argcomplete.


..
 Install from PyPI
 -----------------

 If you use ``pip``, you can install principia-materia with:

 .. code-block:: bash

       pip install principia-materia


 Install from Conda
 ------------------
 
 If you use ``conda``, you can install principia-materia with:
 
 .. code-block:: bash
 
       conda install -c principia-materia


 Using Docker image
 ------------------

 If you use ``docker``, you can install principia-materia with:

 .. code-block:: bash

       docker pull marianettigroup/principia-materia

Obtaining the source code
---------------------------

Clone the git repository:

.. code-block:: bash

  git clone git@github.com:marianettigroup/principia-materia.git

Using a Virtual Environment
---------------------------

A virtual environment is recommended when working with PM.
To setup a virtual environment:

.. code-block:: bash

  python3 -m virtualenv ENVNAME 

(replace ``ENVNAME`` with the name you choose for the environment).

To launch the environment, issue the following command:

.. code-block:: bash

  source ENVNAME/bin/activate

This virtual environment will be launched whenever running PM.


Installing dependencies
------------------------

The PM package depends on several external libraries::

      openmp, lapack, blas, gcc, gfortran

* For Ubuntu 18.04 and later with gcc compilers::

      sudo apt install gcc gfortran libopenblas-dev libgomp1 libhdf5-dev

* For macOS with Homebrew::

      brew install gcc openblas

Required python modules for the packge are listed in the file ``requirements.txt``::

      pip install --upgrade -r requirements.txt

Compiling PM
--------------

The final step is compiling the source code.

* For Ubuntu 18.04 and latear with gcc compilers::

      python setup.py build

* For macOS with Homebrew::

      CC=gcc-11 CXX=g++-11 F90=gfortran-11 python setup.py build

The installation step can be executed with either the regular mode ::

      python setup.py install

or the *development* mode ::

      python setup.py develop

with the latter offering more flexibility during development, where the
repository is dynamically link to serve as the python module so that any
changes to the code can come in effect without reinstalling the module. However
for the extensions of the module that is written in either C or FORTRAN, the
module requires recompilation to reflect any changes to the source code.
We currently recommend installing in the development mode, given that many 
changes are still being made to the code.



Setup Shell Auto-Complete
-------------------------

The auto-complete feature is optional, and is realized with `argcomplete <https://kislyuk.github.io/argcomplete>`_ module.
To activate this feature, in Bash for example, install the moculde first:

.. code-block:: bash

   pip install argcomplete
   activate-global-python-argcomplete

then within the virtual environment source the ``pm-completion.sh`` script in activation script ``ENVNAME/bin/activate``:

.. code-block:: bash

  source ${VIRTUAL_ENV}/../pm-completion.sh