Overview

catalogue ¶

Seeded draws from published merger catalogues.

The catalogues are fetched on demand and verified against a pinned digest rather than shipped with the package, so an installation stays light while a draw is still reproducible from the published product. See :mod:gwmock_pop.catalogue.manifest for the pinned files, :mod:gwmock_pop.catalogue.population for the draw, and :mod:gwmock_pop.catalogue.mdc_list for the regeneration of the Einstein Telescope Mock Data Challenge CBC injection lists from local catalogue copies, and :mod:gwmock_pop.catalogue.imbh_list for intermediate-mass black-hole binary lists in the same per-event format, drawn from a parametric population.

Classes¶

BandComposition `dataclass` ¶

BandComposition(band_detector_frame_chirp_mass: float, imbh_total_mass_threshold: float, n_draws: int, seeds: tuple[int, ...], class_counts: tuple[ClassBandCounts, ...], share_of_band_mean: Mapping[str, float], share_of_band_std: Mapping[str, float], share_of_band_min: Mapping[str, float], share_of_band_max: Mapping[str, float], share_of_band_per_draw: Mapping[str, tuple[float, ...]], bns_share_of_band_lower_90: float, detector_frame_chirp_mass_range: Mapping[str, tuple[float, float] | None], source_frame_chirp_mass_range: Mapping[str, tuple[float, float] | None], redshift_reach: float | None, drawn_rate_per_year: Mapping[str, float], in_band_duration_quantiles: Mapping[str, float])

The measured composition and summaries of a set of draws.

Attributes:

Name	Type	Description
`band_detector_frame_chirp_mass`	`float`	Lower edge of the band.
`imbh_total_mass_threshold`	`float`	Intermediate-mass total-mass threshold.
`n_draws`	`int`	Number of draws pooled.
`seeds`	`tuple[int, ...]`	Seeds of the draws, in order.
`class_counts`	`tuple[ClassBandCounts, ...]`	Per-class pooled counts, in :data:`CLASS_ORDER`.
`share_of_band_mean`	`Mapping[str, float]`	Per class, the mean per-draw share of the band.
`share_of_band_std`	`Mapping[str, float]`	Per class, the standard deviation of the per-draw share of the band.
`share_of_band_min`	`Mapping[str, float]`	Per class, the smallest per-draw share of the band.
`share_of_band_max`	`Mapping[str, float]`	Per class, the largest per-draw share of the band.
`share_of_band_per_draw`	`Mapping[str, tuple[float, ...]]`	Per class, the per-draw share of the band.
`bns_share_of_band_lower_90`	`float`	One-sided 90 per cent Wilson lower bound on the pooled binary-neutron-star share of the band.
`detector_frame_chirp_mass_range`	`Mapping[str, tuple[float, float] \| None]`	Per class, `(min, max)` detector-frame chirp mass over the in-band rows, or `None` when none are in band.
`source_frame_chirp_mass_range`	`Mapping[str, tuple[float, float] \| None]`	The same range in the source frame.
`redshift_reach`	`float \| None`	Largest redshift over all drawn rows, or `None`.
`drawn_rate_per_year`	`Mapping[str, float]`	Per class, the annual rate the draw was made at.
`in_band_duration_quantiles`	`Mapping[str, float]`	Leading-order in-band duration quantiles, in seconds, over the in-band rows.

Methods:¶

to_dict ¶

to_dict() -> dict[str, Any]

Return the composition as a JSON-ready mapping.

Returns:

Type	Description
`dict[str, Any]`	A plain mapping with lists where the dataclass holds tuples, so it
`dict[str, Any]`	can be written as a stamp beside a draw.

CatalogueBandAnchor `dataclass` ¶

CatalogueBandAnchor(band_detector_frame_chirp_mass: float, class_counts: tuple[ClassBandCounts, ...], redshift_reach: float | None)

Band membership counted over every catalogue row, not over a draw.

Attributes:

Name	Type	Description
`band_detector_frame_chirp_mass`	`float`	Lower edge of the band.
`class_counts`	`tuple[ClassBandCounts, ...]`	Per-class counts over the full catalogues, in :data:`CLASS_ORDER`.
`redshift_reach`	`float \| None`	Largest redshift over all catalogue rows.

ClassBandCounts `dataclass` ¶

ClassBandCounts(name: str, drawn: int, in_band: int, in_band_fraction: float, share_of_band: float)

One class's counts in and out of the band, pooled across draws.

Attributes:

