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.

Obtaining the source code

Clone the git repository:

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:

python3 -m virtualenv ENVNAME

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

To launch the environment, issue the following command:

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 module. To activate this feature, in Bash for example, install the moculde first:

pip install argcomplete
activate-global-python-argcomplete

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

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