Installation Guide

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

Using Anaconda (Recommended)

1. Install Anaconda

   If you haven’t already, download and install Anaconda from Anaconda’s official website.

2. Create a New Conda Environment

   Open your terminal or Anaconda prompt and create a new environment called posydon_env using Python 3.11 (the -y automatically answers all confirmations with yes):

   conda create --name posydon_env python=3.11 -y
   

   Activate the new environment:

   conda activate posydon_env
   

3. Install POSYDON

   Warning

   This documentation describes the POSYDON v2.0.0 code which is not yet available on Anaconda. Please use the development version for now. See Using the Development Version for more details.

   With the environment activated, install the POSYDON code from the POSYDON channel using (by default the installation will take place in the current directory, hence please navigate to your desired location first or use the -p option to specify a path):

   conda install -c posydon posydon
   

4. Download the Dataset

   Warning

   The POSYDON v2.0.0 dataset is not yet available on Zenodo. The above instructions currently point to the POSYDON v1.0.0 dataset release. Please refer to the development version of the dataset available on Northwestern and UNIGE HPC facilities for now. To have access to latest pre-release dataset (230914) you must be a POSYDON core developer, please refer to the #developers Slack channel.

   You can use POSYDON’s built-in API command (by default the downloaded data will be saved in the current directory, hence please navigate to your desired location first):

   get-posydon-data
   

   Alternatively, you can manually download the dataset from Zenodo using the provided link. (TODO: update link to v2)

5. Set Environment Variables

   Export the required paths (please change the location names accordingly to your installation):

   export PATH_TO_POSYDON=/path/to/your/posydon/installation
   export PATH_TO_POSYDON_DATA=/path/where/you/want/to/store/data
   

   Note

   You can add these lines to your ~/.bashrc or ~/.bash_profile or your shell equivalent to ensure the environment variables are set every time you open a new terminal.

Using the 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, hence please navigate to your desired location first):

   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 instractions 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.

Using POSYDON on HPC Facilities

(TODO: check whether it is still needed) If you are planning to run POSYDON’s population synthesis on a High-Performance Computing (HPC) facility, it’s essential to have mpi4py installed to enable parallel computations.

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.

Machine Learning Modules Installation

For users who wish to utilize POSYDON’s latest machine learning features:

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.

Documentation Installation & Compilation

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. 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.

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.

Additional Notes

• After installation, ensure you verify the setup by following our Verification Guide.

• Always ensure you activate the posydon_env environment before running POSYDON.

• If you encounter issues during the installation, consult our Troubleshooting Guide or seek support from the community or developers, see the contact us page.