engine
graph_generators.engine
Generic eager procedure engine for TVBO graph generators.
Interprets the symbolic procedure: block of a curated GraphGenerator YAML — an ordered DAG of named intermediates plus output: expressions — and evaluates it once, at Network load time, in numpy, producing a concrete adjacency matrix. This is the engine that replaces the deleted per-generator Python materialisers (builtins.py): a generator is now pure YAML (its procedure: block) and this one engine is its numpy/eager interpreter.
See dev/GenericProcedureEngine.md for the full design.
Eager evaluation uses a restricted eval over a fixed numpy primitive namespace (__builtins__ stripped): the procedure’s array expressions use ordinary Python operator / indexing / keyword-argument semantics on numpy arrays — exactly the syntax the curated procedures are written in (sample(dist, shape=(n, n), seed=seed), M[M != 0], Uniform(0, 1)). The procedure YAMLs are trusted, curated database artefacts, never user input. The codegen mode — emitting the same primitive set into jax / julia source via the printer tables in tvbo/codegen/code.py — is deferred (Stage 3).
RNG contract (GenericProcedureEngine.md §4)
A generator with a fixed seed is deterministic within numpy. Any seed offsets a procedure needs (e.g. seed for the weights, seed + 1 for the sparsity mask) are written explicitly in the procedure: so every backend derives sub-streams the same structural way. Cross-backend bit-identical sampling is not guaranteed (numpy PCG64 ≠ jax Threefry); within-backend reproducibility and statistical equivalence are. A missing seed defaults to 0 so seed + 1 stays well-defined and reproducible.
Functions
| Name | Description |
|---|---|
| load_matrix | Resolve source (IRI / path / bare DB name) into a 2-D adjacency matrix. |
| maslov_sneppen | Degree-preserving edge-swap null model (Maslov–Sneppen) on a weighted matrix. |
| materialize | Evaluate a procedure: block to {weights[, lengths, node_parameters]}. |
| nonzero_positions | Row-major (i, j) indices of the non-zero entries of M. |
| permute | Random permutation of arr (reproducible for a fixed seed). |
| require | Declarative guard usable in a procedure step; raises if condition is false. |
| run_generator | Materialise a curated generator by name from its YAML procedure: block. |
| sample | Sample shape values from a distribution (LinkML / inline / None→Normal). |
| scatter | Return a copy of base with values written at positions. |
load_matrix
graph_generators.engine.load_matrix(source)Resolve source (IRI / path / bare DB name) into a 2-D adjacency matrix.
maslov_sneppen
graph_generators.engine.maslov_sneppen(M, seed=None, n_swaps_per_edge=10)Degree-preserving edge-swap null model (Maslov–Sneppen) on a weighted matrix.
A reusable graph primitive (not generator-specific Python): repeatedly swaps two directed edges (i→j), (k→l) to (i→l), (k→j) when the targets are free, preserving per-row out-degree while rerandomising topology; weights ride along with their edges.
materialize
graph_generators.engine.materialize(
procedure,
params,
seed=None,
declared_params=None,
)Evaluate a procedure: block to {weights[, lengths, node_parameters]}.
Parameters
procedure : dict The generator’s procedure block: {steps: [{name, equation.rhs}], output: {weights: {equation.rhs}, ...}}. params : dict Concrete parameter values (n, sparsity, source, weight_distribution, …) supplied by the GraphGenerator. seed : int | None Fallback seed when params carries none (defaults to 0 so seed arithmetic in the procedure stays well-defined and reproducible). declared_params : Mapping[str, dict] | Iterable[str] | None The generator’s declared parameters. Any not present in params are bound so the procedure resolves them to a default rather than NameError: to the parameter’s default value when declared_params is a mapping of specs (e.g. preserve → binary_mask), otherwise to None (e.g. an optional weight_distribution → standard Normal).
nonzero_positions
graph_generators.engine.nonzero_positions(M)Row-major (i, j) indices of the non-zero entries of M.
Order matches numpy boolean extraction M[M != 0], so values extracted that way scatter back to the same positions.
permute
graph_generators.engine.permute(arr, seed=None)Random permutation of arr (reproducible for a fixed seed).
require
graph_generators.engine.require(condition, message)Declarative guard usable in a procedure step; raises if condition is false.
run_generator
graph_generators.engine.run_generator(name, params, seed=None)Materialise a curated generator by name from its YAML procedure: block.
Convenience entry point for scripts/notebooks (e.g. building a shuffled-SC control). Network.resolve() uses the same engine internally.
sample
graph_generators.engine.sample(dist, shape=None, seed=None)Sample shape values from a distribution (LinkML / inline / None→Normal).
scatter
graph_generators.engine.scatter(base, positions, values)Return a copy of base with values written at positions.