Skip to content

CBC Simulators

cbc

Graph-backed compact-binary-coalescence population simulators.

These simulators express the CBC parameter priors as a config-driven :class:~gwmock_pop.simulators.graph.GraphSimulator graph rather than hard-coded distributions. Each class builds a default parameters graph from its physics-level constructor arguments and deep-merges a user-supplied parameters override, so the distribution of any single parameter can be swapped without subclassing. They satisfy the GWPopSimulator protocol via the inherited :class:GraphSimulator machinery.

The default output reproduces the legacy lightweight prior simulators: uniform component masses, isotropic spins and sky position, distance uniform in comoving volume, and a flat-LambdaCDM distance-to-redshift conversion.

Classes

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.

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.

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.

Functions