Core Module (brutus.core)

Core Module (`brutus.core`)#

The core module provides the fundamental stellar modeling infrastructure for brutus. It contains classes and functions for generating synthetic photometry from stellar evolution models, both for individual stars and stellar populations.

Key Components:

Individual Stars: EEPTracks predicts stellar parameters along evolutionary tracks, StarGrid provides fast grid-based photometry
Populations: Isochrone models coeval stellar populations, StellarPop generates population photometry
Neural Networks: FastNN and FastNNPredictor compute bolometric corrections efficiently
Grid Generation: GridGenerator creates pre-computed model grids for large-scale fitting

Design Philosophy:

The module follows a clean separation of concerns:

Parameter Prediction (EEPTracks, Isochrone): Maps intrinsic stellar parameters (mass, age, metallicity) to observable parameters (temperature, luminosity, radius, surface gravity)
Photometry Generation (StarEvolTrack, StellarPop): Converts stellar parameters to synthetic photometry using neural network bolometric corrections and extinction modeling

This separation allows flexible combinations: you can use different photometry generators with the same parameter predictors, or vice versa.

Typical Usage Patterns:

For individual field stars with unknown evolutionary state:

from brutus.core import EEPTracks, StarEvolTrack

# Parameter prediction
tracks = EEPTracks()

# Photometry generation (on-the-fly)
star = StarEvolTrack(tracks=tracks, filters=['PS_g', 'PS_r', 'PS_i', 'PS_z'])
sed, params1, params2 = star.get_seds(
    mini=1.0, eep=400, feh=0.0,
    av=0.1, dist=1000.0
)

For large samples requiring speed:

from brutus.core import StarGrid
from brutus.data import load_models

# Load pre-computed grid
models, labels, label_mask = load_models('grid_mist_v9.h5')
grid = StarGrid(models, labels)

# Fast photometry lookup (no re-computation)
# Use with BruteForce fitter for thousands to millions of stars

For stellar clusters with shared age and metallicity:

from brutus.core import Isochrone, StellarPop

# Population parameter prediction
iso = Isochrone()

# Population photometry
pop = StellarPop(isochrone=iso)
seds, params1, params2 = pop.get_seds(
    feh=0.0, loga=9.0, av=0.5, dist=2000.0
)

See Also:

Stellar Models and Photometry - Conceptual overview of MIST models, EEP, and isochrones
Grid-Based Fitting - Guide to creating and using pre-computed grids
Population-Based Modeling - Population-based cluster fitting

Individual Star Models#

class brutus.core.EEPTracks(mistfile=None, predictions=['loga', 'logl', 'logt', 'logg', 'feh_surf', 'afe_surf'], ageweight=True, verbose=True, use_cache=True)[source]#

Bases: object

Stellar parameter predictions for individual stars using evolutionary tracks.

This class provides interpolation of stellar parameters along evolutionary tracks as a function of initial mass, equivalent evolutionary point (EEP), metallicity, and alpha enhancement. It focuses solely on stellar parameter prediction without photometry generation.

The class name “EEPTracks” is intentionally general to allow for future implementations beyond MIST, while the current implementation uses MIST (MESA Isochrones and Stellar Tracks) evolutionary models.

For photometry generation, use StarEvolTrack with this class.

Parameters:

mistfile (str, optional) – Path to the HDF5 file containing the evolutionary tracks. If not provided, defaults to the standard MIST v1.2 EEP tracks file.
predictions (iterable of str, optional) – The names of stellar parameters to predict. Default is: [“loga”, “logl”, “logt”, “logg”, “feh_surf”, “afe_surf”].
ageweight (bool, optional) – Whether to compute age weights d(age)/d(EEP) for age priors. Default is True.
verbose (bool, optional) – Whether to output progress messages during initialization. Default is True.
use_cache (bool, optional) – Whether to use pickle caching to speed up loading. If True, will save processed EEPTracks to a .pkl file for faster subsequent loads, and load from cache if available and newer than the original file. Default is True.

labels#

Input parameter names: [‘mini’, ‘eep’, ‘feh’, ‘afe’]

Type:: list of str

predictions#

Output parameter names as specified in initialization

Type:: list of str

ndim, npred

Number of input dimensions and predicted parameters

Type:: int

interpolator#

The main interpolation object for stellar parameter prediction

Type:: scipy.interpolate.RegularGridInterpolator

gridpoints#

Unique grid points for each input parameter

Type:: dict

Examples

Predict parameters for a solar-mass star on the main sequence:

>>> tracks = EEPTracks()
>>> params = tracks.get_predictions([1.0, 350, 0.0, 0.0])  # mini, eep, feh, afe
>>> log_age = params[0]  # log10(age in years)
>>> log_teff = params[2]  # log10(effective temperature)
>>> print(f"Age: {10**log_age:.1e} yr, Teff: {10**log_teff:.0f} K")

Batch prediction for multiple stars:

>>> import numpy as np
>>> labels = np.array([[0.8, 350, -0.5, 0.2],   # Metal-poor dwarf
...                    [1.2, 454, 0.0, 0.0],    # Solar at turnoff
...                    [2.0, 500, 0.3, 0.0]])   # Massive metal-rich
>>> preds = tracks.get_predictions(labels)
>>> ages = 10**preds[:, 0]  # Convert to linear ages

__init__(mistfile=None, predictions=['loga', 'logl', 'logt', 'logg', 'feh_surf', 'afe_surf'], ageweight=True, verbose=True, use_cache=True)[source]#

get_predictions(labels, apply_corr=True, corr_params=None)[source]#

Generate stellar parameter predictions for given input parameters.

Parameters:

labels (array-like of shape (4,) or (Nobj, 4)) – Input parameters [mini, eep, feh, afe] where: - mini: Initial mass in solar masses - eep: Equivalent evolutionary point - feh: Metallicity [Fe/H] in logarithmic solar units - afe: Alpha enhancement [alpha/Fe] in logarithmic solar units
apply_corr (bool, optional) – Whether to apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale).

Returns:

preds – Predicted stellar parameters in the order specified by self.predictions attribute.

Return type:

numpy.ndarray of shape (Npred,) or (Nobj, Npred)

See also

get_corrections: Computes empirical corrections applied when apply_corr=True
StarEvolTrack.get_seds: Uses these predictions to generate photometry

Examples

Single star prediction:

>>> tracks = EEPTracks()
>>> params = tracks.get_predictions([1.0, 350, 0.0, 0.0])
>>> log_age, log_L, log_Teff, log_g = params[:4]

Multiple star prediction:

>>> import numpy as np
>>> labels = np.array([[0.8, 350, -0.5, 0.2], [1.2, 454, 0.0, 0.0]])
>>> params = tracks.get_predictions(labels)

get_corrections(labels, corr_params=None)[source]#

Compute empirical corrections to stellar parameters.

Applies empirical corrections to effective temperature and radius based on stellar mass, evolutionary phase (EEP), and metallicity. These corrections account for systematic offsets between MIST models and observations, particularly for low-mass stars.

Parameters:

labels (array-like of shape (4,) or (Nobj, 4)) – Input parameters [mini, eep, feh, afe] where: - mini: Initial mass in solar masses - eep: Equivalent evolutionary point - feh: Metallicity [Fe/H] - afe: Alpha enhancement [α/Fe]
corr_params (tuple of float, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale) where: - dtdm: Temperature correction slope with mass - drdm: Radius correction slope with mass - msto_smooth: Smoothing scale for main sequence turnoff transition - feh_scale: Metallicity scaling factor Default is (0.09, -0.09, 30.0, 0.5).

Returns:

corrs – Corrections to [log(Teff), log(R)]. These are added to the base predictions from the interpolator.

Return type:

numpy.ndarray of shape (2,) or (Nobj, 2)

See also

get_predictions: Applies these corrections to stellar parameters

Notes

Corrections are applied as:

\[\begin{split}\\Delta \\log T_{\\rm eff} = f_{\\rm EEP} \\cdot f_{\\rm [Fe/H]} \\cdot \\log(1 + \\Delta M \\cdot \\alpha_T) \\Delta \\log R = f_{\\rm EEP} \\cdot f_{\\rm [Fe/H]} \\cdot \\log(1 + \\Delta M \\cdot \\alpha_R)\end{split}\]

where \(\\Delta M = M_{\\rm ini} - 1.0\) and the EEP factor smoothly transitions from 0 (pre-main sequence) to 1 (post-turnoff).

Corrections are set to zero for stars with \(M_{\\rm ini} \\geq 1.0 M_\\odot\).

class brutus.core.StarGrid(models, models_labels, models_params=None, filters=None, verbose=True)[source]#

Bases: object

Grid-based stellar modeling and synthetic photometry generation.

This class provides an interface for working with pre-computed stellar model grids, enabling parameter interpolation and SED generation similar to StarEvolTrack but using grid-based models rather than evolutionary tracks.

The grid structure allows for irregular spacing in each dimension, with models indexed by their array location. Multi-linear interpolation is used to compute stellar parameters and photometry between grid points.

Parameters:

models (numpy.ndarray of shape (Nmodel, Nfilt, Ncoef) or dict/h5py file) – Pre-computed model grid containing photometric coefficients. If dict or h5py file, should contain ‘mag_coeffs’ key. Each model contains 3 coefficients per filter: - Unreddened magnitude - Reddening vector for R_V = 0 - Change in reddening vector as function of R_V
models_labels (structured numpy.ndarray of shape (Nmodel,)) – Labels for each model in the grid (e.g., mini, eep, feh, afe, smf).
models_params (structured numpy.ndarray of shape (Nmodel,), optional) – Additional parameters for each model (e.g., loga, logl, logt, logg). If not provided, these won’t be available in predictions.
filters (list of str, optional) – Filter names for photometry. If None, uses all available filters from the models.
verbose (bool, optional) – Whether to print progress messages. Default is True.

nmodels#

Number of models in the grid

Type:: int

nfilters#

Number of filters

Type:: int

filters#

Array of filter names

Type:: numpy.ndarray

labels#

Grid labels (mini, eep, feh, etc.)

Type:: structured numpy.ndarray

params#

Additional parameters if provided

Type:: structured numpy.ndarray or None

label_names#

Names of available labels

Type:: list

param_names#

Names of available parameters

Type:: list

Notes

Binary star support is currently limited. The smf parameter is accepted for API compatibility with StarEvolTrack, but full binary modeling requires a dedicated binary grid with pre-computed combined photometry. The current implementation returns empty placeholders for secondary parameters.

Examples

Load a pre-computed grid and generate photometry:

>>> from brutus.data import load_models
>>> models, labels, label_mask = load_models('grid_mist_v9.h5')
>>> grid = StarGrid(models, labels)
>>>
>>> # Get predictions for specific stellar parameters
>>> predictions = grid.get_predictions(mini=1.0, eep=350, feh=0.0)
>>>
>>> # Generate SED with extinction
>>> sed, params, params2 = grid.get_seds(
...     mini=1.0, eep=350, feh=0.0,
...     av=0.1, rv=3.3, dist=1000.0
... )

__init__(models, models_labels, models_params=None, filters=None, verbose=True)[source]#: Initialize the StarGrid with model data.

get_predictions(mini=None, eep=None, feh=None, afe=None, smf=None, use_multilinear=True, **kwargs)[source]#

Get stellar parameter predictions from the grid.

Interpolates grid models to estimate stellar parameters at the requested input values using multi-linear interpolation.

Parameters:

mini (float, optional) – Initial mass in solar masses
eep (float, optional) – Equivalent evolutionary phase
feh (float, optional) – Metallicity [Fe/H]
afe (float, optional) – Alpha enhancement [α/Fe]
smf (float, optional) – Secondary mass fraction for binaries
use_multilinear (bool, optional) – Use multi-linear interpolation (True) or KD-tree nearest neighbor (False). Default is True.
**kwargs (additional parameters) – Any additional selection criteria

Returns:

predictions – Predicted stellar parameters. Returns dict with parameter names as keys if parameters are available, otherwise returns array.

Return type:

dict or numpy.ndarray

See also

get_seds: Generate photometry along with parameter predictions
_find_neighbors_multilinear: Multi-linear interpolation method
_find_neighbors_kdtree: KD-tree nearest neighbor method

Examples

>>> grid = StarGrid(models, labels, params)
>>> preds = grid.get_predictions(mini=1.0, eep=350, feh=0.0)
>>> print(f"log(age) = {preds['loga']:.2f}")
>>> print(f"log(L) = {preds['logl']:.2f}")

