Welcome to the documentation of Synthetic Stellar Pop Convolve (SSPC)!

Synthetic Stellar Pop Convolve (SSPC)

docstring coverage test coverage

This repository contains the code and documentation for the synthetic stellar-population convolution code-base Synthetic Stellar Pop Convolve (SSPC). SSPC is available in a Gitlab repository as well as on Pypi.

For detailed tutorials and use-case examples, check out the tutorial notebooks: 📖 Example Notebooks

warning: the code is not fully released yet, some things may not work reliably

Overview

SSPC (Synthetic Stellar Pop Convolve) is a Python package designed to convolve stellar population synthesis outputs (binary_c(-python), COMPAS, COSMIC, SEVN) with star formation histories, enabling detailed predictions of astrophysical event rates over cosmic time. By integrating synthetic stellar and binary evolution models with cosmological and observational constraints, SSPC helps generate realistic event distributions.

The code was originally developed by David Hendriks (with invaluable help from Lieke van Son and inspiration from Coen Neijssels convolution code in COMPAS) for the project of Hendriks et al. 2023 (MNRAS). There it was used to convolve gravitational-wave merger events from binary systems as well as supernova events from both binary systems and single stars with a cosmological star-formation rate.

SSPC can be used to convolve the pre-calculated output of stellar population-synthesis codes with (cosmological) starformation rates, as well as on-the-fly population-synthesis simulation and convolution. It can convolve both event-based (line by line) data, as well as ensemble-based (nested histogram/pre-binned) data, either by integration or by generating samples from the convolution results.

Main Purpose

The core goal of SSPC is to compute astrophysical event rates (e.g., supernovae, compact object mergers, nucleosynthetic yields) by integrating stellar population synthesis outputs with (cosmological) star formation rate (SFR) models.

SSPC is particularly useful for:

Gravitational-wave astrophysics (binary black hole/neutron star mergers).
Supernova rate predictions for different stellar environments.
Galaxy chemical evolution modeling, linking nucleosynthetic yields to cosmic star formation.
Transient event forecasts, such as tidal disruption events, gamma-ray bursts, and luminous red novae.
Generalized stellar population modeling, providing insight into the evolution of stellar populations over cosmic time.

Features

SSPC provides a robust framework for convolving stellar population synthesis data with star formation rates. Its key features include:

✅ Event-based convolution: Handles transient data.
✅ Ensemble-based convolution: Handles nested histograms and binned data.
✅ Convolution by integration: Handles convolution by summing the normalized yields with the star formation rates to get the actual yield.
✅ Convolution by sampling: Generates actual sampled systems from the actual yield.
✅ Supports different SFR prescriptions: Users can apply arbitrary star formation rate models.
✅ Flexible star formation modeling: Supports sequential convolution with multiple SFRs.
✅ Convolution instructions: Supports sequential convolution of multiple convolution instructions.
✅ Multiprocessing and sequential convolution support: Uses multiprocessing when each convolution target time is independent, but can use sequential convolution when the next step depends on the previous one.
✅ Astropy support: Uses Astropy units to perform unit checks and dimensional analysis of yields.
✅ Post-convolution processing: Allows user-provided post-convolution functions to refine results (e.g., LISA frequency range selection), re-weighting based on detection probability, and
✅ Chunked convolution for large datasets that don’t fit into memory (after convolution-by-sampling).

Planned features:

Better support for spatially resolved star-formation rates.
Support for star formation using custom generators for use-cases where the previous convolution time affects the star formation (or metallicity distribution) of the next convolution time.
Support for uncertainty propagation of star-formation rates.

Usage

Using SSPC is designed to be simple, and only requires the following ingredients:

input data: pre-calculated population-synthesis results which contain at least delay time information and a normalized yield value
general configuration: a global configuration.
starformation rate model: a dictionairy-type containing information about the rate of star formation and the corresponding times, and optionally information about metallicity distributions.
convolution instruction: instructions for a particular convolution.
data-column dict: a dictionary that allows SSPC to fetch the relevant data columns, optionally with units and value conversions.

