Metadata-Version: 2.4
Name: scpn-mif-core
Version: 0.0.1
Summary: Deterministic phase synchronisation and hardware synthesis for high-beta pulsed magneto-inertial fusion plasmas
Author-email: Miroslav Sotek <protoscience@anulum.li>
License: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/anulum/scpn-mif-core
Project-URL: Documentation, https://anulum.github.io/scpn-mif-core/
Project-URL: Repository, https://github.com/anulum/scpn-mif-core
Project-URL: Bug Tracker, https://github.com/anulum/scpn-mif-core/issues
Project-URL: Discussions, https://github.com/anulum/scpn-mif-core/discussions
Project-URL: Changelog, https://github.com/anulum/scpn-mif-core/blob/main/CHANGELOG.md
Keywords: magneto-inertial-fusion,field-reversed-configuration,pulsed-plasma,kuramoto-synchronisation,hall-mhd,spiking-neural-network,systemverilog,formal-verification,ultrascale-plus,q8-8
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE.md
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.13
Requires-Dist: jax>=0.4.30
Requires-Dist: pydantic>=2.5
Provides-Extra: ecosystem
Requires-Dist: sc-neurocore-engine>=3.15.25; extra == "ecosystem"
Requires-Dist: scpn-phase-orchestrator>=0.8.0; extra == "ecosystem"
Requires-Dist: scpn-control>=0.20.7; extra == "ecosystem"
Requires-Dist: scpn-fusion-core>=3.9.10; extra == "ecosystem"
Requires-Dist: scpn-quantum-control>=0.9.11; extra == "ecosystem"
Provides-Extra: dev
Requires-Dist: ruff==0.15.17; extra == "dev"
Requires-Dist: mypy==2.1.0; extra == "dev"
Requires-Dist: bandit==1.9.4; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-benchmark>=4.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.5; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: maturin==1.14.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Requires-Dist: mkdocs-include-markdown-plugin>=6.2; extra == "docs"
Provides-Extra: formal
Requires-Dist: pysmt>=0.9; extra == "formal"
Requires-Dist: pyverilog>=1.3; extra == "formal"
Dynamic: license-file

<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
<!-- Commercial license available -->
<!-- © Concepts 1996–2026 Miroslav Šotek. All rights reserved. -->
<!-- © Code 2020–2026 Miroslav Šotek. All rights reserved. -->
<!-- ORCID: 0009-0009-3560-0851 -->
<!-- Contact: www.anulum.li | protoscience@anulum.li -->

# SCPN-MIF-CORE — Magneto-Inertial Fusion Core

<p align="center">
  <img src="docs/assets/scpn_mif_core_landing.png" width="100%" alt="SCPN-MIF-CORE — Magneto-Inertial Fusion pulsed-FRC kinematic and RTL hot-path laboratory">
</p>

