Discussion: Terms of the spin Hamiltonian

[adrybakov]

Topic: What terms should be supported by the file format.?

[adrybakov]

Here is the list of the terms that have been mentioned in the summary or surveys:

• Linear interactions
  • Zeeman term
• Bi-linear interactions
  • Scalar isotropic Heisenberg exchange
  • Antisymmetric exchange (i. e. Dzyaloshinskii-Moriya interaction)
  • Symmetric anisotropic exchange (traceless part of the symmetric part of the full 3x3 matrix)
  • Quadratic on-site anisotropy
  • Classical magnetic dipole-dipole interaction
• Quad-linear interactions
  • Bi-quadratic exchange interaction
  • Quartic on-site anisotropy
• n-linear interactions
• Uniaxial, rotational, and cubic anisotropies up to the 6th order
• Crystal field parameters
• Magneto-elastic interaction

P. S. The micro-magnetic Hamiltonian is not mentioned here.

[adrybakov]

See also: Hamiltonian's zoo.

[adrybakov]

See also: Hamiltonian's zoo.

@malaei, @danielpozsar, @manueldsdias, @tweber-ill, @mcphase, @JeromeCCP9, @mducle, @Puerling, @mailhexu, @richard-evans, @kbarros, @anbergman, could you please check the pages of your tools, add or extend the information if needed and verify it (change status to "Verified")?

@Haichang-Lu, @silpicozunimib, @thomas641-lang, could you please add a page for your tool, following the same template?

[adrybakov]

I have compiled a potential generalisation of the Hamiltonian, that can account for all terms that are present in the participating tools. The compiled version of the document can be read here (compiled from 0d44a5e):

Attempt at generalization

Please try to find time to read it carefully, as in order to progress we need to be able to write the Hamiltonian down.

The Hamiltonian looks convoluted, but its concept is simple. I hope that if you read the page from the top, then its meaning will become clear. I tried to write it in a way, that the concepts are introduced gradually and in a simple way.

At the bottom of the page you can find a summary on how the general form connects to the Hamiltonian of each code.

Here is an overview of what was discussed for the mapping to the general form (screenshoot from the page)

Here are the codes, whose Hamiltonians I have mapped to the general form (only the codes, that have the "Verified" status in the "zoo", as only for those I am sure about the way the Hamiltonians are written)

What do you think?

P. S. If you agree with that form, then I will eventually write an FDP based on this document. As there were not much activity in this issue, perhaps an FDP could have been written right away. Nevertheless, I prefer to discuss this idea first in a less formal way.

[mcphase]

Dear Andrey, I am impressed by the very general way you analyse the problem. The only thought I am missing in the examples is the crystal field - striction, how would this map in your systematic approach ? With kind regards Martin

…

