uvex_transients.simulation.core.SurveySimulator.generate_events#

SurveySimulator.generate_events(time_bins: Time | int, nside: int | None = None, order: str | None = None, downsample: int | Mapping[str, int] | None = None) → EventCatalog[source]#

Sample a Monte Carlo realization of every registered transient type over a time grid.

For each transient type and each bin [t_k, t_{k+1}) of time_bins, events are sampled only within the HEALPix pixels the survey actually observes at some point between t_k and t_{k+1} + transient.duration_limit – i.e. only where an event exploding in this bin could plausibly still be caught by an observation before it fades below relevance. Explosion times themselves are drawn only within [t_k, t_{k+1}), so no event is double-counted across adjacent bins.

Two columns are computed once here, at generation time, so nothing downstream ever re-derives them: luminosity_distance (interpolated per transient type off its own cached luminosity_distance_grid/ redshift_grid, rather than a fresh cosmology.luminosity_distance call per event) and ebv (one vectorized Milky Way dust-map query over every sampled position at once).

Parameters:

  • time_bins (Time or int) – Either an explicit, monotonically increasing Time array of n + 1 bin edges, or a positive int giving the number of evenly-spaced bins to divide survey_schedule’s full span into.

  • nside (int, optional) – HEALPix resolution used both to query the observed footprint and to sample event positions. If None (the default), uses config["healpix.default_nside"].

  • order (str, optional) – HEALPix pixel ordering scheme ("nested" or "ring"). If None (the default), uses config["healpix.default_order"].

  • downsample (int or Mapping of str to int, optional) – Downsample the number of events generated, by drawing a random subset (without replacement) of each per-bin, per-type table rather than a fixed stride – seeded reproducibly off simulation_seed. Either a single factor applied to every registered transient type, or a {type key: factor} mapping giving a different factor per type (a type left out of the mapping is not downsampled at all). The default is None (no downsampling).

Returns:

One row per sampled event, across every registered transient type and time bin.

Return type:

EventCatalog

Raises:

ValueError – If downsample is a mapping naming a key not in self._transients.