Deriving an energy term

All energy terms in micromagneticmodel are in micromagneticmodel/energy directory. They are all derived from micromagneticmodel.energy.EnergyTerm base class.

For instance, let us say we want to implement an energy term with following specifications:

property	value
name	SpecialEnergy
expression	\(U\mathbf{m}\cdot\mathbf{m}\)
parameter	\(U\)
parameter properties	\(U \ge 0\), can be spatially varying

The energy term class would be:

import micromagneticmodel as mm


class SpecialEnergy(mm.EnergyTerm):
    pass

Now, we can try to instantiate it

try:
    se = SpecialEnergy(U=3)
except TypeError:
    print("Exception raised.")

Exception raised.

An exception was raised because effective_field, _reprlatex and _allowed_attributes properties must be implemented. Therefore, an extended implementation of the class is:

class SpecialEnergy(mm.EnergyTerm):
    _reprlatex = r"$U\mathbf{m}\cdot\mathbf{m}$"
    _allowed_attributes = ["U"]

    def effective_field(self, m):
        raise NotImplementedError

We can try to instantiate the class again:

se = SpecialEnergy(U=3)
se

$$U\mathbf{m}\cdot\mathbf{m}$$

The energy object is created. The last thing we have to impose on the energy class is the typesystem. More precisely, we have to make sure no negative \(U\) values are allowed and that name attribute accepts only valid Python variable names. This is done by using ubermagutil. Full documentation can be found here.

import discretisedfield as df
import ubermagutil.typesystem as ts


@ts.typesystem(U=ts.Parameter(descriptor=ts.Scalar(unsigned=True), otherwise=df.Field))
class SpecialEnergy(mm.EnergyTerm):
    _reprlatex = r"$U\mathbf{m}\cdot\mathbf{m}$"
    _allowed_attributes = ["U"]

    def effective_field(self, m):
        raise NotImplementedError

If we now attempt to pass invalid input arguments, exceptions are raised.

try:
    se = SpecialEnergy(U=-3, name="valid_name")  # negative U
except ValueError:
    print("Exception raised.")

Exception raised.

Some of the properties and methods of the implemented energy term are:

se = SpecialEnergy(U=5e-5)

se.U

5e-05

se

$$U\mathbf{m}\cdot\mathbf{m}$$

repr(se)

'SpecialEnergy(U=5e-05)'