Skip to content

Simulators

simulators

Simulator classes.

Classes

BBHSimulator 

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 True, populate only the z spin components.

 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 mass_1 + mass_2.

 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
parameter_names property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
source_type property 
source_type: str

Get the logical source type.

Returns:

Type Description
str

Source type string.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.
from_config_file 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.

from_preset classmethod 
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator

Build a plain :class:GraphSimulator from a packaged preset.

reset 
reset() -> None

Reset the simulator state.

BNSSimulator 

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, populate only the z spin components.

 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 mass_1 + mass_2.

 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
parameter_names property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
source_type property 
source_type: str

Get the logical source type.

Returns:

Type Description
str

Source type string.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.
from_config_file 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.

from_preset classmethod 
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator

Build a plain :class:GraphSimulator from a packaged preset.

reset 
reset() -> None

Reset the simulator state.

CBCSimulator 

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".

 '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 True, populate only the z spin components.

 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 mass_1 + mass_2.

 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 (default) sets both to zero.

 None
ordered_masses bool

If True, enforce mass_1 >= mass_2 per sample.

 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
parameter_names property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
source_type property 
source_type: str

Get the logical source type.

Returns:

Type Description
str

Source type string.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.
from_config_file 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.

from_preset classmethod 
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator

Build a plain :class:GraphSimulator from a packaged preset.

reset 
reset() -> None

Reset the simulator state.

NSBHSimulator 

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 True, populate only the z spin components.

 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 mass_1 + mass_2.

 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
parameter_names property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
source_type property 
source_type: str

Get the logical source type.

Returns:

Type Description
str

Source type string.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.
from_config_file 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.

from_preset classmethod 
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator

Build a plain :class:GraphSimulator from a packaged preset.

reset 
reset() -> None

Reset the simulator state.

GraphSimulator 

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
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
parameter_names property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
source_type property 
source_type: str

Get the logical source type.

Returns:

Type Description
str

Source type string.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.
from_config_file 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.
from_preset classmethod 
from_preset(preset_name: str, **kwargs: Any) -> GraphSimulator

Create a graph simulator from a packaged preset.

reset 
reset() -> None

Reset the simulator state.

MixtureSimulator 

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
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
parameter_names property 
parameter_names: list[str]

Return the shared parameter names of the component simulators.

source_type property 
source_type: str

Return the shared source type of the component simulators.

Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.

PoissonEventSampler 

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
rng_manager property 
rng_manager: RNGManager

Get the RNG manager.

Returns:

Type Description
RNGManager

RNG manager.
rng_key_data 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.
parameter_names property 
parameter_names: list[str]

Return the wrapped simulator parameter names.

source_type property 
source_type: str

Return the wrapped simulator source type.

mean_event_count property 
mean_event_count: float

Return the Poisson mean rate_gpc3_yr * t_obs_yr.

Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.

Simulator 

Simulator(*args: object, **kwargs: object)

Bases: ABC

Abstract base class for generating simulated populations.

Initialize the instance.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}
Attributes
parameter_names abstractmethod property 
parameter_names: list[str]

Get the names of the parameters.

Returns:

Type Description
list[str]

List of parameter names.
Functions
register_node 
register_node(name: str, func: Callable, depends_on: list[str] | None = None) -> None

Register a node function on this instance.

Parameters:

Name Type Description Default
name str

Parameter name.

 required
func Callable

A function to simulate this parameter.

 required
depends_on list[str] | None

A list of dependent parameters.

 None
node 
node(depends_on: list[str] | None = None) -> Callable

Implement a decorator to bind a node to this instance.

Parameters:

Name Type Description Default
depends_on list[str] | None

A list of dependencies.

 None

Returns:

Type Description
Callable

A callable.
simulate 
simulate(*args: object, **kwargs: object) -> Mapping[str, Array]

Simulate a population of sources.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
**kwargs object

Keyword arguments.

 {}

Returns:

Type Description
Mapping[str, Array]

Mapping from parameter names to 1D arrays of length n_samples.
save 
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 parameter_names.

 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 
load(input_path: str | Path) -> Array

Load data from a file.

Parameters:

Name Type Description Default
input_path str | Path

Path to load the file from.

 required

Returns:

Type Description
Array

Loaded data as numpy array.