Metadata-Version: 2.5
Name: flux-hopf-lib
Version: 0.3.1
Summary: Shared core library for Hopf fibrations, quaternions, gauged flux lattices, conduits, and survival/relaxation probes
Project-URL: Homepage, https://github.com/kinaar8340/flux_hopf_lib
Project-URL: Repository, https://github.com/kinaar8340/flux_hopf_lib
Project-URL: Issues, https://github.com/kinaar8340/flux_hopf_lib/issues
Project-URL: Changelog, https://github.com/kinaar8340/flux_hopf_lib/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/kinaar8340/flux_hopf_lib#readme
Project-URL: PyPI, https://pypi.org/project/flux-hopf-lib/
Project-URL: Ecosystem, https://github.com/kinaar8340
Author: kinaar8340
License: MIT
License-File: LICENSE
Keywords: conduit,flux-lattice,gauge-dynamics,hopf-fibration,oam,quaternion,survival-probe,topological-defects
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Provides-Extra: all
Requires-Dist: matplotlib>=3.7; extra == 'all'
Requires-Dist: plotly>=5.0; extra == 'all'
Requires-Dist: pytest-cov>=4.0; extra == 'all'
Requires-Dist: pytest>=7.0; extra == 'all'
Requires-Dist: ruff>=0.4; extra == 'all'
Requires-Dist: torch>=2.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == 'torch'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.7; extra == 'viz'
Requires-Dist: plotly>=5.0; extra == 'viz'
Description-Content-Type: text/markdown

# flux_hopf_lib

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

[![PyPI](https://img.shields.io/pypi/v/flux-hopf-lib)](https://pypi.org/project/flux-hopf-lib/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flux-hopf-lib)](https://pypi.org/project/flux-hopf-lib/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![CI](https://github.com/kinaar8340/flux_hopf_lib/actions/workflows/ci.yml/badge.svg)](https://github.com/kinaar8340/flux_hopf_lib/actions/workflows/ci.yml)

**Shared core library** for the Hopf / flux / quaternion / conduit ecosystem
([kinaar8340](https://github.com/kinaar8340)). Tagged `qga` and `vqc` so
[topic:qga](https://github.com/kinaar8340?tab=repositories&q=topic:qga) includes the math core.

**Version:** [`0.3.1`](https://github.com/kinaar8340/flux_hopf_lib) · **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

```text
                    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/DEPENDENCIES.md), [docs/ECOSYSTEM.md](docs/ECOSYSTEM.md),
and [docs/VIZ.md](docs/VIZ.md) (core Plotly/MPL vs WebGPU companion split).

## Install

```bash
# 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:**

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

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

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

- PyPI: https://pypi.org/project/flux-hopf-lib/
- Publishing: [docs/PUBLISHING.md](docs/PUBLISHING.md) · [CHANGELOG.md](CHANGELOG.md)

## Recommended import style

Keep the namespace **flat and predictable**:

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

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

```bash
python examples/quickstart.py
```

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

| Object | SoT | Not here |
|--------|-----|----------|
| `hopf_map` (Ch. 2 classical), `Quaternion` | this package | a second formula in a visual crate |
| `HURWITZ_UNITS` | this package | a GPU constant; a second listing in `qga-math` |
| QGA book labs (`candidate_adjacency`, topograph classifier) | [`qga/lib`](https://github.com/kinaar8340/qga) | this package |
| `W_g = 350/π` | Hypothesis; attack in [`op5`](https://github.com/kinaar8340/op5) | a lattice theorem |

| In **flux_hopf_lib** (core) | In **leaf** repos |
|-----------------------------|-------------------|
| Quaternion / Rodrigues | Full `RubikConeConduit` + training (toe) |
| Hopf maps, hopfions, linking | VQC/OAM encoding, ICA demixing (vqc_*) |
| Flux lattice / gauge / defects | Analog-gravity / warp solvers (hfb) |
| λt survival, twist PDE, κ sweeps | Gradio / Streamlit UIs (kingdom, HF Spaces) |
| ConduitConfig + mixins | HF Space storytelling, papers, Ray demos |
| Grids / FFT Laplacian | |

## Migration status

| Repo | Status |
|------|--------|
| **mystery** | ✓ `flux_hopf_lib.simulation` (no toe path hacks for survival) |
| **toe** | ✓ `relaxation_survival` shim; golden-angle + GaugePointerMixin |
| **vqc_proto** | ✓ Quaternion codec re-export |
| **vqc_sims_public** | ✓ `quaternion_core` re-export |
| **hfb** | ✓ hopf / grid / defect shims |
| **kingdom** | ✓ constants + hopf + quaternion for portal demos |

Details: [docs/MIGRATION.md](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](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

```bash
pip install -e ".[dev]"
pytest
```

## License

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

X: [@kinaar8340](https://x.com/kinaar8340)

## Ecosystem links

| Repo | URL |
|------|-----|
| flux_hopf_lib | https://github.com/kinaar8340/flux_hopf_lib |
| toe | https://github.com/kinaar8340/toe |
| mystery | https://github.com/kinaar8340/mystery |
| hfb | https://github.com/kinaar8340/hfb |
| vqc_proto | https://github.com/kinaar8340/vqc_proto |
| vqc_sims_public | https://github.com/kinaar8340/vqc_sims_public |
| kingdom_come | https://github.com/kinaar8340/kingdom_come |
