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
47 changes: 43 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,9 @@ Every new feature is checked against exact or independent results; see [Validati

### New since v1.2 (unreleased)

- **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.
- **Strong-field physics** (`quantumlab.strongfield`):
- high-harmonic generation from a hydrogen atom (`SoftCoulomb`) in intense laser pulses (`flat_top_envelope`);
- harmonic spectra, Gabor time–frequency maps, the classical three-step model, and attosecond pulse synthesis.
Expand Down Expand Up @@ -80,6 +83,7 @@ quantumlab/
│ ├── split_step_3d.py # 3D Split-Step Fourier solver (CPU/SciPy)
│ ├── split_step_3d_gpu.py # 3D SSFM with CuPy GPU acceleration + CPU fallback
│ ├── split_operator.py # Generic 1D/2D/3D engine: order 2/4, V(r,t), GPE, imaginary time, rotation, damping
│ ├── multicomponent.py # Coupled multi-component Gross–Pitaevskii solver
│ └── backends.py # NumPy/SciPy (CPU) and CuPy (CUDA GPU) array backends
├── stationary/
│ ├── eigensolver.py # Lanczos / preconditioned LOBPCG on a matrix-free Hamiltonian
Expand Down Expand Up @@ -120,7 +124,7 @@ quantumlab/

## Example Gallery

The framework includes 12 pre-built simulation scripts under the `examples/` directory. Run any example to generate high-quality scientific visualizations saved to the `output/` directory.
The framework includes 13 pre-built simulation scripts under the `examples/` directory. Run any example to generate high-quality scientific visualizations saved to the `output/` directory.

---

Expand Down Expand Up @@ -315,6 +319,35 @@ A hydrogen atom (1D soft-core model, I_p = 13.6 eV) is driven by an intense 800

![Cutoff scan](images/12_hhg_cutoff_scan.png)

### 13. Two-Component Condensates (`examples/13_two_component_bec.py`)

Two condensates with intra-species couplings g₁₁ = g₂₂ = g and inter-species coupling g₁₂ obey coupled Gross–Pitaevskii equations. They mix when g₁₂² < g₁₁g₂₂ and separate when g₁₂² > g₁₁g₂₂.

<p align="center">
<img src="images/13_phase_separation.gif" width="45%" alt="Spinodal phase separation">
<img src="images/13_vortex_lattices.gif" width="45%" alt="Interlaced vortex lattices">
</p>
<p align="center"><em>Left: a uniform mixture with g₁₂ = 1.3g separates into domains that coarsen. Right: a rotating two-component condensate forms two interlaced vortex lattices (pink and cyan).</em></p>

**Validation:**
- **Miscibility:** in a trap, the ground-state overlap Λ stays 1.000 up to g₁₂/g = 1.05 and drops to 0.72, 0.31 and 0.16 at 1.1, 1.2 and 1.4. A finite cloud shifts the uniform threshold g₁₂ = g slightly upward, because the domain wall costs gradient energy.
- **Spinodal decomposition:**
- the spin mode on the |k| ≈ k\* shell grows at 0.2992 against the Bogoliubov rate γ\* = n(g₁₂ − g) = 0.3000 (−0.3%);
- the structure factor peaks at k = 0.785 against k\* = 0.775 (within one bin);
- the populations are conserved to 10⁻¹³.
- **Two-colour vortex lattices:** with g₁₂ = 0.5g, Ω = 0.8 and damping, 16 + 15 vortices form. **Every** vortex core of one component sits on a density maximum of the other, at a median 1.8× its local average.
- **Exact limits, from the test and validation suites:**
- g₁₂ = 0 reproduces two independent condensates bit for bit;
- at the Manakov point g₁₁ = g₂₂ = g₁₂ the total density equals the one-component ground state to 2·10⁻⁷;
- the Bogoliubov spin-mode frequency is reproduced to 10⁻⁹ relative;
- the coupled virial theorem holds to 2·10⁻⁶.

![Miscibility](images/13_miscibility.png)

![Growth of the phase-separation instability](images/13_phase_separation_growth.png)

![Interlaced vortex lattices](images/13_vortex_lattices.png)

---

## Validation
Expand All @@ -331,7 +364,7 @@ A hydrogen atom (1D soft-core model, I_p = 13.6 eV) is driven by an intense 800
| 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.68e-14 |
| Harmonic spectrum 1D, 10 levels (Lanczos) | E_n = n + ½ | 5.24e-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 @@ -340,12 +373,16 @@ A hydrogen atom (1D soft-core model, I_p = 13.6 eV) is driven by an intense 800
| 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) | 3.21e-14 |
| 1D soft-core hydrogen ground state | E₀ = −½ a.u. (I_p = 13.6 eV) | 1.61e-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 |

