Summary

Adds a lightweight restart mechanism that seeds SCF from Mulliken shell charges together with atomic dipole and quadrupole moments. Provides C and Python APIs (including spin-resolved support), wires the guess into wavefunction initialization, and adds tests and a Python example. Default behavior is unchanged unless a guess is explicitly provided.

Motivation

• Reduce restart payload size vs. full density/coefficients.
• Enable portable restarts across language bindings (C, Python).
• Support both closed-shell and open-shell calculations.

Key changes

• Wavefunction seeding from compact restart data:

  • If a guess is provided, initialize wfn%qsh, wfn%dpat, wfn%qpat, and derive wfn%qat via get_qat_from_qsh.
  • Strict shape checks; all three arrays are required together.
  • Implementation in src/tblite/api/calculator.f90 (check_wavefunction and call site).

• Result container extended to hold restart guess:

  • charges_guess_shell [nsh, nspin], dpat_guess [3, nat, nspin], qmat_guess [6, nat, nspin].
  • Allocation/population added in C-bindings.
  • Implementation in src/tblite/api/result.f90.

• C API:

  • tblite_set_result_shell_charges_and_moments_guess(...) (closed-shell).
  • tblite_set_result_shell_charges_and_moments_guess_spin(...) (spin-resolved).
  • Declarations in include/tblite/result.h, implementations in src/tblite/api/result.f90.

• Python API:

  • Result.set("shell-charges-and-moments-guess", (qsh, dpat, qmat)).
  • Shape normalization and dispatch to the appropriate C API (closed-shell vs. spin).
  • Implemented in python/tblite/interface.py and python/tblite/library.py.

• Tests and example:

  • New C test test_calc_restart_compressed in test/api/main.c: compares energy from compressed restart vs. full run (closed-shell).
  • Example script restart_from_charges.py: demonstrates compressed restart and compares to a full wavefunction restart; includes a spin-polarized path.

API additions

• C:
  • tblite_set_result_shell_charges_and_moments_guess(error, res, qsh, nsh, dpat, nat, qmat, nat2)
  • tblite_set_result_shell_charges_and_moments_guess_spin(error, res, qsh, nsh, dpat, nat, qmat, nat2, nspin)
• Python:
  • Result.set("shell-charges-and-moments-guess", (qsh, dpat, qmat))
  • Accepted shapes:
    • qsh: (nsh,) or (2, nsh)
    • dpat: (nat, 3)/(3, nat) or (2, nat, 3)/(2, 3, nat)
    • qmat: (nat, 6)/(6, nat) or (2, nat, 6)/(2, 6, nat)

Behavior and validation

• Providing qsh also requires providing dpat and qmat; otherwise, a fatal error is raised via the context.
• Shapes are validated against the system (nat, nsh) and active spin count.
• Without a guess, existing initialization is unchanged.

Backward compatibility

• No breaking changes. Behavior is identical unless the new setter APIs are used.

Affected files

• src/tblite/api/calculator.f90 (consume guess, seed wfn)
• src/tblite/api/result.f90 (store and set guess; C bindings)
• include/tblite/result.h (C API declarations)
• python/tblite/interface.py (setter wiring)
• python/tblite/library.py (shape normalization, C calls)
• test/api/main.c (new compressed-restart test)

Tests

• test_calc_restart_compressed verifies energy agreement (closed-shell) when restarting from (qsh, dpat, qmat).

Notes

• CLI behavior unchanged.
• Documentation and changelog entries can be added in a follow-up.