Installation
NEoST is a Python software package that performs neutron star equation of state inference process. It is an open source package that is available on GitHub and can be cloned as:
git clone https://github.com/xpsi-group/neost.git
On this page we will describe how to install NEoST and its prerequisites.
Creating an environment and installing NEoST’s dependencies
NEoST was developed in Python 3. We recommend installing NEoST and its dependencies in a virtual environment. There are two main options for creating an environment and installing the dependencies: Python’s first-party package installer, pip, and the third-party Conda package manager. Using conda may be easier because while conda can install MultiNest, pip cannot. The downside is that you will have to install conda.
You need pip in both cases. It is likely already installed. If not, follow the official instructions for installing it.
Using pip
Two of NEoST’s dependencies, GSL (GNU Scientific Library) and MultiNest, are not written in Python and are as such not available in the Python package index (PyPI). They need to be installed separately.
GSL is widely available and can almost always be installed with your operating system’s package manager, or loaded with something like module load gsl
on a computing cluster. Alternatively you can compile it yourself using the official instructions, see Downloading GSL.
However you choose to obtain GSL, make sure it works by executing
gsl-config --version
which should print the installed GSL version.
MultiNest, on the other hand, must likely be compiled manually. Follow these steps (which assume that you have git
, a C++
compiler, cmake
, and make
installed):
git clone https://github.com/JohannesBuchner/MultiNest
cd MultiNest/build
cmake ..
make
You then need to add <path/to>/MultiNest/lib
to an environment variable called LD_LIBRARY_PATH
using
export LD_LIBRARY_PATH=<path/to>/MultiNest/lib:$LD_LIBRARY_PATH
Of course, exchange <path/to>
for the actual path where you cloned MultiNest. You can add the export command to your $HOME/.bashrc
file if you don’t want to execute it in every new terminal in which you’re running NEoST.
The next step is to create a virtual environment and install NEoST. In Python, the official way to create a virtual environment is by using the venv module:
python -m venv path/to/environment
where you should substitute path/to/environment for a location of your choice. Then activate the environment with
source path/to/environment/bin/activate
To install NEoST itself, see Installing NEoST below.
Using Conda
Assuming a Conda base environment has been installed and activated (see Conda installation instructions, e.g., Miniconda), a new virtual environment can then be created by navigating to the NEoST base directory and executing
conda env create -f environment.yml
This will create a new Conda environment called neost and install all dependencies (including GSL and MultiNest). Once the environment has been created, activate it with
conda activate neost
This changes the active virtual environment from the default base environment to the new neost environment and needs to be entered any time NEoST is used.
To install NEoST itself, see Installing NEoST below.
Installing on MAC M-series chips (arm-64)
Errors may occur when installing MultiNest/PyMultiNest on MAC M-series chips as there are no arm-64 coda builds for MultiNest. Although we do not have any definite solutions, we can offer a possible troubleshooting method that has worked in the past.
The first step is to remove PyMultiNest from the enviroment.yml file and re-run
conda env create -f environment.yml
Then activate the conda enviroment via
conda activate neost
Once that is complete, try to install PyMultiNest using pip:
pip install pymultinest
If this works you may proceed to the Installing NEoST instructions as normal. However, if this fails, or works but installing MultiNest fails, we recomend using the following procedure from NMMA to install PyMultiNest/MultiNest. You may also have a glance at the Alternative instructions for prerequisites for installing PyMultiNest/MultiNest as well.
Installing NEoST
With the prerequisites out of the way, NEoST can now be installed. First navigate to the NEoST base directory, if you haven’t done so already, and install NEoST with
make install
or, equivalently,
pip install .
NEoST can optionally be installed without cythonizing the TOV solvers, at the expense of much slower performance. If you wish to do this, rename or delete the setup.py
file before running make install
. We only recommend using the Python TOV solvers if the cythonized solvers fail to compile or run. Note that the unit tests in the tests/
directory fail if the Python solvers are used; this is expected.
Building the documentation
Building the documentation is completely optional and not required for running NEoST. If you do wish to compile the documentation locally you will require Sphinx and extensions.
If you have installed NEoST in a conda environment, you can install the documentation build dependencies using
conda install sphinx nbsphinx decorator sphinxcontrib-websupport sphinx_rtd_theme pandoc
If you haven’t used conda, you can install them using
pip install sphinx nbsphinx decorator sphinxcontrib-websupport sphinx_rtd_theme
Unfortunately, the pandoc
version available in pip does not seem to work, so you may have to install pandoc separately using, e.g., your system’s package manager. See also Pandoc.
Once the dependencies are installed you can compile the documentation by navigating to the docs
directory and executing
make html
The .html
files can then found in docs/build/html
, along with the
notebooks for the tutorials in this documentation. The .html
files can
naturally be opened in a browser, handily via a Jupyter session (this is
particularly useful if the edits are to tutorial notebooks).
Alternative instructions for MultiNest
In case you cannot install MultiNest using either conda or the instructions for manual compilation given above, you could try these older alternative instructions. These have worked in the past, but we are not sure if they still work.
In order to manually install MultiNest and PyMultiNest, first install the prerequisites. These are mpi4py and compilers for C and Fortran, and can be installed with the following commands (assuming you are using a Debian-based distribution):
conda install -c conda-forge mpi4py
sudo apt-get install cmake libblad-dev liblapack-dev libatlas-base-dev
When these have finished installing, clone the MultiNest repository, navigate to the cloned repository and install MultiNest using the following commands:
git clone https://github.com/farhanferoz/MultiNest.git <path/to/clone>/multinest
cd <path/to/clone>/multinest/MultiNest_v3.12_CMake/multinest/
mkdir build
cd build
CC=gcc FC=mpif90 CXX=g++ cmake -DCMAKE_{C,CXX}_FLAGS="-O3 -march=native -funroll-loops" -DCMAKE_Fortran_FLAGS="-O3 -march=native -funroll-loops" ..
make
ls ../lib/
The final step now is to install the Python interface to MultiNest, PyMultiNest. For this, simply install it using pip with
pip install pymultinest
Alternatively you can clone its git repository and install manually:
git clone https://github.com/JohannesBuchner/PyMultiNest.git
cd <path/to/clone>/pymultinest
python setup.py install [--user]
This will install the package in your NEoST environment if this is the active environment. If this is the case, the --user
flag needs to be omitted. Next, PyMultiNest needs to be interfaced with MultiNest itself, achieved by setting an environment variable as follows:
export LD_LIBRARY_PATH=/my/directory/MultiNest/lib/:$LD_LIBRARY_PATH
This command too needs to be given anytime you wish to use PyMultiNest and MultiNest together, so it is again recommended to add it to your ~.bashrc
file.