Name	Type	Description
`name`	`str`	Class label.
`drawn`	`int`	Rows drawn across all draws.
`in_band`	`int`	Rows drawn inside the band across all draws.
`in_band_fraction`	`float`	`in_band / drawn` for a class with rows, else zero.
`share_of_band`	`float`	`in_band` over the total in-band count, else zero.

ImbhList `dataclass` ¶

ImbhList(settings: ImbhListSettings, population: ImbhPopulation, rate: ImbhRate, columns: dict[str, ndarray], n_events: int)

One generated IMBH injection list.

Attributes:

Name	Type	Description
`settings`	`ImbhListSettings`	Settings the list was generated with.
`population`	`ImbhPopulation`	The population model.
`rate`	`ImbhRate`	The rate integral the arrival process was set from.
`columns`	`dict[str, ndarray]`	One 1-D array per column, one entry per listed event, in event order, with the same names as :attr:`gwmock_pop.catalogue.mdc_list. MdcCbcList.columns`. `source_type` is :data:`IMBH_TYPE` or :data:`IMRI_TYPE`.
`n_events`	`int`	Events drawn, including those whose signal starts after the end of the data and so are not listed.

Attributes¶

n_listed `property` ¶

n_listed: int

Return the number of listed events.

Returns:

Type	Description
`int`	The length of every column.

Methods:¶

in_segment ¶

in_segment(segment: int) -> np.ndarray

Return which listed events belong to a data segment.

Parameters:

Name	Type	Description	Default
`segment`	`int`	Zero-based segment index.	required

Returns:

Type	Description
`ndarray`	Boolean mask over the listed events.

population_columns ¶

population_columns() -> dict[str, np.ndarray]

Return the listed events as a canonical CBC population.

Returns:

Name	Type	Description
	`dict[str, ndarray]`	Mapping from canonical parameter name to a 1-D array, in event order,
`for`	`dict[str, ndarray]`	data:`IMBH_ROUTING_KEY`. Both sub-populations are included; the
	`dict[str, ndarray]`	class codes stay on :attr:`columns`.

provenance ¶

provenance(*, file_format: str) -> dict[str, Any]

Return the provenance record of the population file.

Parameters:

Name	Type	Description	Default
`file_format`	`str`	Format the population is written in, `"csv"` or `"hdf5"`.	required

Returns:

Type	Description
`dict[str, Any]`	A record for :func:`gwmock_pop.loaders.write_population_catalogue`
`dict[str, Any]`	naming the population model, the run settings, the rate integral and
`dict[str, Any]`	the derived mean interval, the event counts and the package versions.

ImbhListSettings `dataclass` ¶

ImbhListSettings(start_time: float, segment_duration: float, n_segments: int, seed: int = 100, f_min: float = 5.0)

Settings of one list generation: the data span, the seed and f_min.

Attributes:

Name	Type	Description
`start_time`	`float`	GPS time of the start of the data, in seconds.
`segment_duration`	`float`	Duration of one data segment, in seconds.
`n_segments`	`int`	Number of data segments.
`seed`	`int`	Base seed; event `k` is generated with `seed + k`.
`f_min`	`float`	Lower frequency of the chirp-duration bound, in hertz.

Attributes¶

stop_time `property` ¶

stop_time: float

Return the GPS time of the end of the data.

Returns:

Type	Description
`float`	`start_time + n_segments * segment_duration`.

Methods:¶

validate ¶

validate() -> None

Refuse settings that cannot describe a run.

Raises:

Type	Description
`PopulationValidationError`	If a setting is out of range.

ImbhPopulation `dataclass` ¶

ImbhPopulation(min_total_mass: float = 100.0, max_total_mass: float = 1000.0, min_mass_ratio: float = 1.0, max_mass_ratio: float = 10.0, imri_fraction: float = 0.0, imri_min_mass_ratio: float = 10.0, imri_max_mass_ratio: float = 100.0, max_spin: float = 0.99, local_rate: float = 0.08, max_redshift: float = 10.0, max_detector_frame_total_mass: float = 3000.0, gamma: float = MADAU_DICKINSON_GAMMA, kappa: float = MADAU_DICKINSON_KAPPA, z_peak: float = MADAU_DICKINSON_Z_PEAK, hubble_constant: float = PLANCK18_H0_KM_S_MPC, omega_m: float = PLANCK18_OMEGA_M, waveform_approximant: str = 'IMRPhenomXPHM')

Astrophysical model of the IMBH binaries.

Attributes:

