# Phase-0 Performance Baseline

This document records the Phase-0 benchmark results for `entropyk-solver`. All
later Epic-1 speedup claims (NFR1 ≥2× speedup, NFR2 100% parity) are measured
against these numbers.

## Environment

| Property | Value |
|---|---|
| Date | 2026-07-18 |
| Host OS | Windows (x86_64) |
| Rust toolchain | 1.89.0 (stable, pinned via `rust-toolchain.toml`) |
| Cargo profile | bench (release) |
| Linear algebra path | nalgebra 0.33 dense LU |

## How to Reproduce

```bash
# Ensure the pinned toolchain is active
cargo --version  # should report 1.89.0

# Run the full benchmark suite
cargo bench -p entropyk-solver
```

## Benchmark Results

Results were produced by `cargo bench -p entropyk-solver` on the commit captured
in the story frontmatter (`baseline_commit`).

### LU Solve (Dense)

| Benchmark | Mean time |
|---|---|
| `lu_solve_mock_9x9` | **425.54 ns** |

Measures one Ruiz-equilibrated dense LU solve on the 9×9 Jacobian assembled
from the deterministic mock refrigeration cycle.

### Residual / Jacobian Assembly

| Benchmark | Mean time |
|---|---|
| `residual_assembly_mock` | **420.95 ns** |
| `jacobian_assembly_mock` | **157.47 ns** |

Measures a single full-system pass of `compute_residuals` and
`jacobian_entries` on the mock cycle.

### Full Solve — Reference Cycles

Each benchmark builds a real CoolProp-backed emergent-pressure R134a cycle
(4 components, 9 unknowns) and solves it end-to-end with the fallback Newton
solver.

| Benchmark | Mean time |
|---|---|
| `full_solve_reference_cycle_a` | **48.64 ms** |
| `full_solve_reference_cycle_b` | **67.06 ms** |
| `full_solve_reference_cycle_c` | **66.78 ms** |

### Sequential Batch Solve Scaling

| N | Mean time |
|---|---|
| 1 | **56.03 ms** |
| 2 | **118.01 ms** |
| 4 | **240.03 ms** |

This is the Phase-0 *sequential* baseline. Parallel batch solving is out of
scope and belongs to Epic 4.

## Golden Snapshots

The golden regression test solves the three reference cycles and compares the
converged state against committed canonical JSON snapshots. Run with
`ENTROPYK_BLESS=1` to regenerate snapshots after an intentional change.

| Cycle | SHA-256 (canonical JSON) |
|---|---|
| `golden_cycle_a.json` | `073408dede4ad4622272e9c9375d9f4823e7984ec9e54910a9790229d52af899` |
| `golden_cycle_b.json` | `c01e7cb892ed5829926c38ad5ee1423fdfaa7d262c473a8eca46ebc4632b9142` |
| `golden_cycle_c.json` | `6e1a77958cce1d1cf5e730505912a887c8bf4fc7dcaed820c7da482aa0ad9f98` |

## Integration Corpus

The NFR2 parity corpus consists of **31** pre-existing integration test files in
`crates/solver/tests/` (including `_scratch_debug.rs` and `_tmp_analytic.rs`).
This story added one new file (`golden_snapshot.rs`), bringing the solver test
count to **32**. The 31 pre-existing files must continue to pass unmodified as
later Epic-1 stories land; `golden_snapshot.rs` is part of the Phase-0 safety
net and must also remain green.

## Reproduction Commands

```bash
# Ensure the pinned toolchain is active
cargo --version  # should report 1.89.0

# Full workspace test suite
cargo test --workspace

# Solver integration corpus only (includes golden snapshot)
cargo test -p entropyk-solver --tests

# Golden snapshot regression test specifically
cargo test -p entropyk-solver --test golden_snapshot --features coolprop

# Regenerate snapshots after an intentional physics/solver change
ENTROPYK_BLESS=1 cargo test -p entropyk-solver --test golden_snapshot --features coolprop

# Benchmark suite
cargo bench -p entropyk-solver

# Lint/format gates
cargo fmt --check
cargo clippy --workspace --all-targets -- -D warnings
```
