:orphan:

Examples
========

This gallery walks through ``physicskit.fields``: electrodynamics on a Yee
grid, soliton-bearing nonlinear wave equations, and Gross-Pitaevskii
Bose-Einstein condensates -- each script reproducing the signature
observable of a specific breakthrough in :doc:`/history/fields_breakthroughs`.
Fluid dynamics has since moved to its own package and gallery; see
:mod:`physicskit.fluids` and :doc:`/history/fluid_breakthroughs`.

See also the narrative tutorials:

- :doc:`/tutorials/fdtd_waveguide_simulation`
- :doc:`/tutorials/bec_vortex_lattice_creation`

Each script in this gallery is self-contained and can be run directly with
``python examples/fields/<section>/<script>.py``. Every script also
carries an RST module docstring as its title/description and uses ``# %%``
markers to split narrative text from code, which is exactly what
Sphinx-Gallery renders into the pages below -- the script *is* the source
of truth for what you see, not a copy of it.

Sections
--------

- **solitons** -- the Korteweg-de Vries, nonlinear Schrodinger, and
  Sine-Gordon equations: Russell's shape-preserving wave of translation,
  the elastic KdV soliton-soliton collision, Zabusky and Kruskal's fission
  of a generic pulse into a soliton train, free-particle wavepacket
  spreading under the linear Schrodinger equation, a topologically
  protected Sine-Gordon kink, an exact kink-antikink collision from the
  inverse scattering transform, and a dispersion-free optical soliton --
  several of these animated frame by frame.
- **electrodynamics** -- Maxwell's equations on a Yee grid: measuring the
  vacuum speed of light from a propagating FDTD pulse, a point source
  radiating outward in 2D, Berenger's Perfectly Matched Layer absorbing
  boundary compared against a hard wall, a Hertzian oscillating dipole
  antenna radiating outward, a wave crossing a dielectric slab, and a
  standing TM cavity mode.
- **quantum_fields** -- the Gross-Pitaevskii equation for a trapped BEC:
  detecting a single quantum of circulation around an imprinted vortex, a
  bound vortex-antivortex pair with canceling net winding (the
  Kosterlitz-Thouless building block), relaxing to the interacting
  mean-field ground state, the critical rotation frequency for vortex
  nucleation, a vortex genuinely precessing in real time, self-focusing
  wave collapse of an attractive condensate, and the Casimir vacuum force
  between confining "plates."
- **gauge_confinement** -- a simplified 1+1D toy model of quark
  confinement: a flux tube stretching between two charges, reproducing
  the linearly growing confinement energy of Wilson's 1974 lattice gauge
  theory.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. thumbnail-parent-div-close

.. raw:: html

    </div>

Electrodynamics
------------------

Finite-difference time-domain (FDTD) solutions of Maxwell's equations on a
Yee grid, in 1D and 2D, plus a graded-conductivity absorbing boundary in
the spirit of Berenger's Perfectly Matched Layer. Also includes animated
demos of a Hertzian oscillating dipole antenna, a wave crossing a
dielectric slab, and a standing TM cavity mode.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Kane Yee&#x27;s staggered-grid update handles a wave crossing a material interface with no change to its core leapfrog rule -- only the permittivity map eps_r fed into it changes: the TMz-mode Maxwell curl equations solved at every grid cell,">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_dielectric_slab_propagation_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_dielectric_slab_propagation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A wave crossing a dielectric slab</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Twenty-two years after Maxwell&#x27;s equations predicted electromagnetic radiation, Heinrich Hertz built an oscillating dipole antenna -- an induction coil driving a spark gap -- and detected the resulting waves meters away, confirming they travel at the speed of light and can be reflected, refracted, and polarized just like ordinary light. On the 2D Yee grid used here, the out-of-plane field E_z and the in-plane fields H_x, H_y obey the source-free TMz-mode reduction of Maxwell&#x27;s curl equations,">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_dipole_radiation_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_dipole_radiation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A Hertzian dipole antenna radiating on the Yee grid</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="fdtd_2d_tmz and fdtd_2d_tmz_evolve integrate the same TMz-mode Maxwell curl equations as the other FDTD examples in this gallery, but already enforce Ez=0 on all four grid edges every step -- exactly a perfectly-conducting (PEC) cavity wall, no absorbing boundary needed. A rectangular PEC cavity of size L_x\times L_y supports discrete standing-wave modes">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_em_cavity_modes_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_em_cavity_modes`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A standing TM cavity mode oscillating in place</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="James Clerk Maxwell unified electricity, magnetism, and optics into four coupled equations. In one dimension, source-free, they reduce to a coupled pair for the transverse electric and magnetic field components,">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_maxwell_speed_of_light_thumb.png
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_maxwell_speed_of_light`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Measuring the speed of light from Maxwell's equations</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Jean-Pierre Berenger solved a problem that had limited FDTD simulations since Yee&#x27;s original 1966 paper: a finite grid needs some boundary condition, and a simple wall reflects outgoing waves right back into the simulation. His Perfectly Matched Layer (PML) is a graded absorbing medium whose wave impedance matches the interior exactly, so outgoing waves are absorbed rather than reflected. pml_conductivity_profile implements a simplified (non-split-field) approximation to this idea: it grades an ordinary electric conductivity \sigma(x) smoothly up from zero over the outermost cells at each edge of the grid, so E_z there obeys the lossy telegraph-style update of a conducting medium rather than the lossless Ampere&#x27;s law,">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_pml_absorbing_boundary_thumb.png
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_pml_absorbing_boundary`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Berenger's Perfectly Matched Layer vs. a hard wall</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Kane Yee&#x27;s 1966 idea was deceptively simple: stagger the electric and magnetic field components on interleaved spatial and temporal grids (a &quot;Yee cell&quot;), so each field&#x27;s curl is naturally centered on the other&#x27;s location. fdtd_1d and fdtd_2d_tmz are direct implementations of this staggered-grid leapfrog scheme for the TMz-mode Maxwell curl equations,">

