.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/quantum/harmonic_oscillator/plot_wigner_phase_space.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_api_gallery_quantum_harmonic_oscillator_plot_wigner_phase_space.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_api_gallery_quantum_harmonic_oscillator_plot_wigner_phase_space.py:


Wigner phase-space quasi-probability
========================================

The Wigner function represents a quantum state as a quasi-probability
distribution over classical phase space :math:`(x,p)`,

.. math::

    W(x,p) = \frac{1}{\pi\hbar} \int_{-\infty}^{\infty}
        \psi^*(x+y)\,\psi(x-y)\, e^{2ipy/\hbar}\, dy,

built here from the harmonic-oscillator Fock eigenstates
:math:`\psi=\phi_n(x)`. Unlike a genuine probability density, :math:`W`
can go negative; its :math:`x`- and :math:`p`-marginals still reproduce the
ordinary quantum probabilities, :math:`\int W\,dp = \lvert\psi(x)\rvert^2`.
The ground state (:math:`n=0`) stays a positive Gaussian, but the first
excited state (:math:`n=1`) develops genuinely negative regions -- a
hallmark of non-classicality with no counterpart in any classical
phase-space distribution.

.. GENERATED FROM PYTHON SOURCE LINES 22-33

.. code-block:: Python


    import matplotlib.pyplot as plt
    import numpy as np

    from physicskit.quantum.chapters.harmonic_spin import HarmonicOscillator
    from physicskit.quantum.visualizers.phase_space import WignerVisualizer

    ho = HarmonicOscillator()
    x = np.linspace(-6, 6, 220)
    wv = WignerVisualizer(n_p=180)








.. GENERATED FROM PYTHON SOURCE LINES 34-36

The n=0 and n=1 Fock-state Wigner functions
------------------------------------------------

.. GENERATED FROM PYTHON SOURCE LINES 36-49

.. code-block:: Python


    fig = plt.figure(figsize=(12, 5))

    for i, n in enumerate([0, 1]):
        psi_n = ho.eigenfunction(n, x)
        xg, p, W = wv.compute(x, psi_n, p_max=6.0)

        ax = fig.add_subplot(1, 2, i + 1, projection="3d")
        wv.plot_surface(xg, p, W, ax=ax)
        ax.set_title(f"Fock state n={n}  (min W = {W.min():.3f})")

    fig.tight_layout()




.. image-sg:: /api/gallery/quantum/harmonic_oscillator/images/sphx_glr_plot_wigner_phase_space_001.png
   :alt: Fock state n=0  (min W = -0.000), Fock state n=1  (min W = -0.317)
   :srcset: /api/gallery/quantum/harmonic_oscillator/images/sphx_glr_plot_wigner_phase_space_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 50-51

Sanity check: integrating W over p should recover :math:`\lvert\psi(x)\rvert^2`.

.. GENERATED FROM PYTHON SOURCE LINES 51-57

.. code-block:: Python


    psi1 = ho.eigenfunction(1, x)
    xg, p, W1 = wv.compute(x, psi1)
    marginal = wv.position_marginal(p, W1)
    print("max |marginal - |psi|^2| =", np.max(np.abs(marginal - psi1**2)))





.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    max |marginal - |psi|^2| = 2.937931927970397e-10




.. GENERATED FROM PYTHON SOURCE LINES 58-68

Phase-space interference fringes in a Fock-state superposition
--------------------------------------------------------------------

A single Fock state's Wigner function is rotationally symmetric in phase
space, but a coherent *superposition* of two Fock states develops genuine
interference fringes between them -- oscillatory, sign-alternating ripples
with no classical counterpart -- built here with
:meth:`~physicskit.quantum.chapters.harmonic_spin.HarmonicOscillator.superposition_wavefunction`
and rendered with the (previously unused)
:meth:`~physicskit.quantum.visualizers.phase_space.WignerVisualizer.plot_contour`.

.. GENERATED FROM PYTHON SOURCE LINES 68-78

.. code-block:: Python


    psi_super = ho.superposition_wavefunction([0, 2], [1.0, 1.0], x, t=0.0)
    xg_s, p_s, W_super = wv.compute(x, psi_super, p_max=6.0)

    fig2, ax_super = plt.subplots(figsize=(6.5, 5.5))
    wv.plot_contour(xg_s, p_s, W_super, ax=ax_super)
    ax_super.set_title(r"Wigner function of $(|0\rangle+|2\rangle)/\sqrt{2}$" "\n(interference fringes between the two lobes)")
    fig2.tight_layout()

    print(f"min W of the superposition (non-classicality): {W_super.min():.4f}")



.. image-sg:: /api/gallery/quantum/harmonic_oscillator/images/sphx_glr_plot_wigner_phase_space_002.png
   :alt: Wigner function of $(|0\rangle+|2\rangle)/\sqrt{2}$ (interference fringes between the two lobes)
   :srcset: /api/gallery/quantum/harmonic_oscillator/images/sphx_glr_plot_wigner_phase_space_002.png
   :class: sphx-glr-single-img


.. rst-class:: sphx-glr-script-out

 .. code-block:: none

    min W of the superposition (non-classicality): -0.1647





.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.397 seconds)


.. _sphx_glr_download_api_gallery_quantum_harmonic_oscillator_plot_wigner_phase_space.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_wigner_phase_space.ipynb <plot_wigner_phase_space.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_wigner_phase_space.py <plot_wigner_phase_space.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_wigner_phase_space.zip <plot_wigner_phase_space.zip>`


.. only:: html

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

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