get_seds(mini=None, eep=None, feh=None, afe=None, av=0.0, rv=3.3, smf=None, dist=1000.0, return_dict=True, return_flux=False, return_predictions=True, use_multilinear=True, **kwargs)[source]#

Generate synthetic SED from the grid.

Interpolates grid models and applies extinction to generate synthetic photometry using multi-linear interpolation.

Parameters:

mini (float, optional) – Initial mass in solar masses
eep (float, optional) – Equivalent evolutionary phase
feh (float, optional) – Metallicity [Fe/H]
afe (float, optional) – Alpha enhancement [α/Fe]
av (float, optional) – V-band extinction in magnitudes. Default is 0.0.
rv (float, optional) – Reddening law parameter. Default is 3.3.
smf (float, optional) – Secondary mass fraction for binaries. NOTE: Currently returns empty placeholder for params2. Full binary support requires a dedicated binary grid with pre-computed combined photometry.
dist (float, optional) – Distance in parsecs. Default is 1000.0 (1 kpc), which corresponds to parallax = 1 mas for consistency with Gaia units.
return_dict (bool, optional) – If True, return parameters as dict. Default is True.
return_flux (bool, optional) – If True, return fluxes instead of magnitudes. Default is False.
return_predictions (bool, optional) – If True, compute and return stellar parameters. Set to False to only get photometry (more efficient). Default is True.
use_multilinear (bool, optional) – Use multi-linear interpolation (True) or KD-tree nearest neighbor (False). Default is True.
**kwargs (additional parameters) – Passed to interpolation methods

Returns:

sed (numpy.ndarray of shape (Nfilt,)) – Synthetic photometry (magnitudes or fluxes)
params (dict or numpy.ndarray or None) – Primary star parameters (None if return_predictions=False)
params2 (dict or numpy.ndarray or None) – Secondary star parameters (empty placeholder - full binary implementation requires dedicated binary grid)

See also

get_predictions: Get stellar parameters without photometry
StarEvolTrack.get_seds: Alternative track-based SED generation
brutus.analysis.BruteForce: Fitting with StarGrid

Notes

The SED is computed by interpolating magnitude coefficients and applying the extinction law:

\[\begin{split}m(\\lambda) = m_0(\\lambda) + A_V \\cdot [r_0(\\lambda) + R_V \\cdot dr(\\lambda)]\end{split}\]

where \(m_0\) is the unreddened magnitude, \(r_0\) and \(dr\) are the reddening vector coefficients from the grid.

Examples

>>> grid = StarGrid(models, labels)
>>> sed, params, _ = grid.get_seds(
...     mini=1.0, eep=350, feh=0.0,
...     av=0.1, dist=500.0
... )
>>> print(f"G magnitude: {sed[0]:.2f}")

__repr__()[source]#: Return string representation of the StarGrid object.

__len__()[source]#: Return the number of models in the grid.

class brutus.core.StarEvolTrack(tracks, filters=None, nnfile=None, verbose=True)[source]#

Bases: object

Synthetic photometry generation for individual stars.

This class generates synthetic SEDs and photometry for individual stars using neural network-based bolometric corrections. It provides modeling of binary stars, dust extinction, and observational effects.

This class mirrors StellarPop but for individual stars: - StarEvolTrack: Individual star photometry - StellarPop: Stellar population photometry

The class uses dependency injection, accepting an EEPTracks instance for stellar parameter predictions rather than inheriting from it.

Parameters:

tracks (EEPTracks) – EEPTracks instance for stellar parameter predictions.
filters (list of str, optional) – Filter names for photometry computation. If None, uses all available.
nnfile (str, optional) – Path to neural network file for bolometric corrections.
verbose (bool, optional) – Whether to output progress messages. Default is True.

tracks#

The evolutionary track model for stellar parameter predictions

Type:: EEPTracks

filters#

Array of filter names

Type:: numpy.ndarray

predictor#

Neural network predictor for photometry

Type:: FastNNPredictor

See also

EEPTracks: Stellar parameter predictions used by this class
StarGrid: Alternative grid-based approach for photometry
brutus.core.neural_nets.FastNNPredictor: Neural network used for SEDs

Examples

Basic individual star photometry:

>>> tracks = EEPTracks()
>>> star_track = StarEvolTrack(tracks=tracks)
>>>
>>> # Generate SED for a solar-mass main sequence star
>>> sed, params, params2 = star_track.get_seds(
...     mini=1.0, eep=350, feh=0.0, afe=0.0,
...     av=0.1, rv=3.1, dist=1000.0
... )

Binary star modeling:

>>> # Model binary with 70% mass ratio secondary
>>> sed, params, params2 = star_track.get_seds(
...     mini=1.2, eep=400, feh=-0.2, afe=0.1,
...     smf=0.7, av=0.15, dist=1500.0
... )

__init__(tracks, filters=None, nnfile=None, verbose=True)[source]#

get_seds(mini=1.0, eep=350, feh=0.0, afe=0.0, av=0.0, rv=3.3, smf=0.0, dist=1000.0, loga_max=10.15, eep2=None, mini_bound=0.08, eep_binary_max=480.0, apply_corr=True, corr_params=None, return_eep2=False, return_dict=True, combine_seds=True, tol=0.01, **kwargs)[source]#

Generate synthetic SED for an individual star.

Parameters:

mini (float, optional) – Initial stellar mass in solar masses. Default is 1.0.
eep (float, optional) – Equivalent evolutionary point. Default is 350.
feh (float, optional) – Metallicity [Fe/H]. Default is 0.0.
afe (float, optional) – Alpha enhancement [α/Fe]. Default is 0.0.
av (float, optional) – V-band extinction A(V). Default is 0.0.
rv (float, optional) – Extinction law parameter R(V). Default is 3.3.
smf (float, optional) – Secondary mass fraction for binary. Default is 0.0 (single star).
dist (float, optional) – Distance in parsecs. Default is 1000.0.
loga_max (float, optional) – Maximum log(age) for SED computation. Default is 10.15.
eep2 (float, optional) – EEP of secondary component for binaries.
mini_bound (float, optional) – Minimum mass for SED computation. Default is 0.08.
eep_binary_max (float, optional) – Maximum EEP for binary modeling. Default is 480.0.
apply_corr (bool, optional) – Apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters.
return_eep2 (bool, optional) – Return secondary EEP. Default is False.
return_dict (bool, optional) – Return parameters as dictionary. Default is True.
combine_seds (bool, optional) – If True and binary star requested, combine primary and secondary SEDs by adding their magnitudes. If False, separate SEDs for primary and secondary will be returned. Default is True.
tol (float, optional) – Convergence tolerance (in dex) on the log10(age) match when solving for the secondary’s EEP in a binary. A companion whose age cannot be matched to within tol is treated as non-existent and a primary-only SED is returned (rather than discarding the model). Default is 1e-2. The previous default (1e-6) was far tighter than the age emulator’s own precision and silently dropped most otherwise-valid binary models.

Returns:

sed (numpy.ndarray of shape (Nfilters,) or tuple) – Synthetic SED in magnitudes.
params (dict or numpy.ndarray) – Primary component stellar parameters.
params2 (dict or numpy.ndarray) – Secondary component parameters.
eep2 (float, optional) – Secondary EEP (if return_eep2=True).

See also

EEPTracks.get_predictions: Stellar parameter predictions
FastNNPredictor.sed: Neural network SED generation
_get_eep_for_secondary: Binary companion EEP calculation

Notes

Distance modulus is applied as:

\[\begin{split}m = M + 5 \\log_{10}(d/10\\,{\\rm pc})\end{split}\]

where d is the distance in parsecs.

Binary SEDs are combined using magnitude addition (flux summing):

\[\begin{split}m_{\\rm combined} = -2.5 \\log_{10}(10^{-0.4 m_1} + 10^{-0.4 m_2})\end{split}\]

Examples

Single star:

>>> sed, params, params2 = star_track.get_seds(
...     mini=1.0, eep=350, feh=0.0, afe=0.0
... )

Binary system:

>>> sed, params, params2 = star_track.get_seds(
...     mini=1.2, eep=400, feh=-0.2, afe=0.1, smf=0.7
... )

Population Models#

class brutus.core.Isochrone(mistfile=None, predictions=None, verbose=True)[source]#

Bases: object

Stellar parameter predictions for isochrones using MIST evolutionary models.

This class provides interpolation of stellar parameters along isochrones of fixed metallicity, alpha enhancement, and age. It focuses solely on stellar parameter prediction (masses, temperatures, luminosities, etc.) without photometry generation.

This class is analogous to MISTtracks but for stellar populations: - MISTtracks: Individual star parameters (mini, EEP, feh, afe) → parameters - Isochrone: Population parameters (feh, afe, loga, EEP) → parameters

For photometry generation, use StellarPop with this class.

Parameters:

mistfile (str, optional) – Path to the HDF5 file containing the MIST isochrone grid. If not provided, defaults to the standard MIST v1.2 isochrone file.
predictions (list of str, optional) – The names of stellar parameters to predict. Default is: [“mini”, “mass”, “logl”, “logt”, “logr”, “logg”, “feh_surf”, “afe_surf”].
verbose (bool, optional) – Whether to output progress messages during initialization. Default is True.

predictions#

List of stellar parameter names for prediction

Type:: list of str

feh_grid, afe_grid, loga_grid, eep_grid

Input parameter grids from MIST isochrone file

Type:: numpy.ndarray

pred_grid#

Stellar parameter predictions organized by grid coordinates

Type:: numpy.ndarray

interpolator#

Main interpolation object for stellar parameter prediction

Type:: scipy.interpolate.RegularGridInterpolator

Examples

Generate stellar parameters for a solar metallicity, 1 Gyr population:

>>> iso = Isochrone()
>>> params = iso.get_predictions(feh=0.0, afe=0.0, loga=9.0)
>>> masses = params[:, 0]  # Initial masses
>>> log_teff = params[:, 3]  # log(effective temperatures)
>>> print(f"Mass range: {masses.min():.2f} - {masses.max():.2f} M_sun")

Generate parameters for specific evolutionary phases:

>>> import numpy as np
>>> eep_range = np.arange(200, 500, 50)  # Main sequence to turnoff
>>> params = iso.get_predictions(feh=-0.5, afe=0.3, loga=10.0, eep=eep_range)

__init__(mistfile=None, predictions=None, verbose=True)[source]#

get_predictions(feh=0.0, afe=0.0, loga=8.5, eep=None, apply_corr=True, corr_params=None)[source]#

Generate stellar parameter predictions for an isochrone.

Parameters:

feh (float, optional) – Metallicity [Fe/H] relative to solar. Default is 0.0.
afe (float, optional) – Alpha enhancement [alpha/Fe] relative to solar. Default is 0.0.
loga (float, optional) – Log10(age in years). Default is 8.5 (≈316 Myr).
eep (array-like, optional) – Equivalent evolutionary points. If None, uses default grid.
apply_corr (bool, optional) – Whether to apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale).

Returns:

preds – Stellar parameter predictions for each EEP value. The columns correspond to the parameters listed in self.pred_labels.

Return type:

numpy.ndarray of shape (Neep, Npred)

See also

StellarPop.get_seds: Uses these predictions for photometry generation
brutus.core.EEPTracks.get_predictions: Similar function for individual stars

Notes

The method interpolates across the pre-computed MIST isochrone grid. Returns NaN for parameters outside the grid bounds or where data is not available.

Common EEP ranges: - Pre-main sequence: EEP < 202 - Zero-age main sequence: EEP = 202 - Terminal-age main sequence: EEP = 454 - Subgiant branch: EEP 454-605 - Red giant branch: EEP 605-1409

Examples

>>> iso = Isochrone()
>>> # Get parameters for a 1 Gyr solar metallicity population
>>> params = iso.get_predictions(feh=0.0, afe=0.0, loga=9.0)
>>> masses = params[:, 0]  # Initial masses
>>> temps = 10**params[:, 3]  # Effective temperatures

class brutus.core.StellarPop(isochrone, filters=None, nnfile=None, verbose=True)[source]#

Bases: object

Synthetic photometry generation for stellar populations.

This class generates synthetic SEDs and photometry for stellar populations using neural network-based bolometric corrections. It provides sophisticated modeling of binary stars, dust extinction, and observational effects.

