kshell-cpp

Current Focus

The accepted default backend, kshell-cpu, follows KSHELL's block-local wavefunction layout and is the baseline for both correctness and timing. CPU parity is now the accepted baseline for known single-node stress cases, and the current GPU work is planning-only: docs/gpu_bridge_matvec_plan.md defines the first prospective GPU slice for repeated pp/nn/pn bridge matvec loops. GPU implementation remains gated until explicitly resumed.

Run the canonical KSHELL comparison gates with:

python3 scripts/run_regression_gates.py --build release

Run the opt-in, larger CPU-parity timing gates with:

python3 scripts/run_regression_gates.py --build release --include-cpu-parity

The regression harness writes a per-run comparison_summary.csv with the key KSHELL-vs-kshell-cpp timing, peak resident memory, and correctness fields for the gates it ran. The opt-in CPU-parity gates also enforce a timing budget so meaningful cases fail the harness if kshell-cpp drifts clearly slower than KSHELL.

Long interactive runs print coarse progress heartbeats by default. Use --progress-start-after <seconds> and --progress-interval <seconds> to tune the cadence, or --progress 0 to quiet Lanczos and standalone H*x benchmark progress logs in direct solver runs. The comparator and regression harness forward the same idea through compare_kshell.py --progress..., sweep_kshell_compare.py --progress..., and run_regression_gates.py --cpp-progress.... Comparator runs also stream coarse selected KSHELL and kshell-cpp progress lines live while preserving complete per-command logs for parsing.

Normal Lanczos runs stop at --maxiter if convergence has not been reached. For deliberate unbounded runs, --run-until-convergence 1 ignores that epoch cap and keeps restarting until the existing convergence or lucky-breakdown checks stop the solve. This can run indefinitely if convergence is not reached.

Direct solver runs can also write machine-readable frontend artifacts:

./build/run.out 1 2 --interaction resources/interaction_files/w.snt --run-dir runs/w_1p2n

This creates status.jsonl, summary.json, and command.txt under the run directory. The first frontend plan is documented in docs/archive/accepted_features/frontend_plan.md.

A small TOML job adapter is available for the initial schema:

python3 scripts/kshell_cpp_job.py template --output job.toml
python3 scripts/kshell_cpp_job.py run job.toml

The schema covers the accepted CPU solver modes: block Lanczos, target-J refinement, Lawson, wavefunction I/O, snapshot restart, and levels density output, including the opt-in run-until-convergence solver mode.

The first terminal frontend wraps the same schema and can launch or monitor run directories:

scripts/kshell_cpp_ui.py new job.toml
scripts/kshell_cpp_ui.py wizard
scripts/kshell_cpp_ui.py wizard job.toml
scripts/kshell_cpp_ui.py link job.toml
scripts/kshell_cpp_ui.py validate job.toml
scripts/kshell_cpp_ui.py estimate job.toml
scripts/kshell_cpp_ui.py preflight job.toml
scripts/kshell_cpp_ui.py recommend job.toml
scripts/kshell_cpp_ui.py recommend job.toml --apply recommended
scripts/kshell_cpp_ui.py edit job.toml --n-eig 8 --maxiter 80
scripts/kshell_cpp_ui.py run job.toml
scripts/kshell_cpp_ui.py jobs runs
scripts/kshell_cpp_ui.py history runs
scripts/kshell_cpp_ui.py resume runs/w_1p2n
scripts/kshell_cpp_ui.py resume job.toml
scripts/kshell_cpp_ui.py monitor runs/w_1p2n
scripts/kshell_cpp_ui.py monitor job.toml

wizard without an explicit output filename writes <isotope-label>-<interaction-name>.toml, for example 56Fe-gxpf1a.toml. If the user enters manual valence proton/neutron counts instead of an isotope, the wizard derives the isotope label from the selected interaction's inert core. The default run directory uses the same stem under runs/, for example runs/56Fe-gxpf1a. new and wizard create a local kshell-cpp-ui symlink next to the TOML by default, so the calculation directory can use a short command:

cd path/to
./kshell-cpp-ui monitor job.toml

For an existing TOML directory, create the same symlink with scripts/kshell_cpp_ui.py link path/to/job.toml. Pass --no-link-ui to new or wizard if the local launcher is not wanted.

