Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 15 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,10 @@ Every new feature is checked against exact or independent results; see [Validati

### New since v1.2 (unreleased)

- **Conjugate-gradient ground states** (`ground_state_pcg`):
- preconditioned nonlinear conjugate gradient on the sphere ‖ψ‖² = N, with an exact fixed point (no dτ error);
- converges on soft modes such as vortex lattices where imaginary time stalls;
- `ground_state` also accepts a decreasing dτ schedule.
- **Two-component condensates** (`CoupledGPESolver`, `coupled_ground_state`):
- coupled Gross–Pitaevskii equations, with rotation, damping and GPU support;
- miscibility, spinodal phase separation, and interlaced two-colour vortex lattices.
Expand Down Expand Up @@ -279,16 +283,18 @@ A condensate at rest is placed in a slightly anisotropic trap rotating at Ω = 0
<img src="images/11_vortex_lattice_formation.gif" width="80%" alt="Vortex lattice formation">
</p>

The 2D lattice then seeds a 3D condensate in a cigar-shaped rotating trap (128 × 128 × 64 grid). After 3000 imaginary-time steps in the rotating frame (residual ‖(H − ΩL_z)ψ − μψ‖ = 1.6 × 10⁻³), 18 vortex lines run through the cloud. Below they are drawn as tubes where the density falls below 30% of its local average.
The 2D lattice then seeds a 3D condensate in a cigar-shaped rotating trap (128 × 128 × 64 grid). Vortex lattices have very soft modes. Imaginary time alone, even with a decreasing dτ schedule, stalled near a residual of 3 × 10⁻³ after about 20 000 steps, so the stationary state is found by **conjugate-gradient energy minimisation**, which brings the residual ‖(H − ΩL_z)ψ − μψ‖ below 10⁻⁶ (9.98 × 10⁻⁷ after 9276 iterations). 19 vortex lines run through the cloud. Below they are drawn as tubes where the density falls below 30% of its local average.

<p align="center">
<img src="images/11_vortex_lines_3d.gif" width="60%" alt="3D vortex lines">
</p>

**Validation:**
- Feynman's rule for a rigidly rotating superfluid, n_v = mΩ/(πℏ), predicts a triangular-lattice spacing of 2.129.
- The measured mean nearest-neighbour spacing is 2.034 ± 0.065 in 2D (−4.5%) and 2.044 ± 0.069 in the z = 0 plane of the 3D state (−4.0%).
- Feynman's rule is exact for an infinite uniform lattice. This one has only 18 vortices in an inhomogeneous cloud, so deviations of a few percent are expected.
- The measured mean nearest-neighbour spacing is 2.034 ± 0.065 in 2D (−4.5%) and 2.072 ± 0.059 in the z = 0 plane of the 3D state (−2.7%).
- Feynman's rule is exact for an infinite uniform lattice. This one has only 18–19 vortices in an inhomogeneous cloud, so deviations of a few percent are expected.
- All 19 lines can be followed slice by slice through the central region |z| ≤ 0.6Z. The inner lines stay in the same grid cell, and the outer ring bends outwards by at most 0.35 (about two grid spacings).
- The minimiser lowers the energy at every step, so it ends in a local energy minimum, not necessarily the global one. A run from a different seed converged to an 18-line lattice whose energy is 3 × 10⁻⁵ (relative) higher.
- The rotating-frame solver itself is checked exactly in the validation suite.

![Final 2D vortex lattice](images/11_vortex_lattice_2d.png)
Expand Down Expand Up @@ -364,7 +370,7 @@ Two condensates with intra-species couplings g₁₁ = g₂₂ = g and inter-spe
| Energy conservation, 3D, 500 steps (order 4) | E(t) = E(0) | 2.18e-10 |
| Minimum-uncertainty Gaussian (3D) | Δr_j Δp_j = ℏ/2 for each axis | 4.60e-12 |
| Angular momentum of a vortex state | ⟨L_z⟩ = ℏ for ψ ∝ (x+iy)e^{−r²/2} | 2.22e-16 |
| Harmonic spectrum 1D, 10 levels (Lanczos) | E_n = n + ½ | 5.24e-14 |
| Harmonic spectrum 1D, 10 levels (Lanczos) | E_n = n + ½ | 7.28e-14 |
| Anisotropic 3D harmonic spectrum, 6 levels (LOBPCG) | E = Σ ω_j (n_j + ½) | 1.42e-13 |
| 3D ground state by imaginary time | E₀ = ½(ω_x+ω_y+ω_z) | 6.95e-10 |
| Spectrum from autocorrelation (Feit–Fleck) | peaks of FFT[C(t)] at n + ½ | 1.62e-03 |
Expand All @@ -373,16 +379,18 @@ Two condensates with intra-species couplings g₁₁ = g₂₂ = g and inter-spe
| Imaginary-time GP ground state accuracy | residual ∝ dτ² (ratio 4 when halving dτ) | 2.23e-03 |
| Coherent state in a frame rotating at Ω = 0.6 | ⟨r'⟩ = R(−Ωt)·(x₀ cos ωt, 0) | 1.89e-08 |
| Vortex eigenstate in the rotating frame | C(t) = e^{−i(2ℏω − Ωℏ)t/ℏ} | 1.15e-08 |
| 1D soft-core hydrogen ground state | E₀ = −½ a.u. (I_p = 13.6 eV) | 1.61e-14 |
| 1D soft-core hydrogen ground state | E₀ = −½ a.u. (I_p = 13.6 eV) | 1.94e-14 |
| Three-step model maximum return energy | max E_return = 3.17 U_p | 3.63e-05 |
| HHG: only odd harmonics (800 nm, 10¹⁴ W/cm²) | inversion symmetry forbids even orders | 4.30e-04 |
| Attosecond pulse train (H11–H21) | one burst per half laser cycle | 3.08e-03 |
| Bogoliubov spin mode, miscible mixture (t ≤ 60) | δ(n₁−n₂) ∝ cos ω_s t, ω_s² = ε_k(ε_k + 2n(g − g₁₂)) | 8.53e-10 |
| Phase-separation instability, g₁₂ = 1.3 g | growth rate γ = √(ε_k(2n(g₁₂ − g) − ε_k)) | 9.39e-05 |
| Manakov point g₁₁ = g₂₂ = g₁₂ | n₁ + n₂ equals the one-component GP ground state | 1.76e-07 |
| Virial theorem, coupled GP ground state | 2⟨T⟩ − 2⟨V⟩ + 2E_int = 0 (2D) | 2.27e-06 |
| Conjugate-gradient minimiser, hydrogen (V < 0) | E₀ = −½ a.u. | 7.77e-16 |
| Virial theorem, 3D GP ground state (conjugate gradient) | 2⟨T⟩ − 2⟨V⟩ + 3E_int = 0, no dτ error | 5.79e-10 |

All 25 checks pass. A few rows report something other than a plain error:
All 27 checks pass. A few rows report something other than a plain error:
- The two convergence rows give the deviation of the observed order (2.001 and 3.997) from the theoretical one.
- The Feit–Fleck row is limited by the spectral resolution 2π/T ≈ 0.031.
- The GP ground-state accuracy row gives the relative deviation of the observed residual ratio (3.99) from 4.
Expand Down Expand Up @@ -507,6 +515,7 @@ Test coverage includes:
- `test_rotation.py` — rotating-frame coherent state, vortex eigenstate, E − ΩL_z conservation, damping, vortex lattice energy
- `test_strongfield.py` — laser units, three-step 3.17 U_p, hydrogen ground state, spectra, Gabor maps, attosecond pulses, Ehrenfest acceleration
- `test_multicomponent.py` — uncoupled limit, Manakov point, Bogoliubov spin mode and phase-separation growth rate, energy and population conservation, coupled virial theorem
- `test_conjugate_gradient.py` — exact linear ground states (including V < 0 and ℏ, m ≠ 1), GP virial theorem without a dτ floor, rotating vortex lattice below imaginary time
- `test_backends.py` — GPU code path against NumPy through a strict emulated device; a real CuPy comparison runs where a CUDA device exists

---
Expand Down
10 changes: 6 additions & 4 deletions benchmarks/validation_report.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
Generated by `python benchmarks/validation_suite.py`. Every row compares a
simulation with an exact, analytic or independent numerical reference.
Platform: Python 3.14.6, NumPy 2.4.6, arm64.
Total runtime: 65 s.
Total runtime: 73 s.

| Category | Check | Reference | Metric | Error | Tolerance | Result |
|---|---|---|---|---|---|---|
Expand All @@ -15,7 +15,7 @@ Total runtime: 65 s.
| Dynamics | Energy conservation, 3D, 500 steps (order 4) | E(t) = E(0) | \|ΔE/E\| | 2.18e-10 | 1e-08 | pass |
| Observables | Minimum-uncertainty Gaussian (3D) | Δr_j Δp_j = ℏ/2 for each axis | max \|Δr Δp − ½\| | 4.60e-12 | 1e-08 | pass |
| Observables | Angular momentum of a vortex state | ⟨L_z⟩ = ℏ for ψ ∝ (x+iy)e^{−r²/2} | \|⟨L_z⟩ − 1\| | 2.22e-16 | 1e-10 | pass |
| Stationary states | Harmonic spectrum 1D, 10 levels (Lanczos) | E_n = n + ½ | max \|E_n − exact\| | 5.24e-14 | 1e-10 | pass |
| Stationary states | Harmonic spectrum 1D, 10 levels (Lanczos) | E_n = n + ½ | max \|E_n − exact\| | 7.28e-14 | 1e-10 | pass |
| Stationary states | Anisotropic 3D harmonic spectrum, 6 levels (LOBPCG) | E = Σ ω_j (n_j + ½) | max \|E − exact\| | 1.42e-13 | 1e-08 | pass |
| Stationary states | 3D ground state by imaginary time | E₀ = ½(ω_x+ω_y+ω_z) | \|E₀ − exact\| | 6.95e-10 | 1e-07 | pass |
| Stationary states | Spectrum from autocorrelation (Feit–Fleck) | peaks of FFT[C(t)] at n + ½ | max peak offset (resolution 2π/T = 0.031) | 1.62e-03 | 3e-03 | pass |
Expand All @@ -24,13 +24,15 @@ Total runtime: 65 s.
| Gross–Pitaevskii | Imaginary-time GP ground state accuracy | residual ∝ dτ² (ratio 4 when halving dτ) | observed ratio 3.99 | 2.23e-03 | 1e-01 | pass |
| Rotating frame | Coherent state in a frame rotating at Ω = 0.6 | ⟨r'⟩ = R(−Ωt)·(x₀ cos ωt, 0) | max \|⟨r'⟩ − exact\| | 1.89e-08 | 1e-07 | pass |
| Rotating frame | Vortex eigenstate in the rotating frame | C(t) = e^{−i(2ℏω − Ωℏ)t/ℏ} | \|C(t) − exact\| | 1.15e-08 | 1e-07 | pass |
| Strong-field physics | 1D soft-core hydrogen ground state | E₀ = −½ a.u. (I_p = 13.6 eV) | \|E₀ + ½\| | 1.61e-14 | 1e-09 | pass |
| Strong-field physics | 1D soft-core hydrogen ground state | E₀ = −½ a.u. (I_p = 13.6 eV) | \|E₀ + ½\| | 1.94e-14 | 1e-09 | pass |
| Strong-field physics | Three-step model maximum return energy | max E_return = 3.17 U_p | \|max/U_p − 3.1731\| | 3.63e-05 | 2e-04 | pass |
| Strong-field physics | HHG: only odd harmonics (800 nm, 10¹⁴ W/cm²) | inversion symmetry forbids even orders | even/odd intensity, H5–H20 (odd/even = 2.3e+03) | 4.30e-04 | 1e-02 | pass |
| Strong-field physics | Attosecond pulse train (H11–H21) | one burst per half laser cycle | max \|spacing − ½\| (cycles) | 3.08e-03 | 1e-02 | pass |
| Two-component BEC | Bogoliubov spin mode, miscible mixture (t ≤ 60) | δ(n₁−n₂) ∝ cos ω_s t, ω_s² = ε_k(ε_k + 2n(g − g₁₂)) | max relative deviation | 8.53e-10 | 1e-06 | pass |
| Two-component BEC | Phase-separation instability, g₁₂ = 1.3 g | growth rate γ = √(ε_k(2n(g₁₂ − g) − ε_k)) | \|γ_measured/γ − 1\| | 9.39e-05 | 1e-03 | pass |
| Two-component BEC | Manakov point g₁₁ = g₂₂ = g₁₂ | n₁ + n₂ equals the one-component GP ground state | max \|n₁ + n₂ − n\| | 1.76e-07 | 1e-06 | pass |
| Two-component BEC | Virial theorem, coupled GP ground state | 2⟨T⟩ − 2⟨V⟩ + 2E_int = 0 (2D) | \|2T − 2V + 2E_int\| / V | 2.27e-06 | 1e-04 | pass |
| Stationary states | Conjugate-gradient minimiser, hydrogen (V < 0) | E₀ = −½ a.u. | \|E₀ + ½\| | 7.77e-16 | 1e-12 | pass |
| Gross–Pitaevskii | Virial theorem, 3D GP ground state (conjugate gradient) | 2⟨T⟩ − 2⟨V⟩ + 3E_int = 0, no dτ error | \|2T − 2V + 3E_int\| / V | 5.79e-10 | 1e-08 | pass |

**25/25 checks passed.**
**27/27 checks passed.**
15 changes: 14 additions & 1 deletion benchmarks/validation_suite.py
Original file line number Diff line number Diff line change
Expand Up @@ -307,6 +307,19 @@ def spin(states, k):
'|2T − 2V + 2E_int| / V', abs(2 * T - 2 * V + 2 * E_int) / V, 1e-4)


def energy_minimiser():
from quantumlab.stationary import ground_state_pcg
_, info = ground_state_pcg(Grid1D(2048, -100.0, 100.0), SoftCoulomb(), tol=1e-10)
check('Stationary states', 'Conjugate-gradient minimiser, hydrogen (V < 0)', 'E₀ = −½ a.u.',
'|E₀ + ½|', abs(info.energy + 0.5), 1e-12)
grid = Grid3D(48, -8.0, 8.0, 48, -8.0, 8.0, 48, -8.0, 8.0)
trap, g = HarmonicTrap((1.0, 1.2, 1.4)), 60.0
wf, info = ground_state_pcg(grid, trap, nonlinearity=g, tol=1e-9)
T, V, Ei = kinetic_energy_expectation(wf), potential_energy_expectation(wf, trap), interaction_energy(wf, g)
check('Gross–Pitaevskii', 'Virial theorem, 3D GP ground state (conjugate gradient)',
'2⟨T⟩ − 2⟨V⟩ + 3E_int = 0, no dτ error', '|2T − 2V + 3E_int| / V', abs(2 * T - 2 * V + 3 * Ei) / V, 1e-8)


def write_report(path, elapsed):
lines = [
'# QuantumLab validation report',
Expand Down Expand Up @@ -336,7 +349,7 @@ def main():
t0 = time.time()
for fn in (free_spreading, convergence_orders, driven_oscillator, norm_energy_3d, heisenberg_3d,
vortex_lz, harmonic_spectra, feit_fleck, bright_soliton, gp_virial, gp_dtau_order,
rotating_frame, high_harmonics, two_component):
rotating_frame, high_harmonics, two_component, energy_minimiser):
print(f'{fn.__name__}:')
fn()
out = Path(__file__).with_name('validation_report.md')
Expand Down
2 changes: 2 additions & 0 deletions docs/api/stationary.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,6 @@ Generated from the docstrings in the source code.