.. only:: html

  .. image:: /api/gallery/fields/electrodynamics/images/thumb/sphx_glr_plot_yee_fdtd_point_source_thumb.png
    :alt:

  :doc:`/api/gallery/fields/electrodynamics/plot_yee_fdtd_point_source`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A point source radiating on the Yee grid</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Gauge confinement
---------------------

A simplified, illustrative 1+1D toy model of quark confinement: a field
squeezed into a fixed-cross-section "flux tube" between two opposite
charges, reproducing the linearly growing confinement energy that Kenneth
Wilson's 1974 lattice gauge theory predicted -- not a lattice-QCD or
first-principles gauge-theory calculation.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Kenneth Wilson&#x27;s 1974 lattice gauge theory (&quot;Confinement of Quarks&quot;) showed that, in the strong-coupling limit, the potential energy of a static quark-antiquark pair grows linearly with separation, rather than falling off the way an ordinary Coulomb field does -- the defining signature of confinement. The physical picture is that the gluon field lines are squeezed into a narrow &quot;flux tube&quot; of fixed cross-section connecting the two charges, rather than spreading out in all directions the way an ordinary Coulomb field would.">

.. only:: html

  .. image:: /api/gallery/fields/gauge_confinement/images/thumb/sphx_glr_plot_flux_tube_confinement_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/gauge_confinement/plot_flux_tube_confinement`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A confining flux tube stretching between two charges</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Quantum fields
-----------------

Gross-Pitaevskii mean-field theory for a trapped, rotating Bose-Einstein
condensate: quantized vortex detection, a bound vortex-antivortex pair with
canceling net winding, ground-state relaxation, the critical rotation
frequency for vortex nucleation, a vortex genuinely precessing in real time,
self-focusing wave collapse, and the Casimir vacuum force.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Following the first dilute-gas Bose-Einstein condensates in 1995 (Cornell, Wieman, Ketterle), experimentalists set condensates rotating and watched them nucleate quantized vortices above a critical rotation frequency, arranging themselves into a triangular Abrikosov-like lattice -- exactly as Gross-Pitaevskii theory, by then over three decades old, had predicted. Both the vortex-free and single-vortex states compared here are relaxed (at zero rotation) via imaginary-time propagation of the Gross-Pitaevskii equation for a harmonically trapped condensate,">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_bec_vortex_lattice_nucleation_thumb.png
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_bec_vortex_lattice_nucleation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The critical rotation frequency for BEC vortex nucleation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Hendrik Casimir showed in 1948 that two uncharged, perfectly conducting parallel plates in vacuum should attract each other: only electromagnetic vacuum modes that fit an integer number of wavelengths between the plates are allowed there, so the confined zero-point energy is slightly lower than in the unbounded vacuum outside, producing a net inward force. This is a simplified, standard textbook treatment -- a 1D scalar field confined between two &quot;plates&quot; a distance d apart, not a full 3D electromagnetic calculation. casimir_mode_frequencies builds the resulting discrete standing-wave spectrum,">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_casimir_effect_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_casimir_effect`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">The Casimir energy grows weaker as plates separate</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Eugene Gross and Lev Pitaevskii independently derived, in 1961, a mean-field equation for the macroscopic wavefunction of a dilute Bose-Einstein condensate: a nonlinear Schrodinger equation with a cubic self-interaction term, i\hbar\partial_t\psi = [-\tfrac{\hbar^2}{2m}\nabla^2 + V + g|\psi|^2]\psi. Decades before a real BEC existed in a laboratory, this gave theorists a concrete tool for its structure. In the natural units used here (\hbar=m=1) for a condensate held in a 2D harmonic trap V(\mathbf{r})=\tfrac12(x^2+y^2),">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_gpe_ground_state_relaxation_thumb.png
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_gpe_ground_state_relaxation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Relaxing to the Gross-Pitaevskii interacting ground state</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="gpe_relax only ever finds a stationary vortex state, by imaginary-time relaxation -- it cannot show what a vortex actually does as time passes. gpe_evolve solves the same Gross-Pitaevskii equation in genuine real (lab-frame) time instead,">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_gpe_real_time_vortex_precession_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_gpe_real_time_vortex_precession`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A vortex genuinely precessing in real time</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Vladimir Zakharov showed in &quot;Collapse of Langmuir Waves&quot; (1972) that the focusing nonlinear Schrodinger equation has a regime with no shape-preserving soliton at all: a sufficiently intense, narrow wave packet can self-focus so strongly that it contracts toward a genuine singularity in finite time, rather than settling into a stable envelope. gpe_evolve solves the 2D Gross-Pitaevskii / cubic NLS equation">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_nls_self_focusing_collapse_thumb.gif
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_nls_self_focusing_collapse`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Self-focusing collapse of an attractive condensate</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Lars Onsager (1949) and, independently, Richard Feynman (1955) proposed that frictionless superfluid helium-4 can only rotate by threading itself with discrete vortex lines, each carrying exactly one quantum of circulation,">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_superfluid_vortex_quantization_thumb.png
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_superfluid_vortex_quantization`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Detecting a single quantum of circulation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="John Kosterlitz and David Thouless explained how a two-dimensional superfluid can support order despite thermal fluctuations: below a critical temperature, vortices bind tightly into vortex-antivortex pairs of opposite circulation, whose combined velocity fields cancel at long range, leaving superfluid order intact; above it, the pairs unbind into a free plasma of independent vortices and antivortices. This package does not simulate the thermal binding-unbinding transition itself, but the two ingredients the picture is built from -- an isolated vortex and its oppositely circulating antivortex -- are both exactly representable as phase windings of a condensate wavefunction.">

.. only:: html

  .. image:: /api/gallery/fields/quantum_fields/images/thumb/sphx_glr_plot_vortex_antivortex_pair_thumb.png
    :alt:

  :doc:`/api/gallery/fields/quantum_fields/plot_vortex_antivortex_pair`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A bound vortex-antivortex pair: opposite windings that cancel at long range</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>

Solitons
----------

The Korteweg-de Vries, nonlinear Schrodinger, and Sine-Gordon equations:
shape-preserving traveling waves, elastic collisions, wavepacket spreading,
and topologically protected kinks -- several animated frame by frame.


.. raw:: html

  <div id='sg-tag-list' class='sphx-glr-tag-list'></div>


.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Korteweg and de Vries&#x27;s 1895 equation,">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_kdv_elastic_collision_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_kdv_elastic_collision`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">An elastic KdV soliton-soliton collision</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Trying to resolve the Fermi-Pasta-Ulam-Tsingou recurrence puzzle, Norman Zabusky and Martin Kruskal simulated the continuum (KdV) limit of a nonlinear oscillator chain in 1965 and watched a single generic disturbance -- not an exact multi-soliton solution -- &quot;fission&quot; into a rank-ordered train of solitary waves that then collided and emerged unscathed. kdv_evolve integrates the Korteweg-de Vries equation">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_kdv_soliton_fission_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_kdv_soliton_fission`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Zabusky-Kruskal fission: coining "soliton"</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="In 1834, John Scott Russell watched a solitary heap of water detach from a boat&#x27;s bow wave on the Union Canal and roll on for miles &quot;without change of form or diminution of speed.&quot; Sixty years later, Korteweg and de Vries explained this with the equation now bearing their names,">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_kdv_soliton_translation_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_kdv_soliton_translation`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Russell's wave of translation</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Akira Hasegawa and Fred Tappert showed in 1973 that the same balance of nonlinearity and dispersion behind Russell&#x27;s water wave -- now governed by the focusing nonlinear Schrodinger equation instead of KdV,">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_nls_optical_soliton_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_nls_optical_soliton`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A dispersion-free optical soliton</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Erwin Schrodinger&#x27;s 1926 wave equation,">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_nls_wavepacket_spreading_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_nls_wavepacket_spreading`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Schrodinger's wavepacket spreading</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Yakov Frenkel and Tatiana Kontorova modeled a crystal dislocation as a chain of atoms in a periodic substrate potential -- a chain of coupled pendula; in the continuum limit this becomes the Sine-Gordon equation">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_sine_gordon_kink_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_sine_gordon_kink`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">A topologically protected Sine-Gordon kink</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="Gardner, Greene, Kruskal, and Miura&#x27;s 1967 inverse scattering transform (IST) explained why solitons collide elastically, and showed that KdV was only the first of a broad class of exactly integrable equations -- the Sine-Gordon equation">

.. only:: html

  .. image:: /api/gallery/fields/solitons/images/thumb/sphx_glr_plot_sine_gordon_kink_antikink_ist_thumb.png
    :alt:

  :doc:`/api/gallery/fields/solitons/plot_sine_gordon_kink_antikink_ist`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">An exact kink-antikink collision from inverse scattering</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:
   :includehidden:


   /api/gallery/fields/electrodynamics/index.rst
   /api/gallery/fields/gauge_confinement/index.rst
   /api/gallery/fields/quantum_fields/index.rst
   /api/gallery/fields/solitons/index.rst



.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_