The wizard prompts for the core job fields: interaction, isotope or valence particle counts, parity, number of states, Lanczos block size, and output directory. For isotope input such as 56Fe, it reads the inert-core proton and neutron counts from the selected .snt file and writes the derived valence protons / neutrons into the TOML. Advanced options remain editable in the TOML. The wizard can also enable target-J refinement; it asks for the target J, writes mtot_twice = 2J, and emits explicit [target_j] settings. The default run directory uses the same isotope-interaction stem as the TOML, and the wizard prints a summary for confirmation before writing the file. The interaction prompt tab-completes packaged .snt filenames from resources/interaction_files, and bare names such as gxpf1a.snt resolve to that directory. The jobs command scans run directories and shows active/stopped/completed/failed runs; history shows the frontend launch registry written next to the run directories; resume reattaches to an existing run directory. The edit command updates common TOML fields in place, including output directory, n_eig, maxiter, and target-J enable/disable plus target J. The validate command prints resolved paths, model settings, target-J settings, run-directory warnings, and the exact solver command without running the solver. The preflight command runs validation and then the solver-backed estimate. The recommend command uses the same solver-backed estimate when possible and prints advisory quick_check, recommended, conservative, and many-state block profiles for max_lanc_vec, n_restart_vec, n_block, and run_until_convergence; profiles that enable run_until_convergence intentionally omit maxiter because it is ignored in that mode. Pass --apply PROFILE to update the TOML after review, or add --yes for non-interactive application. The estimate command uses the solver's --estimate-only 1 mode, which reports mdim and vector/output sizing before Hamiltonian work-plan setup. The frontend scripts may be launched from a scratch directory: the default solver binary and repo resources/... paths resolve from the repository, while relative output directories resolve next to the job.toml file. The monitor shows structured Lanczos progress/ETA, recent phase durations, run-directory disk usage, and largest artifacts. It uses curses by default for the live terminal view and clips to the visible terminal size. The curses dashboard keeps a fixed status/progress header and footer, uses restrained status colors when the terminal supports them, shows ASCII progress bars for available Lanczos progress, and supports compact/full detail views. Pass --no-clear to append full plain-text frames instead. The curses monitor uses vim-style controls: q detaches, x cancels after confirmation, v toggles compact/full view, j/k scroll, Ctrl-d/Ctrl-u half-page, Ctrl-f/Ctrl-b page, g/G top/live-tail, r refresh, and ? help. Frontend-launched solver processes run detached from terminal Ctrl+C and write solver.pid; pressing Ctrl+C also stops the UI/monitor while the calculation continues, and the monitor can be reattached with scripts/kshell_cpp_ui.py monitor <run-directory> or scripts/kshell_cpp_ui.py monitor <job.toml>. When given a job TOML, monitor and resume resolve [output].directory and replay that run directory. A second run targeting a run directory that already exists is rejected by default. Pass run --force only to intentionally delete and recreate that run directory before launch; --force is still refused if solver.pid points to a live solver. Change [output].directory for a separate calculation, or reattach and cancel the active one with x, then y.

Curated starter jobs live in examples/jobs/. They cover ordinary levels, block Lanczos, target-J refinement, Lawson, final wavefunction save, and snapshot restart.

Run the frontend smoke with:

scripts/run_frontend_smoke.py

Mixed-parity interactions follow KSHELL's partition parity selector. Direct solver runs accept --parity + or --parity -, and comparator/sweep scripts forward the same option to both KSHELL and kshell-cpp.

Backend Roles

The default backend is kshell-cpu, the accepted CPU implementation that copies KSHELL's block-local wavefunction structure. The active main branch is CPU-focused; paused GPU/generated experiments are preserved on the archive branch archive/full-code-before-cpu-focused-cleanup-20260602.

Backend	Use this when
kshell-cpu	Default CPU path and KSHELL algorithmic/timing baseline.

See docs/strategy.md for the current strategy, docs/gpu_bridge_matvec_plan.md for the planning-only GPU bridge-matvec direction, docs/cpu_performance_metrics.md for CPU performance provenance and fresh-refresh procedure, and docs/diagnostics.md for diagnostic flags. Paused historical GPU design notes remain in docs/paused_*, but their source code is intentionally out of sight on the archive branch.

Install

The active CPU work builds with a C++20 compiler, OpenMP, LAPACKE/LAPACK, spdlog, fmt, and the existing Makefile:

make BUILD=release -j$(nproc)

ROCm/HIP is not required on main. The active GPU bridge plan is documentation only; GPU build notes live only with the paused source on archive/full-code-before-cpu-focused-cleanup-20260602.