syntillate

Name

The name is a portmanteau of scintillate and Synthesizer — the parent package ecosystem. To scintillate is to scatter and reflect light; here, the package scatters photometry with physically motivated noise.

Overview

syntillate is a standalone Python package that provides a score-based diffusion noise model for photometric surveys. It learns the conditional distribution p(σ | m) — the joint flux-uncertainty distribution as a function of observed magnitude — from real survey data, and then draws physically realistic uncertainty samples when generating mock catalogues.

The model is a variance-preserving (VP) score-based diffusion model trained on pairs of observed photometry and flux uncertainties. After training, the reverse-time ODE or SDE is integrated to sample uncertainties conditioned on any input magnitude vector, making it suitable for injecting realistic noise into simulated galaxy catalogues.

syntillate was originally developed as part of Synference, a simulation-based inference (SBI) package for SED fitting. This package extracts the noise-modelling component for standalone use.

Here's an example of a trained model which has learned p(σ | m) for the COSMOS2020 catalog (blue, Weaver et al. 2023) and accurately reproduces the density distribution for the uncertainity distribution of each filter (in red).

Key Features

• Score-based diffusion model: Learns p(σ|m) via a VP-SDE with a linear β schedule, using a residual MLP conditioned on Gaussian Fourier time embeddings.
• Asinh magnitude support: Optional training in asinh magnitude space to handle faint or negative-flux sources.
• HDF5 serialization: Save and restore trained models with full weight and normalisation-statistic preservation.
• Minimal dependencies: Requires only PyTorch, h5py, NumPy, unyt, and matplotlib.

Requirements

syntillate requires Python 3.10 or higher. Core dependencies:

• torch for the neural score network
• numpy for numerical operations
• h5py for HDF5 serialization
• unyt for unit handling

Installation

pip install syntillate

Or from source:

git clone https://github.com/synthesizer-project/syntillate.git
cd syntillate
pip install -e .

Quick Start

import numpy as np
from unyt import Jy, uJy, unyt_array
from syntillate import ScoreBasedUncertaintyModel, save_model_to_hdf5, load_model_from_hdf5

# --- Training ---
# observed_phot: (N, n_filters) array of AB magnitudes
# observed_sigma: (N, n_filters) array of flux uncertainties in uJy
filter_names = ["F115W", "F150W", "F200W", "F277W", "F356W", "F444W"]

model = ScoreBasedUncertaintyModel(filter_names=filter_names)
history = model.fit(
    photometry=observed_phot,           # (N, 6) AB magnitudes, or a unyt_array of fluxes
    flux_uncertainties=observed_sigma,  # (N, 6) uncertainties
    flux_uncertainty_units="uJy",       # or pass observed_sigma as a unyt_array
    n_epochs=500,
    verbose=True,
)

# --- Sampling uncertainties for new photometry ---
new_mags = np.array([[25.0, 24.8, 24.5, 24.2, 24.0, 23.8]])  # (1, 6)
sigma = model.sample_uncertainty(new_mags)  # (1, 6) in model.sigma_units ("uJy" here)

# --- Apply noise to a mock flux array ---
mock_flux = unyt_array(np.array([1e-6, 1.2e-6, 1.5e-6, 2e-6, 2.5e-6, 3e-6]), units=Jy)
noisy_flux = model.apply_noise(mock_flux)

# --- Serialization ---
save_model_to_hdf5(model, "noise_model.hdf5", "my_survey", overwrite=True)
loaded_model = load_model_from_hdf5("noise_model.hdf5", "my_survey")

Asinh Magnitude Training

For surveys with significant numbers of faint or non-detected sources, you can train in asinh magnitude space instead of AB magnitudes. This avoids log(0) failures and handles negative flux entries naturally:

from unyt import uJy

model = ScoreBasedUncertaintyModel(filter_names=filter_names)
history = model.fit(
    photometry=observed_phot_flux,  # unyt_array of fluxes required
    flux_uncertainties=observed_sigma,
    asinh_scaling=True,
    asinh_b_factor=0.01 * uJy,  # softening parameter; a list gives one per filter
)

# Asinh models take fluxes (not magnitudes) at sampling time, and convert
# internally using the stored b factor — negative fluxes are fine:
sigma = model.sample_uncertainty(unyt_array([[-1e-3, 5e-3, ...]], units=uJy))

License

This project is licensed under the GNU General Public License v3.0 (GPLv3). See the LICENSE file for details. syntillate is under active development and is provided "as is" without warranty of any kind.