ML Embeddings API¶

`light_curve.embed.EmbeddingSession` ¶

Bases: ABC

Abstract base for ONNX-backed embedding models.

Subclasses implement :meth:preprocess_lc (convert raw arrays to model tensors) and :meth:predict_tensors (run the session and return embeddings).

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	An `onnxruntime.InferenceSession` (or any object with a compatible `.run()` interface).	required
`reduction`	`str, list of str, or Reduction`	Strategy for mapping variable-length light curves to fixed-length sequences.	required
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`

`light_curve.embed.SingleBandModel` ¶

Bases: EmbeddingSession, ABC

Embedding model that processes one photometric band at a time.

When bands is None the full light curve is treated as a single band. When bands is provided, the light curve is split by band label, each band is embedded independently, and the results are concatenated along :attr:Dim.BAND.

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	ONNX inference session.	required
`bands`	`sequence of str or int`	Ordered band labels to embed. `None` treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict`	Extra kwargs forwarded to :func:`reduction_from_str`.	`None`

`light_curve.embed.AstraCLR` ¶

Bases: ImplicitMultiBandModel

AstraCLR multi-band ZTF embedding model.

AstraCLR is a transformer encoder pretrained on ZTF photometry via a contrastive learning objective. It accepts magnitudes in the ZTF g, r, and i bands and returns a single 512-dimensional embedding per light curve.

Observations are split by band (integers 0, 1, 2 for g, r, i), per-band normalized, and packed into a fixed-length sequence (300 g + 350 r + 50 i = 700). Shorter sequences are zero-padded. Pass a band_groups dict (e.g. {"g": 0, "r": 1, "i": 2}) to use string band labels instead of integers.

.. important::

Observation times **must be in Modified Julian Date (MJD)**.  The model
subtracts a fixed offset of 58 000 during preprocessing, so arbitrary
time units may produce incorrect embeddings.  The model was pretrained
on **ZTF DR16** (Zubercal DR16 × Gaia DR3), which covers
**MJD 58 194 – 59 951** (roughly 2018 Feb – 2023 Jan).

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	An `onnxruntime.InferenceSession` for the AstraCLR ONNX model.	required
`band_groups`	`Mapping, list of Mapping, or None`	Band label → model integer mapping. When `None` (default), the caller must supply integer band indices (0=g, 1=r, 2=i). Please note that some ZTF data products, e.g. "ordinal" ZTF data releases (non-zubercal) would have `filterid` field encoded as (1=g, 2=r, 3=i), please use `{1: 0, 2: 1, 3: 2}` for such cases, and `{"g": 0, "r": 1, "i": 2}` for ZTF string band labels.	`None`
`allow_extra_bands`	`bool`	If `False` (default), raises when the input contains bands not in `band_groups` (or not in 0–2 when `band_groups` is `None`).	`False`
`reduction`	`str, list of str, or Reduction`	Strategy for selecting up to the fixed number of observations per band before zero-padding. Defaults to `"beginning"` (first observations). Any :class:`~light_curve.embed.SingleSubsampleReduction` or :class:`~light_curve.embed.MultipleReductions` thereof works well; :class:`~light_curve.embed.NonOverlappingWindows` requires each band to produce the same number of windows.	`'beginning'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`

Examples:

>>> import numpy as np
>>> from light_curve.embed import AstraCLR
>>> model = AstraCLR.from_hf(
...     band_groups={"g": 0, "r": 1, "i": 2},
... )
>>> rng = np.random.default_rng(0)
>>> n = 300
>>> mjd = np.sort(rng.uniform(58_194, 59_951, n)).astype(np.float64)
>>> mag = rng.normal(17, 0.5, n).astype(np.float32)
>>> magerr = np.full(n, 0.02, dtype=np.float32)
>>> band = np.array(["g", "r", "i"])[rng.integers(0, 3, n)]
>>> embedding = model(mjd, mag, magerr, band)
>>> embedding.shape
(1, 1, 1, 512)

