magnopy.SpinHamiltonian.add_22#

method

SpinHamiltonian.add_22(alpha: int, beta: int, nu: tuple, parameter, units=None, when_present='raise error', replace=None) → None#

Adds a (two spins & two sites) parameter to the Hamiltonian.

Doubles of the bonds are managed automatically (independently of the convention of the Hamiltonian). beta, alpha, -nu, parameter.T is a double of alpha, beta, nu, parameter.

Parameters:
alphaint

Index of an atom from the (0, 0, 0) unit cell.

0 <= alpha < len(spinham.atoms.names).

betaint

Index of an atom from the nu unit cell.

0 <= beta < len(spinham.atoms.names).

nutuple of 3 int

Three relative coordinates with respect to the three lattice vectors, that specify the unit cell for the second atom.

\[\nu = (x_{\boldsymbol{a}_1}, x_{\boldsymbol{a}_2}, x_{\boldsymbol{a}_3})\]
parameter(3, 3) array-like

Value of the parameter (\(3\times3\) matrix). Given in the units of units.

unitsstr, optional

Added in version 0.3.0.

Units in which the parameter is given. Parameters have the the units of energy. By default assumes SpinHamiltonian.units. For the list of the supported units see Units of Hamiltonian's parameters. If given units are different from SpinHamiltonian.units, then the parameter's value will be converted automatically from units to SpinHamiltonian.units.

when_presentstr, default "raise error"

Added in version 0.4.0.

Action to take if a pair of atoms already has a parameter associated with it. Case-insensitive. Supported values are:

  • "raise error" (default): raises an error if a pair of atoms already has a parameter associated with it.

  • "replace": replace existing value of the parameter with the new one.

  • "add": add the value of the parameter to the existing one.

  • "mean": replace the value of the parameter with the arithmetic mean of existing and new parameters.

  • "skip": Leave existing parameter unchanged and continue without raising an error.

replacebool, default False

Whether to replace the value of the parameter if a pair of atoms already has a parameter associated with it.

Deprecated since version 0.4.0: The replace argument will be removed in May of 2026. Use modify="replace" instead.

Raises:
ValueError

If a pair of atoms already has a parameter associated with it and when_present="raise error".

ValueError

If when_present has an unsupported value.

See also

p22
remove_22

Notes

If spinham.convention.multiple_counting is True, then this function adds both the bond and its double to the Hamiltonian. It will cause an ValueError to add the double of the bond after the bond is added.

If spinham.convention.multiple_counting is False, then only the primary version of the bond is added to the Hamiltonian.

For the definition of the primary version see Multiple counting.