Skip to content

ExternalPopulationLoader

loader

Protocol definition for external population catalogue loaders.

Classes

ExternalPopulationLoader

Bases: GWPopSimulator, Protocol

Structural contract for file-backed population catalogues.

ExternalPopulationLoader intentionally has the same runtime surface as :class:~gwmock_pop.protocols.simulator.GWPopSimulator: any object with parameter_names, source_type, and simulate() satisfies both protocols automatically.

In this context, :meth:simulate means sample without replacement from a catalogue that was loaded from an external file such as HDF5 or CSV. Concrete loaders may perform that I/O eagerly during construction or via another package-specific setup step. Unsupported file formats should raise a clear ValueError at load time.

source_type must still be a non-empty routing key that is either set explicitly by the caller or derived from file metadata.

Attributes
parameter_names property 
parameter_names: Sequence[str]

Stable ordered list of output parameter keys.

The returned sequence must be identical across repeated calls on the same instance. gwmock relies on positional consistency when building per-event dicts from the mapping returned by :meth:simulate.

Returns:

Type Description
Sequence[str]

An ordered sequence of parameter name strings. The sequence is the
Sequence[str]

authoritative list of keys present in every mapping returned by
Sequence[str]

meth:simulate.
source_type property 
source_type: str

Non-empty routing key used by gwmock to select a signal simulator.

The value must be a non-empty string. gwmock uses it as a dictionary key to look up the matching gwmock-signal simulator (e.g. "bbh" → CBCSimulator). Returning an empty string or None at call-time is an error.

Returns:

Type Description
str

Source type string (e.g. "bbh", "bns", "nsbh",
str

"stochastic", "supernova", "cosmic_string").
Functions
simulate 
simulate(n_samples: int, **kwargs: Any) -> Mapping[str, PopulationArray]

Draw n_samples parameter sets from the population model.

The returned mapping must satisfy two invariants:

  1. Key completeness and order: list(result.keys()) == list(self.parameter_names).
  2. Shape contract: every value is a 1-D numpy.ndarray or jax.Array with leading dimension n_samples, i.e. result[k].shape[0] == n_samples for all k.

Parameters:

Name Type Description Default
n_samples int

Number of independent source realizations to draw. Must be a positive integer.

 required
**kwargs Any

Optional backend-specific keyword arguments (e.g. a JAX PRNG key or a configuration override). gwmock does not pass any keyword arguments; they exist for direct library use.

 {}

Returns:

Type Description
Mapping[str, PopulationArray]

Mapping from parameter name to 1-D numpy.ndarray or
Mapping[str, PopulationArray]

jax.Array of length n_samples.