Installation Guide

This guide will help you install POSYDON step-by-step. We recommend using Anaconda, a package manager, to manage the installation and dependencies, ensuring a smooth setup process.

Installing POSYDON

GitHub (Development Version)

For users interested in the latest features and developments, you can install POSYDON directly from its GitHub repository:

  1. Clone the Repository

    In your terminal or command prompt (by default, the repository will be placed in the current directory, so navigate to your desired location before proceeding):

    git clone https://github.com/POSYDON-code/POSYDON.git

  2. Install the Development Version

    Warning

    If you are installing POSYDON on a Mac with Apple M1 or M2 chips, you should first install hdf5 and pytables through conda with conda install hdf5 pytables, before following the instructions below.

    Navigate to the cloned repository’s directory:

    cd POSYDON

    Install the software as an editable package using pip:

    pip install -e .

  3. Set Environment Variables and Download Data

    Refer back to the recommended installation steps, starting from point 4, to download the required dataset and set the necessary environment variables.

Installing Jupyter for Tutorials

Our tutorials are provided as Jupyter notebooks. If you want to run these notebooks interactively, you will need to have either Jupyter Lab or Jupyter Notebook installed.

  1. Using Anaconda (Recommended)

    If you have already installed Anaconda as suggested earlier in the installation guide, installing Jupyter Lab or Notebook is straightforward:

    conda install -c conda-forge jupyterlab

    Or, for the classic Jupyter Notebook:

    conda install -c conda-forge notebook

  2. Alternatively, via pip

    If you prefer using pip, you can also install Jupyter Lab or Notebook using the following commands:

    pip install jupyterlab

    Or, for the classic Jupyter Notebook:

    pip install notebook

  3. After Installation

    Once installed, you can start Jupyter Lab or Notebook by running:

    jupyter lab

    Or:

    jupyter notebook

    From the terminal or command prompt. This will open a browser window where you can navigate to the downloaded notebooks and run them interactively.

    Note

    Remember to navigate to the directory containing the Jupyter notebooks or you won’t see them listed in the Jupyter interface.

Installing additional dependencies (Optional)

For some specific functionalities, you may need to install additional dependencies. Below are the instructions for installing these dependencies and what they are used for.

Running grids of MESA models using POSYDON

If you are planning to create MESA grids using POSYDON on HPC facilities, it’s essential to have mpi4py installed to take advantage of parallel computations. You do not need to have mpi4py installed if you are only running population synthesis simulations.

  1. Install mpi4py via Anaconda (Recommended):

    conda install mpi4py

  2. Alternatively, via pip:

    pip install ".[hpc]"

Warning

Users have reported issues when trying to install mpi4py via pip. If you encounter any issues, try installing mpi4py through Anaconda. If you cannot solve the issue, please refer to the Troubleshooting Guide or seek support from the community or developers, see the contact us page.

Documentation Building

If you’re interested in building the POSYDON documentation locally:

  1. Install Documentation Modules:

    Navigate to your POSYDON directory and install the required documentation modules:

    pip install ".[doc]"

  2. Compile the Documentation:

    Once you have the required modules installed, you can build the documentation using Sphinx:

    cd docs
make html

  3. Install Pandoc via Anaconda

    Warning

    If you are installing POSYDON on a Mac with Apple M1 or M2 chips, you should install pandoc through brew with brew install pandoc.

    conda install pandoc

  4. Make the documentation:

    After installing pandoc, you can make the documentation using Sphinx:

    cd docs
make html

    This command will generate the HTML documentation in the _build/html directory within the docs folder.

  1. Open the Compiled Documentation:

    After successfully building the documentation, you can view it in your preferred browser. Navigate to the build directory and open the index.html:

    open _build/html/index.html

    Note

    The open command works on macOS. If you’re using a different OS, you might need to open the index.html using your file manager or use a different command.

Machine Learning Dependencies

For users who wish to utilize POSYDON’s latest machine learning features. This is specifically used in the active learning module and profile interpolation. You do not require these dependencies if you are using the provided Initial-Final interpolators.

  1. Navigate to your POSYDON directory (where the setup.py is located) and run:

    pip install ".[ml]"

Installing Experimental Visualization Libraries

POSYDON provides experimental visualization libraries to enhance the experience of data analysis and results visualization. While these libraries offer advanced features, please note that they might still be in development and could be subject to changes.

To install these experimental visualization libraries

  1. Navigate to your POSYDON directory (where the setup.py is located) and run:

    pip install ".[vis]"

    After installing these libraries, you can access various visualization tools and features integrated within POSYDON. Ensure to consult the documentation or any guides associated with these features for their optimal usage.

    Note

    As these are experimental features, feedback, and bug reports regarding the visualization tools are highly appreciated. It will aid the development and optimization of these features for future stable releases.