.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "school-tutorials/trilmax-2025/1_python-library/plot_3_convention.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

        :ref:`Go to the end <sphx_glr_download_school-tutorials_trilmax-2025_1_python-library_plot_3_convention.py>`
        to download the full example code.

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

.. _sphx_glr_school-tutorials_trilmax-2025_1_python-library_plot_3_convention.py:


Convention of spin Hamiltonian
******************************

.. admonition:: Tutorial tasks

    *   Create an instance of :external:py:class:`magnopy.Convention` for every
        mathematical formula on this page.
    *   (extra) Write down the spin Hamiltonian in the convention that you usually use
        or seen recently. Create an instance of the :py:class:`magnopy.Convention` that
        describes it.

Before we move on to the Hamiltonian itself it is very important to understand that
there is a dozen of different conventions present in the literature of essentially the
same type of Hamiltonian. Here are a few examples of different conventions for the
isotropic exchange term

.. math::

    \mathcal{H}
    &=
    -\sum_{i,j}
    J_{ij}
    \boldsymbol{S}_i
    \cdot
    \boldsymbol{S}_j

    \mathcal{H}
    &=
    \sum_{i,j}
    J_{ij}
    \boldsymbol{e}_i
    \cdot
    \boldsymbol{e}_j

    \mathcal{H}
    &=
    -\dfrac{1}{2}\sum_{i<j}
    J_{ij}
    \boldsymbol{S}_i
    \cdot
    \boldsymbol{S}_j

Please read |magnopy-convention-problem|_ with the illustration of challenges that this
problem introduces.

We did not want to introduce a new convention in |magnopy|_ neither to use a single
convention in particular. As a solution we decided to support **any** convention that user
wants to use. Naturally, that implied a responsibility on the user: to provide one! If
spin Hamiltonian is loaded from the known source (i. e. |TB2J|_ or |GROGU|_), then magnopy
knows the convention and user can just read the Hamiltonian from the file like so

.. code-block:: python

    # Reading from TB2J
    spinham = magnopy.io.load_tb2j("exchange.out")

    # Reading from GROGU
    spinham = magnopy.io.load_grogu("spinham-from-GROGU.txt")

However, when the spin Hamiltonian is created by user, the :py:class:`magnopy.Convention`
object has to be created. For example, to introduce the convention for the Hamiltonian

.. math::

    \mathcal{H}
    =
    \sum_i
    K_z\left(S_i^z\right)^2
    +
    \dfrac{1}{2}
    \sum_{i, j>i}
    J_{i,j}
    \boldsymbol{S}_i
    \cdot
    \boldsymbol{S}_j

one shall create the convention object as

.. GENERATED FROM PYTHON SOURCE LINES 80-87

.. code-block:: Python


    import magnopy

    convention = magnopy.Convention(
        c21=1, c22=0.5, multiple_counting=False, spin_normalized=False
    )








.. GENERATED FROM PYTHON SOURCE LINES 88-90

To consult the convention properties you can either access individual options or print
a summary

.. GENERATED FROM PYTHON SOURCE LINES 91-96

.. code-block:: Python


    print(convention.multiple_counting)

    convention.summary()





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

 .. code-block:: none

    False
    custom convention where
      * Bonds are counted once in the sum;
      * Spin vectors are not normalized;
      * Undefined c1 factor;
      * c21 = 1.0;
      * c22 = 0.5;
      * Undefined c31 factor;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.




.. GENERATED FROM PYTHON SOURCE LINES 97-101

Pre-defined conventions
=======================

Magnopy offers some pre-defined named conventions. Use

.. GENERATED FROM PYTHON SOURCE LINES 101-109

.. code-block:: Python


    convention = magnopy.Convention.get_predefined("GROGU")
    convention.summary()
    convention = magnopy.Convention.get_predefined("Vampire")
    convention.summary()
    convention = magnopy.Convention.get_predefined("TB2J")
    convention.summary()





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

 .. code-block:: none

    grogu convention where
      * Bonds are counted multiple times in the sum;
      * Spin vectors are normalized to 1;
      * Undefined c1 factor;
      * c21 = 1.0;
      * c22 = 0.5;
      * Undefined c31 factor;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.
    vampire convention where
      * Bonds are counted multiple times in the sum;
      * Spin vectors are normalized to 1;
      * Undefined c1 factor;
      * c21 = -1.0;
      * c22 = -0.5;
      * Undefined c31 factor;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.
    tb2j convention where
      * Bonds are counted multiple times in the sum;
      * Spin vectors are normalized to 1;
      * Undefined c1 factor;
      * c21 = -1.0;
      * c22 = -1.0;
      * Undefined c31 factor;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.




.. GENERATED FROM PYTHON SOURCE LINES 110-111

to get one.

.. GENERATED FROM PYTHON SOURCE LINES 114-119

Modifying convention
====================

To get the convention where just a few of the properties are changed one can create a
new convention and populate all of its properties again. Or use a shortcut

.. GENERATED FROM PYTHON SOURCE LINES 119-124

.. code-block:: Python


    modified = convention.get_modified(c31=1)
    modified.summary()






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

 .. code-block:: none

    tb2j convention where
      * Bonds are counted multiple times in the sum;
      * Spin vectors are normalized to 1;
      * Undefined c1 factor;
      * c21 = -1.0;
      * c22 = -1.0;
      * c31 = 1.0;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.





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

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


.. _sphx_glr_download_school-tutorials_trilmax-2025_1_python-library_plot_3_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_3_convention.ipynb <plot_3_convention.ipynb>`

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

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

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

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


.. only:: html

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

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