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. At present, we provide a Makefile to facilitate this process. 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:

  python -m venv 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 external dependencies

PM requires several system-level dependencies, including a C compiler, a Fortran compiler, BLAS/LAPACK, OpenMP, and HDF5. Additionally, python3-venv and pip are recommended to support installation into a dedicated Python virtual environment.

• For Ubuntu 18.04 and later with gcc compilers

sudo apt install gcc gfortran libopenblas-dev libgomp1 libhdf5-dev python3-venv python3-pip

• For macOS with Homebrew

brew install gcc openblas python

Required python modules for PM are listed in the pyproject.toml file, and will normally be installed using pip (see below).

Installing PM

On both Ubuntu and macOS with Homebrew, pip can be used to install python dependencies, compile fortran, and install PM. For convenience, we provide a Makefile, which has various options. The installation step can be executed with either the regular mode:

      $ make install

or in editable mode

      $ make dev

In editable mode, the repository is dynamically link to serve as the python module so that any changes to the code come into effect without reinstalling the module, such that one can pull new changes and immediately use them. However for the extensions of the module that are written in FORTRAN, the module requires recompilation to reflect any changes to the source code (though this should be rare). We currently recommend installing in editable 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 the argcomplete module. To activate this feature in Bash, for example, install the module first:

   $ pip install argcomplete

   # for enabling locally within a shell (recommended)
   $ eval "$(register-python-argcomplete pm)"

   # for enabling globally (can be finicky)
   $ activate-global-python-argcomplete --user