Package
Top-level package for gwmock_pop.
Classes¶
Bases: PopulationError
Raised when a remote population catalogue cannot be fetched.
Bases: PopulationError, ValueError
Raised when a population catalogue fails schema or data validation.
FilePopulationLoader(source_type: str, path: str | PathLike, *, column_map: dict[str, str] | None = None, hdf5_dataset: str = _HDF5_DATASET_NAME, cache_dir: str | PathLike[str] | None = None, refresh: bool = False, token: str | None = None, credentials: Mapping[str, str] | Mapping[str, Mapping[str, str]] | None = None, download_timeout: int = 300)
Load an external population catalogue from HDF5 or CSV.
The loader reads the input file eagerly during construction, normalizes the
catalogue into a mapping of 1-D jax.Array columns, and then provides a
:meth:simulate method that samples catalogue rows without replacement.
This keeps the runtime surface compatible with
:class:gwmock_pop.protocols.ExternalPopulationLoader and
:class:gwmock_pop.protocols.GWPopSimulator without introducing a shared
inheritance hierarchy.
Load and validate a population catalogue from disk or a remote URL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_type
|
str
|
Non-empty routing key used by downstream simulators,
such as |
required |
path
|
str | PathLike
|
Path or supported URL to the input catalogue file. Supported
local and remote formats are |
required |
column_map
|
dict[str, str] | None
|
Optional mapping from file column names to canonical gwmock-pop parameter names. Keys must exist in the loaded catalogue. |
None
|
hdf5_dataset
|
str
|
Dataset name to read from HDF5 files. |
_HDF5_DATASET_NAME
|
cache_dir
|
str | PathLike[str] | None
|
Optional cache directory for remotely fetched catalogues. |
None
|
refresh
|
bool
|
Whether to force a re-download for remote URLs even when a cached copy already exists. |
False
|
token
|
str | None
|
Optional bearer token used for authenticated remote fetches. |
None
|
credentials
|
Mapping[str, str] | Mapping[str, Mapping[str, str]] | None
|
Optional mapping of request headers or scheme-specific credential fields for remote fetches. |
None
|
download_timeout
|
int
|
Timeout in seconds for HTTP(S) downloads. |
300
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Attributes¶
property
¶
parameter_names: list[str]
property
¶
source_type: str
Return the routing key associated with this population catalogue.
Returns:
| Type | Description |
|---|---|
str
|
Source type passed at construction time. |
property
¶
metadata: dict[str, Any]
Return loader metadata, including remote cache details when relevant.
Functions¶
simulate(n_samples: int | None = None, **kwargs: Any) -> Mapping[str, Array]
Sample catalogue rows without replacement.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_samples
|
int | None
|
Number of catalogue rows to draw. Pass |
None
|
**kwargs
|
Any
|
Optional backend-agnostic random-state hints. Supported
keys include |
{}
|
Returns:
| Type | Description |
|---|---|
Mapping[str, Array]
|
Mapping from parameter name to a 1-D |
Mapping[str, Array]
|
values. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
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¶
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: |
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. |
str
|
|
Functions¶
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:
- Key completeness and order:
list(result.keys()) == list(self.parameter_names). - Shape contract: every value is a 1-D
numpy.ndarrayorjax.Arraywith leading dimensionn_samples, i.e.result[k].shape[0] == n_samplesfor allk.
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 |
Mapping[str, PopulationArray]
|
|
Bases: Protocol
Structural contract between gwmock-pop and gwmock.
Any object that exposes parameter_names, source_type, and
simulate satisfies this protocol, regardless of its class hierarchy.
@runtime_checkable means isinstance checks work at runtime, so
gwmock can guard calls with::
assert isinstance(sim, GWPopSimulator)
and receive a clear TypeError if a misconfigured backend is passed.
How gwmock uses this protocol
gwmock drives a population run by calling simulate(n_samples) once
and slicing the returned mapping into per-event dicts for gwmock-signal::
population = sim.simulate(n_samples=1000)
for i in range(n_samples):
params_i = {k: v[i] for k, v in population.items()}
signal_sim.simulate(params_i, ...)
The source_type property is used by gwmock to select the matching
gwmock-signal simulator (e.g. a CBCSimulator for compact-binary keys
such as "bbh", "bns", or "nsbh").
Valid source_type values
+------------------+-------------------------------------------+
| "bbh" | Binary black hole coalescence |
+------------------+-------------------------------------------+
| "bns" | Binary neutron star coalescence |
+------------------+-------------------------------------------+
| "nsbh" | Neutron star - black hole coalescence |
+------------------+-------------------------------------------+
| "stochastic" | Stochastic gravitational-wave background |
+------------------+-------------------------------------------+
| "supernova" | Core-collapse supernova |
+------------------+-------------------------------------------+
| "cosmic_string" | Cosmic string burst |
+------------------+-------------------------------------------+
Array contract
Every value in the mapping returned by simulate is a 1-D
numpy.ndarray or jax.Array of shape (n_samples,). The keys are
exactly parameter_names in the same order. Consumers that want to drop
any downstream JAX dependency can materialize NumPy-backed values with
gwmock_pop.coerce_to_numpy(...).
Attributes¶
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: |
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. |
str
|
|
Functions¶
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:
- Key completeness and order:
list(result.keys()) == list(self.parameter_names). - Shape contract: every value is a 1-D
numpy.ndarrayorjax.Arraywith leading dimensionn_samples, i.e.result[k].shape[0] == n_samplesfor allk.
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 |
Mapping[str, PopulationArray]
|
|
BBHSimulator(*, m_min: float = 5.0, m_max: float = 100.0, d_min: float = 0.0, d_max: float = 5000.0, chi_max: float = 0.99, aligned_spins: bool = False, gps_start: float = 0.0, gps_end: float = 1.0, total_mass_max: float | None = None, f_ref: float = 20.0, parameters: Mapping[str, Any] | None = None, seed: int | None = None)
Bases: _CBCGraphSimulator
Graph-backed binary-black-hole population simulator.
Defaults to ordered component masses on [5, 100] solar masses, isotropic
precessing spins, zero tidal deformability, and source_type="bbh".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m_min
|
float
|
Lower bound for each component mass in solar masses. |
5.0
|
m_max
|
float
|
Upper bound for each component mass in solar masses. |
100.0
|
d_min
|
float
|
Minimum luminosity distance in Mpc. |
0.0
|
d_max
|
float
|
Maximum luminosity distance in Mpc. |
5000.0
|
chi_max
|
float
|
Maximum dimensionless spin magnitude for both components. |
0.99
|
aligned_spins
|
bool
|
If |
False
|
gps_start
|
float
|
Lower bound for the coalescence-time prior. |
0.0
|
gps_end
|
float
|
Upper bound for the coalescence-time prior. |
1.0
|
total_mass_max
|
float | None
|
Optional upper bound on |
None
|
f_ref
|
float
|
Constant reference frequency assigned to every sample. |
20.0
|
parameters
|
Mapping[str, Any] | None
|
Optional partial graph config merged onto the defaults. |
None
|
seed
|
int | None
|
Optional RNG seed forwarded to the graph simulator. |
None
|
Initialize the BBH simulator.
Attributes¶
property
¶
parameter_names: list[str]
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
source_type: str
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
load(input_path: str | Path) -> Array
classmethod
¶
from_config_file(config_path: str | Path, encoding: str = 'utf-8', **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a config file.
The CBC subclasses take physics-level constructor arguments rather than a
raw config mapping, so config-file and preset loading delegate to
:class:GraphSimulator and return a graph simulator directly.
classmethod
¶
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a packaged preset.
BNSSimulator(*, m_min: float = 1.0, m_max: float = 3.0, d_min: float = 0.0, d_max: float = 5000.0, chi_max: float = 0.05, aligned_spins: bool = True, gps_start: float = 0.0, gps_end: float = 1.0, total_mass_max: float | None = None, f_ref: float = 20.0, lambda_max: float = 3000.0, parameters: Mapping[str, Any] | None = None, seed: int | None = None)
Bases: _CBCGraphSimulator
Graph-backed binary-neutron-star population simulator.
Defaults to ordered component masses on [1, 3] solar masses, aligned
low-magnitude spins, uniform tidal deformability on [0, lambda_max] for
both components, and source_type="bns".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
m_min
|
float
|
Lower bound for each component mass in solar masses. |
1.0
|
m_max
|
float
|
Upper bound for each component mass in solar masses. |
3.0
|
d_min
|
float
|
Minimum luminosity distance in Mpc. |
0.0
|
d_max
|
float
|
Maximum luminosity distance in Mpc. |
5000.0
|
chi_max
|
float
|
Maximum dimensionless spin magnitude for both components. |
0.05
|
aligned_spins
|
bool
|
If |
True
|
gps_start
|
float
|
Lower bound for the coalescence-time prior. |
0.0
|
gps_end
|
float
|
Upper bound for the coalescence-time prior. |
1.0
|
total_mass_max
|
float | None
|
Optional upper bound on |
None
|
f_ref
|
float
|
Constant reference frequency assigned to every sample. |
20.0
|
lambda_max
|
float
|
Upper bound for the uniform tidal-deformability prior. |
3000.0
|
parameters
|
Mapping[str, Any] | None
|
Optional partial graph config merged onto the defaults. |
None
|
seed
|
int | None
|
Optional RNG seed forwarded to the graph simulator. |
None
|
Initialize the BNS simulator.
Attributes¶
property
¶
parameter_names: list[str]
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
source_type: str
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
load(input_path: str | Path) -> Array
classmethod
¶
from_config_file(config_path: str | Path, encoding: str = 'utf-8', **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a config file.
The CBC subclasses take physics-level constructor arguments rather than a
raw config mapping, so config-file and preset loading delegate to
:class:GraphSimulator and return a graph simulator directly.
classmethod
¶
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a packaged preset.
CBCSimulator(source_type: str = 'bbh', *, m_min: float = 5.0, m_max: float = 100.0, d_min: float = 0.0, d_max: float = 5000.0, chi_max: float = 0.99, aligned_spins: bool = False, gps_start: float = 0.0, gps_end: float = 1.0, total_mass_max: float | None = None, f_ref: float = 20.0, lambda_max: float | None = None, ordered_masses: bool = False, parameters: Mapping[str, Any] | None = None, seed: int | None = None)
Bases: _CBCGraphSimulator
Configurable graph-backed compact-binary population simulator.
Component masses are drawn uniformly and independently on [m_min, m_max]
(not reordered, matching the legacy CBCPriorSimulator); spins are
isotropic with magnitude uniform on [0, chi_max] (or aligned-only when
aligned_spins is set); distance is uniform in comoving volume; sky
position and orientation angles are isotropic. Pass parameters to
override the distribution of any node (see
:func:gwmock_pop.simulators._graph_config.deep_merge_graph_config).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
source_type
|
str
|
Routing key for downstream orchestration. Defaults to
|
'bbh'
|
m_min
|
float
|
Lower bound for each component mass in solar masses. |
5.0
|
m_max
|
float
|
Upper bound for each component mass in solar masses. |
100.0
|
d_min
|
float
|
Minimum luminosity distance in Mpc. |
0.0
|
d_max
|
float
|
Maximum luminosity distance in Mpc. |
5000.0
|
chi_max
|
float
|
Maximum dimensionless spin magnitude for both components. |
0.99
|
aligned_spins
|
bool
|
If |
False
|
gps_start
|
float
|
Lower bound for the coalescence-time prior. |
0.0
|
gps_end
|
float
|
Upper bound for the coalescence-time prior. |
1.0
|
total_mass_max
|
float | None
|
Optional upper bound on |
None
|
f_ref
|
float
|
Constant reference frequency assigned to every sample. |
20.0
|
lambda_max
|
float | None
|
Upper bound for the uniform tidal-deformability prior applied
to both components. |
None
|
ordered_masses
|
bool
|
If |
False
|
parameters
|
Mapping[str, Any] | None
|
Optional partial graph config merged onto the defaults. |
None
|
seed
|
int | None
|
Optional RNG seed forwarded to the graph simulator. |
None
|
Initialize the configurable CBC simulator.
Attributes¶
property
¶
parameter_names: list[str]
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
source_type: str
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
load(input_path: str | Path) -> Array
classmethod
¶
from_config_file(config_path: str | Path, encoding: str = 'utf-8', **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a config file.
The CBC subclasses take physics-level constructor arguments rather than a
raw config mapping, so config-file and preset loading delegate to
:class:GraphSimulator and return a graph simulator directly.
classmethod
¶
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a packaged preset.
GraphSimulator(config: dict[str, Any], source_type: str | None = None, **kwargs: Any)
Bases: RandomMixin, Simulator
Graph-based population simulator.
This simulator uses a probabilistic graphical model to generate populations. Parameters are defined in a configuration with dependencies, and the simulator executes sampling in topological order based on the dependency graph.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
dict[str, Any]
|
Configuration dictionary defining parameters and their sampling/transform rules. |
required |
**kwargs
|
Any
|
Additional arguments passed to parent class. |
{}
|
Note
source_type must be set before calling simulate(). Construction
without source_type is allowed (e.g. for builder patterns), but
simulate() raises :exc:ValueError if source_type is None
at call time. Pass source_type=<str> to the constructor to avoid
this.
Example
config = { ... "mass_1": { ... "sampler": { ... "function": "planck_tapered_broken_power_law_plus_two_peaks", ... "arguments": { ... "alpha_1": 1.72, ... "alpha_2": 4.51, ... "transition": 35.6, ... "minimum": 5.06, ... "maximum": 300.0, ... }, ... }, ... }, ... "mass_ratio": { ... "sampler": { ... "function": "planck_tapered_conditional_ratio_power_law", ... "arguments": {"denominator": "@mass_1"}, ... }, ... }, ... } simulator = GraphSimulator(config=config) population = simulator()
Initialize the graph-based simulator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
dict[str, Any]
|
Configuration dictionary with parameter definitions. |
required |
source_type
|
str | None
|
Logical source identifier for higher-level orchestration. |
None
|
**kwargs
|
Any
|
Additional arguments passed to parent class. |
{}
|
Attributes¶
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
parameter_names: list[str]
property
¶
source_type: str
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
load(input_path: str | Path) -> Array
classmethod
¶
from_config_file(config_path: str | Path, encoding: str = 'utf-8', **kwargs: Any) -> GraphSimulator
Create simulator from configuration file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config_path
|
str | Path
|
Path to YAML/TOML configuration file. |
required |
encoding
|
str
|
Encoding of the file. |
'utf-8'
|
**kwargs
|
Any
|
Additional arguments passed to init. |
{}
|
Returns:
| Type | Description |
|---|---|
GraphSimulator
|
Configured simulator instance. |
classmethod
¶
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator
Create a graph simulator from a packaged preset.
MixtureSimulator(simulators: Sequence[GWPopSimulator], weights: Sequence[float], *, seed: int | None = None)
Bases: RandomMixin, Simulator
Draw samples from a weighted mixture of GWPopSimulator components.
Initialize the mixture simulator.
Attributes¶
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
parameter_names: list[str]
Return the shared parameter names of the component simulators.
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
NSBHSimulator(*, bh_mass_min: float = 3.0, bh_mass_max: float = 50.0, ns_mass_min: float = 1.0, ns_mass_max: float = 3.0, d_min: float = 0.0, d_max: float = 5000.0, bh_chi_max: float = 1.0, ns_chi_max: float = 0.05, aligned_spins: bool = False, gps_start: float = 0.0, gps_end: float = 1.0, total_mass_max: float | None = None, f_ref: float = 20.0, ns_lambda_max: float = 3000.0, parameters: Mapping[str, Any] | None = None, seed: int | None = None)
Bases: _CBCGraphSimulator
Graph-backed neutron-star--black-hole population simulator.
Defaults to a black-hole primary on [bh_mass_min, bh_mass_max] solar
masses, a neutron-star secondary on [ns_mass_min, ns_mass_max],
component-specific isotropic spin bounds, zero primary tidal deformability,
uniform secondary tidal deformability, and source_type="nsbh".
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bh_mass_min
|
float
|
Lower bound for the black-hole primary mass. |
3.0
|
bh_mass_max
|
float
|
Upper bound for the black-hole primary mass. |
50.0
|
ns_mass_min
|
float
|
Lower bound for the neutron-star secondary mass. |
1.0
|
ns_mass_max
|
float
|
Upper bound for the neutron-star secondary mass. |
3.0
|
d_min
|
float
|
Minimum luminosity distance in Mpc. |
0.0
|
d_max
|
float
|
Maximum luminosity distance in Mpc. |
5000.0
|
bh_chi_max
|
float
|
Maximum dimensionless spin magnitude for the primary. |
1.0
|
ns_chi_max
|
float
|
Maximum dimensionless spin magnitude for the secondary. |
0.05
|
aligned_spins
|
bool
|
If |
False
|
gps_start
|
float
|
Lower bound for the coalescence-time prior. |
0.0
|
gps_end
|
float
|
Upper bound for the coalescence-time prior. |
1.0
|
total_mass_max
|
float | None
|
Optional upper bound on |
None
|
f_ref
|
float
|
Constant reference frequency assigned to every sample. |
20.0
|
ns_lambda_max
|
float
|
Upper bound for the secondary tidal-deformability prior. |
3000.0
|
parameters
|
Mapping[str, Any] | None
|
Optional partial graph config merged onto the defaults. |
None
|
seed
|
int | None
|
Optional RNG seed forwarded to the graph simulator. |
None
|
Initialize the NSBH simulator.
Attributes¶
property
¶
parameter_names: list[str]
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
source_type: str
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
load(input_path: str | Path) -> Array
classmethod
¶
from_config_file(config_path: str | Path, encoding: str = 'utf-8', **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a config file.
The CBC subclasses take physics-level constructor arguments rather than a
raw config mapping, so config-file and preset loading delegate to
:class:GraphSimulator and return a graph simulator directly.
classmethod
¶
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator
Build a plain :class:GraphSimulator from a packaged preset.
PoissonEventSampler(simulator: GWPopSimulator, rate_gpc3_yr: float, t_obs_yr: float, seed: int | None = None)
Bases: RandomMixin, Simulator
Wrap a GWPopSimulator and draw a Poisson-distributed event count.
Initialize the Poisson event sampler.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
simulator
|
GWPopSimulator
|
Wrapped simulator that generates per-event parameters. |
required |
rate_gpc3_yr
|
float
|
Volumetric merger rate factor used in the Poisson mean. |
required |
t_obs_yr
|
float
|
Observation time in years used in the Poisson mean. |
required |
seed
|
int | None
|
Optional seed for deterministic event-count draws. |
None
|
Attributes¶
property
¶
rng_manager: RNGManager
property
¶
rng_key_data: Array
Get the key data of the random number generator.
Returns:
| Type | Description |
|---|---|
Array
|
Key data of the random number generator. |
property
¶
mean_event_count: float
Return the Poisson mean rate_gpc3_yr * t_obs_yr.
Functions¶
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None
node(depends_on: list[str] | None = None) -> Callable
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]
save(output_path: str | Path, file_format: str | None = None, data: Mapping[str, Array] | Array | None = None, compression: str | None = None, metadata: dict[str, Any] | None = None) -> None
Save the simulated data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Path to save the file. |
required |
file_format
|
str | None
|
File format (npy, npz, csv, hdf5). If None, infers from extension. |
None
|
data
|
Mapping[str, Array] | Array | None
|
Data to save. If None, uses last simulated data. Mapping inputs
are converted to a 2D array with columns ordered by
|
None
|
compression
|
str | None
|
Optional compression setting for supported formats. For HDF5, this specifies the compression filter (e.g., "gzip"). For NPZ, any non-None value enables default zlib compression. |
None
|
metadata
|
dict[str, Any] | None
|
Optional metadata to store alongside the samples. |
None
|
Functions¶
coerce_to_numpy(record: Mapping[str, Any]) -> dict[str, Any]
Convert array-backed record values to NumPy arrays or Python scalars.
This helper is intended for consumer boundaries where gwmock-pop output
should no longer require a JAX runtime. Array-valued inputs are materialized
as numpy.ndarray values, while 0-D array scalars are unwrapped to native
Python scalars via :meth:numpy.ndarray.item.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
record
|
Mapping[str, Any]
|
Mapping of parameter names to array-like or scalar values. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A new mapping where JAX and NumPy values are converted to NumPy-backed |
dict[str, Any]
|
objects. Non-array values are passed through unchanged. |
validate_sample(sample: Mapping[str, Array]) -> list[str]
Return human-readable physical-consistency violations for a population sample.
The validator checks only the recognized parameters present in sample and
ignores extra keys. Mass-ordering (m1 >= m2) is enforced only for the short
mass_1/m1 and mass_2/m2 aliases; the detector_frame_mass_*
keys are checked for positivity only, as their ordering is guaranteed by
construction in the simulator pipeline.