Skip to content

perf(lindblad): faster, lower-memory CTPP steps with a shortlist-and-score default - #276

Open
MSRudolph wants to merge 55 commits into
mainfrom
ctpp/memory
Open

MSRudolph wants to merge 55 commits into
mainfrom
ctpp/memory

Conversation

@MSRudolph

@MSRudolph MSRudolph commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Continuous-time Pauli propagation (CTPP) steps reuse their storage and store Pauli strings and generator connections more compactly. On my tests, peak memory savings are 60–67% less over main. Runtime may go down 0-35%, depending on the case. The Python API is unchanged.

Design

  • One main array: candidate strings for the next step are collected in the spare capacity at the end of the main string and coefficient arrays, not in a separate hash map. Coefficients are updated in place.
  • Proposer interface: a CandidateProposer chooses which strings outside the basis a step admits. propose writes candidates to the spare tail through a CandidateBuffer; select moves the admitted ones to its front. pc_step_with_proposer runs a step with any proposer; the other step buffers stay internal.
  • Automatic reuse: each LindbladSpec keeps a set of step buffers for every trajectory running on it: candidate lookup tables, generator connections, the exponential's work vector and the saved pre-step coefficients. Repeated pc_step calls reuse them, with no change to the calling code.
  • Connection cache with general couplings: when every jump operator is a Hermitian Pauli, the generator is stored as connections that name the parent string and the Hamiltonian term. Coefficients are read from the model, so unequal couplings need no special case. Other dissipators use the existing column-by-column generator.
  • Paired connections: in that case, the Hamiltonian part of the generator is antisymmetric. If string i reaches j through term k, then j reaches i through k with the opposite sign. The cache stores each connected pair once and applies it in both directions. Entries take 6 bytes when term IDs fit in 16 bits, otherwise 8 bytes.
  • Compact Pauli strings: ppvm-lindblad's Word stores only the X and Z bit planes: 32 bytes at 128 qubits instead of 48. The number of qubits belongs to the model, and hashes are computed when a table needs them. At B=2^19 this alone lowers peak memory by about 19% on both models.
    • Word hashes with PauliWord::plane_hash, a small public helper added to ppvm-pauli-word that PauliWord also uses for its cached hash. Ordering is BitArray's order, as for PauliWord. Hash tables therefore treat both types alike.
    • ppvm_pauli_sum symmetry routines still take the general type, exposed as GeneralWord. Word::from(&general) and word.to_general(n_qubits) convert between the two. The qubit count is an argument because Word does not store it.

Benchmarks against main

Median of three fresh runs per implementation, alternating between the two. Apple arm64 on AC power, mimalloc (the allocator the Python extension uses) with MIMALLOC_PURGE_DELAY=0, 6 threads. Every case uses dt=0.1, retained support limit B and admission cap 3B. Times measure propagation only; build time is excluded. Memory is OS-reported peak RSS. The baseline is ppvm-lindblad as on main (built at 342e3234).

Both models evolve a magnetization operator in the Heisenberg picture:

  • Ladder: 2 × 41 sites, open boundaries, no dissipation. H = Σ⟨ij⟩ (XᵢXⱼ + YᵢYⱼ) over nearest-neighbour bonds of the ladder. The observable is the average of Z on the two middle sites.
  • Ring: 61 sites with all-to-all couplings. H = Σᵢ<ⱼ Jᵢⱼ (XᵢXⱼ + YᵢYⱼ), with Jᵢⱼ ∝ rᵢⱼ^−1.1 (distance along the ring), normalized so that Σⱼ Jᵢⱼ² = 1. Each site also has Z dephasing at rate γ = 8. The observable is Z on the center site.

Values show main → this PR.

Model String limit B Propagation time Peak RSS
82-spin ladder, Jt=0→5 2^17 12.65 → 8.40 s (−34%) 291 → 109 MiB (−63%)
82-spin ladder, Jt=0→5 2^19 75.15 → 60.49 s (−20%) 939 → 377 MiB (−60%)
61-spin dephased ring, Jt=0→2 2^19 276.31 → 254.06 s (−8%, within run-to-run spread) 1,876 → 625 MiB (−67%)

The three ring runs of this PR took between 242 and 262 s, so its −8% is not a resolved speedup. Differences below about 5% are not treated as resolved either. For scale, storing B strings with their coefficients takes 56·B bytes: 7 MiB at B=2^17 and 28 MiB at B=2^19.

Numerical agreement

These numbers compare this PR with main, not with an exact reference. The results are not bit-identical to main, because the paired connection cache adds generator entries in a different order. Each implementation gives identical trajectories across its three repeats.

  • Ring: final MSD agrees to nine digits (6.091438931). The largest density-profile difference over all recorded times is 4.7e-12.
  • Ladder: final MSD at B=2^19 is 35.711 on main and 35.692 here; at B=2^17 it is 35.213 and 35.267. Small rounding differences can change which strings fall just below the retention cut, so the retained support, and with it the truncation error, can differ slightly.
  • Tests: unit tests compare pc_step with a reference step built from leakage_with_prune and the column-by-column exponential. They agree bit for bit on small models with Hamiltonian-only, Pauli-dephasing, general and Kossakowski dissipators, and to 2e-13 on a 129-qubit model.

