flux_hopf_lib

Spine: qga — manuscript + pedagogical Python
Shared math: this repo — SoT for Hopf / quaternion / Hurwitz 24
Engine: qga_engine (scenes, Rust math) · qga_gpu (frame)
This repo: shared primitives. Not QGA book labs and not a GPU runtime.

Shared core library for the Hopf / flux / quaternion / conduit ecosystem (kinaar8340). Tagged qga and vqc so topic:qga includes the math core.

Version: 0.3.1 · Role: single source of truth for foundational math.

Hurwitz 24 and Hopf (convention)

q = (x₁, x₂, x₃, x₄) = (w, x, y, z). The 24 Hurwitz units are ±1, ±i, ±j, ±k (minus then plus on each axis), then (±1±i±j±k)/2 in itertools.product order (last index fastest). Cardinality 24 is a theorem. That listing order is a Software fact of this package (HURWITZ_UNITS, fixture hurwitz_units_v1).

Hopf map on those units is the Chapter 2 formula in hopf_map: y₁=2(x₁x₃+x₂x₄), y₂=2(x₁x₄−x₂x₃), y₃=x₁²+x₂²−x₃²−x₄². Unit input is not re-normalized by ‖y‖. Fixture hopf_hurwitz_v1. legacy_portal_map is not Hopf.

Specialized experiments, Gradio portals, and full model stacks stay in consumer repos. Consumers depend on this package, not on each other, for shared primitives.

Dependency direction

                    flux_hopf_lib  (core / SoT)
                           │
     ┌─────────┬───────────┼───────────┬──────────┬────────────┬──────────────┐
     ▼         ▼           ▼           ▼          ▼            ▼              ▼
  mystery     toe      vqc_proto      hfb     kingdom   vqc_sims_public  vqc_workbench
   HF ✓                HF ✓         HF ✓     HF ✓      (parent OAM suite)

• Allowed: from flux_hopf_lib…, optional sibling imports of specialized models only.
• Forbidden: sys.path into ../toe for survival/κ math; copy-pasted R residual / Hopf maps.

See docs/DEPENDENCIES.md, docs/ECOSYSTEM.md, and docs/VIZ.md (core Plotly/MPL vs WebGPU companion split).

Install

# Editable (local ecosystem development)
cd ~/Projects/flux_hopf_lib
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Optional torch quaternion helpers
pip install -e ".[torch]"

Consumer repos:

# Production / HF Spaces / paper reproduction
pip install flux-hopf-lib==0.3.0

# Local core development (editable)
pip install -e ../flux_hopf_lib

# requirements.txt / pyproject.toml / HF Space
flux-hopf-lib==0.3.0

• PyPI: https://pypi.org/project/flux-hopf-lib/
• Publishing: docs/PUBLISHING.md · CHANGELOG.md

Recommended import style

Keep the namespace flat and predictable:

from flux_hopf_lib import PHI, R_RESIDUAL, E_INV2, DEFAULT_KAPPA
from flux_hopf_lib.quaternion import Quaternion, small_rotor, q_mult
from flux_hopf_lib.hopf import (
    hopf_map,
    hopf_map_from_angles,
    sample_fiber_family,
    stereographic_project,
    toroidal_hopfion_director,
    wg_from_base,
)
from flux_hopf_lib.flux import FluxLatticeConfig, FluxFlywheel, gaussian_defect
from flux_hopf_lib.simulation import (
    steps_for_lambda_t,
    evolve_gauged_twist_survival,
    simulate_twist_pde_survival,
    compare_to_analogs,
    zero_mode_survival_continuous,
)

# Optional visualizations (pip install 'flux-hopf-lib[viz]')
# from flux_hopf_lib.hopf.viz import (
#     plot_hopf_fibers_stereographic,
#     plot_hopf_fibers_dashboard,      # HF-safe 2×2 Plotly
#     plot_hopf_s2_fiber_explorer,    # S² base picker
#     create_plotly_fiber_animation,  # Play/Pause frames
# )
# Geometry export for a future WebGPU companion (no viz deps):
# from flux_hopf_lib.hopf import export_fiber_curves
from flux_hopf_lib.conduit import (
    ConduitConfig,
    GoldenAngleMixin,
    GaugePointerMixin,
    apply_golden_angle_increment,
)
from flux_hopf_lib.utils import cartesian_grid, laplacian_fft

Leaf repos may keep thin re-export shims for one release cycle (toe.relaxation_survival, hfb.hopf, orbital_braille.quaternion_codec) so old imports keep working while you migrate.

Package layout

src/flux_hopf_lib/
  constants.py          # φ, e, π, R residual, κ defaults, W_g lock
  quaternion/           # Quaternion, q_mult, rotors, encode_shard (+ torch_ops)
  hopf/                 # maps, fibers, stereographic, hopfions, invariants, viz
  flux/                 # FluxLatticeConfig, gauge steps, defect densities
  simulation/           # λt survival, twist PDE, mean-mode ODE, κ sweeps
  conduit/              # ConduitConfig, GoldenAngleMixin, GaugePointerMixin
  utils/                # cartesian/polar grids, FFT Laplacian
examples/
  quickstart.py
  consumer_mixin_pattern.py
  hopf_viz_demo.py      # requires [viz]

Quick start

python examples/quickstart.py

from flux_hopf_lib.simulation import steps_for_lambda_t, evolve_gauged_twist_survival

n = steps_for_lambda_t(lambda_t_target=2.0, kappa=0.85, dt=0.001)
out = evolve_gauged_twist_survival(n_steps=n, n_identities=32, seed=42)
print(out["identity_survival"])

What belongs where

Migration status

Details: docs/MIGRATION.md.

Development workflow

1. Change foundational math only in this repo.
2. Run pytest and python examples/quickstart.py.
3. Update CHANGELOG.md; bump version in pyproject.toml + __init__.py.
4. Tag a release (v0.1.x / v0.2.0); CI publishes via Trusted Publishing.
5. Consumers: pip install -e ../flux_hopf_lib while iterating; pin ==0.1.0 (PyPI) or @v0.1.0 (git) for HF / papers.

Tests

pip install -e ".[dev]"
pytest

License

MIT — see LICENSE. This is a copyright license only. It does not license U.S. Provisional Application 63/913,110. See PATENTS.md.

X: @kinaar8340

Ecosystem links