Convention

For the theoretical background on the convention problem see Convention of the Hamiltonian.

Magnopy implements a compact, hashable Convention class to combine all parameters of the spin Hamiltonian's convention.

Here is an example of the custom convention where constants \(C_1\), \(C_{2,1}\), \(C_{2, 2}\), multiple counting and spin normalization are defined, while the other constants are left undefined.

>>> from magnopy import Convention
>>> convention = Convention(
...    multiple_counting=True,
...    spin_normalized=False,
...    c1=1,
...    c21=1,
...    c22=1,
...    name="Convention example",
... )

The properties of the convention can be checked at any time

>>> convention.multiple_counting
True
>>> convention.spin_normalized
False
>>> convention.c1
1.0
>>> convention.c21
1.0
>>> convention.c22
1.0

As well as the full summary about the convention

>>> print(convention)
"convention example" convention where
  * Bonds are counted multiple times in the sum;
  * Spin vectors are not normalized;
  * c1 = 1.0;
  * c21 = 1.0;
  * c22 = 1.0;
  * Undefined c31 factor;
  * Undefined c32 factor;
  * Undefined c33 factor;
  * Undefined c41 factor;
  * Undefined c42 factor;
  * Undefined c43 factor;
  * Undefined c44 factor;
  * Undefined c45 factor.

Convention is one of the three objects that are required for the creation of an instance of the SpinHamiltonian class. It is stored as an attribute SpinHamiltonian.convention and can be accessed or modified through it.

Modifying convention

Every instance of the convention class is meant to be static, therefore, the properties of the existing instance can not be changed, for example

>>> convention.multiple_counting = False
Traceback (most recent call last):
...
AttributeError: It is intentionally forbidden to set properties of convention. Use convention.get_modified(...) and/or spinham.convention = spinham.convention.get_modified(...)

Thus, Magnopy forces you to create a new instance of the convention class, even if you need to change only one property of the convention.

For example, if you would like to change the value of \(C_{2,1}\) from 1.0 to -1.0, you can do the following

>>> mod_1 = Convention(
...     multiple_counting=convention.multiple_counting,
...     spin_normalized=convention.spin_normalized,
...     c1=convention.c1,
...     c21=-1.0,
...     c22=convention.c22,
...     name="Modified convention (verbose method)",
... )

However, this approach is unnecessarily verbose. Therefore, we provide a shortcut (Convention.get_modified()) to create a modified convention based on the existing one

>>> mod_2 = convention.get_modified(c21=-1.0, name="Modified convention (shortcut method)")

The resulting conventions are the same

>>> mod_1 == mod_2
True

Comparing conventions

As you noticed, two instance of the Convention class can be compared for equality

>>> mod_1 == mod_2
True
>>> mod_2 == convention
False

We note that only the properties of the convention are compared, while the name of the convention is not taken into account

>>> mod_1.name
'modified convention (verbose method)'
>>> mod_2.name
'modified convention (shortcut method)'
>>> # Therefore
>>> mod_1.name == mod_2.name
False
>>> # But
>>> mod_1 == mod_2
True

Pre-defined conventions

Magnopy gives access to the predefined conventions of the spin Hamiltonian from other codes

>>> tb2j_convention = Convention.get_predefined("TB2J")
>>> print(tb2j_convention)
"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 c42 factor;
  * Undefined c43 factor;
  * Undefined c44 factor;
  * Undefined c45 factor.

>>> grogu_convention = Convention.get_predefined("GROGU")
>>> print(grogu_convention)
"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 c42 factor;
  * Undefined c43 factor;
  * Undefined c44 factor;
  * Undefined c45 factor.

To see all supported codes see Convention.get_predefined().