[rasidi3112]

Converges the 3D vortex lattice of example 11 fully. Before this change imaginary time left it at a residual of 1.6 × 10⁻³.

Conjugate-gradient ground states (ground_state_pcg)

• Preconditioned nonlinear conjugate gradient on the sphere ‖ψ‖² = N, following Antoine, Levitt & Tang, J. Comput. Phys. 343, 92 (2017).
  • Preconditioner P_T^½ P_V P_T^½: the kinetic part acts in Fourier space, the potential plus mean field in real space.
  • The fixed point is exact, so there is no O(dτ²) error.
  • It converges on soft modes such as vortex lattices, where imaginary time stalls.
• Works with rotation, nonlinearity, V < 0 and ℏ, m ≠ 1. The initial norm is kept.
• Line search: a quadratic fit of the energy while energy differences are resolvable, then a secant step on the directional derivative. This keeps convergence going below residuals of 10⁻⁷.
• ground_state also accepts a decreasing dτ schedule (continuation). The existing API is unchanged.

Example 11: converged 3D lattice

• Imaginary time, even with a dτ schedule, stalled near a residual of 3 × 10⁻³ after about 20 000 steps. The minimiser reaches 9.98 × 10⁻⁷ in 9276 iterations on a 128 × 128 × 64 grid, about 40 minutes on a CPU.
• 19 vortex lines cross z = 0. Their spacing is 2.072 ± 0.059, against 2.129 from Feynman's rule (−2.7%).
• Straightness is now measured by following each line slice by slice. The old nearest-neighbour check matched a line that leaves the detection region to its neighbour and reported a spurious 2.04.
  • All 19 lines are followed through |z| ≤ 0.6Z.
  • The inner lines stay in one grid cell, and the outer ring bends outwards by at most 0.35.
• The README and docs describe the result as a local energy minimum. A run from a different seed gave an 18-line lattice 3 × 10⁻⁵ higher in energy.

Validation

• New tests (tests/test_conjugate_gradient.py):
  • exact linear ground states to 10⁻¹² (1D/3D harmonic, soft Coulomb, ℏ = 0.7, m = 0.5);
  • 3D GP virial theorem below 10⁻⁸;
  • rotating vortex lattice below the imaginary-time energy;
  • norm preservation, callback and input checks.
• Validation suite (now 27/27):
  • hydrogen |E₀ + ½| = 7.8 × 10⁻¹⁶;
  • 3D GP virial 5.8 × 10⁻¹⁰, against 2.3 × 10⁻⁶ from imaginary time.
• pytest: 147 passed, 12 skipped (CuPy not installed). mkdocs build --strict passes.

Docs

• Guide sections on dτ continuation and conjugate-gradient minimisation.
• API reference for the new module.
• Updated example 11 text, README table and 3D GIF/PNG.