::: quantumlab.stationary.imaginary_time

::: quantumlab.stationary.conjugate_gradient

::: quantumlab.stationary.hamiltonian
2 changes: 1 addition & 1 deletion docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ The first 60 eigenstates of a chaotic billiard computed with LOBPCG. LOBPCG and

## 11. Vortex lattice in a rotating BEC

A condensate in a rotating, slightly anisotropic trap develops surface instabilities. Vortices then enter and crystallise into a triangular lattice of 18 vortices (dissipative GPE, following Tsubota, Kasamatsu & Ueda 2002). The mean lattice spacing is within 4.5% of Feynman's rule n_v = mΩ/πℏ, which is exact only for an infinite uniform lattice. The 3D version shows the vortex lines.
A condensate in a rotating, slightly anisotropic trap develops surface instabilities. Vortices then enter and crystallise into a triangular lattice of 18 vortices (dissipative GPE, following Tsubota, Kasamatsu & Ueda 2002). The mean lattice spacing is within 4.5% (2D) and 2.7% (3D) of Feynman's rule n_v = mΩ/πℏ, which is exact only for an infinite uniform lattice. The 3D state is found by conjugate-gradient energy minimisation (residual below 10⁻⁶) and shows 19 nearly straight vortex lines.

![Vortex lattice formation](images/11_vortex_lattice_formation.gif)
![Vortex lines](images/11_vortex_lines_3d.gif)
Expand Down
23 changes: 22 additions & 1 deletion docs/guide/stationary.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,27 @@ print(info.converged, info.energy, info.chemical_potential, info.residual)
- A good initial guess helps. For BECs, a Thomas–Fermi profile is a good choice.
- `excited_states` finds the lowest states one by one with Gram–Schmidt projection (linear problems only).