Name	Type	Description
`min_total_mass`	`float`	Lower bound of the source-frame total mass, in solar masses.
`max_total_mass`	`float`	Upper bound of the source-frame total mass, in solar masses.
`min_mass_ratio`	`float`	Lower bound of `m1 / m2` in the main population.
`max_mass_ratio`	`float`	Upper bound of `m1 / m2` in the main population.
`imri_fraction`	`float`	Fraction of the events drawn from the IMRI sub-population; `0` switches it off.
`imri_min_mass_ratio`	`float`	Lower bound of `m1 / m2` in the IMRI sub-population.
`imri_max_mass_ratio`	`float`	Upper bound of `m1 / m2` in the IMRI sub-population.
`max_spin`	`float`	Upper bound of the dimensionless spin magnitudes.
`local_rate`	`float`	Source-frame merger-rate density at `z = 0` of the whole population (both sub-populations, the full mass range before the detector-frame cap), in `Gpc^-3 yr^-1`. The default is the GW190521-like rate as revised with the full third observing run, 0.08 (+0.19, -0.07) (LVK, A&A 659, A84 (2022), Sect. 5.3), which supersedes the 0.13 estimated from the first half of that run.
`max_redshift`	`float`	Largest source redshift.
`max_detector_frame_total_mass`	`float`	Largest `(1 + z) M` kept, in solar masses.
`gamma`	`float`	Low-redshift slope of the star-formation shape.
`kappa`	`float`	High-redshift fall-off of the star-formation shape.
`z_peak`	`float`	Redshift of the star-formation peak.
`hubble_constant`	`float`	Hubble constant, in km/s/Mpc.
`omega_m`	`float`	Matter density of the flat Lambda-CDM cosmology.
`waveform_approximant`	`str`	Waveform model the population is meant to be simulated with. It is recorded, not used, by the generator.

Attributes¶

largest_mass_ratio `property` ¶

largest_mass_ratio: float

Return the largest mass ratio any event can have.

Returns:

Type	Description
`float`	`imri_max_mass_ratio` when the IMRI sub-population is on, else `max_mass_ratio`.

Methods:¶

validate ¶

validate() -> None

Refuse a model that cannot describe a population.

Raises:

Type	Description
`PopulationValidationError`	If a parameter is out of range.

ImbhRate `dataclass` ¶

ImbhRate(redshift: ndarray, rate_density: ndarray, cumulative: ndarray, luminosity_distance: ndarray, uncapped_events_per_year: float, events_per_year: float)

The rate integral of a population and the tables it is drawn from.

Attributes:

Name	Type	Description
`redshift`	`ndarray`	Redshift grid, from 0 to `max_redshift`.
`rate_density`	`ndarray`	`dN_dot/dz` on the grid, in events per year per unit redshift.
`cumulative`	`ndarray`	Normalised cumulative distribution of the redshift on the grid.
`luminosity_distance`	`ndarray`	Luminosity distance on the grid, in Mpc.
`uncapped_events_per_year`	`float`	Observed-frame rate without the detector-frame cap.
`events_per_year`	`float`	Observed-frame rate of the population, after the cap.

Attributes¶

mean_interval `property` ¶

mean_interval: float

Return the mean waiting time between mergers, in seconds.

Returns:

Type	Description
`float`	One Julian year divided by :attr:`events_per_year`.

CatalogueFile `dataclass` ¶

CatalogueFile(name: str, source_class: str, filename: str, sha256: str, size_bytes: int, n_rows: int, extra_columns: tuple[str, ...] = (), spin_reference_frequency: float | None = None)

One catalogue file, with the identity needed to fetch and verify it.

Attributes:

Name	Type	Description
`name`	`str`	Short name used to address the file in code and configs.
`source_class`	`str`	Source class the file holds, as recorded in a draw.
`filename`	`str`	File name the document server serves it under.
`sha256`	`str`	Expected SHA-256 of the file contents, lowercase hex.
`size_bytes`	`int`	Expected size of the file in bytes.
`n_rows`	`int`	Number of catalogue rows, a property of the published product.
`extra_columns`	`tuple[str, ...]`	Columns the file carries beyond those every catalogue carries, each one of :data:`OPTIONAL_COLUMNS`. A draw reads and emits them, and refuses the file if one is absent.
`spin_reference_frequency`	`float \| None`	Frequency in Hz at which the file's spin components are defined, or `None` when the file carries only aligned components, which do not depend on it.

Attributes¶

url `property` ¶

url: str

Return the document-server download URL for this file.

Returns:

Type	Description
`str`	The URL, with the file name carried in the `call_file` query
`str`	parameter the server expects.

record_url `property` ¶

record_url: str

Return the human-readable document-server record URL.

Returns:

Type	Description
`str`	The record page URL.

MdcCbcList `dataclass` ¶

MdcCbcList(settings: MdcListSettings, inputs: Mapping[str, MdcInputFile], columns: dict[str, ndarray], n_events: int, rows_consumed: Mapping[str, int])

