.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "api/gallery/md/lj_fluid/plot_02_maxwell_boltzmann_check.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_md_lj_fluid_plot_02_maxwell_boltzmann_check.py>`
        to download the full example code.

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

.. _sphx_glr_api_gallery_md_lj_fluid_plot_02_maxwell_boltzmann_check.py:


Cross-checking an MD trajectory against the Maxwell-Boltzmann distribution
=============================================================================

A direct link between :mod:`chemistrykit.md` and :mod:`chemistrykit.statmech`:
molecular dynamics produces an actual ensemble of particle velocities,
and statistical mechanics predicts what their distribution *should* look
like at equilibrium. After a short equilibration run, an
:class:`~chemistrykit.md.systems.lj_fluid.LJFluid`'s particle speeds are
histogrammed and compared against
:class:`chemistrykit.statmech.MaxwellBoltzmannSpeedDistribution` evaluated
at the simulation's own (instantaneous, measured) temperature -- no
fitting involved.

.. GENERATED FROM PYTHON SOURCE LINES 17-35

.. code-block:: Python

    import matplotlib.pyplot as plt
    import numpy as np

    from chemistrykit.md.systems.lj_fluid import LJFluid
    from chemistrykit.md.visualizers.md_plots import plot_speed_distribution
    from chemistrykit.statmech import MaxwellBoltzmannSpeedDistribution

    fluid = LJFluid.from_lattice(n_per_side=7, density=0.5, temperature=1.5, cutoff=2.5, rng=1)
    fluid.run(dt=0.002, n_steps=1000, sample_every=1000)  # brief equilibration, discard the trajectory

    speeds = np.linalg.norm(fluid.velocities, axis=1)
    T_measured = fluid.temperature()

    fig, ax = plt.subplots(figsize=(7, 5))
    plot_speed_distribution(speeds, mass=1.0, temperature=T_measured, ax=ax, n_bins=30)
    ax.set_title(f"MD speed histogram vs. Maxwell-Boltzmann (T = {T_measured:.3f})")
    fig.tight_layout()




.. image-sg:: /api/gallery/md/lj_fluid/images/sphx_glr_plot_02_maxwell_boltzmann_check_001.png
   :alt: MD speed histogram vs. Maxwell-Boltzmann (T = 1.451)
   :srcset: /api/gallery/md/lj_fluid/images/sphx_glr_plot_02_maxwell_boltzmann_check_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 36-40

The simulated mean speed agrees with the analytic Maxwell-Boltzmann
prediction at the same (measured) temperature to within a few percent
-- the residual gap is ordinary finite-N sampling noise, not a
systematic discrepancy:

.. GENERATED FROM PYTHON SOURCE LINES 40-47

.. code-block:: Python


    distribution = MaxwellBoltzmannSpeedDistribution(mass=1.0, temperature=T_measured, k_b=1.0)
    print(f"simulated mean speed:  {speeds.mean():.4f}")
    print(f"predicted mean speed:  {distribution.mean_speed():.4f}")
    print(f"relative difference:   {abs(speeds.mean() - distribution.mean_speed()) / distribution.mean_speed():.2%}")

    plt.show()




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

 .. code-block:: none

    simulated mean speed:  1.9046
    predicted mean speed:  1.9225
    relative difference:   0.93%





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

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


.. _sphx_glr_download_api_gallery_md_lj_fluid_plot_02_maxwell_boltzmann_check.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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