This class is analogous to StarEvolTrack but for stellar populations: - StarEvolTrack: Individual star photometry - StellarPop: Stellar population photometry

The class uses dependency injection, accepting an Isochrone instance for stellar parameter predictions rather than inheriting from it.

Parameters:

isochrone (Isochrone) – Isochrone instance for stellar parameter predictions.
filters (list of str, optional) – Filter names for photometry computation. If None, uses all available.
nnfile (str, optional) – Path to neural network file for bolometric corrections.
verbose (bool, optional) – Whether to output progress messages. Default is True.

isochrone#

The isochrone model used for stellar parameter predictions

Type:: Isochrone

filters#

Array of filter names

Type:: numpy.ndarray

predictor#

Neural network predictor for photometry

Type:: FastNNPredictor

Examples

Basic stellar population photometry:

>>> iso = Isochrone()
>>> ssp = StellarPop(isochrone=iso)
>>>
>>> # Generate SEDs for solar metallicity, 1 Gyr population
>>> seds, params, params2 = ssp.get_seds(
...     feh=0.0, afe=0.0, loga=9.0,
...     av=0.1, rv=3.1, dist=1000.0
... )

Binary population modeling:

>>> # Model population with 40% mass ratio binaries
>>> seds, params, params2 = ssp.get_seds(
...     feh=-0.5, afe=0.3, loga=10.0,
...     binary_fraction=0.4,
...     av=0.2, dist=2000.0
... )

See also

Isochrone: Stellar parameter predictions used by this class
StarEvolTrack: Individual star analog
brutus.core.neural_nets.FastNNPredictor: Neural network SED generation

Notes

The synthetic photometry generation includes:

Stellar Parameter Prediction: Uses the injected Isochrone instance
Neural Network Photometry: Fast bolometric correction computation
Binary Star Modeling: Sophisticated binary population synthesis
Dust Extinction: Parameterized extinction laws
Distance Effects: Distance modulus calculations

Binary modeling includes mass ratio constraints, evolutionary phase matching, and realistic limits on binary evolution (typically restricted to main sequence phases).

__init__(isochrone, filters=None, nnfile=None, verbose=True)[source]#

get_seds(feh=0.0, afe=0.0, loga=8.5, eep=None, av=0.0, rv=3.3, binary_fraction=0.0, dist=1000.0, mini_bound=0.5, eep_binary_max=480.0, apply_corr=True, corr_params=None, return_dict=True, **kwargs)[source]#

Generate synthetic photometry for a stellar population.

Parameters:

feh (float, optional) – Metallicity [Fe/H]. Default is 0.0.
afe (float, optional) – Alpha enhancement [alpha/Fe]. Default is 0.0.
loga (float, optional) – Log10(age in years). Default is 8.5.
eep (array-like, optional) – Equivalent evolutionary points. If None, uses isochrone default.
av (float, optional) – V-band extinction A(V). Default is 0.0.
rv (float, optional) – Extinction law parameter R(V). Default is 3.3.
binary_fraction (float, optional) – Secondary mass fraction for binaries. Default is 0.0 (no binaries). - 0.0: No binaries - 0 < binary_fraction < 1: Mass ratio binaries - 1.0: Equal mass binaries
dist (float, optional) – Distance in parsecs. Default is 1000.0.
mini_bound (float, optional) – Minimum mass for SED computation. Default is 0.5.
eep_binary_max (float, optional) – Maximum EEP for binary modeling. Default is 480.0.
apply_corr (bool, optional) – Apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters.
return_dict (bool, optional) – Return parameters as dictionaries. Default is True.

Returns:

seds (numpy.ndarray of shape (Neep, Nfilters)) – Synthetic SEDs in magnitudes.
params (dict or numpy.ndarray) – Primary component stellar parameters.
params2 (dict or numpy.ndarray) – Secondary component parameters (for binaries).

See also

Isochrone.get_predictions: Stellar parameter predictions
FastNNPredictor.sed: Neural network photometry generation
StarEvolTrack.get_seds: Individual star analog

Notes

The photometry generation workflow:

Predict stellar parameters from isochrone
Generate primary SEDs using neural network
For binaries: generate secondary SEDs and combine
Apply dust extinction with specified R(V)
Apply distance modulus

Binary stars are modeled with the same age and metallicity as primaries, with masses determined by the binary_fraction parameter. Binary companions are only added for stars below eep_binary_max (typically restricted to main sequence).

Examples

Simple stellar population:

>>> seds, params, params2 = pop_synth.get_seds(
...     feh=0.0, loga=9.0, av=0.1, dist=1000.0
... )

Binary population:

>>> seds, params, params2 = pop_synth.get_seds(
...     feh=-0.5, loga=10.0, binary_fraction=0.4,
...     av=0.2, dist=2000.0
... )

Neural Networks#

class brutus.core.FastNN(filters=None, nnfile=None, verbose=True)[source]#

Bases: object

Object that wraps the underlying neural networks used to interpolate.

between grid points on the bolometric correction tables.

This class provides the core neural network functionality for predicting bolometric corrections from stellar parameters. It loads pre-trained neural network weights and biases, and provides methods for encoding input parameters and evaluating the network.

Parameters:

filters (list of str, optional) – The names of filters that photometry should be computed for. If not provided, all available filters will be used. Filter names should match those defined in brutus.data.filters.FILTERS.
nnfile (str, optional) – Path to the neural network file containing pre-trained weights and biases. Default is ‘brutus/data/DATAFILES/nnMIST_BC.h5’ which will be downloaded automatically if not present.
verbose (bool, optional) – Whether to print initialization progress messages to stderr. Default is True.

w1, w2, w3

Neural network weight matrices for each layer.

Type:: numpy.ndarray

b1, b2, b3

Neural network bias vectors for each layer.

Type:: numpy.ndarray

xmin, xmax

Minimum and maximum values for input parameter scaling.

Type:: numpy.ndarray

xspan#

Range of input parameters (xmax - xmin).

Type:: numpy.ndarray

Notes

The neural network architecture is a 3-layer feedforward network with sigmoid activation functions. Input parameters are scaled to [0,1] range before evaluation.

Expected input parameters (in order): - log10(Teff) : Effective temperature in Kelvin - log g : Surface gravity in cgs units - [Fe/H] : Surface metallicity (log scale) - [α/Fe] : Alpha enhancement (log scale) - Av : V-band extinction in magnitudes - Rv : Reddening parameter R(V) = A(V)/E(B-V)

__init__(filters=None, nnfile=None, verbose=True)[source]#

encode(x)[source]#

Rescale input parameters to [0,1] range for neural network evaluation.

The neural networks are trained on scaled inputs where each parameter is normalized to the range [0,1] based on the training data bounds.

Parameters:: x (numpy.ndarray of shape (Ninput,) or (Ninput, Nsamples)) – Input stellar parameters. Expected parameters are: [log10(Teff), log g, [Fe/H], [alpha/Fe], Av, Rv]
Returns:: xp – Scaled input parameters ready for neural network evaluation.
Return type:: numpy.ndarray of shape (Ninput, 1) or (Ninput, Nsamples)

Notes

The scaling is applied as: x_scaled = (x - xmin) / (xmax - xmin) where xmin and xmax are the bounds from the training data.

sigmoid(a)[source]#

Apply sigmoid activation function.

Computes the logistic sigmoid function: f(a) = 1 / (1 + exp(-a))

Parameters:: a (numpy.ndarray) – Input array to apply sigmoid transformation to.
Returns:: a_t – Output after applying sigmoid activation, same shape as input.
Return type:: numpy.ndarray

Notes

The sigmoid function maps any real number to the range (0, 1), providing smooth activation for the neural network hidden layers.

nneval(x)[source]#

Evaluate the neural network for given input parameters.

Performs forward propagation through the 3-layer neural network to predict bolometric corrections for all filters.

Parameters:: x (numpy.ndarray of shape (Ninput,)) – Stellar parameters: [log10(Teff), log g, [Fe/H], [alpha/Fe], Av, Rv]
Returns:: y – Predicted bolometric corrections for each filter.
Return type:: numpy.ndarray

Notes

The network architecture is: - Input layer: 6 parameters - Hidden layer 1: with sigmoid activation - Hidden layer 2: with sigmoid activation - Output layer: linear activation (bolometric corrections)

class brutus.core.FastNNPredictor(filters=None, nnfile=None, verbose=True)[source]#

Bases: FastNN

Object that generates SED predictions for a provided set of filters using neural networks.

This class extends FastNN to provide a complete interface for stellar SED prediction, including automatic distance modulus calculation and conversion from bolometric corrections to apparent magnitudes.

Parameters:

filters (list of str, optional) – The names of filters that photometry should be computed for. If not provided, all available filters will be used. Must be a subset of filters available in the neural network file.
nnfile (str, optional) – Path to the neural network file containing pre-trained weights. Default is ‘brutus/data/DATAFILES/nnMIST_BC.h5’ which contains networks trained on MIST isochrones with C3K synthetic spectra.
verbose (bool, optional) – Whether to print initialization progress messages. Default is True.

filters#

Array of filter names for which predictions are made.

Type:: numpy.ndarray

NFILT#

Number of filters for which predictions are made.

Type:: int

Examples

Predict SED for a solar analog:

>>> predictor = FastNNPredictor(filters=['g', 'r', 'i'])
>>> sed = predictor.sed(logt=3.76, logg=4.44, feh_surf=0.0,
...                     logl=0.0, dist=1000.)
>>> print(f"g-r color: {sed[0] - sed[1]:.3f}")

Predict for a red giant with extinction:

>>> sed = predictor.sed(logt=3.60, logg=2.5, feh_surf=-0.5,
...                     logl=1.5, av=0.5, rv=3.1, dist=2000.)

Notes

The neural networks provide bolometric corrections which are combined with luminosity and distance to produce apparent magnitudes:

m = -2.5 * log10(L/L_sun) + 4.74 - BC + distance_modulus

where BC is the bolometric correction predicted by the neural network.

__init__(filters=None, nnfile=None, verbose=True)[source]#

sed(logt=3.8, logg=4.4, feh_surf=0.0, logl=0.0, afe=0.0, av=0.0, rv=3.3, dist=1000.0, filt_idxs=slice(None, None, None))[source]#

Generate SED predictions for specified stellar parameters.

Returns predicted apparent magnitudes in the specified filters for a star with the given physical parameters, distance, and extinction. Uses neural network bolometric corrections combined with standard photometric transformations.

Parameters:

logt (float, optional) – Base-10 logarithm of effective temperature in Kelvin. Typical range: [3.3, 4.5] corresponding to ~2000-30000K. Default is 3.8 (6300K, solar-type).
logg (float, optional) – Base-10 logarithm of surface gravity in cgs units (cm/s^2). Typical range: [0, 5] from supergiants to white dwarfs. Default is 4.4 (solar value).
feh_surf (float, optional) – Surface metallicity [Fe/H] in logarithmic units relative to solar. Typical range: [-2.5, 0.5]. Default is 0.0 (solar).
logl (float, optional) – Base-10 logarithm of luminosity in solar luminosities. Typical range: [-4, 6] from low-mass MS to supergiants. Default is 0.0 (solar luminosity).
afe (float, optional) – Alpha element enhancement [alpha/Fe] in logarithmic units relative to solar abundance ratios. Typical range: [-0.2, 0.8]. Default is 0.0 (solar ratios).
av (float, optional) – V-band extinction in magnitudes. Must be non-negative. Typical range: [0, 6] mag. Default is 0.0 (no extinction).
rv (float, optional) – Reddening parameter R(V) = A(V)/E(B-V), describing the extinction curve shape. Typical range: [1, 8]. Default is 3.3 (Milky Way average).
dist (float, optional) – Distance to the star in parsecs. Must be positive. Default is 1000 pc.
filt_idxs (slice or array-like, optional) – Indices or slice object specifying which subset of filters to return predictions for. Default is slice(None) (all filters).

Returns:

sed – Predicted apparent magnitudes in the specified filter subset. Magnitudes are in the AB system and include distance modulus and extinction corrections.

Return type:

numpy.ndarray of shape (Nfilt_subset,)

Notes

The computation follows these steps:

Compute distance modulus: mu = 5 * log10(dist) - 5
Evaluate neural network for bolometric corrections: BC = NN(params)
Convert to apparent magnitudes: m = -2.5 * logl + 4.74 - BC + mu

If any input parameters are outside the neural network training bounds, NaN values are returned for safety.