One generated injection list.

Attributes:

Name	Type	Description
`settings`	`MdcListSettings`	Settings the list was generated with.
`inputs`	`Mapping[str, MdcInputFile]`	The input files, keyed by role.
`columns`	`dict[str, ndarray]`	One 1-D array per column, one entry per listed event, in event order. Canonical gwmock-pop parameter names are used where one exists; the remaining columns are `event_id` (the event counter `k`), `source_type` (class code), `start_time` and `end_time` (signal bounds), `source_frame_mass_1`/`_2`, `spin_1`/`spin_2` (magnitudes), `first_segment` and `stop_segment` (the event is listed in segments `first_segment <= i < stop_segment`).
`n_events`	`int`	Events drawn, including those whose signal starts after the end of the data and so are not listed.
`rows_consumed`	`Mapping[str, int]`	Catalogue rows read per class, which is the number of events of that class drawn.

Attributes¶

n_listed `property` ¶

n_listed: int

Return the number of listed events.

Returns:

Type	Description
`int`	The length of every column.

Methods:¶

in_segment ¶

in_segment(segment: int) -> np.ndarray

Return which listed events belong to a data segment.

Parameters:

Name	Type	Description	Default
`segment`	`int`	Zero-based segment index.	required

Returns:

Type	Description
`ndarray`	Boolean mask over the listed events.

population ¶

population(source_type: str) -> dict[str, np.ndarray]

Return one class's events as a canonical CBC population.

Parameters:

Name	Type	Description	Default
`source_type`	`str`	`"bns"`, `"nsbh"` or `"bbh"`.	required

Returns:

Type	Description
`dict[str, ndarray]`	Mapping from canonical parameter name to a 1-D array, in event order.
`dict[str, ndarray]`	Binary-black-hole events carry an explicit zero tidal
`dict[str, ndarray]`	deformability, and so do neutron-star--black-hole events unless
`dict[str, ndarray]`	`nsbh_tides` gives their neutron star the spline value.

Raises:

Type	Description
`ValueError`	If `source_type` names no class.

provenance ¶

provenance(source_type: str, *, file_format: str) -> dict[str, Any]

Return the provenance record of one class's population file.

Parameters:

Name	Type	Description	Default
`source_type`	`str`	`"bns"`, `"nsbh"` or `"bbh"`.	required
`file_format`	`str`	Format the population is written in, `"csv"` or `"hdf5"`.	required

Returns:

Type	Description
`dict[str, Any]`	A record for :func:`gwmock_pop.loaders.write_population_catalogue`,
`dict[str, Any]`	naming the input digests, the seed, the class fractions, the mean
`dict[str, Any]`	interval, the start time and span, and the package versions.

MdcInputFile `dataclass` ¶

MdcInputFile(name: str, path: Path, sha256: str, size_bytes: int)

One input file, with the identity a generation records.

Attributes:

Name	Type	Description
`name`	`str`	Role of the file: `"bns"`, `"nsbh"`, `"bbh"` or `"lambda"`.
`path`	`Path`	Local path of the file.
`sha256`	`str`	SHA-256 of the file contents, lowercase hex.
`size_bytes`	`int`	Size of the file in bytes.

MdcListSettings `dataclass` ¶

MdcListSettings(start_time: float, segment_duration: float, n_segments: int, mean_interval: float, bns_fraction: float, bbh_fraction: float, seed: int = 100, f_min: float = 5.0, min_component_mass: float = 1.1, nsbh_tides: bool = False)

Settings of one list generation, named after the original options.

Attributes:

Name	Type	Description
`start_time`	`float`	GPS time of the start of the data, in seconds.
`segment_duration`	`float`	Duration of one data segment, in seconds.
`n_segments`	`int`	Number of data segments.
`mean_interval`	`float`	Mean waiting time between mergers, in seconds.
`bns_fraction`	`float`	Probability that an event is a binary neutron star.
`bbh_fraction`	`float`	Probability that an event is a binary black hole. The neutron-star--black-hole fraction is the remainder, so the three cannot disagree.
`seed`	`int`	Base seed; event `k` is generated with `seed + k`.
`f_min`	`float`	Lower frequency of the chirp-duration bound, in hertz.
`min_component_mass`	`float`	Component mass, in solar masses, of the longest signal the run allows for; it fixes how long after the end of the data mergers are still drawn.
`nsbh_tides`	`bool`	Give each neutron-star--black-hole binary's neutron star (the second component) the tidal deformability of the same table and spline as a binary neutron star's, at its source-frame mass. Off by default: the original generator writes zero for these binaries, and the lists then reproduce it.