@MSRudolph
MSRudolph requested review from AlexSchuckert and Roger-luo and a balanced review from Copilot November 3, 2026 10:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor
PR Preview Action v1.8.2

QR code for preview link

🚀 View preview at
https://QuEraComputing.github.io/ppvm/pr-preview/pr-276/

Built to branch gh-pages at 2026-11-20 10:14 UTC.
Preview will be ready when the GitHub Pages deployment is complete.

MSRudolph and others added 5 commits November 3, 2026 17:36
The candidate position table and source ordering are rebuilt by every
proposal and unused by selection, so holding them through the
exponential only raised its peak allocation.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Final truncation allocated a fresh magnitude array alongside the
retained Taylor scratch. The real predictor-corrector step lends that
scratch to the rank cap instead.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The crate's word type was ppvm_pauli_word::PauliWord, which also stores
the register size and a cached hash, making a 128-qubit word 48 bytes.
Word now holds only the X and Z planes (32 bytes); the register size
comes from the model and hashes are computed on demand with the same
digest and ordering, so hash-table iteration order is unchanged.
ppvm_pauli_sum symmetry routines still take the general type, exposed
as GeneralWord, with conversions at that boundary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
With words no longer caching their hash, each action term would be
hashed again for sorting and again for every basis-index probe. The
action plan now emits each output word with its hash, and the sort and
index lookups (get_hashed) reuse it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ries

With only Hermitian Pauli jumps, the off-diagonal generator is real
antisymmetric term by term, so the unit cache keeps each connected pair
once and the product applies it in both directions with opposite signs.
Pairs are grouped into block-to-block tiles with 16-bit block-local
positions and a 16-bit term code (32-bit when the model has more terms),
making an entry 6 bytes instead of 8 for every directed connection.
Entry storage is sized to the block's count with 1/16 headroom rather
than doubled, and the exponential's shift and norm bound are reduced
while streaming rows instead of from a per-row array.

Products agree with the general generator to rounding, not bit for bit,
because each row sums its parents in a different order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copilot AI balanced review requested due to automatic review settings November 4, 2026 08:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

Copilot AI balanced review requested due to automatic review settings November 5, 2026 15:27

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@Roger-luo

Copy link
Copy Markdown
Collaborator

I think this is better to be merged after the main refactor gets in - the new trait system gives more flexibility in choosing different PauliWord data structures

@Roger-luo Roger-luo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These notes on "#276 perf(lindblad): faster, lower-memory CTPP steps with a shortlist-and-score default · 2" cover the change as a whole, so they are one review comment on pull request #276.

New direct dependencies. I might miss it somewhere, what’s the purpose of introducing bytemuck here?

Comment on lines 52 to +72
None
}

/// The Pauli-word storage type used throughout this crate, `C` chunks wide.
/// The Pauli-word storage type used throughout this crate, `C` chunks wide:
/// one X and one Z bit plane, 32 bytes at the default 128-qubit width.
///
/// The crate is const-generic in the chunk count so a register of any size
/// up to [`MAX_SUPPORTED_QUBITS`] gets a fixed-size word; the default
/// `C = W_CHUNKS` covers 128 qubits, byte-for-byte the historical layout.
/// The `FxBuildHasher` matches the hash used by the `FxHashMap` keys we
/// wrap with; `REHASH=true` means `set()` keeps the cached hash in sync.
pub type Word<const C: usize = W_CHUNKS> = PauliWord<[Chunk; C], FxBuildHasher, true>;
/// up to [`MAX_SUPPORTED_QUBITS`] gets a fixed-size word. The register size
/// belongs to the model and is not stored per word; bits at or above it are
/// always zero. The hash is computed from the planes on demand with the same
/// digest `ppvm_pauli_word::PauliWord` caches, so hash tables keyed by words
/// order them exactly as they would order that type. Ordering compares the X
/// plane, then the Z plane.
#[derive(Clone, Copy, Default)]
pub struct Word<const C: usize = W_CHUNKS> {
/// X-bit plane, one bit per qubit.
pub xbits: BitArray<[Chunk; C]>,
/// Z-bit plane, one bit per qubit.
pub zbits: BitArray<[Chunk; C]>,
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason why we are droping the storage abstraction and special case on [Chunk; C]? Chunk seems a quite hard coded choice to me

Comment thread crates/ppvm-lindblad/src/word.rs Outdated

/// Bit-lexicographic order of one plane from qubit 0 upward, as `BitArray`'s
/// `Ord` defines it, evaluated a chunk at a time.
#[inline(always)]

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason why plane_cmp is written by hand?

Comment thread crates/ppvm-lindblad/src/word.rs Outdated
Comment on lines +92 to +116
/// The general `ppvm_pauli_word` word of the same width, which also stores the
/// register size and a cached hash. `ppvm_pauli_sum` symmetry routines take this type.
pub type GeneralWord<const C: usize = W_CHUNKS> =
ppvm_pauli_word::word::PauliWord<[Chunk; C], FxBuildHasher, true>;

impl<const C: usize> Word<C> {
/// This word as the general `PauliWord` used by `ppvm_pauli_sum` symmetry groups.
pub fn to_pauli_word(self, n_qubits: usize) -> GeneralWord<C> {
use ppvm_traits::PauliWordTrait;
let mut word = ppvm_pauli_word::word::PauliWord::new(n_qubits);
word.xbits = self.xbits;
word.zbits = self.zbits;
word.rehash();
word
}

/// The planes of a general `PauliWord`.
pub fn from_pauli_word(word: &GeneralWord<C>) -> Self {
Self {
xbits: word.xbits,
zbits: word.zbits,
}
}
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I’m wondering if we can directly adopt this in the new trait system by @david-pl ? the new trait system should be more generic and allow you using different PauliWord type for different trade offs.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI. @MSRudolph that basically means just using the ppvm-traits-2 crate, which is already there. But I'm not sure if there will be some missing features then (there are a few pending PRs to complete the refactor).

Comment on lines +285 to +313
let mut basis_words = decode_basis::<C>(&basis_view, n_q)?;
let mut coeffs_vec = coeffs_slice.to_vec();

core_sym::canonicalize_pauli_sum(&mut basis_words, &mut coeffs_vec, &group.inner);
let mut general = to_general(&basis_words, n_q);
core_sym::canonicalize_pauli_sum(&mut general, &mut coeffs_vec, &group.inner);
basis_words = from_general(&general);

let basis_arr = encode_basis(py, &basis_words, n_q)?;
Ok((basis_arr, coeffs_vec.into_pyarray(py)))
})
}