Examples

Solar analog at various distances:

>>> predictor = FastNNPredictor(['V', 'K'])
>>> for d in [100, 1000, 10000]:  # pc
...     sed = predictor.sed(dist=d)
...     print(f"{d:5d} pc: V={sed[0]:.2f}, K={sed[1]:.2f}")

Effect of extinction:

>>> sed_clean = predictor.sed(av=0.0)
>>> sed_dusty = predictor.sed(av=1.0, rv=3.1)
>>> extinction = sed_dusty - sed_clean
>>> print(f"V-band extinction: {extinction[0]:.2f} mag")

sed_batch(logt, logg, feh_surf, logl, afe, av, rv, dist, filt_idxs=slice(None, None, None))[source]#

Generate SED predictions for an array of stellar parameters.

Vectorized version of sed() that evaluates the neural network once for all stars, providing significant speedup over looping.

Parameters:

logt (numpy.ndarray of shape (N,)) – Base-10 logarithm of effective temperature for each star.
logg (numpy.ndarray of shape (N,)) – Base-10 logarithm of surface gravity for each star.
feh_surf (numpy.ndarray of shape (N,)) – Surface metallicity [Fe/H] for each star.
logl (numpy.ndarray of shape (N,)) – Base-10 logarithm of luminosity for each star.
afe (numpy.ndarray of shape (N,)) – Alpha element enhancement [alpha/Fe] for each star.
av (float) – V-band extinction (same for all stars).
rv (float) – Reddening parameter R(V) (same for all stars).
dist (float) – Distance in parsecs (same for all stars).
filt_idxs (slice or array-like, optional) – Filter subset to return. Default is all filters.

Returns:

seds – Predicted apparent magnitudes for each star and filter. Stars with out-of-bounds parameters get NaN values.

Return type:

numpy.ndarray of shape (N, Nfilt_subset)

Grid Generation#

class brutus.core.GridGenerator(tracks, filters=None, nnfile=None, verbose=True)[source]#

Bases: object

Generate pre-computed stellar model grids with reddening coefficients.

This class creates HDF5 grid files used by StarGrid for fast photometric predictions. Grids are computed at 1 kpc reference distance and include polynomial coefficients for A_V and R_V reddening corrections.

The generator uses evolutionary tracks (EEPTracks or Isochrone) combined with neural network bolometric corrections to compute photometry across a multi-dimensional parameter grid, then fits reddening vectors to enable fast interpolation.

Parameters:

tracks (EEPTracks or Isochrone) – Stellar evolutionary track model providing parameter predictions. Must have compatible interface (get_predictions method).
filters (list of str, optional) – Names of photometric filters for which to generate models. If None, uses all available filters from FILTERS.
nnfile (str or Path, optional) – Path to neural network file for bolometric corrections. If None, uses default neural network file.
verbose (bool, optional) – Whether to print progress messages during initialization. Default is True.

tracks#

Evolutionary track model

Type:: EEPTracks or Isochrone

star_track#

SED generator combining tracks with neural networks

Type:: StarEvolTrack

filters#

Array of filter names

Type:: numpy.ndarray

predictor#

Neural network predictor for photometry

Type:: FastNNPredictor

Examples

Create grid generator and generate default grid:

>>> from brutus.core.individual import EEPTracks
>>> from brutus.core.grid_generation import GridGenerator
>>>
>>> tracks = EEPTracks(verbose=False)
>>> gen = GridGenerator(tracks)
>>> gen.make_grid(output_file='grid.h5', verbose=True)

Generate grid for specific filters only:

>>> gen_gaia = GridGenerator(tracks, filters=['Gaia_G_MAW', 'Gaia_BP_MAWf', 'Gaia_RP_MAW'])
>>> gen_gaia.make_grid(output_file='grid_gaia.h5')

Notes

The GridGenerator uses dependency injection rather than inheritance, accepting an EEPTracks (or Isochrone) instance. This design: - Maintains consistency with StarEvolTrack architecture - Allows flexibility in track implementations - Enables easier testing with mock tracks - Separates grid generation from track interpolation logic

See also

brutus.core.individual.StarGrid: Uses grids generated by this class
brutus.data.loader.load_models: Loads grids generated by this class

__init__(tracks, filters=None, nnfile=None, verbose=True)[source]#: Initialize grid generator with evolutionary tracks.

make_grid(mini_grid=None, eep_grid=None, feh_grid=None, afe_grid=None, smf_grid=None, av_grid=None, av_wt=None, rv_grid=None, rv_wt=None, dist=1000.0, loga_max=10.14, eep_binary_max=480.0, mini_bound=0.5, apply_corr=True, corr_params=None, output_file=None, verbose=True)[source]#

Generate model grid with reddening coefficients.

Creates a grid of stellar models across the specified parameter space, computing photometry at 1 kpc reference distance and fitting polynomial coefficients for reddening corrections. Results are saved to HDF5 format compatible with StarGrid.

Parameters:

mini_grid (numpy.ndarray, optional) – Grid of initial masses in solar masses. If None, defaults to np.arange(0.5, 2.0, 0.025) covering low to intermediate mass stars.
eep_grid (numpy.ndarray, optional) – Grid of equivalent evolutionary points. If None, defaults to adaptive grid: resolution 6 from 202-454 (MS), resolution 2 from 454-808 (post-MS).
feh_grid (numpy.ndarray, optional) – Grid of [Fe/H] metallicity values. If None, defaults to adaptive grid: resolution 0.1 from -3.0 to -2.0, resolution 0.05 from -2.0 to +0.5.
afe_grid (numpy.ndarray, optional) – Grid of [α/Fe] alpha enhancement values. If None, defaults to np.arange(-0.2, 0.6, 0.2).
smf_grid (numpy.ndarray, optional) – Grid of secondary mass fractions for binaries. If None, defaults to [0.] (single stars only).
av_grid (numpy.ndarray, optional) – Grid of A_V extinction values used for fitting reddening vector. If None, defaults to np.arange(0., 1.5, 0.3).
av_wt (numpy.ndarray, optional) – Weights for A_V grid points when fitting. If None, defaults to (1e-5 + av_grid)**-1 which forces fit through A_V=0.
rv_grid (numpy.ndarray, optional) – Grid of R_V values used for fitting differential reddening. If None, defaults to np.arange(2.4, 4.2, 0.3).
rv_wt (numpy.ndarray, optional) – Weights for R_V grid points when fitting. If None, defaults to exp(-abs(R_V - 3.3) / 0.5) favoring R_V=3.3.
dist (float, optional) – Reference distance in parsecs. Default is 1000 (1 kpc). This should not be changed as it affects StarGrid calibration.
loga_max (float, optional) – Maximum log10(age) in years. Models older than this are masked. Default is 10.14 (13.8 Gyr).
eep_binary_max (float, optional) – Maximum EEP for binary models. Above this, binaries are not computed (typically giant phase). Default is 480.
mini_bound (float, optional) – Minimum initial mass threshold. Models below this are masked. Default is 0.5 solar masses.
apply_corr (bool, optional) – Whether to apply empirical corrections to Teff and radius. Default is True.
corr_params (tuple, optional) – Parameters for empirical corrections (dtdm, drdm, msto_smooth, feh_scale). If None, uses default values from tracks.
output_file (str or Path, optional) – Path to output HDF5 file. If None, results are stored as attributes but not saved to disk.
verbose (bool, optional) – Whether to print progress messages. Default is True.

Returns:

Results are saved to output_file if provided, and stored as class attributes: grid_labels, grid_seds, grid_params, grid_sel

Return type:

None

Notes

Grid Size: Default parameters create ~300,000 models. Computation time scales linearly with grid size and quadratically with number of (av_grid × rv_grid) points for reddening fits.

Memory Usage: Full grid with 20 filters requires ~2 GB for storage. Peak memory during generation can be 3-4× larger.

Reddening Fits: For each valid model, the code: 1. Computes SEDs across (av_grid × rv_grid) combinations 2. Fits linear dependence on A_V at each R_V value 3. Fits linear dependence of A_V slope on R_V 4. Stores [m_0, a, b] where m = m_0 + A_V·(a + b·(R_V-3.3))

Examples

Generate default grid:

>>> gen.make_grid(output_file='grid_default.h5')

Generate sparse testing grid:

>>> gen.make_grid(
...     mini_grid=np.linspace(0.8, 1.2, 5),
...     eep_grid=np.linspace(300, 450, 10),
...     feh_grid=np.array([0.0]),
...     afe_grid=np.array([0.0]),
...     smf_grid=np.array([0.0]),
...     output_file='grid_test.h5',
...     verbose=True
... )

SED Utilities#

brutus.core.get_seds(mag_coeffs, av=None, rv=None, return_flux=False, return_rvec=False, return_drvec=False)[source]#

Compute reddened SEDs from the provided magnitude coefficients.

This is a convenience wrapper around _get_seds that provides parameter handling and optional return values.

Parameters:

mag_coeffs (~numpy.ndarray of shape (Nmodels, Nbands, 3)) – Array of (mag, R, dR/dRv) coefficients used to generate reddened photometry in all bands. The first coefficient is the unreddened photometry, the second is the A(V) reddening vector for R(V)=0, and the third is the change in the reddening vector as a function of R(V).
av (float or ~numpy.ndarray of shape (Nmodels), optional) – Array of A(V) dust attenuation values. If not provided, defaults to av=0..
rv (float or ~numpy.ndarray of shape (Nmodels), optional) – Array of R(V) dust attenuation curve “shape” values. If not provided, defaults to rv=3.3.
return_flux (bool, optional) – Whether to return SEDs as flux densities instead of magnitudes. Default is False.
return_rvec (bool, optional) – Whether to return the reddening vectors at the provided av and rv. Default is False.
return_drvec (bool, optional) – Whether to return the differential reddening vectors at the provided av and rv. Default is False.

Returns:

seds (~numpy.ndarray of shape (Nmodels, Nbands)) – Reddened SEDs.
rvecs (~numpy.ndarray of shape (Nmodels, Nbands), optional) – Reddening vectors. Only returned if return_rvec=True.
drvecs (~numpy.ndarray of shape (Nmodels, Nbands), optional) – Differential reddening vectors. Only returned if return_drvec=True.

Examples

>>> import numpy as np
>>> from brutus.core.sed_utils import get_seds
>>>
>>> # Create mock magnitude coefficients for 2 models, 3 bands
>>> mag_coeffs = np.random.random((2, 3, 3))
>>> mag_coeffs[:, :, 0] = 15.0  # Base magnitudes
>>> mag_coeffs[:, :, 1] = 1.0   # R(V)=0 reddening
>>> mag_coeffs[:, :, 2] = 0.1   # dR/dR(V)
>>>
>>> # Compute reddened SEDs
>>> seds = get_seds(mag_coeffs, av=0.1, rv=3.1)
>>> print(f"SED shape: {seds.shape}")

>>> # Get SEDs and reddening vectors
>>> seds, rvecs = get_seds(mag_coeffs, av=0.1, rv=3.1, return_rvec=True)

>>> # Get all outputs
>>> seds, rvecs, drvecs = get_seds(mag_coeffs, av=0.1, rv=3.1,
...                                return_rvec=True, return_drvec=True)

Notes

This function implements the dust reddening law parameterization from Cardelli, Clayton, & Mathis (1989) and O’Donnell (1994). The reddening is applied as:

A(λ) = A(V) * [R(V)=0 + R(V) * dR/dR(V)]

where A(λ) is the extinction in a given band.

brutus.core._get_seds(mag_coeffs, av, rv, return_flux=False)[source]#

Compute reddened SEDs from the provided magnitude coefficients.

This is the core function for computing reddened SEDs, optimized with numba for performance.

Parameters:

mag_coeffs (~numpy.ndarray of shape (Nmodels, Nbands, 3)) – Array of (mag, R, dR/dRv) coefficients used to generate reddened photometry in all bands. The first coefficient is the unreddened photometry, the second is the A(V) reddening vector for R(V)=0, and the third is the change in the reddening vector as a function of R(V).
av (~numpy.ndarray of shape (Nmodels,)) – Array of A(V) dust attenuation values.
rv (~numpy.ndarray of shape (Nmodels,)) – Array of R(V) dust attenuation curve “shape” values.
return_flux (bool, optional) – Whether to return SEDs as flux densities instead of magnitudes. Default is False.

Returns:

seds (~numpy.ndarray of shape (Nmodels, Nbands)) – Reddened SEDs.
rvecs (~numpy.ndarray of shape (Nmodels, Nbands)) – Reddening vectors.
drvecs (~numpy.ndarray of shape (Nmodels, Nbands)) – Differential reddening vectors.

Submodules#

For advanced users who need access to internal implementations:

Individual stellar modeling and synthetic photometry generation.

This module provides classes for modeling individual stars using MIST (MESA Isochrones and Stellar Tracks) evolutionary tracks and generating synthetic photometry with neural network-based bolometric corrections.

The module follows a clean separation of concerns: - EEPTracks: Stellar parameter predictions for individual stars - StarEvolTrack: SED/photometry generation for individual stars

This design mirrors the stellar population modeling pattern: - Isochrone: Stellar parameter predictions for populations - StellarPop: SED/photometry generation for populations

Classes#

EEPTracksIndividual stellar parameter predictions: Interpolates MIST evolutionary tracks to predict stellar parameters (age, luminosity, temperature, etc.) as a function of initial mass, evolutionary phase (EEP), metallicity, and alpha enhancement.
StarEvolTrackIndividual stellar photometry synthesis: Generates synthetic photometry for individual stars using neural network bolometric corrections, with support for binary companions, dust extinction, and observational effects.

Examples

Basic individual star modeling:

>>> from brutus.core.individual import EEPTracks, StarEvolTrack
>>>
>>> # Create tracks for parameter predictions
>>> tracks = EEPTracks()
>>> params = tracks.get_predictions([1.0, 350, 0.0, 0.0])  # mini, eep, feh, afe
>>>
>>> # Create star track for photometry
>>> star_track = StarEvolTrack(tracks=tracks)
>>> sed, params, params2 = star_track.get_seds(
>>>     mini=1.0, eep=350, feh=0.0, afe=0.0,
>>>     av=0.1, dist=1000.0
>>> )

Advanced usage with binary stars:

>>> # Model binary system with mass ratio 0.7
>>> sed, params, params2 = star_track.get_seds(
>>>     mini=1.2, eep=400, feh=-0.2, afe=0.1,
>>>     smf=0.7, av=0.15, dist=1500.0
>>> )

Notes

This design provides several advantages:

Separation of Concerns: Parameter prediction vs. photometry synthesis
Consistency: Mirrors the stellar population modeling pattern
Flexibility: Can use different SED generators with same tracks
Generality: EEPTracks name allows for future non-MIST implementations
Maintainability: Cleaner, more focused class responsibilities

The StarEvolTrack class uses dependency injection, accepting an EEPTracks instance rather than inheriting from it. This makes the code more modular and allows for different track implementations.

This implementation is based on the MIST stellar evolution framework (Choi et al. 2016; Dotter 2016).

References

Choi et al. 2016, “MESA Isochrones and Stellar Tracks (MIST) 0. Methods for the Construction of Stellar Isochrones”, ApJ, 823, 102
Dotter 2016, “MESA Isochrones and Stellar Tracks (MIST) I. Solar-scaled Models”, ApJS, 222, 8

class brutus.core.individual.EEPTracks(mistfile=None, predictions=['loga', 'logl', 'logt', 'logg', 'feh_surf', 'afe_surf'], ageweight=True, verbose=True, use_cache=True)[source]

Bases: object

Stellar parameter predictions for individual stars using evolutionary tracks.

This class provides interpolation of stellar parameters along evolutionary tracks as a function of initial mass, equivalent evolutionary point (EEP), metallicity, and alpha enhancement. It focuses solely on stellar parameter prediction without photometry generation.

The class name “EEPTracks” is intentionally general to allow for future implementations beyond MIST, while the current implementation uses MIST (MESA Isochrones and Stellar Tracks) evolutionary models.

For photometry generation, use StarEvolTrack with this class.

Parameters:

mistfile (str, optional) – Path to the HDF5 file containing the evolutionary tracks. If not provided, defaults to the standard MIST v1.2 EEP tracks file.
predictions (iterable of str, optional) – The names of stellar parameters to predict. Default is: [“loga”, “logl”, “logt”, “logg”, “feh_surf”, “afe_surf”].
ageweight (bool, optional) – Whether to compute age weights d(age)/d(EEP) for age priors. Default is True.
verbose (bool, optional) – Whether to output progress messages during initialization. Default is True.
use_cache (bool, optional) – Whether to use pickle caching to speed up loading. If True, will save processed EEPTracks to a .pkl file for faster subsequent loads, and load from cache if available and newer than the original file. Default is True.

labels

Input parameter names: [‘mini’, ‘eep’, ‘feh’, ‘afe’]

Type:: list of str

predictions

Output parameter names as specified in initialization

Type:: list of str

ndim, npred

Number of input dimensions and predicted parameters

Type:: int

interpolator

The main interpolation object for stellar parameter prediction

Type:: scipy.interpolate.RegularGridInterpolator

gridpoints

Unique grid points for each input parameter

Type:: dict

Examples

Predict parameters for a solar-mass star on the main sequence:

>>> tracks = EEPTracks()
>>> params = tracks.get_predictions([1.0, 350, 0.0, 0.0])  # mini, eep, feh, afe
>>> log_age = params[0]  # log10(age in years)
>>> log_teff = params[2]  # log10(effective temperature)
>>> print(f"Age: {10**log_age:.1e} yr, Teff: {10**log_teff:.0f} K")

Batch prediction for multiple stars:

>>> import numpy as np
>>> labels = np.array([[0.8, 350, -0.5, 0.2],   # Metal-poor dwarf
...                    [1.2, 454, 0.0, 0.0],    # Solar at turnoff
...                    [2.0, 500, 0.3, 0.0]])   # Massive metal-rich
>>> preds = tracks.get_predictions(labels)
>>> ages = 10**preds[:, 0]  # Convert to linear ages

__init__(mistfile=None, predictions=['loga', 'logl', 'logt', 'logg', 'feh_surf', 'afe_surf'], ageweight=True, verbose=True, use_cache=True)[source]

get_predictions(labels, apply_corr=True, corr_params=None)[source]

Generate stellar parameter predictions for given input parameters.

Parameters:

labels (array-like of shape (4,) or (Nobj, 4)) – Input parameters [mini, eep, feh, afe] where: - mini: Initial mass in solar masses - eep: Equivalent evolutionary point - feh: Metallicity [Fe/H] in logarithmic solar units - afe: Alpha enhancement [alpha/Fe] in logarithmic solar units
apply_corr (bool, optional) – Whether to apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale).

Returns:

preds – Predicted stellar parameters in the order specified by self.predictions attribute.

Return type:

numpy.ndarray of shape (Npred,) or (Nobj, Npred)

See also

get_corrections: Computes empirical corrections applied when apply_corr=True
StarEvolTrack.get_seds: Uses these predictions to generate photometry

Examples

Single star prediction:

>>> tracks = EEPTracks()
>>> params = tracks.get_predictions([1.0, 350, 0.0, 0.0])
>>> log_age, log_L, log_Teff, log_g = params[:4]

Multiple star prediction:

>>> import numpy as np
>>> labels = np.array([[0.8, 350, -0.5, 0.2], [1.2, 454, 0.0, 0.0]])
>>> params = tracks.get_predictions(labels)

get_corrections(labels, corr_params=None)[source]

Compute empirical corrections to stellar parameters.

Applies empirical corrections to effective temperature and radius based on stellar mass, evolutionary phase (EEP), and metallicity. These corrections account for systematic offsets between MIST models and observations, particularly for low-mass stars.

Parameters:

labels (array-like of shape (4,) or (Nobj, 4)) – Input parameters [mini, eep, feh, afe] where: - mini: Initial mass in solar masses - eep: Equivalent evolutionary point - feh: Metallicity [Fe/H] - afe: Alpha enhancement [α/Fe]
corr_params (tuple of float, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale) where: - dtdm: Temperature correction slope with mass - drdm: Radius correction slope with mass - msto_smooth: Smoothing scale for main sequence turnoff transition - feh_scale: Metallicity scaling factor Default is (0.09, -0.09, 30.0, 0.5).

Returns:

corrs – Corrections to [log(Teff), log(R)]. These are added to the base predictions from the interpolator.

Return type:

numpy.ndarray of shape (2,) or (Nobj, 2)

See also

get_predictions: Applies these corrections to stellar parameters

Notes

Corrections are applied as:

\[\begin{split}\\Delta \\log T_{\\rm eff} = f_{\\rm EEP} \\cdot f_{\\rm [Fe/H]} \\cdot \\log(1 + \\Delta M \\cdot \\alpha_T) \\Delta \\log R = f_{\\rm EEP} \\cdot f_{\\rm [Fe/H]} \\cdot \\log(1 + \\Delta M \\cdot \\alpha_R)\end{split}\]

where \(\\Delta M = M_{\\rm ini} - 1.0\) and the EEP factor smoothly transitions from 0 (pre-main sequence) to 1 (post-turnoff).

Corrections are set to zero for stars with \(M_{\\rm ini} \\geq 1.0 M_\\odot\).

class brutus.core.individual.StarEvolTrack(tracks, filters=None, nnfile=None, verbose=True)[source]

Bases: object

Synthetic photometry generation for individual stars.

This class generates synthetic SEDs and photometry for individual stars using neural network-based bolometric corrections. It provides modeling of binary stars, dust extinction, and observational effects.

This class mirrors StellarPop but for individual stars: - StarEvolTrack: Individual star photometry - StellarPop: Stellar population photometry

The class uses dependency injection, accepting an EEPTracks instance for stellar parameter predictions rather than inheriting from it.

Parameters:

tracks (EEPTracks) – EEPTracks instance for stellar parameter predictions.
filters (list of str, optional) – Filter names for photometry computation. If None, uses all available.
nnfile (str, optional) – Path to neural network file for bolometric corrections.
verbose (bool, optional) – Whether to output progress messages. Default is True.

tracks

The evolutionary track model for stellar parameter predictions

Type:: EEPTracks

filters

Array of filter names

Type:: numpy.ndarray

predictor

Neural network predictor for photometry

Type:: FastNNPredictor

See also

EEPTracks: Stellar parameter predictions used by this class
StarGrid: Alternative grid-based approach for photometry
brutus.core.neural_nets.FastNNPredictor: Neural network used for SEDs

Examples

Basic individual star photometry:

>>> tracks = EEPTracks()
>>> star_track = StarEvolTrack(tracks=tracks)
>>>
>>> # Generate SED for a solar-mass main sequence star
>>> sed, params, params2 = star_track.get_seds(
...     mini=1.0, eep=350, feh=0.0, afe=0.0,
...     av=0.1, rv=3.1, dist=1000.0
... )

Binary star modeling:

>>> # Model binary with 70% mass ratio secondary
>>> sed, params, params2 = star_track.get_seds(
...     mini=1.2, eep=400, feh=-0.2, afe=0.1,
...     smf=0.7, av=0.15, dist=1500.0
... )

__init__(tracks, filters=None, nnfile=None, verbose=True)[source]

get_seds(mini=1.0, eep=350, feh=0.0, afe=0.0, av=0.0, rv=3.3, smf=0.0, dist=1000.0, loga_max=10.15, eep2=None, mini_bound=0.08, eep_binary_max=480.0, apply_corr=True, corr_params=None, return_eep2=False, return_dict=True, combine_seds=True, tol=0.01, **kwargs)[source]

Generate synthetic SED for an individual star.

Parameters:

mini (float, optional) – Initial stellar mass in solar masses. Default is 1.0.
eep (float, optional) – Equivalent evolutionary point. Default is 350.
feh (float, optional) – Metallicity [Fe/H]. Default is 0.0.
afe (float, optional) – Alpha enhancement [α/Fe]. Default is 0.0.
av (float, optional) – V-band extinction A(V). Default is 0.0.
rv (float, optional) – Extinction law parameter R(V). Default is 3.3.
smf (float, optional) – Secondary mass fraction for binary. Default is 0.0 (single star).
dist (float, optional) – Distance in parsecs. Default is 1000.0.
loga_max (float, optional) – Maximum log(age) for SED computation. Default is 10.15.
eep2 (float, optional) – EEP of secondary component for binaries.
mini_bound (float, optional) – Minimum mass for SED computation. Default is 0.08.
eep_binary_max (float, optional) – Maximum EEP for binary modeling. Default is 480.0.
apply_corr (bool, optional) – Apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters.
return_eep2 (bool, optional) – Return secondary EEP. Default is False.
return_dict (bool, optional) – Return parameters as dictionary. Default is True.
combine_seds (bool, optional) – If True and binary star requested, combine primary and secondary SEDs by adding their magnitudes. If False, separate SEDs for primary and secondary will be returned. Default is True.
tol (float, optional) – Convergence tolerance (in dex) on the log10(age) match when solving for the secondary’s EEP in a binary. A companion whose age cannot be matched to within tol is treated as non-existent and a primary-only SED is returned (rather than discarding the model). Default is 1e-2. The previous default (1e-6) was far tighter than the age emulator’s own precision and silently dropped most otherwise-valid binary models.

Returns:

sed (numpy.ndarray of shape (Nfilters,) or tuple) – Synthetic SED in magnitudes.
params (dict or numpy.ndarray) – Primary component stellar parameters.
params2 (dict or numpy.ndarray) – Secondary component parameters.
eep2 (float, optional) – Secondary EEP (if return_eep2=True).

See also

EEPTracks.get_predictions: Stellar parameter predictions
FastNNPredictor.sed: Neural network SED generation
_get_eep_for_secondary: Binary companion EEP calculation

Notes

Distance modulus is applied as:

\[\begin{split}m = M + 5 \\log_{10}(d/10\\,{\\rm pc})\end{split}\]

where d is the distance in parsecs.

Binary SEDs are combined using magnitude addition (flux summing):

\[\begin{split}m_{\\rm combined} = -2.5 \\log_{10}(10^{-0.4 m_1} + 10^{-0.4 m_2})\end{split}\]

Examples

Single star:

>>> sed, params, params2 = star_track.get_seds(
...     mini=1.0, eep=350, feh=0.0, afe=0.0
... )

Binary system:

>>> sed, params, params2 = star_track.get_seds(
...     mini=1.2, eep=400, feh=-0.2, afe=0.1, smf=0.7
... )

Stellar population modeling and synthetic photometry generation.

This module provides classes for modeling stellar populations using MIST (MESA Isochrones and Stellar Tracks) isochrones and generating synthetic photometry with neural network-based bolometric corrections.

The module follows a clean separation of concerns: - Isochrone: Stellar parameter predictions for populations - StellarPop: SED/photometry generation for populations

This design is consistent with the individual star modeling pattern: - EEPtracks: Stellar parameter predictions for individuals - StarEvolTrack: SED/photometry generation for individuals

Classes#

IsochroneStellar population parameter predictions: Interpolates MIST isochrones to predict stellar parameters (mass, age, temperature, etc.) as a function of metallicity, alpha enhancement, age, and evolutionary phase.
StellarPopStellar population photometry synthesis: Generates synthetic photometry for stellar populations using neural network bolometric corrections, with support for binary stars, dust extinction, and complex evolutionary modeling.

Examples

Basic stellar population modeling:

>>> from brutus.core.populations import Isochrone, StellarPop
>>>
>>> # Create isochrone for parameter predictions
>>> iso = Isochrone()
>>> params = iso.get_predictions(feh=0.0, afe=0.0, loga=9.0)
>>>
>>> # Create population synthesizer for photometry
>>> pop_synth = StellarPop(isochrone=iso)
>>> seds, params, params2 = pop_synth.get_seds(
...     feh=0.0, afe=0.0, loga=9.0,
...     av=0.1, dist=1000.0
... )

Advanced usage with binary populations:

>>> # Model binary stellar populations
>>> seds, params, params2 = pop_synth.get_seds(
...     feh=-0.5, afe=0.3, loga=10.0,
...     binary_fraction=0.4,  # 40% mass ratio binaries
...     av=0.2, dist=2000.0
... )

Notes

This design provides several advantages over the original combined approach:

Separation of Concerns: Parameter prediction vs. photometry synthesis
Flexibility: Can use different SED generators with same isochrone
Consistency: Matches the individual star modeling pattern
Maintainability: Cleaner, more focused class responsibilities
Testability: Each component can be tested independently

The StellarPop class uses dependency injection, accepting an Isochrone instance rather than inheriting from it. This makes the code more modular and allows for different isochrone implementations.

This implementation is based on the MIST stellar evolution framework (Choi et al. 2016; Dotter 2016).

References

Choi et al. 2016, “MESA Isochrones and Stellar Tracks (MIST) 0. Methods for the Construction of Stellar Isochrones”, ApJ, 823, 102
Dotter 2016, “MESA Isochrones and Stellar Tracks (MIST) I. Solar-scaled Models”, ApJS, 222, 8

class brutus.core.populations.Isochrone(mistfile=None, predictions=None, verbose=True)[source]

Bases: object

Stellar parameter predictions for isochrones using MIST evolutionary models.

This class provides interpolation of stellar parameters along isochrones of fixed metallicity, alpha enhancement, and age. It focuses solely on stellar parameter prediction (masses, temperatures, luminosities, etc.) without photometry generation.

This class is analogous to MISTtracks but for stellar populations: - MISTtracks: Individual star parameters (mini, EEP, feh, afe) → parameters - Isochrone: Population parameters (feh, afe, loga, EEP) → parameters

For photometry generation, use StellarPop with this class.

Parameters:

mistfile (str, optional) – Path to the HDF5 file containing the MIST isochrone grid. If not provided, defaults to the standard MIST v1.2 isochrone file.
predictions (list of str, optional) – The names of stellar parameters to predict. Default is: [“mini”, “mass”, “logl”, “logt”, “logr”, “logg”, “feh_surf”, “afe_surf”].
verbose (bool, optional) – Whether to output progress messages during initialization. Default is True.

predictions

List of stellar parameter names for prediction

Type:: list of str

feh_grid, afe_grid, loga_grid, eep_grid

Input parameter grids from MIST isochrone file

Type:: numpy.ndarray

pred_grid

Stellar parameter predictions organized by grid coordinates

Type:: numpy.ndarray

interpolator

Main interpolation object for stellar parameter prediction

Type:: scipy.interpolate.RegularGridInterpolator

Examples

Generate stellar parameters for a solar metallicity, 1 Gyr population:

>>> iso = Isochrone()
>>> params = iso.get_predictions(feh=0.0, afe=0.0, loga=9.0)
>>> masses = params[:, 0]  # Initial masses
>>> log_teff = params[:, 3]  # log(effective temperatures)
>>> print(f"Mass range: {masses.min():.2f} - {masses.max():.2f} M_sun")

Generate parameters for specific evolutionary phases:

>>> import numpy as np
>>> eep_range = np.arange(200, 500, 50)  # Main sequence to turnoff
>>> params = iso.get_predictions(feh=-0.5, afe=0.3, loga=10.0, eep=eep_range)

__init__(mistfile=None, predictions=None, verbose=True)[source]

get_predictions(feh=0.0, afe=0.0, loga=8.5, eep=None, apply_corr=True, corr_params=None)[source]

Generate stellar parameter predictions for an isochrone.

Parameters:

feh (float, optional) – Metallicity [Fe/H] relative to solar. Default is 0.0.
afe (float, optional) – Alpha enhancement [alpha/Fe] relative to solar. Default is 0.0.
loga (float, optional) – Log10(age in years). Default is 8.5 (≈316 Myr).
eep (array-like, optional) – Equivalent evolutionary points. If None, uses default grid.
apply_corr (bool, optional) – Whether to apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters (dtdm, drdm, msto_smooth, feh_scale).

Returns:

preds – Stellar parameter predictions for each EEP value. The columns correspond to the parameters listed in self.pred_labels.

Return type:

numpy.ndarray of shape (Neep, Npred)

See also

StellarPop.get_seds: Uses these predictions for photometry generation
brutus.core.EEPTracks.get_predictions: Similar function for individual stars

Notes

The method interpolates across the pre-computed MIST isochrone grid. Returns NaN for parameters outside the grid bounds or where data is not available.

Common EEP ranges: - Pre-main sequence: EEP < 202 - Zero-age main sequence: EEP = 202 - Terminal-age main sequence: EEP = 454 - Subgiant branch: EEP 454-605 - Red giant branch: EEP 605-1409

Examples

>>> iso = Isochrone()
>>> # Get parameters for a 1 Gyr solar metallicity population
>>> params = iso.get_predictions(feh=0.0, afe=0.0, loga=9.0)
>>> masses = params[:, 0]  # Initial masses
>>> temps = 10**params[:, 3]  # Effective temperatures

class brutus.core.populations.StellarPop(isochrone, filters=None, nnfile=None, verbose=True)[source]

Bases: object

Synthetic photometry generation for stellar populations.

This class generates synthetic SEDs and photometry for stellar populations using neural network-based bolometric corrections. It provides sophisticated modeling of binary stars, dust extinction, and observational effects.

This class is analogous to StarEvolTrack but for stellar populations: - StarEvolTrack: Individual star photometry - StellarPop: Stellar population photometry

The class uses dependency injection, accepting an Isochrone instance for stellar parameter predictions rather than inheriting from it.

Parameters:

isochrone (Isochrone) – Isochrone instance for stellar parameter predictions.
filters (list of str, optional) – Filter names for photometry computation. If None, uses all available.
nnfile (str, optional) – Path to neural network file for bolometric corrections.
verbose (bool, optional) – Whether to output progress messages. Default is True.

isochrone

The isochrone model used for stellar parameter predictions

Type:: Isochrone

filters

Array of filter names

Type:: numpy.ndarray

predictor

Neural network predictor for photometry

Type:: FastNNPredictor

Examples

Basic stellar population photometry:

>>> iso = Isochrone()
>>> ssp = StellarPop(isochrone=iso)
>>>
>>> # Generate SEDs for solar metallicity, 1 Gyr population
>>> seds, params, params2 = ssp.get_seds(
...     feh=0.0, afe=0.0, loga=9.0,
...     av=0.1, rv=3.1, dist=1000.0
... )

Binary population modeling:

>>> # Model population with 40% mass ratio binaries
>>> seds, params, params2 = ssp.get_seds(
...     feh=-0.5, afe=0.3, loga=10.0,
...     binary_fraction=0.4,
...     av=0.2, dist=2000.0
... )

See also

Isochrone: Stellar parameter predictions used by this class
StarEvolTrack: Individual star analog
brutus.core.neural_nets.FastNNPredictor: Neural network SED generation

Notes

The synthetic photometry generation includes:

Stellar Parameter Prediction: Uses the injected Isochrone instance
Neural Network Photometry: Fast bolometric correction computation
Binary Star Modeling: Sophisticated binary population synthesis
Dust Extinction: Parameterized extinction laws
Distance Effects: Distance modulus calculations

Binary modeling includes mass ratio constraints, evolutionary phase matching, and realistic limits on binary evolution (typically restricted to main sequence phases).

__init__(isochrone, filters=None, nnfile=None, verbose=True)[source]

get_seds(feh=0.0, afe=0.0, loga=8.5, eep=None, av=0.0, rv=3.3, binary_fraction=0.0, dist=1000.0, mini_bound=0.5, eep_binary_max=480.0, apply_corr=True, corr_params=None, return_dict=True, **kwargs)[source]

Generate synthetic photometry for a stellar population.

Parameters:

feh (float, optional) – Metallicity [Fe/H]. Default is 0.0.
afe (float, optional) – Alpha enhancement [alpha/Fe]. Default is 0.0.
loga (float, optional) – Log10(age in years). Default is 8.5.
eep (array-like, optional) – Equivalent evolutionary points. If None, uses isochrone default.
av (float, optional) – V-band extinction A(V). Default is 0.0.
rv (float, optional) – Extinction law parameter R(V). Default is 3.3.
binary_fraction (float, optional) – Secondary mass fraction for binaries. Default is 0.0 (no binaries). - 0.0: No binaries - 0 < binary_fraction < 1: Mass ratio binaries - 1.0: Equal mass binaries
dist (float, optional) – Distance in parsecs. Default is 1000.0.
mini_bound (float, optional) – Minimum mass for SED computation. Default is 0.5.
eep_binary_max (float, optional) – Maximum EEP for binary modeling. Default is 480.0.
apply_corr (bool, optional) – Apply empirical corrections. Default is True.
corr_params (tuple, optional) – Correction parameters.
return_dict (bool, optional) – Return parameters as dictionaries. Default is True.

Returns:

seds (numpy.ndarray of shape (Neep, Nfilters)) – Synthetic SEDs in magnitudes.
params (dict or numpy.ndarray) – Primary component stellar parameters.
params2 (dict or numpy.ndarray) – Secondary component parameters (for binaries).

See also

Isochrone.get_predictions: Stellar parameter predictions
FastNNPredictor.sed: Neural network photometry generation
StarEvolTrack.get_seds: Individual star analog

Notes

The photometry generation workflow:

Predict stellar parameters from isochrone
Generate primary SEDs using neural network
For binaries: generate secondary SEDs and combine
Apply dust extinction with specified R(V)
Apply distance modulus

Binary stars are modeled with the same age and metallicity as primaries, with masses determined by the binary_fraction parameter. Binary companions are only added for stars below eep_binary_max (typically restricted to main sequence).

Examples

Simple stellar population:

>>> seds, params, params2 = pop_synth.get_seds(
...     feh=0.0, loga=9.0, av=0.1, dist=1000.0
... )

Binary population:

>>> seds, params, params2 = pop_synth.get_seds(
...     feh=-0.5, loga=10.0, binary_fraction=0.4,
...     av=0.2, dist=2000.0
... )

Neural network utilities for fast SED prediction.

This module contains classes for neural network-based bolometric correction predictions, enabling fast computation of stellar spectral energy distributions from fundamental stellar parameters (Teff, log g, [Fe/H], [α/Fe], Av, Rv).

The neural networks are trained on synthetic stellar spectra and provide rapid computation of bolometric corrections across multiple photometric bands, significantly speeding up stellar parameter inference compared to full spectral synthesis.

Classes#

FastNNBase neural network class: Provides core neural network functionality for bolometric correction prediction using pre-trained weights and biases.
FastNNPredictorSED prediction class: Extends FastNN to generate complete spectral energy distributions for multiple filters with distance modulus and reddening corrections.

Examples

Basic usage for SED prediction:

>>> from brutus.core.neural_nets import FastNNPredictor
>>> from brutus.data.filters import FILTERS
>>>
>>> # Initialize predictor for specific filters
>>> predictor = FastNNPredictor(filters=['g', 'r', 'i', 'z'])
>>>
>>> # Predict SED for a solar-type star at 1 kpc
>>> sed = predictor.sed(logt=3.76, logg=4.44, feh_surf=0.0,
...                     logl=0.0, afe=0.0, av=0.1, rv=3.1, dist=1000)
>>> print(f"Predicted magnitudes: {sed}")

Notes

The neural networks require pre-trained model files containing weights, biases, and input scaling parameters. Default files are stored in the data directory and are automatically downloaded when needed.

class brutus.core.neural_nets.FastNN(filters=None, nnfile=None, verbose=True)[source]

Bases: object

Object that wraps the underlying neural networks used to interpolate.

between grid points on the bolometric correction tables.

This class provides the core neural network functionality for predicting bolometric corrections from stellar parameters. It loads pre-trained neural network weights and biases, and provides methods for encoding input parameters and evaluating the network.

Parameters:

filters (list of str, optional) – The names of filters that photometry should be computed for. If not provided, all available filters will be used. Filter names should match those defined in brutus.data.filters.FILTERS.
nnfile (str, optional) – Path to the neural network file containing pre-trained weights and biases. Default is ‘brutus/data/DATAFILES/nnMIST_BC.h5’ which will be downloaded automatically if not present.
verbose (bool, optional) – Whether to print initialization progress messages to stderr. Default is True.

w1, w2, w3

Neural network weight matrices for each layer.

Type:: numpy.ndarray

b1, b2, b3

Neural network bias vectors for each layer.

Type:: numpy.ndarray

xmin, xmax

Minimum and maximum values for input parameter scaling.

Type:: numpy.ndarray

xspan

Range of input parameters (xmax - xmin).

Type:: numpy.ndarray

Notes

The neural network architecture is a 3-layer feedforward network with sigmoid activation functions. Input parameters are scaled to [0,1] range before evaluation.

Expected input parameters (in order): - log10(Teff) : Effective temperature in Kelvin - log g : Surface gravity in cgs units - [Fe/H] : Surface metallicity (log scale) - [α/Fe] : Alpha enhancement (log scale) - Av : V-band extinction in magnitudes - Rv : Reddening parameter R(V) = A(V)/E(B-V)

__init__(filters=None, nnfile=None, verbose=True)[source]

encode(x)[source]

Rescale input parameters to [0,1] range for neural network evaluation.

The neural networks are trained on scaled inputs where each parameter is normalized to the range [0,1] based on the training data bounds.

Parameters:: x (numpy.ndarray of shape (Ninput,) or (Ninput, Nsamples)) – Input stellar parameters. Expected parameters are: [log10(Teff), log g, [Fe/H], [alpha/Fe], Av, Rv]
Returns:: xp – Scaled input parameters ready for neural network evaluation.
Return type:: numpy.ndarray of shape (Ninput, 1) or (Ninput, Nsamples)

Notes

The scaling is applied as: x_scaled = (x - xmin) / (xmax - xmin) where xmin and xmax are the bounds from the training data.

sigmoid(a)[source]

Apply sigmoid activation function.

Computes the logistic sigmoid function: f(a) = 1 / (1 + exp(-a))

Parameters:: a (numpy.ndarray) – Input array to apply sigmoid transformation to.
Returns:: a_t – Output after applying sigmoid activation, same shape as input.
Return type:: numpy.ndarray

Notes

The sigmoid function maps any real number to the range (0, 1), providing smooth activation for the neural network hidden layers.

nneval(x)[source]

Evaluate the neural network for given input parameters.

Performs forward propagation through the 3-layer neural network to predict bolometric corrections for all filters.

Parameters:: x (numpy.ndarray of shape (Ninput,)) – Stellar parameters: [log10(Teff), log g, [Fe/H], [alpha/Fe], Av, Rv]
Returns:: y – Predicted bolometric corrections for each filter.
Return type:: numpy.ndarray

Notes

The network architecture is: - Input layer: 6 parameters - Hidden layer 1: with sigmoid activation - Hidden layer 2: with sigmoid activation - Output layer: linear activation (bolometric corrections)

class brutus.core.neural_nets.FastNNPredictor(filters=None, nnfile=None, verbose=True)[source]

Bases: FastNN

Object that generates SED predictions for a provided set of filters using neural networks.

This class extends FastNN to provide a complete interface for stellar SED prediction, including automatic distance modulus calculation and conversion from bolometric corrections to apparent magnitudes.

Parameters:

filters (list of str, optional) – The names of filters that photometry should be computed for. If not provided, all available filters will be used. Must be a subset of filters available in the neural network file.
nnfile (str, optional) – Path to the neural network file containing pre-trained weights. Default is ‘brutus/data/DATAFILES/nnMIST_BC.h5’ which contains networks trained on MIST isochrones with C3K synthetic spectra.
verbose (bool, optional) – Whether to print initialization progress messages. Default is True.

filters

Array of filter names for which predictions are made.

Type:: numpy.ndarray

NFILT

Number of filters for which predictions are made.

Type:: int

Examples

Predict SED for a solar analog:

>>> predictor = FastNNPredictor(filters=['g', 'r', 'i'])
>>> sed = predictor.sed(logt=3.76, logg=4.44, feh_surf=0.0,
...                     logl=0.0, dist=1000.)
>>> print(f"g-r color: {sed[0] - sed[1]:.3f}")

Predict for a red giant with extinction:

>>> sed = predictor.sed(logt=3.60, logg=2.5, feh_surf=-0.5,
...                     logl=1.5, av=0.5, rv=3.1, dist=2000.)

Notes

The neural networks provide bolometric corrections which are combined with luminosity and distance to produce apparent magnitudes:

m = -2.5 * log10(L/L_sun) + 4.74 - BC + distance_modulus

where BC is the bolometric correction predicted by the neural network.

__init__(filters=None, nnfile=None, verbose=True)[source]

sed(logt=3.8, logg=4.4, feh_surf=0.0, logl=0.0, afe=0.0, av=0.0, rv=3.3, dist=1000.0, filt_idxs=slice(None, None, None))[source]

Generate SED predictions for specified stellar parameters.

Returns predicted apparent magnitudes in the specified filters for a star with the given physical parameters, distance, and extinction. Uses neural network bolometric corrections combined with standard photometric transformations.

Parameters:

logt (float, optional) – Base-10 logarithm of effective temperature in Kelvin. Typical range: [3.3, 4.5] corresponding to ~2000-30000K. Default is 3.8 (6300K, solar-type).
logg (float, optional) – Base-10 logarithm of surface gravity in cgs units (cm/s^2). Typical range: [0, 5] from supergiants to white dwarfs. Default is 4.4 (solar value).
feh_surf (float, optional) – Surface metallicity [Fe/H] in logarithmic units relative to solar. Typical range: [-2.5, 0.5]. Default is 0.0 (solar).
logl (float, optional) – Base-10 logarithm of luminosity in solar luminosities. Typical range: [-4, 6] from low-mass MS to supergiants. Default is 0.0 (solar luminosity).
afe (float, optional) – Alpha element enhancement [alpha/Fe] in logarithmic units relative to solar abundance ratios. Typical range: [-0.2, 0.8]. Default is 0.0 (solar ratios).
av (float, optional) – V-band extinction in magnitudes. Must be non-negative. Typical range: [0, 6] mag. Default is 0.0 (no extinction).
rv (float, optional) – Reddening parameter R(V) = A(V)/E(B-V), describing the extinction curve shape. Typical range: [1, 8]. Default is 3.3 (Milky Way average).
dist (float, optional) – Distance to the star in parsecs. Must be positive. Default is 1000 pc.
filt_idxs (slice or array-like, optional) – Indices or slice object specifying which subset of filters to return predictions for. Default is slice(None) (all filters).

Returns:

sed – Predicted apparent magnitudes in the specified filter subset. Magnitudes are in the AB system and include distance modulus and extinction corrections.

Return type:

numpy.ndarray of shape (Nfilt_subset,)

Notes

The computation follows these steps:

Compute distance modulus: mu = 5 * log10(dist) - 5
Evaluate neural network for bolometric corrections: BC = NN(params)
Convert to apparent magnitudes: m = -2.5 * logl + 4.74 - BC + mu

If any input parameters are outside the neural network training bounds, NaN values are returned for safety.

Examples

Solar analog at various distances:

>>> predictor = FastNNPredictor(['V', 'K'])
>>> for d in [100, 1000, 10000]:  # pc
...     sed = predictor.sed(dist=d)
...     print(f"{d:5d} pc: V={sed[0]:.2f}, K={sed[1]:.2f}")

Effect of extinction:

>>> sed_clean = predictor.sed(av=0.0)
>>> sed_dusty = predictor.sed(av=1.0, rv=3.1)
>>> extinction = sed_dusty - sed_clean
>>> print(f"V-band extinction: {extinction[0]:.2f} mag")

sed_batch(logt, logg, feh_surf, logl, afe, av, rv, dist, filt_idxs=slice(None, None, None))[source]

Generate SED predictions for an array of stellar parameters.

Vectorized version of sed() that evaluates the neural network once for all stars, providing significant speedup over looping.

Parameters:

logt (numpy.ndarray of shape (N,)) – Base-10 logarithm of effective temperature for each star.
logg (numpy.ndarray of shape (N,)) – Base-10 logarithm of surface gravity for each star.
feh_surf (numpy.ndarray of shape (N,)) – Surface metallicity [Fe/H] for each star.
logl (numpy.ndarray of shape (N,)) – Base-10 logarithm of luminosity for each star.
afe (numpy.ndarray of shape (N,)) – Alpha element enhancement [alpha/Fe] for each star.
av (float) – V-band extinction (same for all stars).
rv (float) – Reddening parameter R(V) (same for all stars).
dist (float) – Distance in parsecs (same for all stars).
filt_idxs (slice or array-like, optional) – Filter subset to return. Default is all filters.

Returns:

seds – Predicted apparent magnitudes for each star and filter. Stars with out-of-bounds parameters get NaN values.

Return type:

numpy.ndarray of shape (N, Nfilt_subset)

SED computation utilities for brutus.

This module contains functions for computing reddened spectral energy distributions (SEDs) from magnitude coefficients and dust parameters.

brutus.core.sed_utils.get_seds(mag_coeffs, av=None, rv=None, return_flux=False, return_rvec=False, return_drvec=False)[source]

Compute reddened SEDs from the provided magnitude coefficients.

This is a convenience wrapper around _get_seds that provides parameter handling and optional return values.