Attributes¶

nsbh_fraction `property` ¶

nsbh_fraction: float

Return the neutron-star--black-hole fraction, the remainder of the other two.

Returns:

Type	Description
`float`	`1 - bns_fraction - bbh_fraction`.

stop_time `property` ¶

stop_time: float

Return the GPS time of the end of the data.

Returns:

Type	Description
`float`	`start_time + n_segments * segment_duration`.

Methods:¶

validate ¶

validate() -> None

Refuse settings that cannot describe a run.

Raises:

Type	Description
`PopulationValidationError`	If a setting is out of range.

CatalogueDraw `dataclass` ¶

CatalogueDraw(seed: int, span_seconds: float, rate_multiplier: float, band_detector_frame_chirp_mass: float, imbh_total_mass_threshold: float, parameters: dict[str, ndarray], source_class: ndarray, population_class: ndarray, detector_frame_chirp_mass: ndarray, source_frame_chirp_mass: ndarray, in_band: ndarray, expected_per_class: Mapping[str, float], drawn_per_class: Mapping[str, int], resolved: tuple[ResolvedCatalogue, ...], allow_replacement: bool = False)

One seeded draw of a merger catalogue into injection parameters.

Attributes:

Name	Type	Description
`seed`	`int`	Seed the draw's generator was initialized with.
`span_seconds`	`float`	Observation span the draw covers, in seconds.
`rate_multiplier`	`float`	Factor applied to every catalogue's annual rate.
`band_detector_frame_chirp_mass`	`float`	Lower edge of the searched band, in the detector frame.
`imbh_total_mass_threshold`	`float`	Source-frame total mass at or above which a black-hole-catalogue row is labelled intermediate-mass.
`parameters`	`dict[str, ndarray]`	Mapping from output parameter name to a 1-D array, in :data:`PARAMETER_NAMES` order.
`source_class`	`ndarray`	Catalogue class of each drawn row.
`population_class`	`ndarray`	Labelled class of each drawn row -- a catalogue class, or `"IMBH"` for a heavy black-hole row.
`detector_frame_chirp_mass`	`ndarray`	Detector-frame chirp mass of each row.
`source_frame_chirp_mass`	`ndarray`	Source-frame chirp mass of each row.
`in_band`	`ndarray`	Whether the row's detector-frame chirp mass is above the band.
`expected_per_class`	`Mapping[str, float]`	Poisson mean the count of each catalogue class was drawn from, summed over the catalogues of a class.
`drawn_per_class`	`Mapping[str, int]`	Realized count per catalogue class.
`resolved`	`tuple[ResolvedCatalogue, ...]`	The verified catalogue files the draw was made from.
`allow_replacement`	`bool`	Whether a class whose count exceeds its catalogue's rows was permitted to be sampled with replacement.

Attributes¶

n_rows `property` ¶

n_rows: int

Return the number of drawn rows.

Returns:

Type	Description
`int`	The number of rows, zero when the span admitted no merger.

in_band_rows `property` ¶

in_band_rows: int

Return the number of drawn rows inside the searched band.

Returns:

Type	Description
`int`	The count of rows whose detector-frame chirp mass is above the band.

ResolvedCatalogue `dataclass` ¶

ResolvedCatalogue(catalogue: CatalogueFile, path: Path, metadata: dict[str, Any])

A catalogue file on local disk, with the identity it was verified against.

Attributes:

Name	Type	Description
`catalogue`	`CatalogueFile`	The pinned catalogue the file belongs to.
`path`	`Path`	Local path of the verified file.
`metadata`	`dict[str, Any]`	Fetch metadata, including whether the cache was hit and the digest the bytes matched.

Functions:¶

catalogue_band_anchor ¶

catalogue_band_anchor(resolved: Sequence[ResolvedCatalogue], *, band_detector_frame_chirp_mass: float, imbh_total_mass_threshold: float) -> CatalogueBandAnchor

Count the band composition of every catalogue row.

A draw measures the composition of a sample; this measures it over the whole published product. The two are not the same number, and reporting them together is the check that the draw samples the catalogue rather than something shaped like it -- the draw's spread should contain the catalogue count, and a systematic offset is a sampling bug rather than a fluctuation.

Parameters:

Name	Type	Description	Default
`resolved`	`Sequence[ResolvedCatalogue]`	The verified catalogue files to count.	required
`band_detector_frame_chirp_mass`	`float`	Lower edge of the band.	required
`imbh_total_mass_threshold`	`float`	Source-frame total mass at or above which a black-hole row is labelled intermediate-mass.	required

