Skip to content

Binary Black Hole

bbh

Modules of binary black hole population simulators.

Classes

BBHSimulator 

BBHSimulator(*args: object, seed: int | None = None, **kwargs: object)

Bases: RandomMixin, Simulator

Base class for binary black hole population simulator.

Initialize the instance.

Parameters:

Name Type Description Default
*args object

Positional arguments.

 ()
seed int | None

Random seed for reproducibility.

 None
**kwargs object

Keyword arguments.

 {}
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.

Definition of the parameters:

  • detector_frame_mass_1: The mass of the first component object in the binary (in solar masses) in detector frame.
  • detector_frame_mass_2: The mass of the second component object in the binary (in solar masses) in the detector frame.
  • spin_1x: The x component of the first binary component's dimensionless spin.
  • spin_1y: The y component of the first binary component's dimensionless spin.
  • spin_1z: The z component of the first binary component's dimensionless spin.
  • spin_2x: The x component of the second binary component's dimensionless spin.
  • spin_2y: The y component of the second binary component's dimensionless spin.
  • spin_2z: The z component of the second binary component's dimensionless spin.
  • eccentricity: Eccentricity.
  • distance: Luminosity distance to the binary (in Mpc).
  • coa_phase: Coalescence phase of the binary (in rad).
  • inclination: Inclination (rad), defined as the angle between the orbital angular momentum L and the line-of-sight at the reference frequency.
  • theta_jn: The angle between the total angular momentum J and the line-of-sight.
  • long_asc_node: Longitude of ascending nodes axis (rad).
  • mean_per_ano: Mean anomaly of the periastron (rad).
  • coa_time: Coalescence time (s) is the time when a GW reaches the origin of a certain coordinate system.
  • right_ascension: Right ascension (rad).
  • declination: Declination (rad).
  • polarization_angle: Polarization angle (rad) in a certain coordinate system.
  • redshift: Redshift.
  • f_ref: The reference frequency that defines the spin components.

Returns:

Type Description
list[str]

List of parameter names.
source_type property 
source_type: str

Get the 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.