topographo

Executable tools for Topographical Graph Theory (TGT): reusable Cayley-Dickson and sedenion settlement math.

Topographo packages the reusable mathematical core behind the Occurrence Theory research notes. The package is intentionally narrower than the paper: it exposes the Cayley-Dickson and sedenion settlement computations needed for TGT without importing the interpretive narrative layer or printing audit output at import time.

In this package, TGT means the computational study of the sedenion zero-divisor crack as a topological, graph-like, and operator-theoretic object. The basic workflow is:

1. Build the 16-dimensional Cayley-Dickson algebra, the sedenions.
2. Enumerate or sample unit zero divisors, the distinguished singular locus called the crack.
3. Turn those events into multiplication operators and diagnostics.
4. Build finite graphs or channels whose edges/transitions are defined by multiplication, annihilation, metric transport, or settlement strain.
5. Check every result against validation gates before treating numerical output as evidence.

Sedenion Settlement Dynamics (SSD)

The central reusable object is Sedenion Settlement Dynamics. SSD studies the 16-dimensional Cayley-Dickson algebra, its unit zero-divisor locus, and operators built from left multiplication:

• L_x: left multiplication by an algebra element.
• M_x = L_x.T @ L_x: the metric operator measuring norm transport.
• T_x = L_{x^2} - L_x^2: the alternator used to express settlement strain.

These operators are enough to express the main graph-theoretic and channel computations. For example, a zero-divisor graph can use crack samples as vertices and connect two vertices when a multiplication-derived test such as rank(L_z @ L_w) or z * w == 0 detects annihilation. A settlement channel averages the operator action L_z.T @ X @ L_z over crack events.

Package layout

The reusable TGT/SSD layer is separated from the interpretive Occurrence Theory layer, which lives outside this package.

• topographo.core — one exact signed-basis specification for Cayley-Dickson multiplication, the derived NumPy structure tensor, multiplication operators, and mandatory validation gates. It does not know about Occurrence Theory, event/state language, or report formatting. f2_groups adds abstract finite group machinery over F_2 on the same terms: labels only, no Events.
• topographo.ssd — the sedenion-specific wrapper (SedenionAlgebra), small channel diagnostics, and layered exact-rational execution. Exact algebra, typed programs, raw execution, projective state, observers, and JSON codecs have separate modules; exact_machine remains as a compatibility facade. frames adds the Theory 068.02 mutual Operational-Frame machine (Native/Cyclic state, seed guard, and explicit round policies) without widening that facade.
• topographo.exceptional — the exceptional-algebra layer: the 27-dimensional Albert algebra J3(O) and its F4/G2 structure (Peirce/Hessian analysis, determinant invariants, anisotropy). Generic exceptional-algebra math, not Occurrence-Theory-specific.

Installation

pip install topographo

Requires Python 3.11+ and NumPy.

Minimal use

import numpy as np

from topographo.core import verify_gates
from topographo.ssd import SedenionAlgebra, average_metric_operator

assert all(result.passed for result in verify_gates())

algebra = SedenionAlgebra()
events = algebra.basis_zero_divisors()
mean_metric = average_metric_operator(algebra, events)

equilibrium_error = np.linalg.norm(mean_metric - np.eye(algebra.dim))

Sketch of a TGT zero-divisor graph

import numpy as np

from topographo.ssd import SedenionAlgebra

algebra = SedenionAlgebra()
events = algebra.basis_zero_divisors()
operators = [algebra.left_operator(z) for z in events]

graph = {i: [] for i in range(len(events))}
for i, left_i in enumerate(operators):
    for j, left_j in enumerate(operators):
        if i == j:
            continue
        if np.linalg.svd(left_i @ left_j, compute_uv=False)[-1] < 1e-9:
            graph[i].append(j)

For exact finite crack certificates, use SedenionAlgebra.basis_zero_divisors() to enumerate the full 84-point design. sample_crack(n) samples from that design with replacement and is intended for stochastic diagnostics, not machine-zero theorem gates. These dimension-16 helpers belong to SedenionAlgebra; generic CayleyDicksonAlgebra supplies only algebra and operator operations.

Exact ordered-event machine

The exact implementation has explicit responsibility boundaries:

• topographo.core.exact derives exact rational arithmetic from the canonical signed-basis table.
• topographo.ssd.exact adapts that backend to the pinned 061.11 coordinates.
• topographo.ssd.program defines typed, fully parenthesized expressions and immutable ordered event programs.
• topographo.ssd.machine performs repeated left action through one policy-driven transition engine; raw execution continues through zero.
• topographo.ssd.projective identifies every nonzero rational scaling, including negative scaling, and returns Annihilated for a zero product.
• topographo.ssd.observers derives measurements such as squared norm, while topographo.ssd.codec owns JSON encoding and exact replay validation.

topographo.ssd.exact_machine remains as a compatibility facade for the 0.4 API. Both exact and NumPy backends use the same algebraic specification. The map Phi(a, b) = (conj(a), b) converts 061.11 values to core coordinates; to_core_coordinates() and from_core_coordinates() provide the checked boundary.

from topographo.ssd import exact, machine, program, projective

initial = exact.basis(4)
events = program.Program([exact.basis(2), exact.basis(1)])
result = machine.run(initial, events)

assert result.state == exact.mul(
    exact.basis(1), exact.mul(exact.basis(2), initial)
)
assert projective.run_projective(initial, events).state == result.state

Mutual Operational-Frame machine

topographo.ssd.frames exposes the certified Theory 068.02 local machine: OperationalFrame with Native or Cyclic retained state, Event/edge predicates, seed guard, step / advance, and explicit serial or snapshot round_step policies. Presentation wiring is an experimental input; no global selector is inferred. See experiments/mutual-frames/ for the finite census audit.

