Metadata-Version: 2.4
Name: topographo
Version: 0.5.0
Summary: Reusable Cayley-Dickson and sedenion settlement math for Topographo.
Author: The Swan Factory
License-Expression: MIT
Project-URL: Homepage, https://github.com/TheSwanFactory/occurrence
Project-URL: Documentation, https://theswanfactory.github.io/occurrence/
Project-URL: Source, https://github.com/TheSwanFactory/occurrence
Project-URL: Issues, https://github.com/TheSwanFactory/occurrence/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Dynamic: license-file

# 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.
- `topographo.ssd` — the sedenion-specific wrapper (`SedenionAlgebra`) and small
  channel diagnostics used by the settlement audit, plus the exact-rational
  ordered-event machine (`exact_machine`).
- `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

```bash
pip install topographo
```

Requires Python 3.11+ and NumPy.

## Minimal use

```python
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

```python
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

`topographo.ssd.exact_machine` provides immutable 16-component rational values,
exact Cayley–Dickson arithmetic, explicitly parenthesized expressions, ordered
left-multiplication traces, replay validation, and projective ray execution.
It exposes the convention pinned by programming handoff 061.11 as an explicit
coordinate presentation of the same algebra used by the NumPy backend. 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. Both backends derive multiplication from the single exact integer
signed-basis table in `topographo.core`.

```python
from topographo.ssd import exact_machine as exact

initial = exact.basis(4)
result = exact.run(initial, [exact.basis(2), exact.basis(1)])

assert result.state == exact.mul(
    exact.basis(1), exact.mul(exact.basis(2), initial)
)
```

## 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.