All 21 checks pass. A few rows report something other than a plain error:
All 25 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 @@ -435,6 +472,7 @@ python examples/09_soliton_collision.py
python examples/10_quantum_chaos_stadium.py
python examples/11_rotating_bec_vortex_lattice.py
python examples/12_high_harmonic_generation.py
python examples/13_two_component_bec.py

# CPU vs GPU timing (GPU columns appear only with CuPy and a CUDA device)
python benchmarks/gpu_split_operator.py
Expand Down Expand Up @@ -468,6 +506,7 @@ Test coverage includes:
- `test_volume_3d.py` — isosurface geometry, phase sampling, PNG/GIF/HTML export, overlays
- `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_backends.py` — GPU code path against NumPy through a strict emulated device; a real CuPy comparison runs where a CUDA device exists

---
Expand Down
12 changes: 8 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: 57 s.
Total runtime: 65 s.

| Category | Check | Reference | Metric | Error | Tolerance | Result |
|---|---|---|---|---|---|---|
Expand All @@ -15,7 +15,7 @@ Total runtime: 57 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.68e-14 | 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 | 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,9 +24,13 @@ Total runtime: 57 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₀ + ½\| | 3.21e-14 | 1e-09 | 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 | 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 |

**21/21 checks passed.**
**25/25 checks passed.**
67 changes: 66 additions & 1 deletion benchmarks/validation_suite.py
Original file line number Diff line number Diff line change
Expand Up @@ -242,6 +242,71 @@ def level(q):
'max |spacing − ½| (cycles)', float(np.max(np.abs(spacing - 0.5))), 0.01)


def two_component():
from quantumlab.solvers.multicomponent import CoupledGPESolver
from quantumlab.stationary import coupled_ground_state
box = Grid1D(256, -20 * np.pi, 20 * np.pi)
n, g = 1.0, 1.0

def seeded(k):
return (WaveFunction1D(box, np.sqrt(n) * (1 + 1e-6 * np.cos(k * box.x)) + 0j),
WaveFunction1D(box, np.sqrt(n) * (1 - 1e-6 * np.cos(k * box.x)) + 0j))

def spin(states, k):
return float(np.sum((states[0].probability_density - states[1].probability_density)
* np.cos(k * box.x)) * 2 / box.N)

g12, k = 0.6, box.dk * 10
omega = np.sqrt(k ** 2 / 2 * (k ** 2 / 2 + 2 * n * (g - g12)))
solver = CoupledGPESolver(box, (None, None), [[g, g12], [g12, g]], 0.01, order=4)
state, err = seeded(k), 0.0
for _ in range(12):
state = solver.evolve(state, 500)
err = max(err, abs(spin(state, k) - 4e-6 * np.cos(omega * solver.t)) / 4e-6)
check('Two-component BEC', 'Bogoliubov spin mode, miscible mixture (t ≤ 60)',
'δ(n₁−n₂) ∝ cos ω_s t, ω_s² = ε_k(ε_k + 2n(g − g₁₂))', 'max relative deviation', err, 1e-6)