Parameters:

mag_coeffs (~numpy.ndarray of shape (Nmodels, Nbands, 3)) – Array of (mag, R, dR/dRv) coefficients used to generate reddened photometry in all bands. The first coefficient is the unreddened photometry, the second is the A(V) reddening vector for R(V)=0, and the third is the change in the reddening vector as a function of R(V).
av (float or ~numpy.ndarray of shape (Nmodels), optional) – Array of A(V) dust attenuation values. If not provided, defaults to av=0..
rv (float or ~numpy.ndarray of shape (Nmodels), optional) – Array of R(V) dust attenuation curve “shape” values. If not provided, defaults to rv=3.3.
return_flux (bool, optional) – Whether to return SEDs as flux densities instead of magnitudes. Default is False.
return_rvec (bool, optional) – Whether to return the reddening vectors at the provided av and rv. Default is False.
return_drvec (bool, optional) – Whether to return the differential reddening vectors at the provided av and rv. Default is False.

Returns:

seds (~numpy.ndarray of shape (Nmodels, Nbands)) – Reddened SEDs.
rvecs (~numpy.ndarray of shape (Nmodels, Nbands), optional) – Reddening vectors. Only returned if return_rvec=True.
drvecs (~numpy.ndarray of shape (Nmodels, Nbands), optional) – Differential reddening vectors. Only returned if return_drvec=True.

Examples

>>> import numpy as np
>>> from brutus.core.sed_utils import get_seds
>>>
>>> # Create mock magnitude coefficients for 2 models, 3 bands
>>> mag_coeffs = np.random.random((2, 3, 3))
>>> mag_coeffs[:, :, 0] = 15.0  # Base magnitudes
>>> mag_coeffs[:, :, 1] = 1.0   # R(V)=0 reddening
>>> mag_coeffs[:, :, 2] = 0.1   # dR/dR(V)
>>>
>>> # Compute reddened SEDs
>>> seds = get_seds(mag_coeffs, av=0.1, rv=3.1)
>>> print(f"SED shape: {seds.shape}")

>>> # Get SEDs and reddening vectors
>>> seds, rvecs = get_seds(mag_coeffs, av=0.1, rv=3.1, return_rvec=True)

>>> # Get all outputs
>>> seds, rvecs, drvecs = get_seds(mag_coeffs, av=0.1, rv=3.1,
...                                return_rvec=True, return_drvec=True)

Notes

This function implements the dust reddening law parameterization from Cardelli, Clayton, & Mathis (1989) and O’Donnell (1994). The reddening is applied as:

A(λ) = A(V) * [R(V)=0 + R(V) * dR/dR(V)]

where A(λ) is the extinction in a given band.

Grid generation utilities for pre-computed stellar model grids.

This module provides functionality to generate the HDF5 model grid files used by StarGrid for fast photometric predictions. Grids store pre-computed photometry at a reference distance (1 kpc) along with polynomial coefficients for reddening corrections as a function of A_V and R_V.

The grid generation process: 1. Creates a 5D grid in (mini, eep, feh, afe, smf) parameter space 2. Computes base photometry at A_V=0, R_V=3.3, distance=1 kpc 3. Fits polynomial coefficients for reddening dependence 4. Saves in HDF5 format compatible with StarGrid and load_models()

Classes#

GridGeneratorMain grid generation class: Generates pre-computed model grids from evolutionary tracks

Functions#

None (all functionality in GridGenerator class)

Examples

Generate a grid from evolutionary tracks:

>>> from brutus.core.individual import EEPTracks
>>> from brutus.core.grid_generation import GridGenerator
>>>
>>> # Initialize tracks and generator
>>> tracks = EEPTracks()
>>> generator = GridGenerator(tracks, filters=['g', 'r', 'i', 'z'])
>>>
>>> # Generate grid with default spacing
>>> generator.make_grid(output_file='my_grid.h5')

Generate a custom sparse grid:

>>> import numpy as np
>>> # Define custom grids
>>> mini_grid = np.arange(0.7, 1.5, 0.1)
>>> eep_grid = np.arange(300, 500, 10)
>>> feh_grid = np.array([-0.5, 0.0, 0.5])
>>>
>>> generator.make_grid(
...     mini_grid=mini_grid,
...     eep_grid=eep_grid,
...     feh_grid=feh_grid,
...     output_file='custom_grid.h5',
...     verbose=True
... )

Notes

Grid Reference Distance: All grids are generated at 1 kpc (1000 pc) reference distance. This choice provides consistency with Gaia parallax measurements (1 mas = 1 kpc) and is documented in the grid attributes.

Reddening Parameterization: Photometry is parameterized as:: m(A_V, R_V) = m_0 + A_V · (a + b · (R_V - 3.3))

where m_0 is the unreddened magnitude, and (a, b) are fitted coefficients. This allows fast computation of reddened photometry for arbitrary (A_V, R_V).

Grid Format: HDF5 files follow the format established in Speagle et al. (2025) and contain three datasets: - mag_coeffs: Structured array (Nmodel, Nfilter, 3) with coefficients - labels: Structured array (Nmodel,) with input parameters - parameters: Structured array (Nmodel,) with predicted stellar parameters

Memory and Performance: Large grids can require substantial memory and computation time. A full grid with default spacing contains ~300k models and takes ~2-4 hours to generate. Use sparse grids for testing or when covering a limited parameter space.

References

Grid format follows the structure established in Speagle et al. (2025), optimized for StarGrid interpolation performance.

class brutus.core.grid_generation.GridGenerator(tracks, filters=None, nnfile=None, verbose=True)[source]

Bases: object

Generate pre-computed stellar model grids with reddening coefficients.

This class creates HDF5 grid files used by StarGrid for fast photometric predictions. Grids are computed at 1 kpc reference distance and include polynomial coefficients for A_V and R_V reddening corrections.

The generator uses evolutionary tracks (EEPTracks or Isochrone) combined with neural network bolometric corrections to compute photometry across a multi-dimensional parameter grid, then fits reddening vectors to enable fast interpolation.

Parameters:

tracks (EEPTracks or Isochrone) – Stellar evolutionary track model providing parameter predictions. Must have compatible interface (get_predictions method).
filters (list of str, optional) – Names of photometric filters for which to generate models. If None, uses all available filters from FILTERS.
nnfile (str or Path, optional) – Path to neural network file for bolometric corrections. If None, uses default neural network file.
verbose (bool, optional) – Whether to print progress messages during initialization. Default is True.

tracks

Evolutionary track model

Type:: EEPTracks or Isochrone

star_track

SED generator combining tracks with neural networks

Type:: StarEvolTrack

filters

Array of filter names

Type:: numpy.ndarray

predictor

Neural network predictor for photometry

Type:: FastNNPredictor

Examples

Create grid generator and generate default grid:

>>> from brutus.core.individual import EEPTracks
>>> from brutus.core.grid_generation import GridGenerator
>>>
>>> tracks = EEPTracks(verbose=False)
>>> gen = GridGenerator(tracks)
>>> gen.make_grid(output_file='grid.h5', verbose=True)

Generate grid for specific filters only:

>>> gen_gaia = GridGenerator(tracks, filters=['Gaia_G_MAW', 'Gaia_BP_MAWf', 'Gaia_RP_MAW'])
>>> gen_gaia.make_grid(output_file='grid_gaia.h5')

Notes

The GridGenerator uses dependency injection rather than inheritance, accepting an EEPTracks (or Isochrone) instance. This design: - Maintains consistency with StarEvolTrack architecture - Allows flexibility in track implementations - Enables easier testing with mock tracks - Separates grid generation from track interpolation logic

See also

brutus.core.individual.StarGrid: Uses grids generated by this class
brutus.data.loader.load_models: Loads grids generated by this class

__init__(tracks, filters=None, nnfile=None, verbose=True)[source]: Initialize grid generator with evolutionary tracks.

make_grid(mini_grid=None, eep_grid=None, feh_grid=None, afe_grid=None, smf_grid=None, av_grid=None, av_wt=None, rv_grid=None, rv_wt=None, dist=1000.0, loga_max=10.14, eep_binary_max=480.0, mini_bound=0.5, apply_corr=True, corr_params=None, output_file=None, verbose=True)[source]

Generate model grid with reddening coefficients.

Creates a grid of stellar models across the specified parameter space, computing photometry at 1 kpc reference distance and fitting polynomial coefficients for reddening corrections. Results are saved to HDF5 format compatible with StarGrid.

Parameters:

mini_grid (numpy.ndarray, optional) – Grid of initial masses in solar masses. If None, defaults to np.arange(0.5, 2.0, 0.025) covering low to intermediate mass stars.
eep_grid (numpy.ndarray, optional) – Grid of equivalent evolutionary points. If None, defaults to adaptive grid: resolution 6 from 202-454 (MS), resolution 2 from 454-808 (post-MS).
feh_grid (numpy.ndarray, optional) – Grid of [Fe/H] metallicity values. If None, defaults to adaptive grid: resolution 0.1 from -3.0 to -2.0, resolution 0.05 from -2.0 to +0.5.
afe_grid (numpy.ndarray, optional) – Grid of [α/Fe] alpha enhancement values. If None, defaults to np.arange(-0.2, 0.6, 0.2).
smf_grid (numpy.ndarray, optional) – Grid of secondary mass fractions for binaries. If None, defaults to [0.] (single stars only).
av_grid (numpy.ndarray, optional) – Grid of A_V extinction values used for fitting reddening vector. If None, defaults to np.arange(0., 1.5, 0.3).
av_wt (numpy.ndarray, optional) – Weights for A_V grid points when fitting. If None, defaults to (1e-5 + av_grid)**-1 which forces fit through A_V=0.
rv_grid (numpy.ndarray, optional) – Grid of R_V values used for fitting differential reddening. If None, defaults to np.arange(2.4, 4.2, 0.3).
rv_wt (numpy.ndarray, optional) – Weights for R_V grid points when fitting. If None, defaults to exp(-abs(R_V - 3.3) / 0.5) favoring R_V=3.3.
dist (float, optional) – Reference distance in parsecs. Default is 1000 (1 kpc). This should not be changed as it affects StarGrid calibration.
loga_max (float, optional) – Maximum log10(age) in years. Models older than this are masked. Default is 10.14 (13.8 Gyr).
eep_binary_max (float, optional) – Maximum EEP for binary models. Above this, binaries are not computed (typically giant phase). Default is 480.
mini_bound (float, optional) – Minimum initial mass threshold. Models below this are masked. Default is 0.5 solar masses.
apply_corr (bool, optional) – Whether to apply empirical corrections to Teff and radius. Default is True.
corr_params (tuple, optional) – Parameters for empirical corrections (dtdm, drdm, msto_smooth, feh_scale). If None, uses default values from tracks.
output_file (str or Path, optional) – Path to output HDF5 file. If None, results are stored as attributes but not saved to disk.
verbose (bool, optional) – Whether to print progress messages. Default is True.

Returns:

Results are saved to output_file if provided, and stored as class attributes: grid_labels, grid_seds, grid_params, grid_sel

Return type:

None

Notes

Grid Size: Default parameters create ~300,000 models. Computation time scales linearly with grid size and quadratically with number of (av_grid × rv_grid) points for reddening fits.

Memory Usage: Full grid with 20 filters requires ~2 GB for storage. Peak memory during generation can be 3-4× larger.

Reddening Fits: For each valid model, the code: 1. Computes SEDs across (av_grid × rv_grid) combinations 2. Fits linear dependence on A_V at each R_V value 3. Fits linear dependence of A_V slope on R_V 4. Stores [m_0, a, b] where m = m_0 + A_V·(a + b·(R_V-3.3))

Examples

Generate default grid:

>>> gen.make_grid(output_file='grid_default.h5')

Generate sparse testing grid:

>>> gen.make_grid(
...     mini_grid=np.linspace(0.8, 1.2, 5),
...     eep_grid=np.linspace(300, 450, 10),
...     feh_grid=np.array([0.0]),
...     afe_grid=np.array([0.0]),
...     smf_grid=np.array([0.0]),
...     output_file='grid_test.h5',
...     verbose=True
... )

Core Module (brutus.core)

Contents

Core Module (brutus.core)#

Individual Star Models#

Population Models#

Neural Networks#

Grid Generation#

SED Utilities#

Submodules#

Classes#

Classes#

Classes#

Classes#

Functions#

Core Module (`brutus.core`)#