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 

Anaconda (Recommended)

Install Anaconda

If you haven’t already, download and install Anaconda from Anaconda’s official website.
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
As many of the required versions of packages are available on conda-forge you may need to add this channel to conda if you have not already:
conda config --add channels conda-forge
Install POSYDON
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
Note

In the next step you will need to know where this package was installed. You can find it by running the following commands in Python:
import posydon print(posydon.__file__)

Set Environment Variables
Export the required paths (please change the location names accordingly to your installation from the previous step):
conda env config vars set PATH_TO_POSYDON=/path/to/your/posydon/installation conda env config vars set PATH_TO_POSYDON_DATA=/path/where/you/want/to/store/data
The path for the data location is up to you, but keeping the data separate from the code is recommended for organization.
Note

So that your new conda environment is loaded whenever you open a new terminal, you can add the following line to your ~/.bashrc or ~/.bash_profile or your shell equivalent:
conda activate posydon_env
Download the Dataset
You can use POSYDON’s built-in API command (the downloaded data will be downloaded to the directory specified by PATH_TO_POSYDON_DATA):

Warning

Executing the following command get-posydon-data will download the full DR2 data set. This includes data for all eight of the available metallicities, plus auxillary data. This may be more than you want, the data for each metallicity requires about 10 GB of disk space. In total, the DR2 dataset requires 103 GB of disk space.
get-posydon-data
You may use get-posydon-data -h to see all the options for this command, which allows you to list all the datasets and download the ones of your choice. If you would rather download something more minimal to run populations, you will need at least the auxillary data:
get-posydon-data auxillary
and data for at least one metallicity (the examples and tutorials typically use solar):
get-posydon-data DR2_1Zsun
Alternatively, you can manually download the datasets from Zenodo. You can find the POSYDON datasets on the POSYDON community on Zenodo.

GitHub (Stable Version)

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

Clone the Repository
In your terminal or command prompt execute one of the following command to clone the repo with the https protocol:

Warning

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
For the ssh protocol:
git clone git@github.com:POSYDON-code/POSYDON.git
Or for the Github CLI:
gh repo clone POSYDON-code/POSYDON
Install the Stable 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 .
Set Environment Variables
Next, export the required paths as environment variables. From the POSYDON directory that you just performed the installation in, you can execute pwd if you are unsure of the path name. Please change the location names accordingly below to your installation path:
export PATH_TO_POSYDON=/path/to/your/posydon/installation export PATH_TO_POSYDON_DATA=/path/where/you/want/to/store/data
The path for the data location is up to you, but keeping the data separate from the code is recommended for organization.

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.
Download the Dataset
You can use POSYDON’s built-in API command (the downloaded data will be downloaded to the directory specified by PATH_TO_POSYDON_DATA):

Warning

Executing the following command get-posydon-data will download the full DR2 data set. This includes data for all eight of the available metallicities, plus auxillary data. This may be more than you want, the data for each metallicity requires about 10 GB of disk space. In total, the DR2 dataset requires 103 GB of disk space.
get-posydon-data
You may use get-posydon-data -h to see all the options for this command, which allows you to list all the datasets and download the ones of your choice. If you would rather download something more minimal to run populations, you will need at least the auxillary data:
get-posydon-data auxillary
and data for at least one metallicity (the examples and tutorials typically use solar):
get-posydon-data DR2_1Zsun
Alternatively, you can manually download the datasets from Zenodo. You can find the POSYDON datasets on the POSYDON community on Zenodo.

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.

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

Install mpi4py via Anaconda (Recommended):
conda install mpi4py
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:

Install Documentation Modules:
Navigate to your POSYDON directory and install the required documentation modules:
pip install ".[doc]"
Warning

If you are installing POSYDON on a Mac with Apple M1 or M2 chips, you should install pandoc separately through brew with brew install pandoc.
Compile the Documentation:
Once you have the required modules installed, you can build the documentation using Sphinx:
cd docs make html
This command will generate the HTML documentation in the _build/html directory within the docs folder.
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.

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

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.