py_utils.core.rag Namespace Reference

Classes
class	Edge
class	ReactionAdmissibilityGraph

Detailed Description

core/rag.py — The Reaction Admissibility Graph  G = (V, E, nu, k)  (Layer 1).

Host-independent.  Implements the labelled multidigraph of
Ghoniem (2026), *A Generalized Graph-Based Cluster Dynamics Framework*,
Sections 2.2 and 3.2:

    G = (V, E, nu, k)

  V : admissible vertex set — cluster identifiers (chi, n, p, c)
  E : edge set — every admissible elementary reaction, each carrying a
      stoichiometric tuple nu and an :class:`EdgeClass`
  nu: the stoichiometric action (fixed per EdgeClass by EDGE_CLASS_SPEC)
  k : the rate-kernel library — calibration-specific, supplied by a host

The graph is *host-specific in (V, E)* and *calibration-specific in k*;
the algorithmic core (the graph walker) is host-independent.  This module
provides only the container and the admissibility logic — it declares no
populations, no edges and no kernels itself.  A host material builds a
RAG by declaring its populations, adding :class:`Edge` families, and
registering rate kernels.

Physically forbidden reactions are excluded at construction time: an edge
is admissible only if its endpoints are admissible and its stoichiometry
respects the host conservation laws.  Once built, the master equation is
the host-independent graph-walking accumulator applied edge-by-edge.