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: Computation methods from one-or-many sources to one target
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 computation edge between declared nodes.

Parameters:

method (ComputationMethod[Any, Any])
label (LabelName)
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 many-to-one computations (n sources → 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]

property declared_characteristics: set[GenericCharacteristicName]: Return declared registry characteristics.

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

Add a labeled computation edge.

Parameters:

method (ComputationMethod) – Computation object with one-or-many sources and one target.
label (LabelName, 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 has no sources, 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
Hyperedges are represented as projected edges from each source to target, while preserving one shared underlying computation method.

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

Computes present nodes for the distribution
Filters edges by node presence and edge constraints
Adds analytical self-loops from distribution analytical computations
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[LabelName, 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[LabelName, 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[LabelName, EdgeMeta]

analytical_variants(state)[source]

Get analytical self-loop variants for a characteristic.

Parameters:: state (str) – Characteristic name.
Returns:: Label → analytical loop metadata for state -> state.
Return type:: Mapping[LabelName, 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 (LabelName, 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 Any or None

Notes

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