docs/METHOD.md

# The Miller Harmonic Method (MHM) — Technical Overview

This document explains the method implemented in `batterymhm/`. The method is
**patent pending**; this description is provided for understanding and
reproduction under the repository's CC BY-NC 4.0 license.

---

## 1. The harmonic digit space and the fold map

MHM works in a finite digit space **D = {1, 2, …, 9}**. Any integer is projected
into D by the **fold map**:

```
HIN(k) = 1 + ((k − 1) mod 9)
```

`HIN` stands for *Harmonic Identity Number*. In code this is `f9` (general) and
`hin` (applied to an atomic number Z). Two integers that differ by a multiple of
9 share a harmonic class. Real-valued measurements (capacity, voltage,
temperature) are first quantised into 9 bins (`seq_to_harmonics`) so they, too,
live in D.

## 2. The binary operations

Two complementary operations act on D, each folded back into D:

| Operation | Symbol | Definition | Role |
|---|---|---|---|
| Creative addition | `⊕` | `f9(a + b + 1)` | recombination / creative synthesis |
| Growth product | `⊗` | `f9(a·b + 1)` | growth / energy exchange |
| Energy addition | `⊕_E` | `f9(a + b + 1 + tier)` | shell-tiered energy coupling |
| Miller subtraction | `⊖` | `f9(a − b + 9)` | directed harmonic difference |

These are the building blocks for the histograms and the calculus below. (Note:
`⊕` and `⊖` are *not* exact inverses — the `+1` in creative addition is
deliberate and gives the algebra its asymmetry.)

## 3. The Chi compatibility matrix

The heart of the method is a fixed **9×9 Chi matrix** `Χ[i, j] ∈ (0, 1]`
(`batterymhm/atomic.py`). `Χ[i, j]` is the harmonic *compatibility* (resonance)
between classes `i` and `j`. It is symmetric with a unit diagonal.

The nine classes split into two physical channels:

- **Matter** — classes 1–8, scored on the 8×8 sub-matrix `CHI_MATTER_8x8`.
- **Energy** — class 9, the "energy pole," scored on a separate 9-vector
  `CHI_ENERGY_9`.
- **Tesla nodes** — classes {3, 6, 9} are energy-focusing; they get their own
  network features.

This matter/energy split lets crystal-structure models score matter–matter
bonding and the energy-pole contribution on distinct geometries.

## 4. The Miller sequence and shell levels

The **Miller sequence** is a Fibonacci-like sequence with seed `[1, 1, 3]`:

```
1, 1, 3, 4, 7, 11, 18, 29, 47, 76, …
```

Its positions group into **shell levels** (level 1 = positions 1–3, level 2 =
4–12, level 3 = 13–39, …), each level three times larger than the last. These
levels provide a *physically meaningful sampling grid*: for a battery, level-1
positions correspond to the first few cycles (the "initialization signature"),
and later levels to the long-term aging trajectory. The sequence and its
class trajectory (via **CMR**, repeated creative-addition reduction) are turned
into features.

## 5. Embeddings

Two embeddings bridge the discrete digit space to continuous math:

- **χ-embedding**: `χ(a) = (a + 1) mod 9` → an index in ℤ₉ (bridge to calculus).
- **φ-embedding**: `φ(d) = sin(πd / 9)` → a real number (bridge to geometry).

## 6. Miller calculus

Operating on a harmonic sequence, MHM defines discrete differential operators
(`batterymhm/calculus.py`):

- **velocity** — mean first-order Miller difference,
- **acceleration** — mean second-order difference,
- **integral** — cumulative creative addition,
- **curvature** — curvature `κ = |y''| / (1 + y'²)^{3/2}` of the φ-embedded
  curve, which spikes at the onset of capacity-fade degradation (the aging
  "knee").

Evaluated at multiple window scales, these capture multi-scale degradation
dynamics.

## 7. The descriptor (557 features)

`mhm_full_features(hins)` returns a fixed **557-dimensional** vector
(`batterymhm/features.py`):

| Group | # | What it encodes |
|---|---:|---|
| Chi9 full histogram | 81 | distance-weighted 9×9 compatibility |
| Chi9 count histogram | 81 | unweighted pair counts |
| HIN transition matrix | 81 | Markov ordering of the sequence |
| Growth-product histogram | 81 | `⊗` energy-exchange character |
| Energy-addition histograms (2 tiers) | 162 | `⊕_E` shell-coupled resonance |
| Miller-level breakdown | 27 | class occupancy per shell level |
| Tesla-network features | 9 | {3,6,9} focusing nodes and bridges |
| Multi-scale Miller calculus | 12 | velocity/accel/curvature/integral × 3 scales |
| Creative-addition chains | 15 | cumulative `⊕` chain statistics |
| CMR multi-point | 5 | reductions at 5 truncations |
| HIN / GP / EA entropy | 3 | diversity of harmonic interactions |

For crystals, `mhm_matter8_neighbor_histograms` and `mhm_neighbor_histograms`
build the descriptor from the actual neighbour-pair list `(HIN_a, HIN_b, dist)`,
so every feature is physically grounded.

## 8. The model

The descriptor feeds `MHMEnsemble` (`batterymhm/ensemble.py`):

- **ExtraTrees** (600 trees) + **XGBoost** (400 trees), blended 0.75 / 0.25,
- with an optional **Ridge** out-of-fold stacking meta-learner,
- all seeds fixed at 42 for reproducibility.

The ensemble is deliberately light and CPU-only; the harmonic descriptor does
the heavy lifting.

## 9. Two battery applications

**Cell state-of-health.** Quantise an early-cycle capacity curve into HINs →
compute the 557-feature descriptor → predict SOH / remaining useful life. On the
MIT–Stanford–TRI dataset this reaches MAE 0.0114 (5-fold CV, 30% window), #1 on
that benchmark.

**Crystal formation energy.** Fold each crystallographic site to a HIN by atomic
number → score neighbour pairs through the 8×8 matter matrix + HIN-9 energy
channel → predict formation energy. On Matbench `mp_e_form` this reaches MAE
0.1513 eV/atom — better than the classic RF baseline, below modern GNNs (an
honest, documented limitation).

---

*The fold map, the operations, the Chi matrix, the Miller sequence, and the
multi-scale aggregation are the subject of pending patent applications by
William T. L. Miller.*