from topographo.ssd import exact
from topographo.ssd.frames import Native, OperationalFrame, round_step

a = exact.add(exact.basis(1), exact.basis(10))
b = exact.add(exact.basis(4), exact.basis(15))
pair = (OperationalFrame(Native(a)), OperationalFrame(Native(b)))
result = round_step(pair, "AB")
assert result.complete

Futurator gate (Outcome / FIPS / seal)

Issue-005 Milestone F adds Outcome-aware ask without identifying Futurator with soft μ-or-bottom:

• topographo.ssd.outcome_runtime: ask(presentation, admissibility, enacted_law) returns ConstitutedOutcome or typed NonAdmission. Laws include NativeLeftAction, ProjectiveNativeLeftAction, and FipsClosure. Projective zero products constitute AnnihilationBoundary.
• topographo.ssd.fips_basic: certified finite table (84/56/336) and forced third — never ranked candidates.
• topographo.ssd.seal: classify / seal / resolve with a Theory-39 witness that public incidence ≠ sealed evaluator denotation.

Sealed Event frames use EventDenotation. Do not confuse them with OperationalFrame from Theory 068.02 (ssd.frames), which owns retained Native or Cyclic state and local round policies. Non-goals for this gate: Theory-41 effect runtime, physical SCE family guards, and optimizer/loss imports in the Outcome path (Fut≠μ|⊥).

from topographo.ssd.outcome_runtime import (
    Admissibility,
    Presentation,
    ProjectiveNativeLeftAction,
    ask,
)
from topographo.ssd.seal import seal
from topographo.ssd import exact

z = seal(exact.add(exact.basis(1), exact.basis(10)))
outcome = ask(Presentation((z, exact.one())), Admissibility(True), ProjectiveNativeLeftAction())

Validation gates

The validation gates are deliberately conservative. They catch sign-convention or tensor-indexing errors early: they certify that the implementation uses the intended Cayley-Dickson convention rather than acting as broad theorem tests. Any independent implementation should pass composition, antisymmetry, quadratic, and Moufang checks before its numerical certificates are trusted.

Links

• Source: https://github.com/TheSwanFactory/occurrence
• API documentation: https://theswanfactory.github.io/occurrence/

License

MIT.

Issue 005 Milestone T adapters (0.8.1)

• ssd.fips_adapter — hard FIPS index/tensor path and declared STE learning adapter (exact Fraction conformance stays in fips_basic / frames; no optimizer imports).
• ssd.structural_control — matched non-isomorphic degree-matched rewiring with C1–C5 checks.
• Training smoke lives in experiments/tlm_modular/ (torch optional; not a CI GPU job).

Single-step OT Born transport identity

topographo.ot_born_transport evaluates Theorem 4.3 for one real unit state x, one settlement operator K_a, and a canonical complex structure J, all in the same 16-dimensional presentation. For a non-annihilating transition it returns an immutable BornTransportResult containing

y = K_a x
x' = y / ||y||
cost = ||y||^2
tau = cost - 1
s(x') = (x' . e0)^2 + (x' . J e0)^2
A(z_a, x) = (z_a . x)^2 + ((J z_a) . x)^2,  z_a = K_a e0
residual = s(x') cost - A(z_a, x)

The transported state is an owned, non-writeable array. Before evaluating the quotient, the API checks the OT relations that force it: operator antisymmetry, J^2 = -I, complex-structure antisymmetry, unit event recovery, and compatibility of the transported spine axes with the Hermitian event axes, at tolerance 1e-10. Arbitrary same-shaped matrices are therefore rejected rather than returned with a scientifically meaningless residual.

Exact and numerical near-annihilation raise BornTransportAnnihilation with kind, squared cost, and squared-cost threshold; normalization is not attempted first. The default threshold is 1e-12. Passing annihilation_tolerance=0 requests exact-annihilation handling only. A nonzero transition whose positive squared cost underflows float64 is rejected rather than returned with a zero cost. Scaled nonunit states are rejected rather than silently normalized, because the reported strain is defined relative to a unit retained state.

from topographo import BornTransportAnnihilation, ot_born_transport

try:
    result = ot_born_transport(x, K_a, J)
except BornTransportAnnihilation as annihilation:
    print(annihilation.kind, annihilation.cost)
else:
    assert not result.transported_state.flags.writeable

This API is only the established single-step OT Born transport identity. It does not supply a normalized family of outcomes, sampling law, conditioning, projection or collapse, density-matrix evolution, POVM, path interference, or multistep measurement composition. In particular, it is not by itself a full generalized measurement law.

Fixed head (0.8.2)

topographo.ssd.fixed_head is a separate Issue-006 configured two-step Fixed projection/twirl adapter. Its Theory-27 readout_probability evaluates a scale-invariant quadratic effect for a word (b, a). It does not transport a single state with K_a, use the canonical J spine, report event strain, or implement the single-step identity above. Neither API is an alias or theorem claim for the other. See experiments/tlm_fixed_head/README.md for that adapter's capacity probe and physical fence.

Abstract F_2 groups (0.8.3)

topographo.core.f2_groups holds the label machinery the Issue-009 representation ablation is built on: the Fano plane PG(2,2), GL(3,2), GL(2,2)/AGL(2,2), the K4 edge action, and is_structure_preserving — the predicate that separates the 24 induced edge permutations from the 48 that merely preserve the opposite-edge matchings. certificate() re-derives every order, incidence count and relational law; assert_f2_group_laws() also checks the frozen digest.

It sits in core rather than ssd because it imports nothing beyond the standard library and knows nothing about Events, sedenions, or the SFP codec. experiments/sfp_representation/groups.py is the artifact driver for 009_artifacts/groups.json and holds no math of its own.