[![License: AGPL-3.0-or-later](https://img.shields.io/badge/License-AGPL_3.0--or--later-blue.svg)](LICENSE)
[![CI](https://github.com/anulum/scpn-mif-core/actions/workflows/ci.yml/badge.svg)](https://github.com/anulum/scpn-mif-core/actions/workflows/ci.yml)
[![Coverage: 100%](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/anulum/scpn-mif-core/actions/workflows/ci.yml)
[![CodeQL](https://github.com/anulum/scpn-mif-core/actions/workflows/codeql.yml/badge.svg)](https://github.com/anulum/scpn-mif-core/actions/workflows/codeql.yml)
[![Docs](https://github.com/anulum/scpn-mif-core/actions/workflows/docs.yml/badge.svg)](https://github.com/anulum/scpn-mif-core/actions/workflows/docs.yml)
[![Pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit)](https://github.com/anulum/scpn-mif-core/actions/workflows/pre-commit.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/anulum/scpn-mif-core/badge)](https://securityscorecards.dev/viewer/?uri=github.com/anulum/scpn-mif-core)
[![Python: 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](pyproject.toml)
[![Rust: 1.85](https://img.shields.io/badge/rust-1.85-orange.svg)](rust-toolchain.toml)
[![Julia: 1.11](https://img.shields.io/badge/julia-1.11-purple.svg)](Project.toml)
[![Lean: 4.13](https://img.shields.io/badge/lean-4.13-darkgreen.svg)](lean-toolchain)
[![Go: 1.23](https://img.shields.io/badge/go-1.23-00ADD8.svg)](go.mod)
[![Status: pre-alpha](https://img.shields.io/badge/status-pre--alpha-red.svg)](#status)
[![DOI: pending](https://img.shields.io/badge/DOI-pending-yellow.svg)](CITATION.cff)

Deterministic phase synchronisation and hardware synthesis for high-beta
pulsed magneto-inertial fusion plasmas on field-reversed configurations.
Sub-50-nanosecond combinatorial sensor-to-actuator triggering on AMD Xilinx
UltraScale+ FPGAs.

> **Status:** pre-alpha with P1 local surfaces in progress. The current
> upstream-pending API set includes MIF-001 Doppler-Kuramoto synchronisation,
> MIF-002 moving-frame UPDE remap, MIF-003 merge-window monitoring, MIF-004
> pulsed-shot scheduling, MIF-005 capacitor-bank dynamics, MIF-006 AER
> spike-buffer decoding, MIF-007 B-dot ADC to Q8.8 spike-rate quantisation,
> MIF-009 Faraday recovery, MIF-011 kinematic safety, MIF-012 plasmoid-merger
> Petri-net control, MIF-016 diagnostic normalisation, MIF-017 sensor stress
> injection, and MIF-018 DAQ bus replay. Python and Rust are present for
> hot-path surfaces where applicable; Julia exists for MIF-001, MIF-002,
> MIF-005, MIF-009, MIF-011, MIF-016, and MIF-017; Go is present for MIF-018.
> Lean proofs cover the current safety/bookkeeping contracts for MIF-004,
> MIF-005, MIF-009, MIF-011, and MIF-012. MIF-007 has Python golden-reference,
> synthesisable SystemVerilog, Yosys, Verilator, and local regression evidence.
> MIF-015 now has a local ADC/Q8.8/RTL-trace cosimulation harness for the
> MIF-007 sensor path. MIF also detects the accepted SCPN-FUSION-CORE FRC
> contract surfaces without dispatching those FUSION-owned physics kernels
> locally. Vivado ZU3EG timing, hardware waveform equivalence, full external
> FUSION reference parity, and the P6 hardware trigger chain remain open
> hardware/tooling lanes. See
> [`docs/api/`](docs/api/index.md) for the implemented surfaces.

## Reading path

| Audience | Start here |
|---|---|
| Researcher evaluating fit | [Architecture overview](docs/architecture/index.md) |
| Engineer checking sibling readiness | [Dynamic compatibility matrix](docs/generated/compatibility_matrix.md) |
| Contributor | [CONTRIBUTING](CONTRIBUTING.md) |
| Security researcher | [SECURITY](SECURITY.md) |
| Citation | [CITATION.cff](CITATION.cff) |

## Quick start

```bash
git clone https://github.com/anulum/scpn-mif-core.git
cd scpn-mif-core
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
make install-hooks   # wires preflight as the pre-push gate
make preflight       # ten-gate local quality check
```

The Rust workspace builds independently:

```bash
cd scpn-mif-rs
cargo test --workspace --all-features
cargo clippy --workspace --all-targets -- -D warnings
```

Optional tool-chains (gate the related accelerators and proofs):

```bash
julia --project=julia/SCPNMIFCore -e 'using Pkg; Pkg.instantiate()'
lake build          # Lean proof surface; uses the repo-root lakefile.lean
cd go && go test ./...
pixi install         # Mojo via Modular's pixi channel
```

## Architecture in one figure

```
sensor → [AER]  ┐
                ├── SNN (Q8.8) → combinatorial trigger fabric → coil switch
slow control ───┘   ↑
                    └── PulsedScenarioScheduler (CONTROL Petri-net + NMPC)
                          ↑
                          ├── CapacitorBank model
                          ├── DopplerEngine + MovingFrameUPDE (PHASE-ORCH)
                          ├── Hall-MHD pulsed + MRTI + tilt (FUSION-CORE)
                          └── QAOA-MPC + PQC trigger signer (QUANTUM-CONTROL)
```

Latency budget end to end: **≤ 50 nanoseconds** sensor edge → switch edge.
Formal proof of the budget is mechanised in SymbiYosys with a nuXmv / Kind 2
timed-automata back-end (see `hdl/formal/timing/`).

## Sibling repositories

MIF consumes sibling repositories through a generated compatibility report,
not through hand-maintained equality pins. Regenerate it with:

```bash
python tools/generate_compatibility_matrix.py
```

| Sibling | Role | Dynamic status source |
|---|---|---|
| [`sc-neurocore-engine`](https://github.com/anulum/sc-neurocore) | SNN → SystemVerilog emitter, Q8.8 quantiser, AER HDL, SymbiYosys properties | [`docs/generated/compatibility_matrix.md`](docs/generated/compatibility_matrix.md) |
| [`scpn-phase-orchestrator`](https://github.com/anulum/scpn-phase-orchestrator) | Kuramoto family, distance coupling, monitors, Rust kernel, Lean SPO base | [`docs/generated/compatibility_matrix.md`](docs/generated/compatibility_matrix.md) |
| [`scpn-control`](https://github.com/anulum/scpn-control) | Petri-net runtime + formal verification, SNN controller, Rust hot path, replay | [`docs/generated/compatibility_matrix.md`](docs/generated/compatibility_matrix.md) |
| [`scpn-fusion-core`](https://github.com/anulum/scpn-fusion-core) | Canonical physics-solver laboratory (Hall-MHD, MRTI, tilt, equilibrium) | [`docs/generated/compatibility_matrix.md`](docs/generated/compatibility_matrix.md) |
| [`scpn-quantum-control`](https://github.com/anulum/scpn-quantum-control) | QAOA-MPC, pulse shaping, bridges, QRNG, PQC trigger signer | [`docs/generated/compatibility_matrix.md`](docs/generated/compatibility_matrix.md) |

The specific contract lanes MIF consumes, developed in the siblings under the
bidirectional sync protocol, are:

- **`scpn-fusion-core` — FUS-C.1…C.7**: FRC rigid-rotor equilibrium, two-fluid
  Hall-MHD pulsed solver, non-adiabatic flux constraint, MRTI and tilt-mode
  trackers, pulsed compression. Fusion Core owns the solver mathematics; MIF
  consumes the public contract through `scpn_mif_core.physics.fusion_frc_contract`
  without duplicating the kernels.
- **`scpn-control` — CON-C.1…C.7**: pulsed-scenario scheduler, capacitor-bank
  state model, AER control observation, replay schema, NMPC pulsed-shot adapter,
  multi-shot campaign orchestrator, PREEMPT_RT runtime binding.
- **`scpn-phase-orchestrator` — PHA-C.1…C.6**: spatial coupling modulator,
  Doppler engine, moving-frame UPDE engine, merge-window monitor, time-varying
  angular frequency, and Lean 4 kinematic safety lemmas.
- **`sc-neurocore-engine` — NEU-C.1…C.6**: UltraScale+ synthesis target,
  timing-aware formal framework, mixed-precision Q8.8/Q16.16, AER priority queue,
  ADC-to-spike quantiser HDL, and the DCLS Q8.8 RTL path.
- **`scpn-quantum-control` — QUA-C.1…C.6**: QRNG stream, PQC trigger signer,
  FRC QAOA-MPC cost, UltraScale+ HLS codegen, sub-microsecond tracker, and NV
  magnetometry. This lane is deferred for the current MIF gate.

Live readiness and version status for every lane are derived from sibling source
by the generated matrix, never from static equality pins.

## Technical specification

> The remainder of this document is the original functional specification
> that anchors the development plan. It is preserved verbatim. The
> mathematical objects below are the carrier equations referenced from
> [`docs/architecture/index.md`](docs/architecture/index.md).

### Operational target

`scpn-mif-core` solves the bottleneck in pulsed magneto-inertial fusion:
**direct energy recovery latency**.

Pulsed FRC devices have proven they can reach fusion ignition temperatures
(> 100 M °C). Creating fusion is mathematically distinct from extracting
net electricity. High-beta reactors do not boil water; they extract energy
via Faraday induction when the fusion reaction forces the plasma to expand
radially against the external 20-tesla magnetic field.

If the control architecture is reactive (operating in the > 1 µs CPU
envelope), it fails. Asymmetrical kinematic merging at Mach 1 triggers an
n = 1 tilt mode, or late compression triggers magneto-Rayleigh–Taylor
instabilities (MRTI). The plasma breaches confinement and hits the vacuum
wall before it can expand and push electromagnetic energy back into the
capacitor banks.

`scpn-mif-core` is engineered to preempt these macroscopic instabilities
*before* they compromise the energy-recovery cycle. It discards steady-state
tokamak logic entirely, isolating the `scpn-phase-orchestrator` Kuramoto
models and compiling them via `sc-neurocore` into sub-50-nanosecond, purely
combinatorial SystemVerilog triggers.

---

### Architectural payload and physics priors

The framework replaces standard Grad–Shafranov equilibria with non-adiabatic
two-fluid Hall-MHD logic and kinematic phase synchronisation.

#### 1. FRC kinematic phase synchronisation module

This module tracks the relative phase velocities of two incoming macroscopic
plasma bodies. It calculates the exact timing delta required for the
opposing formation coils to ensure the left and right FRCs enter phase-lock
precisely at the geometric centre of the compression chamber.

```python
import math


def kinematic_frc_synchronisation(
    omega_i: float,
    omega_rate_i: float,
    t_s: float,
    theta_i: float,
    theta_j: float,
    v_z_i: float,
    v_z_j: float,
    z_i: float,
    z_j: float,
    K_mag: float,
    alpha: float,
) -> float:
    """Rate of phase change for an FRC plasmoid during high-speed kinematic merging."""
    omega_i_t = omega_i + omega_rate_i * t_s
    spatial_coupling = K_mag / (1.0 + abs(z_i - z_j))
    doppler_shift = (v_z_i - v_z_j) / (abs(v_z_i) + 1e-9)
    return omega_i_t + spatial_coupling * math.sin(theta_j - theta_i - alpha) + doppler_shift
```

**Equation parameters:**

- `omega_i` — natural rotational frequency of the FRC driven by ion
  diamagnetic drift (rad s⁻¹).
- `omega_rate_i` — optional affine frequency drift (rad s⁻²); the default
  implementation uses zero drift and therefore preserves constant-frequency
  operation.
- `t_s` — non-negative simulation time used to evaluate `omega_i(t)`.
- `theta_i`, `theta_j` — instantaneous internal rotational phases of the
  left and right FRCs.
- `v_z_i`, `v_z_j` — axial velocities of the plasmoids moving toward the
  central chamber (m s⁻¹).
- `z_i`, `z_j` — spatial positions of the FRCs along the longitudinal axis
  (m).
- `K_mag` — base magnetic coupling strength during the reconnection phase.
- `alpha` — frustration parameter representing non-ideal resistive delays
  in magnetic reconnection.

#### 2. High-beta direct-energy-recovery module

This module provides the digital-twin verification for energy extraction.
It maps the rate of change of the internal plasma pressure directly to the
induced back-electromotive force on the external coil array.

```python
import math


def direct_energy_recovery_emf(
    R_s: float,
    dR_s_dt: float,
    B_ext: float,
    N_turns: float,
) -> float:
    """Back-EMF induced in the recovery coils due to radial expansion of the high-beta FRC."""
    dPhi_dt = B_ext * (2.0 * math.pi * R_s * dR_s_dt)
    return -N_turns * dPhi_dt
```

**Equation parameters:**

- `R_s` — instantaneous radius of the FRC separatrix (m).
- `dR_s_dt` — radial expansion velocity of the plasma post-fusion (m s⁻¹).
  Positive values indicate expansion against the field.
- `B_ext` — external confining magnetic field (T).
- `N_turns` — number of turns in the magnetic-pickup / recovery coil array.

---

### Hardware-synthesis target

`scpn-mif-core` acts as an intermediate-representation compiler. It takes
the differential equations above and translates them into an event-driven
spiking neural network. Through the `sc-neurocore` back end, the SNN is
synthesised into Q8.8 fixed-point SystemVerilog. The primary engineering
deliverable is a **formally verified FPGA bitstream** capable of reading
Address-Event-Representation magnetic-probe spikes and firing the
compression coils entirely within the sub-50-nanosecond hardware layer,
bypassing the CPU completely.

---

## Status

The repository is currently in **pre-alpha**. P0 bootstrap (the present
release `0.0.1`) shipped the governance, build system, source-tree skeleton,
testing infrastructure, benchmark scaffolding, documentation site, CI/CD
workflows, and the compatibility matrix `LOCKED-skeleton` row. Current main
also contains the first P1 upstream-pending modules:

- MIF-005 capacitor-bank dynamics with Python, Rust, and Julia paths.
- MIF-009 Faraday recovery with Python, Rust, and Julia paths.

The broader public surface still stabilises at `0.1.0`.

## Licence

This work is licensed under the GNU Affero General Public License v3.0 or
later (AGPL-3.0-or-later). See [LICENSE](LICENSE) and [NOTICE](NOTICE.md).
Commercial licensing is available for organisations that cannot use AGPL —
contact [protoscience@anulum.li](mailto:protoscience@anulum.li).

## Citation

If you use this work, please cite it using [CITATION.cff](CITATION.cff)
metadata.