### Continuation in dτ

`dtau` can also be a decreasing sequence, e.g. `dtau=[0.04, 0.01, 0.0025]`. The large steps relax slow modes in few iterations, and the small ones lower the O(dτ²) error floor. `max_steps` and `tol` apply per stage.

## Conjugate-gradient energy minimisation

[`ground_state_pcg`](../api/stationary.md) minimises the (Gross–Pitaevskii) energy directly on the sphere ‖ψ‖² = N with a preconditioned nonlinear conjugate-gradient method (Antoine, Levitt & Tang, *J. Comput. Phys.* **343**, 92 (2017)):

```python
from quantumlab.stationary import ground_state_pcg

wf, info = ground_state_pcg(grid, trap, initial=guess, nonlinearity=500.0, rotation=0.8, tol=1e-8)
print(info.converged, info.steps, info.residual)
```

Use it when imaginary time is too slow or not accurate enough:
- **Exact fixed point.** There is no dτ, so the residual ‖Hψ − μψ‖ can be driven to ~10⁻¹⁰. In the validation suite the 3D Gross–Pitaevskii virial theorem holds to 10⁻⁹, against 10⁻⁵–10⁻⁶ from imaginary time.
- **Soft modes.** Vortex lattices and elongated condensates have modes with tiny energy gaps. Imaginary time relaxes them as e^{−Δτ}, while conjugate directions converge on them much faster. In [example 11](../examples.md#11-vortex-lattice-in-a-rotating-bec) a 3D vortex lattice on a 128 × 128 × 64 grid reaches a residual below 10⁻⁶ in about 9300 iterations; imaginary time stalled near 3 × 10⁻³.

The preconditioner combines the kinetic operator (in Fourier space) and the potential plus mean field (in real space), so it works with both stiff kinetic and stiff potential terms, including attractive potentials such as `SoftCoulomb`. Near convergence the line search switches from energy values to directional derivatives, which stay resolvable below residuals of 10⁻⁷.

### Rotating frames and vortex states

`ground_state(..., rotation=Ω)` works in the rotating frame, and energies and μ refer to H − ΩL_z. Above the critical rotation the ground state contains vortices. Imaginary time reaches it only from a guess that breaks rotational symmetry, for example an imprinted vortex or a lattice obtained from damped real-time dynamics, as in [example 11](../examples.md#11-vortex-lattice-in-a-rotating-bec).
`ground_state(..., rotation=Ω)` works in the rotating frame, and energies and μ refer to H − ΩL_z. Above the critical rotation the ground state contains vortices. Imaginary time (or the conjugate-gradient minimiser) reaches it only from a guess that breaks rotational symmetry, for example an imprinted vortex or a lattice obtained from damped real-time dynamics, as in [example 11](../examples.md#11-vortex-lattice-in-a-rotating-bec).
Loading
Loading