Quick Start Guide

Here’s a minimal example demonstrating how to use SSPC:

import os, copy, h5py
import astropy.units as u
import numpy as np
import pandas as pd
from syntheticstellarpopconvolve import convolve, default_convolution_config, default_convolution_instruction
from syntheticstellarpopconvolve.general_functions import generate_boilerplate_outputfile, extract_unit_dict, temp_dir

TMP_DIR = temp_dir(
    "examples", "minimal_working_example", clean_path=True
)

# Create instance of output
output_hdf5_filename = os.path.join(TMP_DIR, "output_example.h5")
generate_boilerplate_outputfile(output_hdf5_filename)

# SET UP DATA
example_data = {
    "delay_time": np.array([0, 1, 2, 3]),
    "value": np.array([3, 2, 1, 0]),
    "probability": np.array([1, 2, 3, 4]),
}
example_df = pd.DataFrame.from_records(example_data)
example_df.to_hdf(output_hdf5_filename, key="input_data/example")

# Set up global configuration
convolution_config = copy.copy(default_convolution_config)
convolution_config["output_filename"] = output_hdf5_filename

# Set up SFR
convolution_config["SFR_info"] = {
    "lookback_time_bin_edges": np.array([0, 1, 2, 3, 4, 5]) * u.yr,
    "starformation_rate_array": np.array([1, 2, 3, 4, 5]) * u.Msun / u.yr
}

# set up convolution bin edges
convolution_config["convolution_lookback_time_bin_edges"] = (
    np.array([0, 1]) * u.yr
)

# Set up the convolution instructions
convolution_config["convolution_instructions"] = [
    {
        **default_convolution_instruction,
        "input_data_name": "example",
        "output_data_name": "example",
        "data_column_dict": {
            "delay_time": "delay_time",
            "normalized_yield": {"column_name": "probability", "unit": 1/u.Msun},
        },
    }
]

# run convolution
convolve(convolution_config)

# read out results
with h5py.File(
    convolution_config["output_filename"], "r"
) as output_hdf5file:
    groupname = "output_data/example/example/convolution_results/0.5 yr/"

    yield_data = output_hdf5file[groupname + "/yield"][()]
    unit_dict = extract_unit_dict(output_hdf5file, groupname)

    print(yield_data) # values
    print(unit_dict) # units

For more detailed examples, check out the tutorial notebooks: 📖 Example Notebooks

Installation

Requirements

SSPC relies on several Python dependencies, listed in requirements.txt. These are automatically installed via pip or setup.py.

Install via PyPI

To install the latest release:

pip install syntheticstellarpopconvolve

Install from Source

If you need the development version, clone the repository and run:

git clone https://gitlab.com/dhendriks/syntheticstellarpopconvolve.git
cd syntheticstellarpopconvolve
./install.sh

This ensures all dependencies are installed into your active virtual environment.

Documentation

Comprehensive documentation is available on ReadTheDocs: 📚 SSPC Documentation, including tutorial and example use-case notebooks

Development & Contributions

We welcome contributions! If you’re interested in contributing:

Install development dependencies:

pip install -r development_requirements.txt

Read the HOW_TO_CONTRIBUTE guide.
Submit bug reports or feature requests via GitLab Issues.

Naming conventions for branches:

development/<SSPC version>
releases/<SSPC version>

Generating Reports & Documentation

Run the following commands from the commands/ directory:

📖 Generate documentation:

./generate_docs.sh

📊 Generate docstring & test coverage reports:

./generate_reports.sh

Community & Support

If you have questions or suggestions, bugfixes, or feature requests, feel free to reach out via:

Gitlab issue: Gitlab issue
Email: mail@davidhendriks.com

Please help improve SSPC by reporting issues and suggesting new features!

License

SSPC is released under the GPL License. See LICENSE for details.

Contents: