gwkokab.parameters

Canonical parameter names and the relation graph that connects them.

Parameters is the single source of truth for how a gravitational-wave source parameter is spelled on disk and in configuration files; it is imported almost everywhere as from gwkokab.parameters import Parameters as P.

RelationMesh turns the closed-form maps in gwkokab.utils.transformations into a rule graph over those names, so that given whichever parameters a dataset happens to carry, every reachable parameter can be derived by forward chaining. default_relation_mesh() assembles the standard rule set – mass relations, source/detector frame conversions, spin projections and the redshift/luminosity-distance pair – and is what backs the --derive-parameters flag of the synthetic-data CLIs.

Classes

Parameters	Enumeration of common parameter names used in GWKokab.
RelationMesh	A rule graph over gravitational-wave parameters.

Functions

default_relation_mesh(→ RelationMesh)

Build the default mesh of common gravitational-wave parameter relations.

Module Contents

class gwkokab.parameters.Parameters

Bases: str, enum.Enum

Enumeration of common parameter names used in GWKokab.

Each member’s value is the string used for the parameter in data files, JSON configuration and column headers. The enum subclasses str, and __eq__()/__hash__() are specialised so a member compares and hashes equal to its own value – Parameters.REDSHIFT == "redshift" is True, and a member and its string spelling index the same dictionary entry.

Initialize self. See help(type(self)) for accurate signature.

CHIRP_MASS = 'chirp_mass'

CHIRP_MASS_DETECTOR = 'chirp_mass_detector'

CHIRP_MASS_SOURCE = 'chirp_mass_source'

CHI_1 = 'chi_1'

CHI_2 = 'chi_2'

CHI_MINUS = 'chiminus'

COS_IOTA = 'cos_iota'

COS_TILT_1 = 'cos_tilt_1'

COS_TILT_2 = 'cos_tilt_2'

DELTA_M = 'delta_m'

DETECTION_TIME = 'detection_time'

ECCENTRICITY = 'eccentricity'

EFFECTIVE_SPIN = 'chi_eff'

LUMINOSITY_DISTANCE = 'luminosity_distance'

MASS_RATIO = 'mass_ratio'

MEAN_ANOMALY = 'mean_anomaly'

PHI_1 = 'phi_1'

PHI_12 = 'phi_12'

PHI_2 = 'phi_2'

PHI_ORB = 'phi_orb'

POLARIZATION_ANGLE = 'psi'

PRECESSING_SPIN = 'chi_p'

PRIMARY_MASS_DETECTED = 'mass_1'

PRIMARY_MASS_SOURCE = 'mass_1_source'

PRIMARY_SPIN_MAGNITUDE = 'a_1'

PRIMARY_SPIN_X = 'spin_1x'

PRIMARY_SPIN_Y = 'spin_1y'

PRIMARY_SPIN_Z = 'spin_1z'

REDSHIFT = 'redshift'

REDUCED_MASS = 'reduced_mass'

RIGHT_ASCENSION = 'ra'

SECONDARY_MASS_DETECTED = 'mass_2'

SECONDARY_MASS_SOURCE = 'mass_2_source'

SECONDARY_SPIN_MAGNITUDE = 'a_2'

SECONDARY_SPIN_X = 'spin_2x'

SECONDARY_SPIN_Y = 'spin_2y'

SECONDARY_SPIN_Z = 'spin_2z'

SIN_DECLINATION = 'dec'

SYMMETRIC_MASS_RATIO = 'symmetric_mass_ratio'

TOTAL_MASS = 'total_mass'

class gwkokab.parameters.RelationMesh

A rule graph over gravitational-wave parameters.

A rule is a triple (inputs, output, func): whenever every name in inputs is present, func is applied to their values and its result is stored under output. output may be a tuple, for functions returning several parameters at once (for instance m1_m2_chieff_chiminus_to_chi1z_chi2z()).

resolve() forward-chains the rules to a fixed point. Rules are kept in a work queue keyed on how many of their inputs are still missing, so each rule fires at most once and only after its inputs exist. Several rules may target the same output; the first one to fire wins and the rest become no-ops, which means the graph tolerates redundant paths (\(q\) from \(\eta\) or from \(m_1, m_2\)) without recomputing or contradicting itself.

Registered rules are held in rules, in insertion order.

See also

default_relation_mesh

Builds the mesh with the standard GW parameter relations.

add_rule(inputs: Tuple[Any, ...], output: Any, func: Callable)

Add a rule to the mesh.

Multiple rules can target the same output; during resolve() the first one whose inputs become available is the one that fires.

Parameters:

• inputs (Tuple[Any, ...]) – Parameter names func consumes, in call order.

• output (Any) – Parameter name func produces, or a tuple of names when func returns several values.

• func (Callable) – The map from the input values to the output value(s). It is called positionally, so it must accept len(inputs) positional arguments; a keyword-only function has to be wrapped before being registered.

Raises:

LoggedValueError – If func cannot accept len(inputs) positional arguments. Rules are applied positionally by resolve(), so registering a keyword-only function would otherwise fail only once that rule happened to fire.

derive_only(initial_state: Dict[Any, Any], targets: Set[Any]) → Dict[Any, Any]

Derive a chosen subset of parameters.

The full resolution is run first, so intermediate parameters needed to reach the targets are computed even though they are not returned.

Parameters:

• initial_state (Dict[Any, Any]) – The parameters that are already known.

• targets (Set[Any]) – The parameter names to return.

Returns:

The subset of the resolved state restricted to targets. Targets that could not be derived are silently absent.

Return type:

Dict[Any, Any]

resolve(initial_state: Dict[Any, Any]) → Dict[Any, Any]

Derive every parameter reachable from the given state.

Rules are fired by forward chaining until no further rule can be applied: a rule becomes eligible once all of its inputs are present, and is skipped if all of its outputs already are. Values already in initial_state are never overwritten.

Parameters:

initial_state (Dict[Any, Any]) – The parameters that are already known, keyed by Parameters member (or the equivalent string).

Returns:

A new dictionary containing the initial state plus every derivable parameter.

Return type:

Dict[Any, Any]

resolve_from_arrays(initial_state: numpy.ndarray, param_order: Tuple[Any, ...]) → Tuple[numpy.ndarray, Tuple[Any, ...]]

Resolve a 2-D array of samples whose columns are named by param_order.

Parameters:

• initial_state (np.ndarray) – Array of shape (n_samples, len(param_order)); column i holds the values of param_order[i].

• param_order (Tuple[Any, ...]) – Names of the columns of initial_state.

Returns:

The resolved samples and the names of their columns. Columns are sorted by name so the output order is deterministic and independent of param_order.

Return type:

Tuple[np.ndarray, Tuple[Any, …]]

rules = []

gwkokab.parameters.default_relation_mesh() → RelationMesh

Build the default mesh of common gravitational-wave parameter relations.

The registered rules cover mass combinations (total mass, mass ratio, chirp mass, symmetric mass ratio, reduced mass, \(\delta_m\)) and their inversions, source/detector frame conversions through redshift, spin magnitude and tilt from Cartesian components, the effective and precessing spins, and the redshift/luminosity-distance pair through the default cosmology.

Returns:

A freshly built mesh. The cosmology is captured at call time, so the mesh reflects the value of GWKOKAB_DEFAULT_COSMOLOGY as of that moment.

Return type:

RelationMesh