This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Installation

How you can obtain and install PM.

    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. Please note that Python 3.7 or later is required to install and use PM.

    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 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 PM are listed in the file requirements.txt, and can be installed using pip:

    Installing PM

    On both Ubuntu and macOS with Homebrew, pip can be used to install python dependencies, compile fortran, and install PM. The installation step can be executed with either the regular mode:

          pip install .
    

    or in editable mode:

          pip install -e .
    

    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. However for the extensions of the module that are written in FORTRAN, the module requires recompilation to reflect any changes to the source code. 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
       activate-global-python-argcomplete
    

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

      # append to ENVNAME/bin/activate
      source ${VIRTUAL_ENV}/../pm-completion.sh
    

    Restart the environment to activate changes.