Add dense/recursive NEGF switch, audit performance, parallelize with rayon

[reneotten]

Summary

Builds on #1 (not yet merged, hence that branch as the base here).

• Dense/recursive switch: the NEGF engine previously only had the O(N) recursive algorithm. Promoted the dense O(N³) reference (previously test-only) to a real, selectable algorithm (GreenFunctionAlgorithm::{Recursive, Dense} in Rust, algorithm="recursive"|"dense" in Python) so both are available and validated against each other — dense as an easy-to-trust reference / fallback, recursive as the fast default.
• Performance audit + parallelism: added crates/negforge-core/examples/benchmark.rs and used it to find and exploit the real parallelism in this problem:
  • The NEGF energy loop is embarrassingly parallel (each energy point only reads the same fixed Hamiltonian) — parallelized with rayon, benefiting both algorithms.
  • Bias sweeps (sweep_v_g/sweep_v_ds) are parallel per bias point, since set_v_g/set_v_ds already reset device state from scratch — nothing carries over between points. This changes their signature from &mut Device to &Device (each point runs on its own clone), which also fixes a surprising side effect where a sweep used to silently leave the device parked at its last bias point.
  • Self-consistent loop iterations remain sequential (each depends on the previous iteration's potential) — documented as the one thing that genuinely can't be parallelized here.
• README gets a new "Performance" section with the tradeoff explanation and real benchmark numbers (dense scales ~cubically, recursive is flat; parallel energy loop gets ~3-4x on a 4-core machine).
• Notebook gets a new section demonstrating the switch live (small device, both algorithms agree to ~1e-12, dense is measurably slower even at N=31).

Test plan

• cargo test --workspace — 19 tests pass, including new cross-checks: negf::tests::dense_and_recursive_algorithms_agree_end_to_end, selfconsistent::tests::dense_and_recursive_converge_to_the_same_potential, sweep::tests::sweep_does_not_mutate_the_input_device
• cargo clippy --workspace --all-targets — clean
• cargo run --release --example benchmark -p negforge-core — produces the numbers quoted in the README
• maturin develop --release rebuilds; verified algorithm="dense"/"recursive" give matching results at different speeds, and an invalid algorithm string raises ValueError
• notebooks/negforge_demo.ipynb re-executed end-to-end with the new section included, no errors

---

Generated by Claude Code

[Copilot]

Pull request overview

This PR adds a selectable NEGF Green’s-function backend (dense reference vs. recursive fast path) and introduces Rayon-based parallelism over independent energy points and bias-sweep points, with corresponding updates to the Rust core, PyO3 bindings, Python convenience wrapper, benchmark tooling, and documentation/notebook examples.

Changes:

• Introduces GreenFunctionAlgorithm::{Recursive, Dense} and wires it through NEGF sweeps and the self-consistent solver (Rust + Python API surface).
• Parallelizes NEGF energy-point evaluation and bias sweeps using rayon, and makes Rust sweep APIs non-mutating (&Device).
• Adds a benchmark example and expands README/notebook documentation with performance guidance and usage examples.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
README.md	Documents the dense/recursive switch, parallelism approach, and benchmark numbers.
python/negforge/__init__.py	Exposes algorithm= in the Python wrapper for self-consistent solves, LDOS, and sweeps.
notebooks/negforge_demo.ipynb	Demonstrates dense vs. recursive behavior and timing in the notebook flow.
crates/negforge-py/src/lib.rs	Implements Python-facing parsing/validation of algorithm and updates bindings to new Rust APIs.
crates/negforge-core/src/sweep.rs	Makes sweeps non-mutating and parallel per bias point via cloning + Rayon.
crates/negforge-core/src/selfconsistent.rs	Threads the algorithm selection into the self-consistent loop via options.
crates/negforge-core/src/negf.rs	Adds GreenFunctionAlgorithm, dense backend, and parallel energy loop execution.
crates/negforge-core/src/lib.rs	Re-exports GreenFunctionAlgorithm publicly.
crates/negforge-core/examples/benchmark.rs	Adds a benchmark harness for algorithm and parallelism comparisons.
crates/negforge-core/Cargo.toml	Adds rayon dependency for parallel execution.
Cargo.lock	Locks new transitive dependencies introduced by rayon.

Comments suppressed due to low confidence (1)

crates/negforge-py/src/lib.rs:206

• Same issue as sweep_v_g: algorithm is parsed even when self_consistent=false, so invalid strings raise ValueError despite being documented as irrelevant unless self-consistency is enabled. Only parse/validate when self_consistent is true.

        let opts = SelfConsistentOptions {
            algorithm: parse_algorithm(algorithm)?,
            ..Default::default()
        };
        let sc = if self_consistent { Some(&opts) } else { None };
        let points = negforge_core::sweep::sweep_v_ds(&self.inner, v_min, v_max, step, sc)

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.