Model license

MIT.

References

Majumder et al. (2026, in prep)

https://huggingface.co/light-curve/astra-clr

`from_hf` `classmethod` ¶

Load the model from the HuggingFace Hub.

Downloads (and caches) the ONNX model from https://huggingface.co/light-curve/astra-clr, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`band_groups`	`Mapping, list of Mapping, or None`	Band label → model integer mapping. When `None` (default), the caller must supply integer band indices (0=g, 1=r, 2=i). Please note that some ZTF data products, e.g. "ordinal" ZTF data releases (non-zubercal) would have `filterid` field encoded as (1=g, 2=r, 3=i), please use `{1: 0, 2: 1, 3: 2}` for such cases, and `{"g": 0, "r": 1, "i": 2}` for ZTF string band labels.	`None`
`allow_extra_bands`	`bool`	Silently ignore observations with unknown band labels when `True`. Default is `False`.	`False`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy per band. Default is `"beginning"` (first observations).	`'beginning'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`ort_session_kwargs`	`dict or None`	Keyword arguments forwarded to `onnxruntime.InferenceSession`: `"sess_options"`, `"providers"`, `"provider_options"`.	`None`

Returns:

Type	Description
`AstraCLR`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.Astromer1` ¶

Bases: _AstromerModel

Astromer 1 embedding model.

Transformer encoder pretrained on MACHO R-band light curves via masked magnitude prediction. Accepts single-band photometry and returns a 256-dimensional embedding (2 layers, 4 attention heads).

The ONNX model is hosted on HuggingFace at https://huggingface.co/light-curve/astromer1 (astromer1.onnx). Three named outputs are available; select with the output parameter:

"mean" (default) — masked mean pooling → shape (batch, 256)
"max" — masked max pooling → shape (batch, 256)
"sequence" — per-timestep features → shape (batch, 200, 256)

Use :meth:from_hf to download and load the model directly.

Model license

MIT.

References

Donoso-Oliva et al. (2023), ASTROMER: A transformer-based embedding for the representation of light curves, A&A 670, A54. https://ui.adsabs.harvard.edu/abs/2023A%26A...670A..54D/abstract

Parameters:

Name	Type	Description	Default
`session`		ONNX inference session for the Astromer 1 model file.	required
`output`	`str`	Which named output to return: `"mean"`, `"max"`, or `"sequence"`. Defaults to `"mean"`.	`'mean'`
`bands`	`sequence of str or int`	Band labels. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing strategy. Defaults to :class:`NonOverlappingWindows`.	`'non-overlapping-windows'`

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return. One of: `"mean"` (default) — masked mean pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"max"` — masked max pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"sequence"` — per-timestep embeddings (no aggregation), output shape `(bands, reductions, 200, 256)`	`'mean'`
`bands`	`sequence of str or int or None`	Ordered band labels to embed. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`ort_session_kwargs`	`dict or None`	Additional keyword arguments forwarded to `onnxruntime.InferenceSession`: "sess_options", "providers", "provider_options".	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognised output names.
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.Astromer1ZTF` ¶

Bases: _AstromerModel

Astromer 1 embedding model fine-tuned on ZTF DR20 g-band.

The Astromer 1 encoder retrained on ZTF DR20 g-band light curves for the QZO quasar catalog (Nakoneczny et al. 2025). Architecture matches the original Astromer 1 (2 layers, 4 attention heads); accepts single-band g-band photometry and returns a 256-dimensional embedding.

The ONNX model is hosted on HuggingFace at https://huggingface.co/light-curve/astromer1-ztfdr20 (astromer1_ztfdr20.onnx). Three named outputs are available; select with the output parameter:

"mean" (default) — masked mean pooling → shape (batch, 256)
"max" — masked max pooling → shape (batch, 256)
"sequence" — per-timestep features → shape (batch, 200, 256)

Use :meth:from_hf to download and load the model directly.

Model license

GPL-3.0 (upstream ZTF DR20 weights license).

References

Nakoneczny et al. (2025), QZO: A Catalog of 5 Million Quasars from the Zwicky Transient Facility, ApJ 992, 153. https://ui.adsabs.harvard.edu/abs/2025ApJ...992..153N/abstract

Original Astromer 1 architecture — Donoso-Oliva et al. (2023), ASTROMER: A transformer-based embedding for the representation of light curves, A&A 670, A54. https://ui.adsabs.harvard.edu/abs/2023A%26A...670A..54D/abstract

Parameters:

Name	Type	Description	Default
`session`		ONNX inference session for the Astromer 1 (ZTF DR20) model file.	required
`output`	`str`	Which named output to return: `"mean"`, `"max"`, or `"sequence"`. Defaults to `"mean"`.	`'mean'`
`bands`	`sequence of str or int`	Band labels. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing strategy. Defaults to :class:`NonOverlappingWindows`.	`'non-overlapping-windows'`

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return. One of: `"mean"` (default) — masked mean pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"max"` — masked max pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"sequence"` — per-timestep embeddings (no aggregation), output shape `(bands, reductions, 200, 256)`	`'mean'`
`bands`	`sequence of str or int or None`	Ordered band labels to embed. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`ort_session_kwargs`	`dict or None`	Additional keyword arguments forwarded to `onnxruntime.InferenceSession`: "sess_options", "providers", "provider_options".	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognised output names.
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.Astromer2` ¶

Bases: _AstromerModel

Astromer 2 embedding model.

Pretrained on 1.5 million MACHO light curves. Accepts single-band photometry and returns a 256-dimensional embedding.

The ONNX model is hosted on HuggingFace at https://huggingface.co/light-curve/astromer2 (astromer2.onnx). Three named outputs are available; select with the output parameter:

"mean" (default) — masked mean pooling → shape (batch, 256)
"max" — masked max pooling → shape (batch, 256)
"sequence" — per-timestep features → shape (batch, 200, 256)

Use :meth:from_hf to download and load the model directly.

Model license

MIT.

References

Donoso-Oliva et al. (2026), Generalizing across astronomical surveys: Few-shot light curve classification with Astromer 2, A&A 707, A170. https://ui.adsabs.harvard.edu/abs/2026A%26A...707A.170D/abstract

Parameters:

Name	Type	Description	Default
`session`		ONNX inference session for the Astromer 2 model file.	required
`output`	`str`	Which named output to return: `"mean"`, `"max"`, or `"sequence"`. Defaults to `"mean"`.	`'mean'`
`bands`	`sequence of str or int`	Band labels. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing strategy. Defaults to :class:`NonOverlappingWindows`, which matches the sequential-window preprocessing used to produce the reference embeddings on HuggingFace.	`'non-overlapping-windows'`

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return. One of: `"mean"` (default) — masked mean pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"max"` — masked max pooling over valid timesteps, output shape `(bands, reductions, 1, 256)` `"sequence"` — per-timestep embeddings (no aggregation), output shape `(bands, reductions, 200, 256)`	`'mean'`
`bands`	`sequence of str or int or None`	Ordered band labels to embed. `None` (default) treats the whole light curve as one band.	`None`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`ort_session_kwargs`	`dict or None`	Additional keyword arguments forwarded to `onnxruntime.InferenceSession`: "sess_options", "providers", "provider_options".	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognised output names.
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.ATAT` ¶

Bases: MultiBandModel

ATAT multiband transformer embedding model.

ATAT (Astronomical Transformer for time series And Tabular data) is a transformer encoder for irregularly-sampled, multi-band light curves. Each of the six photometric bands is embedded independently with a learned sinusoidal time modulation, the bands are then merged, sorted by observation time, and passed through a multi-head self-attention transformer with a learnable CLS token. The CLS-token output is the default representation used in the paper. ATAT was trained for transient classification on the ELAsTiCC simulation (20 classes, LSST-like photometry).

The model expects raw fluxes calibrated to AB zero-point 27.5 (ELAsTiCC / SNANA FITS convention), with no normalisation. Use mag_zp to convert from a different zero-point at call time — common values are 31.4 (LSST nJy) and 8.9 (Jy).

Valid model band indices are 0–5, corresponding to LSST u g r i z Y. Pass a band_groups dict (e.g. {"u": 0, "g": 1, ...}) to use string band labels instead of integers.

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	An `onnxruntime.InferenceSession` for the ATAT ONNX model.	required
`output`	`(token, mean, sequence)`	Which model head to return: `"token"` (default) — CLS-token embedding, output shape `(n_band_groups, n_subsamples, 1, 192)` `"mean"` — masked mean pooling over valid observations, output shape `(n_band_groups, n_subsamples, 1, 192)` `"sequence"` — per-observation embeddings (CLS token excluded), output shape `(n_band_groups, n_subsamples, 390, 192)`	`"token"`
`band_groups`	`Mapping, list of Mapping, or None`	Band label → model integer mapping(s). See :class:`~light_curve.embed.model.MultiBandModel` for details.	`None`
`allow_extra_bands`	`bool`	If `False` (default), raises :exc:`ValueError` when the input contains band labels not in `band_groups` (or not in 0–5 when `band_groups` is `None`).	`False`
`reduction`	`str, list of str, or Reduction`	Strategy for selecting up to 65 observations per band before zero-padding. Defaults to `"non-overlapping-windows"`. Any :class:`~light_curve.embed.SingleSubsampleReduction` or :class:`~light_curve.embed.MultipleReductions` thereof works well; :class:`~light_curve.embed.NonOverlappingWindows` requires every band to produce the same number of windows.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`
`mag_zp`	`float`	AB zero-point of the input fluxes. Fluxes are rescaled to ZP = 27.5 (ELAsTiCC / SNANA FITS convention) before inference. Common values: 31.4 (LSST nJy, default), 27.5 (no rescaling needed), 8.9 (Jy).	`31.4`

Examples:

>>> import numpy as np
>>> from light_curve.embed import ATAT
>>> model = ATAT.from_hf(
...     output="token",
...     band_groups={"u": 0, "g": 1, "r": 2, "i": 3, "z": 4, "Y": 5},
... )
>>> time = np.linspace(0, 200, 100, dtype=np.float32)
>>> flux = np.ones(100, dtype=np.float32)
>>> band = np.array(["g", "r"] * 50)
>>> embedding = model(time, flux, band)
>>> embedding.shape
(1, 1, 1, 192)

Model license

Apache-2.0 (upstream ATAT license).

References

Becker et al. (2024), ATAT: Astronomical Transformer for time series And Tabular data, Astronomy & Astrophysics, 691, A163. https://doi.org/10.1051/0004-6361/202451418

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return. One of: `"token"` (default) — CLS-token embedding, output shape `(band_groups, reductions, 1, 192)` `"mean"` — masked mean pooling over valid observations, output shape `(band_groups, reductions, 1, 192)` `"sequence"` — per-observation embeddings (CLS token excluded), output shape `(band_groups, reductions, 390, 192)`	`'token'`
`band_groups`	`Mapping, list of Mapping, or None`	Band label → model integer mapping. `None` (default) expects integer band indices 0–5 (LSST u g r i z Y).	`None`
`allow_extra_bands`	`bool`	If `False` (default), raises an error if the input light curve contains bands not used by the model: either `dict` keys in `band_groups` or integers 0–5 (LSST ugrizy) when `band_groups` is `None`.	`False`
`reduction`	`str, list of str, or Reduction`	Per-band windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`mag_zp`	`float`	AB zero-point of the input fluxes. Fluxes are rescaled to ZP = 27.5 (ELAsTiCC / SNANA FITS convention) before inference. Common values: 31.4 (LSST nJy, default), 27.5 (no rescaling needed), 8.9 (Jy).	`31.4`
`ort_session_kwargs`	`dict or None`	Additional keyword arguments forwarded to `onnxruntime.InferenceSession`: "sess_options", "providers", "provider_options".	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognized output names.
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.ATCAT` ¶

