ProMage

ProMage is the inference wrapper for the magnitude emulator used by GalSBI. End users provide galaxy physical properties and requested bands; ProMage loads opaque TorchScript resources and returns emulated magnitudes.

The public API intentionally does not expose the neural-network architecture, activation function, training loop, or scalers.

Each emulator instance is bound to one ProSpect star-formation-history (SFH) model. The SFH model passed to ProMage must be the same SFH model used to create the galaxy properties. Current resources provide massfunc_snorm_trunc and massfunc_snorm_burst_trunc.

Installation

Install the released package from PyPI with:

pip install promage

For development, install a local checkout in editable mode:

pip install -e .

If the Python environment has no network access but already contains the build dependencies, use:

pip install -e . --no-build-isolation

The magnitude-emulator resources are distributed separately through cosmo-torrent. In GalSBI-SPS, load them with data_path("ProMage_res").

Basic Usage

from promage import ProMage
from cosmo_torrent import data_path

emu = ProMage(
    data_path("ProMage_res"),
    sfh_model="massfunc_snorm_trunc",
)

mags = emu.predict(
    properties=properties,
    bands=["g_HSC", "r_HSC", "i_HSC"],
)

SFH-aware resources require sfh_model; omitting it or requesting an unavailable family raises an error rather than silently loading the wrong network. The selected family and all families in the resource can be inspected with emu.sfh_model and emu.available_sfh_models.

By default, predict uses frame="observed" and returns final observer-frame magnitudes. For artifacts trained as m_obs - DM(z), ProMage adds the fixed training distance modulus internally.

mags is a dictionary mapping each requested band to a NumPy array with the same shape as the input property arrays.

Absolute Magnitudes

Absolute/rest-frame magnitudes are requested with frame="absolute":

mags_abs = emu.predict(
    properties=properties,
    bands=["g_HSC", "r_HSC", "i_HSC"],
    frame="absolute",
)

Absolute-frame artifacts are trained directly on the ProSpect absolute_magnitudes dataset. No distance-modulus correction is applied to absolute-frame outputs.

Available frames and bands can be inspected with:

print(emu.available_frames)
print(emu.available_roles)
print(emu.available_bands)

Current Band Coverage

The current resource provides observer-frame and absolute magnitudes for:

HSC:   g_HSC, r_HSC, i_HSC, z_HSC, Y_HSC
VST:   u_VST, g_VST, r_VST, i_VST
VISTA: Z_VISTA, Y_VISTA, J_VISTA, H_VISTA, Ks_VISTA
DECam: DECam_g, DECam_r, DECam_i, DECam_z, DECam_y
LSST:  lsstcam_u, lsstcam_g, lsstcam_r, lsstcam_i, lsstcam_z, lsstcam_y

ProSpect produces exactly zero observed u_VST flux for the current training samples at 4 <= z <= 5. The resource manifest therefore declares a constant observer-frame magnitude of 99 in those two redshift bins. This value is a zero-flux/nondetection sentinel, not a measured physical magnitude. Absolute u_VST magnitudes continue to use trained artifacts over the full redshift range.

Selection Magnitudes

Some resources include a threshold-selection role. This is separate from the default precision magnitude emulators and is intended for broad sample selection over the full redshift range. Current resources provide i_HSC, i_VST, DECam_i, and lsstcam_i selection artifacts with a magnitude threshold of 32 for both SFH families:

i_selection = emu.predict(
    properties=properties,
    bands=["i_HSC"],
    role="selection",
)["i_HSC"]

threshold = emu.selection_threshold("i_HSC")
selected = i_selection < threshold

The default role is role="magnitude", so existing calls to predict(...) are unchanged. The selection role should not be treated as the final precision magnitude estimate for all downstream photometry.

Inputs

The resource manifest defines the required properties. Current ProSpect Latin-hypercube resources use:

[
    "z",
    "logmSFR",
    "mpeak",
    "logmperiod",
    "mskew",
    "logZfinal",
    "logtaubirth",
    "logtauscreen",
    "alphabirth",
    "alphascreen",
    "logU",
]

The massfunc_snorm_burst_trunc family additionally requires logfburst, defined as log10(fburst), where fburst = M_burst / (M_smooth + M_burst). The manifest supplies the required property ordering internally.

All arrays must have the same shape. Redshifts must lie inside the resource domain, typically 0 < z <= 5.

Return Formats

The default return format is a dictionary:

{
    "g_HSC": np.ndarray,
    "r_HSC": np.ndarray,
    "i_HSC": np.ndarray,
}

An array can be requested with:

mag_array = emu.predict(
    properties=properties,
    bands=["g_HSC", "r_HSC", "i_HSC"],
    return_format="array",
)

The final axis follows the order of the requested bands.

Resource Directory

ProMage(...) expects a directory containing a manifest.json and its referenced TorchScript .pt artifacts. A manifest can also contain explicit constant-output redshift bins for physically defined zero-flux cases.

An SFH-aware resource directory looks like:

manifest.json
models/
  massfunc_snorm_trunc/
    observed/
      magnitude/
        g_HSC/
          z0p0_0p5.pt
          z0p5_1p0.pt
          ...
        r_HSC/
          ...
      selection/
        i_HSC/
          z0p0_5p0.pt
    absolute/
      magnitude/
        g_HSC/
          z0p0_0p5.pt
          z0p5_1p0.pt
          ...
        r_HSC/
          ...
  massfunc_snorm_burst_trunc/
    ...

SFH families, observer-frame artifacts, and absolute-frame artifacts can coexist in the same ProMage_res directory because each has a distinct model path.

Legacy manifests without explicit SFH families remain supported through ProMage(resource_dir). They cannot be safely assigned to a named SFH at load time; regenerate those resources to obtain an SFH-aware manifest. Legacy manifests without explicit roles are treated as role="magnitude".

Cosmology

The training data use a fixed flat LambdaCDM cosmology:

H0 = 67.8
Omega_M = 0.308
Tcmb0 = 2.725

The package uses Astropy:

from astropy.cosmology import FlatLambdaCDM

FlatLambdaCDM(H0=67.8, Om0=0.308, Tcmb0=2.725)

The distance-modulus correction is applied only for observer-frame artifacts whose target convention is obs_minus_dm.

Out-of-Range Redshifts

By default, ProMage raises an error if a redshift is outside the manifest domain:

emu = ProMage(
    data_path("ProMage_res"),
    sfh_model="massfunc_snorm_trunc",
    on_out_of_range="raise",
)

To leave out-of-range predictions as NaN:

emu = ProMage(
    data_path("ProMage_res"),
    sfh_model="massfunc_snorm_trunc",
    on_out_of_range="nan",
)

License

ProMage is distributed under the MIT License. See LICENSE.