CBC Simulators
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(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
Methods:¶
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_catalogue(output_path: str | Path, *, data: Mapping[str, Array] | None = None, provenance: Mapping[str, Any] | None = None, compression: str | None = None) -> None
Persist a simulated population as a named-column catalogue.
Persistence goes through :func:~gwmock_pop.loaders.write_population_catalogue,
the one writer in this package, so a file written here is one the
package's own readers accept and it carries the same provenance record
as a file written by the CLI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Destination |
required |
data
|
Mapping[str, Array] | None
|
Population to write. Defaults to the last simulated population. |
None
|
provenance
|
Mapping[str, Any] | None
|
Record to store with the catalogue. Defaults to the one this simulator can describe itself with. |
None
|
compression
|
str | None
|
Optional HDF5 compression filter. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no population is given and none has been simulated. |
TypeError
|
If the population is not a mapping of named columns. |
build_provenance_record(*, n_samples: int, file_format: str, parameter_names: Sequence[str] | None = None, run: Mapping[str, Any] | None = None, writer: str | None = None) -> dict[str, Any]
Build the provenance record describing a catalogue from this simulator.
This is the single record builder behind both persistence paths: the CLI
calls it with the run settings it resolved, and :meth:save_catalogue
calls it with what the simulator knows about itself. Neither assembles a
record of its own, so the two cannot drift apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_samples
|
int
|
Number of rows being written. |
required |
file_format
|
str
|
Format the catalogue is written in. |
required |
parameter_names
|
Sequence[str] | None
|
Column names in output order. Defaults to this simulator's parameter names. |
None
|
run
|
Mapping[str, Any] | None
|
Block from :func: |
None
|
writer
|
str | None
|
Import path of the code writing the file. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The record. |
classmethod
¶
from_target(target: SimulationTarget, **kwargs: Any) -> GraphSimulator
Create a simulator from an already-resolved simulation target.
The target is kept, so the simulator can describe the configuration it was built from when a catalogue is written.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
SimulationTarget
|
Resolved preset or configuration file. |
required |
**kwargs
|
Any
|
Additional arguments passed to init. A |
{}
|
Returns:
| Type | Description |
|---|---|
GraphSimulator
|
Configured simulator instance. |
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.
reset() -> None
Reset the simulator state.
The random stream is rewound to the seed the simulator was built with, including a seed that was drawn rather than requested. Anything else would make the state after a reset undescribable.
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
Methods:¶
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_catalogue(output_path: str | Path, *, data: Mapping[str, Array] | None = None, provenance: Mapping[str, Any] | None = None, compression: str | None = None) -> None
Persist a simulated population as a named-column catalogue.
Persistence goes through :func:~gwmock_pop.loaders.write_population_catalogue,
the one writer in this package, so a file written here is one the
package's own readers accept and it carries the same provenance record
as a file written by the CLI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Destination |
required |
data
|
Mapping[str, Array] | None
|
Population to write. Defaults to the last simulated population. |
None
|
provenance
|
Mapping[str, Any] | None
|
Record to store with the catalogue. Defaults to the one this simulator can describe itself with. |
None
|
compression
|
str | None
|
Optional HDF5 compression filter. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no population is given and none has been simulated. |
TypeError
|
If the population is not a mapping of named columns. |
build_provenance_record(*, n_samples: int, file_format: str, parameter_names: Sequence[str] | None = None, run: Mapping[str, Any] | None = None, writer: str | None = None) -> dict[str, Any]
Build the provenance record describing a catalogue from this simulator.
This is the single record builder behind both persistence paths: the CLI
calls it with the run settings it resolved, and :meth:save_catalogue
calls it with what the simulator knows about itself. Neither assembles a
record of its own, so the two cannot drift apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_samples
|
int
|
Number of rows being written. |
required |
file_format
|
str
|
Format the catalogue is written in. |
required |
parameter_names
|
Sequence[str] | None
|
Column names in output order. Defaults to this simulator's parameter names. |
None
|
run
|
Mapping[str, Any] | None
|
Block from :func: |
None
|
writer
|
str | None
|
Import path of the code writing the file. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The record. |
classmethod
¶
from_target(target: SimulationTarget, **kwargs: Any) -> GraphSimulator
Create a simulator from an already-resolved simulation target.
The target is kept, so the simulator can describe the configuration it was built from when a catalogue is written.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
SimulationTarget
|
Resolved preset or configuration file. |
required |
**kwargs
|
Any
|
Additional arguments passed to init. A |
{}
|
Returns:
| Type | Description |
|---|---|
GraphSimulator
|
Configured simulator instance. |
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.
reset() -> None
Reset the simulator state.
The random stream is rewound to the seed the simulator was built with, including a seed that was drawn rather than requested. Anything else would make the state after a reset undescribable.
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
Methods:¶
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_catalogue(output_path: str | Path, *, data: Mapping[str, Array] | None = None, provenance: Mapping[str, Any] | None = None, compression: str | None = None) -> None
Persist a simulated population as a named-column catalogue.
Persistence goes through :func:~gwmock_pop.loaders.write_population_catalogue,
the one writer in this package, so a file written here is one the
package's own readers accept and it carries the same provenance record
as a file written by the CLI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Destination |
required |
data
|
Mapping[str, Array] | None
|
Population to write. Defaults to the last simulated population. |
None
|
provenance
|
Mapping[str, Any] | None
|
Record to store with the catalogue. Defaults to the one this simulator can describe itself with. |
None
|
compression
|
str | None
|
Optional HDF5 compression filter. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no population is given and none has been simulated. |
TypeError
|
If the population is not a mapping of named columns. |
build_provenance_record(*, n_samples: int, file_format: str, parameter_names: Sequence[str] | None = None, run: Mapping[str, Any] | None = None, writer: str | None = None) -> dict[str, Any]
Build the provenance record describing a catalogue from this simulator.
This is the single record builder behind both persistence paths: the CLI
calls it with the run settings it resolved, and :meth:save_catalogue
calls it with what the simulator knows about itself. Neither assembles a
record of its own, so the two cannot drift apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_samples
|
int
|
Number of rows being written. |
required |
file_format
|
str
|
Format the catalogue is written in. |
required |
parameter_names
|
Sequence[str] | None
|
Column names in output order. Defaults to this simulator's parameter names. |
None
|
run
|
Mapping[str, Any] | None
|
Block from :func: |
None
|
writer
|
str | None
|
Import path of the code writing the file. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The record. |
classmethod
¶
from_target(target: SimulationTarget, **kwargs: Any) -> GraphSimulator
Create a simulator from an already-resolved simulation target.
The target is kept, so the simulator can describe the configuration it was built from when a catalogue is written.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
SimulationTarget
|
Resolved preset or configuration file. |
required |
**kwargs
|
Any
|
Additional arguments passed to init. A |
{}
|
Returns:
| Type | Description |
|---|---|
GraphSimulator
|
Configured simulator instance. |
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.
reset() -> None
Reset the simulator state.
The random stream is rewound to the seed the simulator was built with, including a seed that was drawn rather than requested. Anything else would make the state after a reset undescribable.
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
Methods:¶
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_catalogue(output_path: str | Path, *, data: Mapping[str, Array] | None = None, provenance: Mapping[str, Any] | None = None, compression: str | None = None) -> None
Persist a simulated population as a named-column catalogue.
Persistence goes through :func:~gwmock_pop.loaders.write_population_catalogue,
the one writer in this package, so a file written here is one the
package's own readers accept and it carries the same provenance record
as a file written by the CLI.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
output_path
|
str | Path
|
Destination |
required |
data
|
Mapping[str, Array] | None
|
Population to write. Defaults to the last simulated population. |
None
|
provenance
|
Mapping[str, Any] | None
|
Record to store with the catalogue. Defaults to the one this simulator can describe itself with. |
None
|
compression
|
str | None
|
Optional HDF5 compression filter. |
None
|
Raises:
| Type | Description |
|---|---|
ValueError
|
If no population is given and none has been simulated. |
TypeError
|
If the population is not a mapping of named columns. |
build_provenance_record(*, n_samples: int, file_format: str, parameter_names: Sequence[str] | None = None, run: Mapping[str, Any] | None = None, writer: str | None = None) -> dict[str, Any]
Build the provenance record describing a catalogue from this simulator.
This is the single record builder behind both persistence paths: the CLI
calls it with the run settings it resolved, and :meth:save_catalogue
calls it with what the simulator knows about itself. Neither assembles a
record of its own, so the two cannot drift apart.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_samples
|
int
|
Number of rows being written. |
required |
file_format
|
str
|
Format the catalogue is written in. |
required |
parameter_names
|
Sequence[str] | None
|
Column names in output order. Defaults to this simulator's parameter names. |
None
|
run
|
Mapping[str, Any] | None
|
Block from :func: |
None
|
writer
|
str | None
|
Import path of the code writing the file. |
None
|
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The record. |
classmethod
¶
from_target(target: SimulationTarget, **kwargs: Any) -> GraphSimulator
Create a simulator from an already-resolved simulation target.
The target is kept, so the simulator can describe the configuration it was built from when a catalogue is written.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target
|
SimulationTarget
|
Resolved preset or configuration file. |
required |
**kwargs
|
Any
|
Additional arguments passed to init. A |
{}
|
Returns:
| Type | Description |
|---|---|
GraphSimulator
|
Configured simulator instance. |
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.
reset() -> None
Reset the simulator state.
The random stream is rewound to the seed the simulator was built with, including a seed that was drawn rather than requested. Anything else would make the state after a reset undescribable.