Returns:

Type	Description
`CatalogueBandAnchor`	The full-catalogue counts and redshift reach.

Raises:

Type	Description
`PopulationValidationError`	If a catalogue cannot be read.

composition_summary ¶

composition_summary(draws: Sequence[CatalogueDraw], *, f_low: float = 5.0, black_hole_rate_split: Mapping[str, float] | None = None) -> BandComposition

Summarise the composition of several draws of the same population.

Parameters:

Name	Type	Description	Default
`draws`	`Sequence[CatalogueDraw]`	Draws to summarise. All must sample the same population under the same settings -- the band, the intermediate-mass threshold, the observation span, the rate multiplier and the pinned catalogues; the seeds must not be empty.	required
`f_low`	`float`	Observed low-frequency cutoff, for the in-band duration.	`5.0`
`black_hole_rate_split`	`Mapping[str, float] \| None`	Fraction of the black-hole catalogue's annual rate each mutually exclusive black-hole-derived class takes, keyed by class label (for example `{"BBH": 0.9847, "IMBH": 0.0153}`). Pass the fractions measured from the full catalogue when they are available; omit them to split the rate by the draw's own labelled counts. Either way the classes partition the black-hole rate.	`None`

Returns:

Type	Description
`BandComposition`	The composition and the draw-to-draw spread.

Raises:

Type	Description
`ValueError`	If no draws are given, they disagree on the band edge, the intermediate-mass threshold, the observation span, the rate multiplier or the pinned catalogues, or `black_hole_rate_split` names a class that is not black-hole-derived, does not sum to one, or holds a negative or non-finite fraction.

generate_imbh_list ¶

generate_imbh_list(settings: ImbhListSettings, population: ImbhPopulation | None = None) -> ImbhList

Generate an IMBH injection list.

Parameters:

Name	Type	Description	Default
`settings`	`ImbhListSettings`	Data span, seed and `f_min`.	required
`population`	`ImbhPopulation \| None`	Population model; the defaults when omitted.	`None`

Returns:

Type	Description
`ImbhList`	The listed events and the record of how they were generated.

Raises:

Type	Description
`PopulationValidationError`	If the settings or the model are out of range.

imbh_rate ¶

imbh_rate(population: ImbhPopulation) -> ImbhRate

Integrate the population's merger rate over redshift.

The comoving volume element and the luminosity distance come from one distance table, so the rate and the distances written to the lists share a single cosmology.

Parameters:

Name	Type	Description	Default
`population`	`ImbhPopulation`	The population model.	required

Returns:

Type	Description
`ImbhRate`	The rate integral, with and without the detector-frame cap, and the
`ImbhRate`	redshift tables the events are drawn from.

Raises:

Type	Description
`PopulationValidationError`	If the model is out of range.

generate_mdc_cbc_list ¶

generate_mdc_cbc_list(settings: MdcListSettings, inputs: Mapping[str, MdcInputFile]) -> MdcCbcList

Generate the CBC injection list for a set of settings and input files.

Parameters:

Name	Type	Description	Default
`settings`	`MdcListSettings`	Run settings; :data:`MDC1_SETTINGS` reproduces the first Mock Data Challenge.	required
`inputs`	`Mapping[str, MdcInputFile]`	Input files keyed by role, from :func:`resolve_mdc_inputs`.	required

Returns:

Type	Description
`MdcCbcList`	The listed events and the record of how they were generated.

Raises:

Type	Description
`PopulationValidationError`	If the settings are out of range, an input is missing or malformed, a catalogue runs out of rows, or a neutron-star mass lies outside the tidal-deformability table.

resolve_mdc_inputs ¶

resolve_mdc_inputs(directory: str | PathLike[str], *, expected_sha256: Mapping[str, str] | None = MDC1_CATALOGUE_SHA256) -> dict[str, MdcInputFile]

Locate and fingerprint the four input files in a directory.

The catalogues are not distributed with this package; point this at a local copy of them.

Parameters:

Name	Type	Description	Default
`directory`	`str \| PathLike[str]`	Directory holding the files under :data:`CATALOGUE_FILENAMES`.	required
`expected_sha256`	`Mapping[str, str] \| None`	Digests the files must match, keyed by role. Defaults to the inputs of the first Mock Data Challenge; pass `None` to accept any files and only record their digests.	`MDC1_CATALOGUE_SHA256`

Returns:

Type	Description
`dict[str, MdcInputFile]`	The input files keyed by role.

Raises:

Type	Description
`PopulationValidationError`	If a file is missing or does not match its expected digest.

draw_catalogue_population ¶