Bases: MultiBandModel

ATCAT multiband transformer embedding model.

ATCAT (Astronomical Transformer for Classification and Analysis of Transients) is a transformer-based model trained on LSST-like multiband light curves. It accepts flux, flux-error, time, and integer channel-index arrays and produces dense embeddings.

The model expects fluxes calibrated to AB zero-point 27.5 (ELAsTiCC / SNANA FITS convention). Use mag_zp to convert from a different zero-point at call time — common values are 31.4 (LSST nJy) and 8.9 (Jy).

Valid model band indices are 0–5, corresponding to LSST u g r i z Y. Pass a band_groups dict (e.g. {"u": 0, "g": 1, ...}) to use string band labels instead of integers.

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	An `onnxruntime.InferenceSession` for the ATCAT ONNX model.	required
`output`	`(last, mean, sequence)`	Which model head to return: `"last"` — embedding of the last valid timestep, output shape `(n_band_groups, n_subsamples, 1, 384)` `"mean"` — masked mean pooling over valid timesteps, output shape `(n_band_groups, n_subsamples, 1, 384)` `"sequence"` — per-timestep embeddings, output shape `(n_band_groups, n_subsamples, 243, 384)`	`"last"`
`band_groups`	`Mapping, list of Mapping, or None`	Band label → model integer mapping(s). See :class:`~light_curve.embed.model.ExplicitMultiBandModel` for details.	`None`
`allow_extra_bands`	`bool`	If `False` (default), raises :exc:`ValueError` when the input contains band labels not in `band_groups` (or not in 0–5 when `band_groups` is `None`).	`False`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`
`mag_zp`	`float`	AB zero-point of the input fluxes. Fluxes are rescaled to ZP = 27.5 (ELAsTiCC / SNANA FITS convention) before inference. Common values: 31.4 (LSST nJy, default), 27.5 (no rescaling needed), 8.9 (Jy).	`31.4`

Examples:

>>> import numpy as np
>>> from light_curve.embed import ATCAT
>>> model = ATCAT.from_hf(
...     output="last",
...     band_groups={"u": 0, "g": 1, "r": 2, "i": 3, "z": 4, "Y": 5},
... )
>>> time = np.linspace(0, 200, 100, dtype=np.float32)
>>> flux = np.ones(100, dtype=np.float32)
>>> flux_err = np.full(100, 0.1, dtype=np.float32)
>>> band = np.array(["g", "r"] * 50)
>>> embedding = model(time, flux, flux_err, band)
>>> embedding.shape
(1, 1, 1, 384)

Model license

Modified MIT with a non-military-use restriction (upstream ATCAT license).

References

Tung (2025), ATCAT: Astronomical Timeseries CAusal Transformer, arXiv:2511.00614. https://ui.adsabs.harvard.edu/abs/2025arXiv251100614T/abstract

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return. One of: `"last"` — embedding of the last valid timestep, output shape `(band_groups, reductions, 1, 384)` `"mean"` (default) — masked mean pooling over valid timesteps, output shape `(band_groups, reductions, 1, 384)` `"sequence"` — per-timestep embeddings (no aggregation), output shape `(band_groups, reductions, 243, 384)`	`'last'`
`use_fp16`	`bool`	Whether to load the model in float16 precision if supported. Defaults to `False` (float32) for maximum compatibility; set to `True` to use original model precision and reduce memory usage if your hardware supports it.	`False`
`band_groups`	`sequence of str or int or None`	Ordered band labels to embed. `None` (default) treats the whole light curve as one band.	`None`
`allow_extra_bands`	`bool`	If `False` (default), raises an error if the input light curve contains any bands which may not be used by the model: either bands specified as `dict` keys in `band_groups` or integers 0,1,2,3,4,5 (LSST ugrizy) if `band_groups` is `None`.	`False`
`reduction`	`str, list of str, or Reduction`	Windowing / subsampling strategy. Defaults to `"non-overlapping-windows"`.	`'non-overlapping-windows'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str` when `reduction` is given as a string.	`None`
`mag_zp`	`float`	AB zero-point of the input fluxes. Fluxes are rescaled to ZP = 27.5 (ELAsTiCC / SNANA FITS convention) before inference. Common values: 31.4 (LSST nJy, default), 27.5 (no rescaling needed), 8.9 (Jy).	`31.4`
`ort_session_kwargs`	`dict or None`	Additional keyword arguments forwarded to `onnxruntime.InferenceSession`: "sess_options", "providers", "provider_options".	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognized output names.
`ImportError`	If `huggingface_hub` is not installed.
`ImportError`	If no `onnxruntime` variant is installed.

`light_curve.embed.Chronos2` ¶

Bases: _ChronosModel

Chronos 2 univariate light-curve embedding model.

A T5-style transformer encoder pretrained on a large corpus of real and synthetic time series. It maps a magnitude sequence to 768-dimensional patch embeddings (native context up to 8192 observations).

The ONNX model is hosted on HuggingFace at https://huggingface.co/light-curve/chronos2 (chronos2.onnx).

Use :meth:from_hf to download and load the model directly.

Model license

Apache-2.0 (upstream amazon/chronos-2 license).

References

Ansari et al. (2024), Chronos: Learning the Language of Time Series, Transactions on Machine Learning Research. https://huggingface.co/amazon/chronos-2

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	ONNX inference session for the Chronos 2 model file.	required
`output`	`str`	`"mean"` (default) or `"sequence"`.	`'mean'`
`reduction`	`str, list of str, or Reduction`	Observation-selection strategy for light curves longer than 8192. Defaults to `"end"`.	`'end'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`

`from_hf` `classmethod` ¶

Load a model from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`output`	`str`	Named ONNX output to return: `"mean"` (default, masked mean pool over valid context patches → `(..., 1, embed_dim)`) or `"sequence"` (per-patch encoder states → `(..., n_patches, embed_dim)`).	`'mean'`
`reduction`	`str, list of str, or Reduction`	Strategy for selecting observations when a light curve exceeds `max_obs`. Defaults to `"end"` (the most recent `max_obs` observations, matching the model's native right-aligned context).	`'end'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`
`ort_session_kwargs`	`dict or None`	Keyword arguments forwarded to `onnxruntime.InferenceSession`.	`None`

Returns:

Type	Description
`instance of the calling class`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `output` is not one of the recognised output names.
`ImportError`	If `huggingface_hub` or an `onnxruntime` variant is missing.

`light_curve.embed.ChronosBolt` ¶

Bases: _ChronosModel

Chronos-Bolt univariate light-curve embedding model.

A faster, patch-based Chronos variant available in four sizes with different embedding dimensions (native context up to 2048 observations): tiny (256), mini (384), small (512), and base (768).

The ONNX models are hosted on HuggingFace at https://huggingface.co/light-curve/chronos-bolt-<size>.

Use :meth:from_hf (with size=) to download and load the model.

Model license

Apache-2.0 (upstream amazon/chronos-bolt license).

References

Ansari et al. (2024), Chronos: Learning the Language of Time Series, Transactions on Machine Learning Research. https://huggingface.co/amazon/chronos-bolt-base

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	ONNX inference session for the Chronos-Bolt model file.	required
`size`	`(tiny, mini, small, base)`	Which model size this session corresponds to (sets `embed_dim`).	`"tiny"`
`output`	`str`	`"mean"` (default) or `"sequence"`.	`'mean'`
`reduction`	`str, list of str, or Reduction`	Observation-selection strategy for light curves longer than 2048. Defaults to `"end"`.	`'end'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`

`from_hf` `classmethod` ¶

Load a Chronos-Bolt model of the given size from the HuggingFace Hub.

Parameters:

Name	Type	Description	Default
`size`	`(tiny, mini, small, base)`	Model size to load. Required: the sizes have different embedding dimensions, so there is no meaningful default.	`"tiny"`
`output`	`str`	`"mean"` (default) or `"sequence"`.	`'mean'`
`reduction`	`str, list of str, or Reduction`	Observation-selection strategy for light curves longer than 2048. Defaults to `"end"`.	`'end'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`
`ort_session_kwargs`	`dict or None`	Keyword arguments forwarded to `onnxruntime.InferenceSession`.	`None`

Returns:

Type	Description
`ChronosBolt`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `size` or `output` is not recognised.
`ImportError`	If `huggingface_hub` or an `onnxruntime` variant is missing.

`light_curve.embed.Moment1` ¶

Bases: SingleBandModel

MOMENT-1 univariate light-curve embedding model.

A T5-based time-series foundation model (Goswami et al. 2024) pretrained with a masked-reconstruction objective on the Time-series Pile. It embeds a single univariate magnitude series: timestamps are discarded and observations are treated as sequentially ordered (the same convention used for the Chronos models). The series is capped to the most recent 512 observations and left-padded with NaN to that fixed window; reversible instance normalisation (RevIN) is applied internally by the model.

The model comes in three sizes with different embedding dimensions: small (512), base (768), and large (1024). Unlike Chronos, the context length is fixed at 512 observations (64 patches of 8), not a dynamic axis.

The ONNX models are hosted on HuggingFace at https://huggingface.co/light-curve/moment1-<size>.

Use :meth:from_hf (with size=) to download and load the model.

Model license

MIT (upstream AutonLab/MOMENT-1 license).

References

Goswami et al. (2024), MOMENT: A Family of Open Time-series Foundation Models, ICML 2024. https://huggingface.co/AutonLab/MOMENT-1-base

Parameters:

Name	Type	Description	Default
`session`	`InferenceSession`	ONNX inference session for the MOMENT-1 model file.	required
`size`	`(small, base, large)`	Which model size this session corresponds to (sets `embed_dim`).	`"small"`
`output`	`str`	`"mean"` (default) or `"sequence"`.	`'mean'`
`reduction`	`str, list of str, or Reduction`	Observation-selection strategy for light curves longer than 512. Defaults to `"end"`.	`'end'`
`reduction_kwargs`	`dict`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`

`from_hf` `classmethod` ¶

Load a MOMENT-1 model of the given size from the HuggingFace Hub.

Downloads (and caches) the ONNX model file, creates an onnxruntime.InferenceSession, and returns a ready-to-use instance.

Parameters:

Name	Type	Description	Default
`size`	`(small, base, large)`	Model size to load. Required: the sizes have different embedding dimensions, so there is no meaningful default.	`"small"`
`output`	`str`	Named ONNX output to return: `"mean"` (default, masked mean pool over valid patches → `(..., 1, embed_dim)`) or `"sequence"` (per-patch encoder states → `(..., 64, embed_dim)`).	`'mean'`
`reduction`	`str, list of str, or Reduction`	Observation-selection strategy for light curves longer than 512. Defaults to `"end"` (the most recent 512 observations, matching the model's native right-aligned context).	`'end'`
`reduction_kwargs`	`dict or None`	Extra keyword arguments forwarded to :func:`reduction_from_str`.	`None`
`ort_session_kwargs`	`dict or None`	Keyword arguments forwarded to `onnxruntime.InferenceSession`.	`None`

Returns:

Type	Description
`Moment1`	Instance with a live ONNX inference session.

Raises:

Type	Description
`ValueError`	If `size` or `output` is not recognised.
`ImportError`	If `huggingface_hub` or an `onnxruntime` variant is missing.

Reduction strategies¶

`light_curve.embed.Beginning` ¶

Bases: SingleSubsampleReduction

Select the chronologically first seq_size observations of the light curve.

`light_curve.embed.End` ¶

Bases: SingleSubsampleReduction

Select the chronologically last seq_size observations of the light curve.

`light_curve.embed.Middle` ¶

Bases: SingleSubsampleReduction

Select the seq_size observations centred on the midpoint of the light curve.

The centre index is len // 2; the window is shifted toward the edges when there are fewer than seq_size observations on one side.

`light_curve.embed.RandomSubsample` ¶

Bases: SingleSubsampleReduction

Draw seq_size observations uniformly at random without replacement.

Parameters:

Name	Type	Description	Default
`rng`	`int, np.random.Generator, or None`	Seed or generator for reproducible sampling.	required

`light_curve.embed.NonOverlappingWindows` ¶

Bases: Reduction

Split the light curve into consecutive non-overlapping windows of seq_size observations.

A light curve of length L yields ceil(L / seq_size) windows; the last window may be shorter than seq_size and is zero-padded. Per-window embeddings are averaged to produce a single embedding per light curve.

`light_curve.embed.MultipleReductions` ¶

Bases: Reduction

Apply several :class:SingleSubsampleReduction strategies in parallel.

Each strategy produces one window; embeddings are stacked along the subsample axis rather than aggregated, giving one embedding per strategy.

Parameters:

Name	Type	Description	Default
`reductions`	`list of SingleSubsampleReduction`	Ordered list of strategies to apply.	required

Raises:

Type	Description
`ValueError`	If any element of `reductions` is not a :class:`SingleSubsampleReduction`.

`light_curve.embed.SingleSubsampleReduction` ¶

Bases: Reduction, ABC

Base for strategies that produce exactly one window per light curve.

ML Embeddings API¶

light_curve.embed.EmbeddingSession ¶

light_curve.embed.SingleBandModel ¶

light_curve.embed.AstraCLR ¶

from_hf classmethod ¶

light_curve.embed.Astromer1 ¶

from_hf classmethod ¶

light_curve.embed.Astromer1ZTF ¶

from_hf classmethod ¶

light_curve.embed.Astromer2 ¶

from_hf classmethod ¶

light_curve.embed.ATAT ¶

from_hf classmethod ¶

light_curve.embed.ATCAT ¶

from_hf classmethod ¶

light_curve.embed.Chronos2 ¶

from_hf classmethod ¶

light_curve.embed.ChronosBolt ¶

from_hf classmethod ¶

light_curve.embed.Moment1 ¶

from_hf classmethod ¶

Reduction strategies¶

light_curve.embed.Beginning ¶

light_curve.embed.End ¶

light_curve.embed.Middle ¶

light_curve.embed.RandomSubsample ¶

light_curve.embed.NonOverlappingWindows ¶

light_curve.embed.MultipleReductions ¶

light_curve.embed.SingleSubsampleReduction ¶

`light_curve.embed.EmbeddingSession` ¶

`light_curve.embed.SingleBandModel` ¶

`light_curve.embed.AstraCLR` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Astromer1` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Astromer1ZTF` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Astromer2` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.ATAT` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.ATCAT` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Chronos2` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.ChronosBolt` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Moment1` ¶

`from_hf` `classmethod` ¶

`light_curve.embed.Beginning` ¶

`light_curve.embed.End` ¶

`light_curve.embed.Middle` ¶

`light_curve.embed.RandomSubsample` ¶

`light_curve.embed.NonOverlappingWindows` ¶

`light_curve.embed.MultipleReductions` ¶

`light_curve.embed.SingleSubsampleReduction` ¶