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.
Functions
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.
reset 
reset() -> None

Reset the simulator state.

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.

Functions