draw_catalogue_population(*, seed: int, span_seconds: float, catalogues: Sequence[CatalogueFile] | None = None, resolved: Sequence[ResolvedCatalogue] | None = None, rate_multiplier: float = 1.0, band_detector_frame_chirp_mass: float = 5.0, imbh_total_mass_threshold: float = 100.0, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, offline: bool = False, timeout: int = 300, allow_replacement: bool = False) -> CatalogueDraw

Draw a seeded population from pinned catalogues into injection parameters.

Classes are drawn in catalogues order, each with a Poisson count and a without-replacement row sample, so the same seed, span and files reproduce the draw exactly. A count larger than its catalogue is refused unless allow_replacement is set. Pass resolved to draw from already-resolved files (a cached or locally built catalogue); otherwise the files are fetched and digest-verified on demand.

Parameters:

Name	Type	Description	Default
`seed`	`int`	Seed for the draw's generator.	required
`span_seconds`	`float`	Observation span the draw covers, in seconds.	required
`catalogues`	`Sequence[CatalogueFile] \| None`	Pinned catalogues to draw from, in draw order. Defaults to the catalogues of `resolved` when those are given, otherwise to the design-comparison pair.	`None`
`resolved`	`Sequence[ResolvedCatalogue] \| None`	Already-resolved catalogue files, in the same order and each an instance of its configured pin. When given, no fetch is performed.	`None`
`rate_multiplier`	`float`	Factor applied to every catalogue's annual rate.	`1.0`
`band_detector_frame_chirp_mass`	`float`	Lower edge of the searched band, in the detector frame.	`5.0`
`imbh_total_mass_threshold`	`float`	Source-frame total mass at or above which a black-hole-catalogue row is labelled intermediate-mass.	`100.0`
`cache_dir`	`str \| PathLike[str] \| None`	Cache directory for on-demand fetches.	`None`
`refresh`	`bool`	Whether to re-download catalogues even when cached.	`False`
`offline`	`bool`	Whether to refuse network access and use only matching caches.	`False`
`timeout`	`int`	Timeout in seconds for each catalogue download.	`300`
`allow_replacement`	`bool`	Whether a class count larger than its catalogue may be sampled with replacement, repeating rows, instead of being refused. A count the catalogue can meet is unaffected.	`False`

Returns:

Type	Description
`CatalogueDraw`	The draw, its parameters and its class labels.

Raises:

Type	Description
`PopulationValidationError`	If the settings are out of range, a supplied resolved catalogue does not match its configured pin, a catalogue is malformed, or a class count exceeds its catalogue's rows and `allow_replacement` is not set.
`PopulationFetchError`	If a catalogue cannot be fetched or does not match its pinned digest.

draw_catalogue_population_many ¶

draw_catalogue_population_many(*, seeds: Sequence[int], span_seconds: float, catalogues: Sequence[CatalogueFile] | None = None, resolved: Sequence[ResolvedCatalogue] | None = None, rate_multiplier: float = 1.0, band_detector_frame_chirp_mass: float = 5.0, imbh_total_mass_threshold: float = 100.0, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, offline: bool = False, timeout: int = 300, allow_replacement: bool = False) -> tuple[CatalogueDraw, ...]

Draw the same population once per seed.

The catalogues are resolved once and reused across seeds, so a repeated-draw measurement pays for one download and reseeds only the draw.

Parameters:

Name	Type	Description	Default
`seeds`	`Sequence[int]`	Seeds to draw, one draw each.	required
`span_seconds`	`float`	Observation span each draw covers, in seconds.	required
`catalogues`	`Sequence[CatalogueFile] \| None`	Pinned catalogues to draw from, in draw order. Defaults to the catalogues of `resolved` when those are given, otherwise to the design-comparison pair.	`None`
`resolved`	`Sequence[ResolvedCatalogue] \| None`	Already-resolved catalogue files, in the same order.	`None`
`rate_multiplier`	`float`	Factor applied to every catalogue's annual rate.	`1.0`
`band_detector_frame_chirp_mass`	`float`	Lower edge of the searched band.	`5.0`
`imbh_total_mass_threshold`	`float`	Source-frame total mass at or above which a black-hole row is labelled intermediate-mass.	`100.0`
`cache_dir`	`str \| PathLike[str] \| None`	Cache directory for on-demand fetches.	`None`
`refresh`	`bool`	Whether to re-download catalogues even when cached.	`False`
`offline`	`bool`	Whether to refuse network access and use only matching caches.	`False`
`timeout`	`int`	Timeout in seconds for each catalogue download.	`300`
`allow_replacement`	`bool`	Whether a class count larger than its catalogue may be sampled with replacement instead of being refused.	`False`

