graph

Characteristic Graph (global) + View (per distribution profile)

This module defines the global characteristic registry and per-distribution views.

The CharacteristicRegistry maintains a directed graph over characteristic names (PDF, CDF, PPF, PMF, etc.) with nodes and edges guarded by constraints. Each distribution profile sees a filtered view of this graph based on its specific features (kind, dimension, etc.).

Core concepts:

Nodes: Characteristics (PDF, CDF, etc.) with presence and definitiveness rules
Edges: Unary computation methods between characteristics
Constraints: Rules that determine when nodes/edges are applicable
View: A filtered subgraph for a specific distribution
Definitive characteristics: Starting points for computations

class pysatl_core.distributions.registry.graph.CharacteristicRegistry[source]

Bases: object

Global characteristic graph with constraint-guarded nodes and edges.

This registry maintains the complete graph of characteristics and computation methods. It serves as a singleton that can be configured once and then used to create filtered views for specific distributions.

Invariants (enforced per view): 1. The subgraph induced by definitive characteristics is strongly connected 2. Every non-definitive characteristic is reachable from at least one definitive 3. No path exists from any non-definitive characteristic to any definitive

Return type:: Self

add_characteristic(name, is_definitive, presence_constraint=None, definitive_constraint=None)[source]

Declare a characteristic with presence and optional definitiveness rules.

Parameters:

name (GenericCharacteristicName)
is_definitive (bool)
presence_constraint (GraphPrimitiveConstraint | None)
definitive_constraint (GraphPrimitiveConstraint | None)

Return type:

None

add_computation(method, label=DEFAULT_COMPUTATION_KEY, constraint=None)[source]

Add a unary computation edge between declared nodes.

Parameters:

method (ComputationMethod[Any, Any])
label (str)
constraint (GraphPrimitiveConstraint | None)

Return type:

None

view(distr)[source]

Create a filtered view for the given distribution.

Parameters:: distr (pysatl_core.distributions.distribution.Distribution)
Return type:: RegistryView

Notes

Nodes must be declared before adding computations
Only unary computations (1 source → 1 target) are supported
No invariant validation happens during mutation; validation occurs when creating a view with view()

__init__()[source]

Return type:: None

__copy__()[source]

Singleton copy returns the same instance.

Return type:: Self

__deepcopy__(memo)[source]

Singleton deepcopy returns the same instance.

Return type:: Self
Parameters:: memo (dict[Any, Any])

__reduce__()[source]

Ensure pickling preserves singleton semantics.

Return type:: tuple[type[Self], tuple]

add_computation(method, *, label='PySATL_default_computation', constraint=None)[source]

Add a labeled unary computation edge.

Parameters:

method (ComputationMethod) – Computation object with exactly one source and one target.
label (str, default DEFAULT_COMPUTATION_KEY) – Variant label for the edge.
constraint (GraphPrimitiveConstraint, optional) – Edge applicability constraint. If None, a pass-through constraint is used.

Raises:

ValueError – If method is not unary, or source/target nodes are not declared.

Return type:

None

Notes

Multiple edges with different labels can exist between the same nodes
The first matching edge for each label is kept when creating views

add_characteristic(name, is_definitive, *, presence_constraint=None, definitive_constraint=None)[source]

Declare a characteristic with presence and optional definitiveness rules.

Parameters:

name (str) – Characteristic name (e.g., “pdf”, “cdf”).
is_definitive (bool) – Whether this characteristic can serve as a starting point for computations.
presence_constraint (GraphPrimitiveConstraint, optional) – Constraint determining when this characteristic exists for a distribution.
definitive_constraint (GraphPrimitiveConstraint, optional) – Constraint determining when this characteristic is definitive. Ignored if is_definitive is False.

Return type:

None

Notes

If is_definitive is False but definitive_constraint is provided, a warning is issued and the constraint is ignored
Presence constraints are required; without one, the characteristic will never appear in any view

view(distr)[source]

Create a filtered view of the graph for the given distribution.

Parameters:: distr (Distribution) – Distribution profile to filter for.
Returns:: Filtered view containing only applicable nodes and edges.
Return type:: RegistryView

Notes

Filters edges by their constraints
Removes edges touching absent nodes
Computes definitive nodes from the remaining present nodes
Validates graph invariants

class pysatl_core.distributions.registry.graph.RegistryView(adj, definitive_nodes, present_nodes)[source]

Bases: object

Filtered view of the characteristic graph for a specific distribution.

This view contains only the nodes and edges applicable to a particular distribution profile, with all graph invariants validated.

Parameters:

adj (Mapping[src, Mapping[dst, Mapping[label, EdgeMeta]]]) – Filtered adjacency preserving label variants.
definitive_nodes (set of str) – Definitive characteristics in this view.
present_nodes (set of str) – All present characteristics in this view.

Raises:

GraphInvariantError – If any graph invariant is violated.

definitive_characteristics

Definitive characteristics for this distribution.

Type:: set of str

all_characteristics

All present characteristics for this distribution.

Type:: set of str

__init__(adj, definitive_nodes, present_nodes)[source]

Parameters:

adj (Mapping[GenericCharacteristicName, Mapping[GenericCharacteristicName, Mapping[str, EdgeMeta]]])
definitive_nodes (set[GenericCharacteristicName])
present_nodes (set[GenericCharacteristicName])

Return type:

None

property indefinitive_characteristics: set[GenericCharacteristicName]

Present but non-definitive characteristics.

Returns:: Characteristics that exist but are not definitive.
Return type:: set of str

successors(v)[source]

Get outgoing edges from a characteristic.

Parameters:: v (str) – Source characteristic.
Returns:: Destination → label → edge metadata.
Return type:: Mapping[str, Mapping[str, EdgeMeta]]

successors_nodes(v)[source]

Get directly reachable characteristics from v.

Parameters:: v (str) – Source characteristic.
Returns:: Characteristics directly reachable from v.
Return type:: set of str

predecessors(v)[source]

Get characteristics with edges to v.

Parameters:: v (str) – Destination characteristic.
Returns:: Characteristics that can reach v directly.
Return type:: set of str

variants(src, dst)[source]

Get all labeled edges between two characteristics.

Parameters:

src (str) – Edge endpoints.
dst (str) – Edge endpoints.

Returns:

Label → edge metadata mapping.

Return type:

Mapping[str, EdgeMeta]

find_path(src, dst, *, prefer_label=None)[source]

Find a computation path from src to dst using BFS.

Parameters:

src (str) – Source and destination characteristics.
dst (str) – Source and destination characteristics.
prefer_label (str, optional) – Preferred edge label to use when multiple options exist.

Returns:

List of computation methods forming the path, or None if no path exists.

Return type:

list of ComputationMethod or None

Notes

Label selection priority: 1. prefer_label if present 2. DEFAULT_COMPUTATION_KEY if present 3. Lexicographically smallest label