g12 = 1.3
k = box.dk * np.round(np.sqrt(2 * n * (g12 - g)) / box.dk)
gamma = np.sqrt(k ** 2 / 2 * (2 * n * (g12 - g) - k ** 2 / 2))
solver = CoupledGPESolver(box, (None, None), [[g, g12], [g12, g]], 0.01, order=4)
state, t, amp = seeded(k), [], []
while not amp or amp[-1] < 1e-3:
state = solver.evolve(state, 100)
t.append(solver.t)
amp.append(abs(spin(state, k)))
t, amp = np.array(t), np.array(amp)
rate = np.polyfit(t[amp > 1.2e-4], np.log(amp[amp > 1.2e-4]), 1)[0]
check('Two-component BEC', 'Phase-separation instability, g₁₂ = 1.3 g', 'growth rate γ = √(ε_k(2n(g₁₂ − g) − ε_k))',
'|γ_measured/γ − 1|', abs(rate / gamma - 1), 1e-3)

grid = Grid2D(64, -8.0, 8.0, 64, -8.0, 8.0)
trap, G = HarmonicTrap((1.0, 1.3)), 60.0
a = WaveFunction2D.gaussian(grid, 1.0, 0.0, 0.0, 0.0, 1.0, 1.0)
b = WaveFunction2D.gaussian(grid, -1.0, 0.5, 0.0, 0.0, 1.0, 1.0)
a.psi *= np.sqrt(0.3)
b.psi *= np.sqrt(0.7)
(s1, s2), _ = coupled_ground_state(grid, (trap, trap), [[G, G], [G, G]], (a, b), dtau=0.005)
single, _ = ground_state(grid, trap, dtau=0.005, nonlinearity=G)
check('Two-component BEC', 'Manakov point g₁₁ = g₂₂ = g₁₂', 'n₁ + n₂ equals the one-component GP ground state',
'max |n₁ + n₂ − n|', float(np.max(np.abs(s1.probability_density + s2.probability_density
- single.probability_density))), 1e-6)

G2 = np.array([[100.0, 70.0], [70.0, 120.0]])
grid = Grid2D(80, -9.0, 9.0, 80, -9.0, 9.0)
a = WaveFunction2D.gaussian(grid, 1.5, 0.0, 0.0, 0.0, 1.0, 1.0)
b = WaveFunction2D.gaussian(grid, -1.5, 0.0, 0.0, 0.0, 1.0, 1.0)
a.psi *= np.sqrt(0.5)
b.psi *= np.sqrt(0.5)
states, _ = coupled_ground_state(grid, (HarmonicTrap(1.0), HarmonicTrap(1.0)), G2, (a, b), dtau=0.005)
T = sum(kinetic_energy_expectation(s) for s in states)
V = sum(potential_energy_expectation(s, HarmonicTrap(1.0)) for s in states)
nn = [s.probability_density for s in states]
E_int = 0.5 * sum(G2[i, j] * np.sum(nn[i] * nn[j]) for i in range(2) for j in range(2)) * grid.dx * grid.dy
check('Two-component BEC', 'Virial theorem, coupled GP ground state', '2⟨T⟩ − 2⟨V⟩ + 2E_int = 0 (2D)',
'|2T − 2V + 2E_int| / V', abs(2 * T - 2 * V + 2 * E_int) / V, 1e-4)


def write_report(path, elapsed):
lines = [
'# QuantumLab validation report',
Expand Down Expand Up @@ -271,7 +336,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):
rotating_frame, high_harmonics, two_component):
print(f'{fn.__name__}:')
fn()
out = Path(__file__).with_name('validation_report.md')
Expand Down
2 changes: 2 additions & 0 deletions docs/api/solvers.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Generated from the docstrings in the source code.

::: quantumlab.solvers.split_operator

::: quantumlab.solvers.multicomponent

::: quantumlab.solvers.backends

::: quantumlab.solvers.split_step_1d
Expand Down
13 changes: 13 additions & 0 deletions docs/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,3 +86,16 @@ A hydrogen atom (soft-core model, I_p = 13.6 eV) is driven by an 800 nm pulse at
![Electron in space and time](images/12_electron_spacetime.png)
![Cutoff scan](images/12_hhg_cutoff_scan.png)

## 13. Two-component condensates

