Skip to content

Graph Simulator

graph

Graph-based population simulator.

Classes

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
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.
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.
Methods:
from_target 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 source_type given here wins over the one the target declares.

 {}

Returns:

Type Description
GraphSimulator

Configured simulator instance.
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.

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.

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_catalogue 
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 .csv, .h5, or .hdf5 file.

 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 
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:gwmock_pop.provenance.run_metadata. Defaults to what the simulator's own generator reports.

 None
writer str | None

Import path of the code writing the file.

 None

Returns:

Type Description
dict[str, Any]

The record.

Functions: