magnopy.SpinHamiltonian.add#

method

SpinHamiltonian.add(nus, alphas, parameter, units=None, populate_equivalent=False, when_present='raise error')[source]#

Adds any parameter with at most four components of spin operator to the Hamiltonian.

Added in version 0.5.0.

See Spin Hamiltonian for the definition of the Hamiltonian.

Parameters:
nus(n, 3) or (n-1, 3) list/tuple of tuple of int

List of unit cell indices associated with the parameter. Each unit cell index is a tuple of three integers (t_1, t_2, t_3) corresponding to the translation by \(t_1 \boldsymbol{a}_1 + t_2 \boldsymbol{a}_2 + t_3 \boldsymbol{a}_3\).

alphas(n,) list/tuple of int

List of indices of atoms associated with the parameter. Based on the order in SpinHamiltonian.atoms.

unitsstr, optional

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

populate_equivalentbool, default False

Whether to automatically populate all equivalent parameters related by the symmetrization procedure. Ignored if convention.multiple_counting is False. See Equivalent parameters for more details.

when_presentstr, default "raise error"

Action to take if such parameter is already present in the Hamiltonian. Case-insensitive. Supported values are:

  • "raise error" (default): raises an error.

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

  • "sum": 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.

Notes

If len(nus) == len(alphas) - 1, then

  • alphas[0] always located in the unit cell (0, 0, 0).

  • alphas[i] is located in the unit cell nus[i-1] for i >= 1.

If len(nus) == len(alphas), then

  • alphas[i] is located in the unit cell nus[i] for all i.

Note that the translational symmetry is always enforced, so in the second case the nus are updated as nus[i] = nus[i] - nus[0] for all i before the parameter is added to the Hamiltonian.

Examples

See Adding parameters for more details on how to use this method.