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

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

.. _sphx_glr_api_gallery_md_periodic_boundaries_plot_01_minimum_image_convention.py:


Periodic boundary conditions and the minimum-image convention
================================================================

Metropolis and coworkers (1953) avoided the walls of a finite box by
surrounding it with periodic copies of itself: a particle leaving one
face re-enters through the opposite one
(:func:`~chemistrykit.md.utils.pbc.wrap_positions`), and each pair
interacts through whichever periodic image of the partner is nearest
(:func:`~chemistrykit.md.utils.pbc.minimum_image_displacement`):

.. math::

   \Delta\vec r = \vec r_i - \vec r_j - L\,\mathrm{round}\!\left(\frac{\vec r_i - \vec r_j}{L}\right).

The left panel shows a two-dimensional box with its eight neighboring
images and, for one particle, the line to the nearest image of each
partner; the right panel follows a particle drifting across the box,
wrapped back in each time it crosses an edge.

.. GENERATED FROM PYTHON SOURCE LINES 23-51

.. code-block:: Python

    import matplotlib.pyplot as plt
    import numpy as np

    from chemistrykit.md.utils.pbc import minimum_image_displacement, wrap_positions

    L = 10.0
    rng = np.random.default_rng(3)
    positions = rng.uniform(0.0, L, size=(6, 2))
    positions[0] = [1.0, 8.8]  # the reference particle, near a corner

    fig, axes = plt.subplots(1, 2, figsize=(11, 5.2))
    ax = axes[0]
    for sx in (-1, 0, 1):
        for sy in (-1, 0, 1):
            shift = np.array([sx, sy]) * L
            primary = sx == 0 and sy == 0
            ax.add_patch(plt.Rectangle(shift, L, L, fill=False, edgecolor="black" if primary else "lightgray", linewidth=1.5 if primary else 0.8))
            ax.scatter(*(positions + shift).T, s=25, color="steelblue" if primary else "lightsteelblue", zorder=3)
    ax.scatter(*positions[0], s=60, color="firebrick", zorder=4, label="reference particle")
    for j in range(1, len(positions)):
        d = minimum_image_displacement(positions[j], positions[0], L)
        ax.plot(*np.stack([positions[0], positions[0] + d]).T, color="firebrick", linewidth=1.0)
    ax.set_xlim(-L, 2 * L)
    ax.set_ylim(-L, 2 * L)
    ax.set_aspect("equal")
    ax.set_title("Nearest images of each partner")
    ax.legend(loc="lower left")




.. image-sg:: /api/gallery/md/periodic_boundaries/images/sphx_glr_plot_01_minimum_image_convention_001.png
   :alt: Nearest images of each partner
   :srcset: /api/gallery/md/periodic_boundaries/images/sphx_glr_plot_01_minimum_image_convention_001.png
   :class: sphx-glr-single-img


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

 .. code-block:: none


    <matplotlib.legend.Legend object at 0x11c316510>



.. GENERATED FROM PYTHON SOURCE LINES 52-55

A particle moving at constant velocity through the periodic box. The
wrapped coordinate jumps back each time it crosses a face, while the
motion itself is unbroken:

.. GENERATED FROM PYTHON SOURCE LINES 55-67

.. code-block:: Python


    t = np.linspace(0.0, 30.0, 600)
    unwrapped = np.array([2.0, 3.0]) + np.outer(t, [0.9, 0.4])
    wrapped = wrap_positions(unwrapped, L)
    axes[1].plot(t, unwrapped[:, 0], color="gray", linestyle=":", label="x, unwrapped")
    axes[1].plot(t, wrapped[:, 0], color="steelblue", label="x, wrapped into [0, L)")
    axes[1].set_xlabel("t")
    axes[1].set_ylabel("x")
    axes[1].set_title("A particle crossing the periodic boundary")
    axes[1].legend()
    fig.tight_layout()








.. GENERATED FROM PYTHON SOURCE LINES 68-69

Two particles on opposite edges of the box are actually neighbors:

.. GENERATED FROM PYTHON SOURCE LINES 69-75

.. code-block:: Python


    r_i, r_j = np.array([0.5, 5.0]), np.array([9.5, 5.0])
    print("plain displacement:        ", r_i - r_j)
    print("minimum-image displacement:", minimum_image_displacement(r_i, r_j, L))

    plt.show()




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

 .. code-block:: none

    plain displacement:         [-9.  0.]
    minimum-image displacement: [1. 0.]





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

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


.. _sphx_glr_download_api_gallery_md_periodic_boundaries_plot_01_minimum_image_convention.py:

.. only:: html

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

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

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

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

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

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

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


.. only:: html

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

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