Two condensates with couplings g₁₁ = g₂₂ = g and g₁₂:
- **Miscibility:** in a trap, the overlap of the ground states drops sharply just above g₁₂ = g. The uniform criterion is g₁₂² = g₁₁g₂₂, and a finite cloud shifts the transition slightly upward.
- **Spinodal decomposition:** a uniform mixture with g₁₂ = 1.3g separates into labyrinthine domains. Their growth on the |k| ≈ k\* shell matches the Bogoliubov rate γ\* = n(g₁₂ − g) to 0.3%, and the structure-factor peak sits at k\* within one bin. Afterwards the domains coarsen.
- **Two-colour vortex lattices:** in a rotating trap both components nucleate vortices, which interlace. Every vortex core of one component sits on a density maximum of the other, at a median 1.8× its local average.

![Phase separation](images/13_phase_separation.gif)
![Interlaced vortex lattices](images/13_vortex_lattices.gif)
![Miscibility](images/13_miscibility.png)
![Growth of the instability](images/13_phase_separation_growth.png)
![Interlaced lattices](images/13_vortex_lattices.png)

43 changes: 43 additions & 0 deletions docs/guide/multicomponent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
# Two-component condensates

[`CoupledGPESolver`](../api/solvers.md) integrates coupled Gross–Pitaevskii equations for condensates of equal mass, for example two hyperfine states of ⁸⁷Rb:

> iℏ ∂ψ_i/∂t = [ −ℏ²∇²/2m + V_i(r) + Σ_j g_ij |ψ_j|² − ΩL_z ] ψ_i

```python
from quantumlab.solvers.multicomponent import CoupledGPESolver
from quantumlab.stationary import coupled_ground_state

G = [[100.0, 120.0],
[120.0, 100.0]] # g11, g12 / g21, g22 (symmetric)
states, info = coupled_ground_state(grid, (trap, trap), G, (guess_1, guess_2), dtau=0.005)
print(info.chemical_potentials, info.residuals)

solver = CoupledGPESolver(grid, (trap, trap), G, dt=0.005, order=4, rotation=0.8)
psi_1, psi_2 = solver.evolve(states, 1000)
```

- The solver supports the same options as `SplitOperatorSolver`: order 2/4, imaginary time, rotation, damping and the GPU backend.
- Each component keeps its own particle number, which is the norm of its initial state.
- In real time the coupled potential step is exact. In imaginary time and with damping it uses rescaled midpoint densities, as for one component.

## Miscibility

A uniform mixture with g₁₁, g₂₂ > 0 is stable (**miscible**) when g₁₂² < g₁₁g₂₂ and separates into domains (**immiscible**) when g₁₂² > g₁₁g₂₂. `miscibility_overlap(wf_1, wf_2)` gives Λ = ∫n₁n₂ / √(∫n₁²∫n₂²): 1 for identical profiles, close to 0 for separated ones. In a trap the transition is slightly shifted above g₁₂ = g, because the domain wall between the components costs gradient energy.

!!! tip
Immiscible ground states break the symmetry between the components. Start imaginary time from a guess that already breaks it, e.g. displaced clouds; a symmetric guess can stay on a symmetric saddle point.

## Dynamics and the Bogoliubov spin mode

For equal densities n and g₁₁ = g₂₂ = g, small differences between the components (the *spin* mode) obey

> ω_s(k)² = ε_k (ε_k + 2n(g − g₁₂)), ε_k = ℏ²k²/2m

For g₁₂ < g these are stable oscillations. For g₁₂ > g the long wavelengths become unstable and grow as e^{γt}, fastest at k\* = √(2mn(g₁₂ − g))/ℏ with γ\* = n(g₁₂ − g). This **spinodal decomposition** is reproduced to 10⁻⁹ (frequency) and 10⁻⁴ (growth rate) in the validation suite.

`coupled_gp_energy` gives the conserved total energy Σ(⟨T⟩ + ⟨V_i⟩) + ½Σg_ij∫n_in_j.

## Numerical stability

For nonlinear real-time runs on a uniform background, keep the kinetic phase of the shortest grid wavelength below π per (sub)step, i.e. ℏk_max²/2m · |w|dt < π with k_max = π/dx (|w| ≤ 1.71 for order 4). Above it, the split-step method has a parametric instability in which round-off noise grows (Weideman & Herbst 1986).
Loading
Loading