Examples
========

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.

.. contents:: Table of Contents
   :local:
   :depth: 2

1D Examples
-----------

Free Particle Dispersion
~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** ``examples/free_particle_1d.py``

**Physics:**

A free particle is described by the time-dependent Schrödinger equation with zero potential:

.. math::

   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 :math:`\sigma_0` and momentum :math:`p_0`:

.. math::

   \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:

.. math::

   \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 :math:`v_g = p_0/m`, while the dispersion causes the uncertainty :math:`\Delta x` to increase over time, satisfying the time-energy uncertainty relation.

**Visualization:**

The example generates an animated movie showing the probability density :math:`|\psi(x,t)|^2` evolving in time, along with a plot comparing the numerical width evolution with the analytical prediction.


Quantum Tunneling
~~~~~~~~~~~~~~~~~

**File:** ``examples/tunneling_1d.py``

**Physics:**

Quantum tunneling allows particles to penetrate classically forbidden regions. Consider a rectangular barrier:

.. math::

   V(x) = 
   \begin{cases}
   V_0 & \text{if } |x - x_0| < a/2 \\
   0 & \text{otherwise}
   \end{cases}

For a particle with energy :math:`E < V_0`, the wavefunction inside the barrier (:math:`E < V`) decays exponentially:

.. math::

   \psi(x) \propto e^{-\kappa x}, \quad \kappa = \sqrt{2m(V_0 - E)}/\hbar

The transmission coefficient through a rectangular barrier of width :math:`a` is:

.. math::

   T = \frac{1}{1 + \dfrac{V_0^2 \sinh^2(\kappa a)}{4E(V_0 - E)}}

For :math:`\kappa a \gg 1`, this simplifies to :math:`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.

2D Examples
-----------

Double-Slit Experiment
~~~~~~~~~~~~~~~~~~~~~~

**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 :math:`d`, creating an interference pattern on a distant screen.

The interference pattern arises from the superposition:

.. math::

   \psi(x, y, t) = \psi_1(x, y, t) + \psi_2(x, y, t)

where :math:`\psi_1` and :math:`\psi_2` are contributions from each slit. The probability density :math:`|\psi|^2` exhibits fringes with spacing:

.. math::

   \Delta y = \frac{\lambda L}{d}

where :math:`\lambda = 2\pi\hbar/p` is the de Broglie wavelength, :math:`L` is the distance to the screen, and :math:`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

Quantum Vortex
~~~~~~~~~~~~~~

**File:** ``examples/quantum_vortex_2d.py``

**Physics:**

A quantum vortex is a topological defect in a complex wavefunction where the phase winds by :math:`2\pi m` around a singularity (:math:`m` is the winding number). The wavefunction takes the form:

.. math::

   \psi(r, \theta) = f(r) e^{im\theta}

where :math:`f(r) \sim r^{|m|}` near the core to ensure single-valuedness. In a harmonic trap :math:`V(r) = \frac{1}{2}m\omega^2 r^2`, the vortex state exhibits:

1. **Phase structure:** The phase arg(:math:`\psi`) winds :math:`m` times around the vortex core
2. **Density depletion:** :math:`|\psi|^2 \to 0` at the core (:math:`r \to 0`)
3. **Angular momentum:** The state carries angular momentum :math:`L_z = m\hbar` per particle

The probability current circulates around the vortex:

.. math::

   \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:

1. Probability density :math:`|\psi|^2` showing the vortex core
2. Phase structure revealing the :math:`2\pi m` winding

**Key Observable:** Angular momentum expectation value :math:`\langle L_z \rangle` and phase winding number.

QED Examples
------------

Photon Field Basics
~~~~~~~~~~~~~~~~~~~

**File:** ``examples/photon_field.py``

**Physics:**

A quantized photon field is described in Fock space using creation (:math:`a^\dagger`) and annihilation (:math:`a`) operators satisfying:

.. math::

   [a, a^\dagger] = 1

These operators act on number states :math:`|n\rangle`:

.. math::

   \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 :math:`\hat{n} = a^\dagger a` counts photons:

.. math::

   \hat{n}|n\rangle = n|n\rangle

The Hamiltonian for a single mode is:

.. math::

   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 :math:`[a, a^\dagger] = 1` and proper normalization.

Jaynes-Cummings Dynamics
~~~~~~~~~~~~~~~~~~~~~~~~

**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:

.. math::

   \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:

* :math:`\omega_a` is the atomic transition frequency
* :math:`\omega_c` is the cavity mode frequency  
* :math:`g` is the atom-field coupling strength
* :math:`\hat{\sigma}_z = |e\rangle\langle e| - |g\rangle\langle g|` is the Pauli z operator
* :math:`\hat{\sigma}_+ = |e\rangle\langle g|` raises the atom to the excited state
* :math:`\hat{\sigma}_- = |g\rangle\langle e|` lowers the atom to the ground state

For the resonant case (:math:`\omega_a = \omega_c`) starting from :math:`|e,0\rangle` (excited atom, vacuum field), the system undergoes Rabi oscillations:

.. math::

   P_e(t) = \cos^2(\Omega_R t/2)

where :math:`\Omega_R = 2g` is the Rabi frequency. Energy is exchanged periodically between atom and field:

* At :math:`t = 0`: atom excited, zero photons
* At :math:`t = \pi/\Omega_R`: atom in ground state, one photon
* At :math:`t = 2\pi/\Omega_R`: back to initial state

**Visualization:**

An animated plot showing the time evolution of:

1. Excited state probability :math:`P_e(t)`
2. Average photon number :math:`\langle n \rangle(t)`

Both oscillate with the Rabi frequency, demonstrating coherent energy exchange.

**Key Observable:** Rabi frequency :math:`\Omega_R` extracted from oscillation period.

Running Examples

----------------

All examples can be run directly with uv:

.. code-block:: bash

   # 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.py

Modifying Examples
------------------

All 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 frequency
* ``dpi``: Image resolution
* ``cmap``: Colormap (try 'viridis', 'plasma', 'hot', etc.)

Next Steps
----------

* 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