Returns:

Type	Description
`tuple[CatalogueDraw, ...]`	One draw per seed, in seed order.

fetch_catalogue ¶

fetch_catalogue(catalogue: CatalogueFile, *, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, offline: bool = False, timeout: int = 300) -> ResolvedCatalogue

Fetch one pinned catalogue into the local cache, verifying its digest.

Parameters:

Name	Type	Description	Default
`catalogue`	`CatalogueFile`	The pinned catalogue to fetch.	required
`cache_dir`	`str \| PathLike[str] \| None`	Cache directory. Defaults to the package cache location.	`None`
`refresh`	`bool`	Whether to re-download even when a matching entry is cached.	`False`
`offline`	`bool`	Whether to refuse network access and use only a matching cache.	`False`
`timeout`	`int`	Timeout in seconds for the download.	`300`

Returns:

Type	Description
`ResolvedCatalogue`	The verified local file and its fetch metadata.

Raises:

Type	Description
`PopulationFetchError`	If the file cannot be fetched, or the bytes do not match the pinned digest or size.

fetch_catalogues ¶

fetch_catalogues(catalogues: Sequence[CatalogueFile] = COBA_CATALOGUES, *, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, offline: bool = False, timeout: int = 300) -> tuple[ResolvedCatalogue, ...]

Fetch several pinned catalogues, preserving the given order.

Parameters:

Name	Type	Description	Default
`catalogues`	`Sequence[CatalogueFile]`	The pinned catalogues to fetch.	`COBA_CATALOGUES`
`cache_dir`	`str \| PathLike[str] \| None`	Cache directory. Defaults to the package cache location.	`None`
`refresh`	`bool`	Whether to re-download even when a matching entry is cached.	`False`
`offline`	`bool`	Whether to refuse network access and use only a matching cache.	`False`
`timeout`	`int`	Timeout in seconds for the download.	`300`

Returns:

Type	Description
`tuple[ResolvedCatalogue, ...]`	One resolved catalogue per input, in the same order.

Raises:

Type	Description
`PopulationFetchError`	If any file cannot be fetched or does not match its pin.

Overview

catalogue ¶

Classes¶

BandComposition dataclass ¶

Methods:¶

to_dict ¶

CatalogueBandAnchor dataclass ¶

ClassBandCounts dataclass ¶

ImbhList dataclass ¶

Attributes¶

n_listed property ¶

Methods:¶

in_segment ¶

population_columns ¶

provenance ¶

ImbhListSettings dataclass ¶

Attributes¶

stop_time property ¶

Methods:¶

validate ¶

ImbhPopulation dataclass ¶

Attributes¶

largest_mass_ratio property ¶

Methods:¶

validate ¶

ImbhRate dataclass ¶

Attributes¶

mean_interval property ¶

CatalogueFile dataclass ¶

Attributes¶

url property ¶

record_url property ¶

MdcCbcList dataclass ¶

Attributes¶

n_listed property ¶

Methods:¶

in_segment ¶

population ¶

provenance ¶

MdcInputFile dataclass ¶

MdcListSettings dataclass ¶

Attributes¶

nsbh_fraction property ¶

stop_time property ¶

Methods:¶

validate ¶

CatalogueDraw dataclass ¶

Attributes¶

n_rows property ¶

in_band_rows property ¶

ResolvedCatalogue dataclass ¶

Functions:¶

catalogue_band_anchor ¶

composition_summary ¶

generate_imbh_list ¶

imbh_rate ¶

generate_mdc_cbc_list ¶

resolve_mdc_inputs ¶

draw_catalogue_population ¶

draw_catalogue_population_many ¶

fetch_catalogue ¶

fetch_catalogues ¶

BandComposition `dataclass` ¶

CatalogueBandAnchor `dataclass` ¶

ClassBandCounts `dataclass` ¶

ImbhList `dataclass` ¶

n_listed `property` ¶

ImbhListSettings `dataclass` ¶

stop_time `property` ¶

ImbhPopulation `dataclass` ¶

largest_mass_ratio `property` ¶

ImbhRate `dataclass` ¶

mean_interval `property` ¶

CatalogueFile `dataclass` ¶

url `property` ¶

record_url `property` ¶

MdcCbcList `dataclass` ¶

n_listed `property` ¶

MdcInputFile `dataclass` ¶

MdcListSettings `dataclass` ¶

nsbh_fraction `property` ¶

stop_time `property` ¶

CatalogueDraw `dataclass` ¶

n_rows `property` ¶

in_band_rows `property` ¶

ResolvedCatalogue `dataclass` ¶