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

.. only:: html

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

        :ref:`Go to the end <sphx_glr_download_master-tutorial_1_python-library_plot_2_convention.py>`
        to download the full example code.

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

.. _sphx_glr_master-tutorial_1_python-library_plot_2_convention.py:


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

.. include:: ../../exercises/2.inc

Before we move on to the Hamiltonian itself it is very important to understand that
there is a dozen of different conventions of essentially the same type of Hamiltonian
present in the literature. 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|_ for the illustration of the challenges that this
problem introduces.

In |magnopy|_ we did not want to introduce a new one or to use one convention in
particular. As a solution we decided to support **any** convention that the user wants to
use. Naturally, that implied a responsibility on the user: to provide one! When spin
Hamiltonian is read from the knows source (i. e. |TB2J|_ or |GROGU|_), 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, :py:class:`magnopy.Convention` object has to be created and supplied when the
spin Hamiltonian is created by user. For example, to introduce the convention for the
Hamiltonian that is written as

.. 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 75-82

.. code-block:: Python


    import magnopy

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








.. GENERATED FROM PYTHON SOURCE LINES 83-84

To consult the convention properties you can display either individual properties

.. GENERATED FROM PYTHON SOURCE LINES 85-89

.. code-block:: Python


    print(convention.c21)
    print(convention.multiple_counting)





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

 .. code-block:: none

    1.0
    False




.. GENERATED FROM PYTHON SOURCE LINES 90-91

or the whole convention

.. GENERATED FROM PYTHON SOURCE LINES 92-95

.. code-block:: Python


    print(convention)





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

 .. code-block:: none

    "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 96-100

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

Magnopy has some pre-defined named conventions. To get one use

.. GENERATED FROM PYTHON SOURCE LINES 100-108

.. code-block:: Python


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





.. 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 109-114

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 114-120

.. code-block:: Python


    convention = magnopy.Convention.get_predefined("TB2J")
    modified = convention.get_modified(c31=1, name="modified")
    print(convention)
    print(modified)





.. 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;
      * Undefined c31 factor;
      * Undefined c32 factor;
      * Undefined c33 factor;
      * Undefined c41 factor;
      * Undefined c421 factor;
      * Undefined c422 factor;
      * Undefined c43 factor;
      * Undefined c44 factor.
    "modified" 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.002 seconds)


.. _sphx_glr_download_master-tutorial_1_python-library_plot_2_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_2_convention.ipynb <plot_2_convention.ipynb>`

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

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

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

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


.. only:: html

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

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