This section describes complete, runnable examples demonstrating various capabilities of schr. All examples are available in the examples/ directory and include animated visualizations of quantum phenomena.
Table of Contents
File: examples/free_particle_1d.py
Physics:
A free particle is described by the time-dependent Schrödinger equation with zero potential:
i\hbar \frac{\partial \psi}{\partial t} = -\frac{\hbar^2}{2m} \frac{\partial^2 \psi}{\partial x^2}
For a Gaussian wavepacket with initial width \sigma_0 and momentum p_0:
\psi(x, 0) = \frac{1}{(\pi \sigma_0^2)^{1/4}}
\exp\left(-\frac{x^2}{2\sigma_0^2} + \frac{ip_0 x}{\hbar}\right)
The wavepacket spreads in time due to quantum dispersion. The width evolves as:
\sigma(t) = \sigma_0 \sqrt{1 + \left(\frac{\hbar t}{2m\sigma_0^2}\right)^2}
The center of the wavepacket moves with group velocity v_g = p_0/m, while the dispersion causes the uncertainty \Delta x to increase over time, satisfying the time-energy uncertainty relation.
Visualization:
The example generates an animated movie showing the probability density |\psi(x,t)|^2 evolving in time, along with a plot comparing the numerical width evolution with the analytical prediction.
File: examples/tunneling_1d.py
Physics:
Quantum tunneling allows particles to penetrate classically forbidden regions. Consider a rectangular barrier:
V(x) =
\begin{cases}
V_0 & \text{if } |x - x_0| < a/2 \\
0 & \text{otherwise}
\end{cases}
For a particle with energy E < V_0, the wavefunction inside the barrier (E < V) decays exponentially:
\psi(x) \propto e^{-\kappa x}, \quad \kappa = \sqrt{2m(V_0 - E)}/\hbar
The transmission coefficient through a rectangular barrier of width a is:
T = \frac{1}{1 + \dfrac{V_0^2 \sinh^2(\kappa a)}{4E(V_0 - E)}}
For \kappa a \gg 1, this simplifies to T \approx 16\dfrac{E}{V_0}\left(1 - \dfrac{E}{V_0}\right) e^{-2\kappa a}.
The wavefunction exhibits interference between incident, reflected, and transmitted components, producing characteristic oscillations near the barrier edges.
Visualization:
The example creates an animated movie showing a Gaussian wavepacket encountering the potential barrier. The animation clearly shows the wavepacket splitting into reflected and transmitted parts, with the transmitted amplitude significantly smaller than classically expected.
Key Observable: Transmission and reflection coefficients compared with analytical predictions.
File: examples/double_slit.py
Physics:
The double-slit experiment demonstrates wave-particle duality. A plane wave or wavepacket passes through two slits separated by distance d, creating an interference pattern on a distant screen.
The interference pattern arises from the superposition:
\psi(x, y, t) = \psi_1(x, y, t) + \psi_2(x, y, t)
where \psi_1 and \psi_2 are contributions from each slit. The probability density |\psi|^2 exhibits fringes with spacing:
\Delta y = \frac{\lambda L}{d}
where \lambda = 2\pi\hbar/p is the de Broglie wavelength, L is the distance to the screen, and p is the particle momentum.
Visualization:
An animated 2D visualization shows the wavefunction propagating through the double slit and forming interference fringes. Absorbing boundary conditions prevent reflections from domain edges.
Key Observable: Fringe spacing and visibility of interference pattern.
python examples/double_slit.py
File: examples/quantum_vortex_2d.py
Physics:
A quantum vortex is a topological defect in a complex wavefunction where the phase winds by 2\pi m around a singularity (m is the winding number). The wavefunction takes the form:
\psi(r, \theta) = f(r) e^{im\theta}
where f(r) \sim r^{|m|} near the core to ensure single-valuedness. In a harmonic trap V(r) = \frac{1}{2}m\omega^2 r^2, the vortex state exhibits:
- Phase structure: The phase arg(\psi) winds m times around the vortex core
- Density depletion: |\psi|^2 \to 0 at the core (r \to 0)
- Angular momentum: The state carries angular momentum L_z = m\hbar per particle
The probability current circulates around the vortex:
\mathbf{j} = \frac{\hbar}{m} \operatorname{Im}(\psi^* \nabla \psi)
= \frac{\hbar m}{mr^2} |\psi|^2 \hat{\boldsymbol{\theta}}
Visualization:
The example generates two animations:
- Probability density |\psi|^2 showing the vortex core
- Phase structure revealing the 2\pi m winding
Key Observable: Angular momentum expectation value \langle L_z \rangle and phase winding number.
File: examples/photon_field.py
Physics:
A quantized photon field is described in Fock space using creation (a^\dagger) and annihilation (a) operators satisfying:
[a, a^\dagger] = 1
These operators act on number states |n\rangle:
\begin{aligned}
a^\dagger|n\rangle &= \sqrt{n+1}|n+1\rangle \\
a|n\rangle &= \sqrt{n}|n-1\rangle
\end{aligned}
The number operator \hat{n} = a^\dagger a counts photons:
\hat{n}|n\rangle = n|n\rangle
The Hamiltonian for a single mode is:
H = \hbar\omega\left(a^\dagger a + \frac{1}{2}\right)
Demonstration:
The example verifies:
- Commutation relations
- Action of operators on Fock states
- Photon number expectation values
Key Observable: Verification of [a, a^\dagger] = 1 and proper normalization.
File: examples/jaynes_cummings.py
Physics:
The Jaynes-Cummings model describes a two-level atom coupled to a single photon mode. The Hamiltonian (in the rotating wave approximation) is:
\hat{H}_{\text{JC}} = \frac{\hbar\omega_a}{2}\hat{\sigma}_z
+ \hbar\omega_c \hat{a}^\dagger\hat{a}
+ \hbar g(\hat{a}\hat{\sigma}_+ + \hat{a}^\dagger\hat{\sigma}_-)
where:
- \omega_a is the atomic transition frequency
- \omega_c is the cavity mode frequency
- g is the atom-field coupling strength
- \hat{\sigma}_z = |e\rangle\langle e| - |g\rangle\langle g| is the Pauli z operator
- \hat{\sigma}_+ = |e\rangle\langle g| raises the atom to the excited state
- \hat{\sigma}_- = |g\rangle\langle e| lowers the atom to the ground state
For the resonant case (\omega_a = \omega_c) starting from |e,0\rangle (excited atom, vacuum field), the system undergoes Rabi oscillations:
P_e(t) = \cos^2(\Omega_R t/2)
where \Omega_R = 2g is the Rabi frequency. Energy is exchanged periodically between atom and field:
- At t = 0: atom excited, zero photons
- At t = \pi/\Omega_R: atom in ground state, one photon
- At t = 2\pi/\Omega_R: back to initial state
Visualization:
An animated plot showing the time evolution of:
- Excited state probability P_e(t)
- Average photon number \langle n \rangle(t)
Both oscillate with the Rabi frequency, demonstrating coherent energy exchange.
Key Observable: Rabi frequency \Omega_R extracted from oscillation period.
Running Examples
All examples can be run directly with uv:
# Ensure dependencies are synced
uv sync
# Navigate to examples directory
cd examples
# Run 1D examples
uv run python free_particle_1d.py
uv run python tunneling_1d.py
# Run 2D examples
uv run python double_slit.py
uv run python quantum_vortex_2d.py
# Run QED examples
uv run python photon_field.py
uv run python jaynes_cummings.py
# Run benchmarks
uv run python benchmark_gpu.pyAll examples are designed to be easily modified. Key parameters to adjust:
Grid Parameters:
nx, ny: Number of grid points (powers of 2 recommended)x_min, x_max: Spatial extent
Physical Parameters:
mass: Particle mass (default: 1.0 = electron mass)hbar: Reduced Planck constant (default: 1.0)- Potential parameters:
V0,omega, etc.
Numerical Parameters:
dt: Time step (reduce for better accuracy)num_steps: Number of evolution steps
Visualization:
save_every: Frame saving frequencydpi: Image resolutioncmap: Colormap (try 'viridis', 'plasma', 'hot', etc.)
- Adapt examples for your research problem
- Combine multiple techniques (e.g., tunneling + time-dependent potential)
- Explore parameter space systematically
- Validate against analytical solutions when available
For more details, see:
- :doc:`api/modules` for detailed API documentation
- :doc:`theory` for mathematical foundations