/// `ppvm_pauli_sum` symmetry routines take the general word type; the Lindblad words
/// store only their bit planes.
fn to_general<const C: usize>(
words: &[ppvm_lindblad::Word<C>],
n_qubits: usize,
) -> Vec<ppvm_lindblad::GeneralWord<C>> {
words.iter().map(|w| w.to_pauli_word(n_qubits)).collect()
}

fn from_general<const C: usize>(
words: &[ppvm_lindblad::GeneralWord<C>],
) -> Vec<ppvm_lindblad::Word<C>> {
words
.iter()
.map(ppvm_lindblad::Word::from_pauli_word)
.collect()
}

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a reason we are not using standard type conversations here? or this cannot be made into standard type conversions?

Add `PauliWord::plane_hash`, the hash `PauliWord` caches, computed from
the two bit planes; `rehash` uses it too. `ppvm-lindblad`'s `Word` hashes
with it instead of its own byte view, so the crate no longer depends on
bytemuck, and derives `Ord` (BitArray order, as `PauliWord` uses) instead
of a hand-written comparison. Conversions are `Word::from(&general)` and
`word.to_general(n_qubits)`; the qubit count is an argument because `Word`
does not store it.
The helper only computed `admit_basis = ceil(ratio * max_basis)`, which
callers can set directly; drop it with its two error variants.
`PcStepWorkspace::allocation_bytes` and the per-cache helpers behind it
only served profiling and had no callers in the library.
…poser API

Streaming candidate selection is the only strategy. Remove
`ShortlistScoreProposer`, `CandidateStrategy` and the Python `proposer=`
keyword, and make the proposer and step buffers internal: the
`CandidateProposer` trait, `CandidateBuffer`, `PcStepWorkspace`,
`pc_step_with_proposer` and `pc_step_with_workspace` are gone. `pc_step`
still reuses one set of buffers per trajectory automatically.

`leakage_with_prune` is restored to its map-based form, and the test
reference step builds on it. A unit test checks that streaming admission
selects the same strings in the same order.
When every jump is a Hermitian Pauli, the paired unit cache already
stores the generator. The row-gather CSR cache was only reached for
Hamiltonians that list the same Pauli term twice. Those models, like
general dissipators, now use the column-assembled exponential
`expm_apply_mf`. `ActionScratch` moves to the candidate module, its only
remaining user.
`ActionScratch::fill` and `IndexedCandidates::add` run once per source
string and once per generated term. Under the default 16 codegen units
they were not always inlined into the generation and accumulation loops,
which made the first leakage pass up to 20% slower on the dephased ring.
A `CandidateProposer` chooses which strings outside the basis a step
admits: `propose` writes candidates to the spare tail of the basis array
through a `CandidateBuffer`, and `select` moves the admitted ones to the
front of that tail. `StreamingProposer` is the default implementation, and
`pc_step_with_proposer` runs a step with any proposer while the step's
other buffers stay internal and reused. `CandidateBuffer::push` grows the
shared array by a quarter of its capacity rather than doubling it.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants