# Symbolic port validation plan

## Purpose

Validation answers two separate questions:

1. **Port parity:** Does C++/SymEngine reproduce corrected MATLAB QFA behavior?
2. **Model validity:** Does the QFA model agree with thesis equations, PLECS simulations, and measurements within the expected analytical-model error?

Only port parity and thesis analytical examples are hard completion gates for the one-to-one port.

## Validation tiers

### Tier 0 — MATLAB characterization

Before an affected module is ported, corrected MATLAB must have tests for its supported behavior. These tests establish architecture ordering, graph operations, symbolic matrix dimensions, symbol order, errors, and two-phase duty behavior.

**Gate:** Every behavior implemented in the next C++ layer has a passing MATLAB characterization test.

### Tier 1 — Structural parity

Compare MATLAB and C++ for:

- architecture matrices `Acaps`, `Asw`, and `Asw_act`;
- contracted phase graphs;
- selected trees;
- cut-set and loop matrices;
- component, phase, branch, switch, and output ordering;
- ordered symbol vectors.

**Gate:** Shapes, integer entries, metadata, and ordering match exactly.

### Tier 2 — Symbolic QFA parity

Compare corresponding entries of:

- net charge matrices `A`;
- pumped charge matrices `B`;
- redistributed charge matrices `G` or `r`;
- resistive charge matrices `Ar`;
- conversion-ratio vector `m`;
- capacitor and switch stress;
- `ZSSL`, `ZFSL`, ESR contribution, and `ZSCC`.

Use the ADR-0001 layered proof:

1. verify shape and semantic ordering;
2. simplify the symbolic difference;
3. if simplification is inconclusive, use exact non-singular rational substitutions;
4. use high-precision substitutions as the final software-equivalence check.

**Gate:** Every supported matrix entry is algebraically equivalent. Expression strings are diagnostic only.

### Tier 3 — Numerical evaluation parity

Substitute fixed values for `D`, `C`, `Ron`, `Resr`, and `Fsw`. Compare evaluated MATLAB and C++ model outputs.

Default software tolerances:

- integer and rational outputs: exact;
- high-precision symbolic evaluation: relative `1e-12`, absolute `1e-14`;
- binary64 evaluation: relative `1e-10`, absolute `1e-12`.

Each fixture records its own tolerance. A different tolerance requires a reason in the fixture provenance.

**Gate:** All supported evaluated outputs satisfy their fixture tolerances.

### Tier 4 — Optimizer parity

For SSL and FSL optimization, compare:

- selected outputs and duty distribution;
- constraints and feasibility;
- relative capacitor allocation;
- relative switch-area allocation;
- objective value after substitution.

Because two numerical optimizers can reach equivalent minima through different iterates, compare the final constraints and objective as well as the allocation.

Default optimizer tolerances:

- equality-constraint residual: `1e-9`;
- allocation absolute tolerance: `1e-6`;
- objective relative tolerance: `1e-6`.

**Gate:** The C++ result is feasible and reaches an equivalent objective within fixture tolerance.

### Tier 5 — Thesis analytical spine

Use these primary-source examples:

1. **3:1 H-Dickson QFA**, thesis §3.1.5–3.1.6, pp. 51–57:
   - phase charge equations;
   - symbolic `A` and `B` relationships;
   - conversion ratio `m=(2-D)/3`.
2. **Multi-output OTM**, thesis §3.2, pp. 60–64:
   - matrix dimensions and output-column meaning;
   - expected transresistance symmetry/relationships;
   - conversion-ratio vector construction.
3. **5:1 design at `D=0.75`**, thesis §5.2.1–5.2.2, pp. 91–92:
   - relative capacitor allocation `[0.28, 0.39, 0.23, 0.05, 0.05]`;
   - total capacitance `CT=810 nF`;
   - `RFSL=3.8 Ron` for identical switches.

**Gate:** Symbolic equations pass algebraic equivalence and published evaluated values pass their documented rounding tolerance.

### Tier 6 — PLECS and measurement benchmarks

Record, but do not treat as exact software-parity gates:

- Chapter 4 PLECS comparisons, pp. 67–84;
- Table 6.1 at `D=50%`, `Fsw=2.77 MHz`, p. 99;
- predicted `RSCC=894 mΩ`;
- measured-fit `RSCC=877 mΩ` from loss and `842 mΩ` from voltage;
- predicted `K21=495 mΩ` and measured-fit `K21=497 mΩ`.

**Benchmark:** Report absolute and percentage deviation from each source value. A change that materially worsens the corrected MATLAB result requires investigation, but physical-model disagreement does not by itself prove a port defect.

### Tier 7 — Native/WebAssembly parity

After native C++ parity, run the same JSON fixtures through native and WebAssembly builds.

**Gate:** Exact outputs and ordering match; binary64 values meet the Tier 3 tolerance. WebAssembly must not use a different model or fixture interpretation.

## Thesis-spine fixture set

The minimum fixture set is:

- representative Dickson architecture matrices for odd, even, and two-stage cases;
- the 3:1 H-Dickson symbolic example;
- one multi-output OTM example;
- the 5:1 `D=0.75` sizing example;
- the Table 6.1 evaluated benchmark;
- explicit unsupported behavior for more than two phases.

Additional ladder, floating-ladder, SCC 1:1, old Seeman, and ancillary fixtures are added when those compatibility modules enter the port sequence. They do not block initial current-QFA parity.

## Versioned JSON fixture contract

Each fixture contains:

```json
{
  "schemaVersion": 1,
  "id": "thesis-h-dickson-3-to-1",
  "source": {
    "kind": "thesis",
    "citation": "Section 3.1.5, equations 3.17–3.22, pages 52–54"
  },
  "architecture": {
    "Acaps": [],
    "Asw": [],
    "AswAct": []
  },
  "symbols": {
    "duty": [],
    "capacitance": [],
    "switchResistance": [],
    "capacitorEsr": [],
    "switchingFrequency": []
  },
  "assumptions": [],
  "expected": {
    "shape": {},
    "exact": {},
    "symbolic": {},
    "numeric": {}
  },
  "tolerances": {
    "relative": 1e-10,
    "absolute": 1e-12
  },
  "provenance": {
    "matlabVersion": "",
    "symbolicToolboxVersion": "",
    "sourceRevision": ""
  }
}
```

Rules:

- Preserve matrix arrays and symbol order explicitly.
- Encode exact rationals as strings such as `"2/3"`.
- Include units for physical values.
- Keep symbolic text for transport and diagnostics, not direct string equality.
- Record singular or excluded parameter values.
- Never overwrite a fixture after its meaning changes; increment `schemaVersion` or create a new fixture ID.

## Existing gap

The repository currently has no MATLAB unit-test suite and no cross-language fixture set. `ports/test/test_dickson_matrix.cpp` covers only one 5-stage incidence-matrix case. Fixture generation begins with MATLAB characterization and repair work, not with the C++ implementation.