# Kalika MD performance benchmarks

All timings use optimized Rust (`cargo run --release`), deterministic fixtures,
and `std::hint::black_box`. CSV output includes the phase-120 target and whether
the local measurement passes it. Run one benchmark process at a time.

Before a full size matrix, follow the repository resource-safety gate. The CI
smoke profile is intentionally small and verifies execution, not performance:

```sh
cargo run -p md-benchmarks --release --bin classical-md-benchmark -- --smoke
```

The full classical matrix measures 1K, 10K, 100K, and 1M atom LJ force steps
with a retained Verlet list and PME steps with linked-cell real-space work.
Override repetitions with `KALIKA_BENCH_ITERATIONS`; use `KALIKA_LJ_SIZES` or
`KALIKA_PME_SIZES` to select an explicit subset after reviewing host resources.

The `comparator` column records whether a LAMMPS serial executable (`lmp` or
`lammps`) is available. It does not substitute or estimate an external result.

## Baseline: 2026-07-13

The first full single-core run on the 15 GiB Linux validation host used one
timed force step per size (release/LTO build):

| kernel                       |     atoms | atom-steps/s | phase target | result |
| ---------------------------- | --------: | -----------: | -----------: | ------ |
| LJ + retained Verlet list    |     1,000 |    2,439,310 |    1,000,000 | pass   |
| LJ + retained Verlet list    |    10,000 |    1,586,952 |    1,000,000 | pass   |
| LJ + retained Verlet list    |   100,000 |    2,210,653 |    1,000,000 | pass   |
| LJ + retained Verlet list    | 1,000,000 |    2,129,851 |    1,000,000 | pass   |
| PME + linked-cell real space |     1,000 |      337,951 |      100,000 | pass   |
| PME + linked-cell real space |    10,000 |      340,591 |      100,000 | pass   |
| PME + linked-cell real space |   100,000 |      309,838 |      100,000 | pass   |
| PME + linked-cell real space | 1,000,000 |      315,284 |      100,000 | pass   |

Neither `lmp` nor `lammps` was installed, so no same-host LAMMPS number is
reported. The local results retain the original phase targets verbatim; the
comparator is never estimated or substituted.

## Native versus WebAssembly bindings

`scripts/build-bindings.sh` builds the exact same Rust entry point as a napi-rs
Node addon, a wasm-bindgen Node module, and a browser-targeted WASM module. It
compares neighbor-list construction, retained-list LJ forces, and PME in Node
and in a real Playwright-launched Chromium page. Each result includes a
checksum; the comparators abort before reporting ratios if native and WASM
disagree.

Use `KALIKA_BINDING_SMOKE=1` for the small build/ABI gate. The default profile
uses 10K atoms for neighbor/force kernels and 1K atoms for the current PME
reference kernel. The phase gate is `wasm_over_native <= 2`.

The 2026-07-13 same-host browser release run produced:

| kernel                 | native (s) | browser WASM (s) | WASM/native | result |
| ---------------------- | ---------: | ---------------: | ----------: | ------ |
| neighbor list, 10K × 5 |     0.4895 |           0.5663 |       1.157 | pass   |
| LJ force, 10K × 5      |     0.1258 |           0.1264 |       1.005 | pass   |
| PME, 1K × 3            |     0.0134 |           0.0162 |       1.210 | pass   |

The smoke profile is an ABI/correctness gate only: its very short calls can be
dominated by module-boundary and timer overhead, so its ratios are not used as
performance acceptance values.

## ReaxFF

The reactive benchmark parses the vendored canonical C/H/O force field and
profiles neutral methane boxes at 500, 2,000, and 10,000 atoms. The evaluator's
opt-in profiler reports QEq, raw/corrected bond order, bonded corrections, and
nonbonded wall time without changing its normal WASM-safe path.

```sh
cargo run -p md-benchmarks --release --bin reaxff-benchmark
cargo run -p md-benchmarks --release --bin reaxff-benchmark -- --smoke
```

The CSV retains an explicit LAMMPS availability field. This host has no `lmp` or
`lammps`, so the requested ≤3× `reax/c` comparison cannot be computed here.

The 2026-07-13 one-step release profile measured:

|  atoms |  steps/s |  QEq (s) | bond order (s) | bonded corrections (s) | nonbonded (s) | total (s) |
| -----: | -------: | -------: | -------------: | ---------------------: | ------------: | --------: |
|    500 |   4.3013 |   0.2137 |         0.0085 |                 0.0032 |        0.0071 |    0.2325 |
|  2,000 |  0.08046 |  12.1518 |         0.1157 |                 0.0509 |        0.1093 |   12.4279 |
| 10,000 | 0.002243 | 438.7440 |         2.8292 |                 1.5039 |        2.7277 |  445.8049 |

This baseline exposes QEq as the scaling bottleneck (98.4% of the 10K step),
which is actionable performance evidence rather than a hidden or extrapolated
result.

## Trajectory analysis

The trajectory runner uses 10K and 100K atom, 1,000-frame deterministic
trajectories. MSD streams every frame without retaining 2.4 GiB of coordinates.
RDF samples ten frames and CNA/Voronoi sample one frame by default, matching
normal structural-analysis cadence while still reporting the declared 1,000
frame trajectory and exact sampled-frame count. All neighbor discovery uses the
production linked-cell implementation.

```sh
cargo run -p md-benchmarks --release --bin trajectory-benchmark
cargo run -p md-benchmarks --release --bin trajectory-benchmark -- --smoke
```

`KALIKA_RDF_FRAMES` and `KALIKA_STRUCTURAL_FRAMES` can expand the sampling
matrix. Acceptance gates are one million RDF pairs/s and 100,000 CNA atoms/s.
The comparator column reports OVITO availability; OVITO is absent on this host,
so no external Python API timing is inferred.

The 2026-07-13 release profile measured:

| kernel  |   atoms | sampled frames |      throughput | target | result   |
| ------- | ------: | -------------: | --------------: | -----: | -------- |
| MSD     |  10,000 |          1,000 |  16.37M atoms/s |      — | measured |
| RDF     |  10,000 |             10 |   4.24M pairs/s |     1M | pass     |
| CNA     |  10,000 |              1 | 829,627 atoms/s |   100K | pass     |
| Voronoi |  10,000 |              1 | 207,865 atoms/s |      — | measured |
| MSD     | 100,000 |          1,000 |  16.16M atoms/s |      — | measured |
| RDF     | 100,000 |             10 |   4.37M pairs/s |     1M | pass     |
| CNA     | 100,000 |              1 | 928,597 atoms/s |   100K | pass     |
| Voronoi | 100,000 |              1 | 216,792 atoms/s |      — | measured |