On 21. Jan 2026, at 20:46, Andrey Rybakov ***@***.***> wrote: adrybakov left a comment (spinham/spinham-format#1) <#1 (comment)> I have compiled a potential generalisation of the Hamiltonian, that can account for all terms that are present in the participating tools. The compiled version of the document can be read here (compiled from 0d44a5e <0d44a5e>): Attempt at generalization <https://spinham.github.io/spinham-format/generalization/index.html> Please try to find time to read it carefully, as in order to progress we need to be able to write the Hamiltonian down. Screenshot.2026-01-21.at.20.37.07.png (view on web) <https://github.com/user-attachments/assets/6aa7101f-a970-415b-9914-129cb838666b> Screenshot.2026-01-21.at.20.37.23.png (view on web) <https://github.com/user-attachments/assets/1c2ba823-0ece-4ab5-9f7a-e8d74c410ad9> The Hamiltonian looks convoluted, but its concept is simple. I hope that if you read the page from the top, then its meaning will become clear. I tried to write it in a way, that the concepts are introduced gradually and in a simple way. At the bottom of the page you can find a summary on how the general form connects to the Hamiltonian of each code. Here is an overview of what was discussed for the mapping to the general form (screenshoot from the page) Screenshot.2026-01-21.at.20.32.22.png (view on web) <https://github.com/user-attachments/assets/48d53870-9eab-4b6c-ade8-fac0c4e8d540> Here are the codes, whose Hamiltonians I have mapped to the general form (only the codes, that have the "Verified" status in the "zoo", as only for those I am sure about the way the Hamiltonians are written) Screenshot.2026-01-21.at.20.33.42.png (view on web) <https://github.com/user-attachments/assets/d818d079-12d1-4118-9919-9afb2f76dad1> What do you think? P. S. If you agree with that form, then I will eventually write an FDP based on this document. As there were not much activity in this issue, perhaps an FDP could have been written right away. Nevertheless, I prefer to discuss this idea first in a less formal way. — Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BDXATU54FPIAMAHUXWDO7334H7JQHAVCNFSM6AAAAACNPTY5JKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOOBQHAZTAMRZGQ>. You are receiving this because you were mentioned.

[adrybakov]

Dear Martin,

I was focused on purely magnetic "entities", however, you are right that the presented approach could account for, lets say, "half-magnetic" or "mixed" terms as well.

I have updated the text accordingly (basically moving from "magnetic sites" to "sites", still emphasising that they are usually magnetic, in the context of this effort) — build from 7c7a0ad. There is a new page that discusses the term that you mention: Magneto-elastic interaction and a the summary table was updated to include it.

P. S. Please note that I considered only one part of the term $\hat{\mathcal{H}}_{ME1}$ (the one that contains magnetic operator), however, the first term of that Hamiltonian can be mapped essentially in the same way.

Best,
Andrey

[mcphase]

Dear Andrey, Thank you for pointing this out and including the crystal field striction, I have only a formal problem - my safari browser does not show all formulas for the examples, it cuts off the right side … I attach a screenshot, With best wishes Martin 

…

On 23. Jan 2026, at 14:19, Andrey Rybakov ***@***.***> wrote: adrybakov left a comment (spinham/spinham-format#1) <#1 (comment)> Dear Martin, I was focused on purely magnetic "entities", however, you are right that the presented approach could account for, lets say, "half-magnetic" or "mixed" terms as well. I have updated the text accordingly (basically moving from "magnetic sites" to "sites", still emphasising that they are usually magnetic, in the context of this effort) — build from 7c7a0ad <7c7a0ad>. There is a new page that discusses the term that you mention: Magneto-elastic interaction <https://spinham.github.io/spinham-format/generalization/magneto-elastic.html> and a the summary table was updated to include it. P. S. Please note that I considered only one part of the term $\hat{\mathcal{H}}_{ME1}$ (the one that contains magnetic operator), however, the first term of that Hamiltonian can be mapped essentially in the same way. Best, Andrey — Reply to this email directly, view it on GitHub <#1 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BDXATUYUROXSWUS7PRL3VMT4IINVPAVCNFSM6AAAAACNPTY5JKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZTOOJQGIYDANJTHE>. You are receiving this because you were mentioned.

[adrybakov]

Dear Martin,

I can not see the screenshot, my guess is that GitHub does not display it, when a reply is made via e-mail (it is possible to attache images through the interface of GitHub itself, though. Here: #1).

In any case on the rendered page (Attempt at generalization) the formulas are supposed to be scrollable horizontally.

I checked it with Safary, so I can say that the scrolling works in my environment, please let me know if it does not work in yours.

Best,
Andrey

[lrozsa]

Dear Andrey,

thank you for compiling your ideas on the general format of the Hamiltonian. I agree with most of the points. However, I do not find the introduced l indices ideal for the notation.

I prefer to make the notation as transparent as possible. For the interaction coefficients V, this means that the identifiers should be unique, and by looking at the coefficient you should be able to reconstruct the corresponding term in the Hamiltonian easily. For me, this is not clear in the present notation. For example, for k=4, the coefficients both for l=2 and l=3 are denoted as V_{\mu_{1},\mu_{2};\alpha_{1},\alpha_{2}}^{i_{1},i_{2},i_{3},i_{4}}. To know what kind of interaction this term denotes, one has to additionally provide the l value, then one has to remember or look up in a table how for this specific l value the magnetic entities are distributed over the sites by the convention (i.e., the n values, in this case (3,1) or (2,2), with the order being also important).

I would suggest to consider an alternative notation: V_{\mu_{1},...,\mu_{k};\alpha_{1},...,\alpha_{k}}^{i_{1},...,i_{k}}, so the number of site and component indices is the same k, but the site indices may be repeated. This way the interaction coefficients would have a longer name, but there would be no need to introduce additional l,m,n indices.

Here the question arises whether the site indices could be written in any order (e.g., 1212), or that components from the same site are always written in one block (only 1122 or 2211), similarly to what you suggested. Here I would prefer the second option, although the first one might be easier to keep track of.

There is also the issue of multiple counting of the terms; I am not sure whether this applies to this discussion or you wanted to include this in a later topic. Since X_{\mu_{1};\alpha_{1}}^{i_{1}}X_{\mu_{2};\alpha_{2}}^{i_{2}}=X_{\mu_{2};\alpha_{2}}^{i_{2}}X_{\mu_{1};\alpha_{1}}^{i_{1}}, usually it is convenient to assume that V_{\mu_{1},\mu_{2};\alpha_{1},\alpha_{2}}^{i_{1},i_{2}}=V_{\mu_{2},\mu_{1};\alpha_{2},\alpha_{1}}^{i_{2},i_{1}} since only the symmetric part contributes to the energy. An alternative is to write each term only once, with a predefined order of indices. To generalize this to more magnetic entities, for me the symmetrization appears the most straightforward way. If you want to write each term only once, then in each case you have to define a convention in which order you want to write the indices. If you use the k and l indices, then you have to remember which indices you are allowed to permute (those sites which appear the same number of times in the expression), and this may get complicated if you want to define a unique normalization of the coefficients.

The multiple counting intersects with the issue of the repeated indices if you consider a quantum Hamiltonian. You generally have X_{\mu_{1};\alpha_{1}}^{i_{1}}X_{\mu_{1};\alpha_{1}}^{i_{2}}\neq_X__{\mu_{1};\alpha_{1}}^{i_{2}}X_{\mu_{1};\alpha_{1}}^{i_{1}}, because the operators on the same site do not commute. This means that it is necessary to enforce V_{\mu_{1},\mu_{1};\alpha_{1},\alpha_{1}}^{i_{1},i_{2}}=V_{\mu_{1},\mu_{1};\alpha_{1},\alpha_{1}}^{i_{2},i_{1}} (using the repeated indices I mentioned above), otherwise the Hamiltonian would not be self-adjoint. Again one has to think how to generalize this to more magnetic entities, but using the repeated indices and symmetrizing over the components seems to be rather straightforward.

I would also suggest to consider how you can calculate the effective field or force B_{\mu;\alpha}^{i}=-d_H_/d_X__{\mu;\alpha}^{i}. For this, you have to find all terms in the Hamiltonian which contain X_{\mu;\alpha}^{i}. If you use the k and l indices, it is necessary to go over all site indices in each term to find all such terms. With repeated site indices and the symmetrization mentioned above, it may be sufficient to find the terms where the first magnetic entity is X_{\mu;\alpha}^{i}, and calculate the effective field by knowing the correct normalization constants.

I would be interested in hearing your opinion about this.

Best regards,
Levente

[adrybakov]

I prefer to make the notation as transparent as possible. For the interaction coefficients V, this means that the identifiers should be unique, and by looking at the coefficient you should be able to reconstruct the corresponding term in the Hamiltonian easily. For me, this is not clear in the present notation. For example, for $k=4$, the coefficients both for $l=2$ and $l=3$ are denoted as $V_{\mu_{1},\mu_{2};\alpha_{1},\alpha_{2}}^{i_{1},i_{2},i_{3},i_{4}}$. To know what kind of interaction this term denotes, one has to additionally provide the $l$ value, then one has to remember or look up in a table how for this specific $l$ value the magnetic entities are distributed over the sites by the convention (i.e., the $n$ values, in this case (3,1) or (2,2), with the order being also important).

I would suggest to consider an alternative notation: $V_{\mu_{1},...,\mu_{k};\alpha_{1},...,\alpha_{k}}^{i_{1},...,i_{k}}$, so the number of site and component indices is the same $k$, but the site indices may be repeated. This way the interaction coefficients would have a longer name, but there would be no need to introduce additional $l$, $m$, $n$ indices.

At the moment I do not have a strong feeling for either one. Perhaps it will be the one to use at the end.

Note (for all): here is how this choice will translate into the file format itself (with $k = 4$ as an example):

The parameter is a $3\times3\times3\times3$ tensor (assume 3-component spins for entities). Then one will have to differentiate between five cases somehow. The amount of sites differentiate some of the cases (i. e. $l=2,3$ are still degenerate). Then one have to indicate something else to differentiate between all cases.

If the Hamiltonian is written as of now (7c7a0ad), then the term's "header" will be written as (for the case $l = 2$)

l = 2
 (1,1,0) 0 1

with the interpretation $\mu_1 = (0,0,0), \mu_2 = (1,1,0), \alpha_1 = 0, \alpha_2 = 1$

with the proposal of Levente, the header of the same term would be written as

(0,0,0) (1, 1, 0) (1, 1, 0) 0 0 1 1 

with the same interpretation. In both cases the header will be followed by the $3\times3\times3\times3$ tensor

Note that the unit cell's index for the first magnetic site can be always assumed to be $(0,0,0)$ and therefore omitted due to the periodicity of the lattice. The format of the header is arbitrary, please focus on its content.

EDIT: Actually, after writing that note I think that Levente's idea is better

[adrybakov]

usually it is convenient to assume that $V_{\mu_{1},\mu_{2};\alpha_{1},\alpha_{2}}^{i_{1},i_{2}}=V_{\mu_{2},\mu_{1};\alpha_{2},\alpha_{1}}^{i_{2},i_{1}}$ since only the symmetric part contributes to the energy.

I would like to note, that this property would be a conscience of assuming that the Hamiltonian is Hermitian.

Moreover, I have issue with saying that "only symmetric part contributes to the energy", as I find it misleading. Antisymmetric part of the $3\times3$ matrix do contribute to the energy of the Hamiltonian (think about the DMI term). In particular due to the property that you mention.

[adrybakov]

Here the question arises whether the site indices could be written in any order (e.g., 1212), or that components from the same site are always written in one block (only 1122 or 2211), similarly to what you suggested. Here I would prefer the second option, although the first one might be easier to keep track of.

This issue is separate from the multiple counting issue. Choose a fixed $\mu_1, \mu_2, \alpha_1, \alpha_2$, for example say that $(\mu_1, \alpha_1) = 1$ and $(\mu_2, \alpha_2) = 2$. Then, the question here is whether to write

$\sum_{i_1, i_2, i_3}V_{1,2}^{i_1, i_2, i_3} X_1^{i_1}X_1^{i_2}X_2^{i_3}$ $(1)$

or

$\sum_{i_1, i_2, i_3}V_{1,2}^{i_1, i_2, i_3} X_1^{i_1}X_2^{i_2}X_1^{i_3}$ $(2)$

while the issue of multiple counting is concerned about whether to include in the sum both terms: $(\mu_1, \alpha_1, \mu_2, \alpha_2) = (1, 2)$ and $(\mu_1, \alpha_1, \mu_2, \alpha_2) = (2, 1)$ or only one term: either $(\mu_1, \alpha_1, \mu_2, \alpha_2) = (1, 2)$ or $(\mu_1, \alpha_1, \mu_2, \alpha_2) = (2, 1)$. Problem of multiple counting applies to both forms written above.

Note that this issue appears only with $k &gt;= 3$.

First of all, note that the equations (1) and (2) contain exactly the same information. one can be transformed into another by mere reordering of components of the interaction parameters. For example, start with (2), then rename $i_2 \leftrightarrow i_3$, one gets

$\sum_{i_1, i_2, i_3}V_{1,2}^{i_1, i_3, i_2} X_1^{i_1}X_2^{i_3}X_1^{i_2}$ $(2)$

$X_2$, $X_1$ commute, then

$\sum_{i_1, i_2, i_3}V_{1,2}^{i_1, i_3, i_2} X_1^{i_1}X_1^{i_2}X_2^{i_3}$ $(2)$

Finally, by reordering dimensions of the parameter $V$ as $V_{1,2}^{i_1, i_3, i_2} \rightarrow V_{1,2}^{i_1, i_2, i_3}$ one gets (1).

With the argument above I tried to highlight that this issue is purely about the choice of how to write a Hamiltonian as all variations of that choice contain exactly the same information, independently of whether the Hamiltonian is Hermitian or not.

On contrary the multiple counting is being a convention choice only for the Hermitian Hamiltonians.

[adrybakov]

Now, coming back with

l = 2
 (1,1,0) 0 1

vs

(0,0,0) (1, 1, 0) (1, 1, 0) 0 0 1 1 

The first option enforces the choice of the indices order (see previous comment), while the second allows that liberty. Therefore, the second option bloats the amount of possible interpretations for each term.