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:

In [1]:

import micromagneticmodel as mm


class SpecialEnergy(mm.EnergyTerm):
    pass

Now, we can try to instantiate it

In [2]:

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:

In [3]:

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:

In [4]:

se = SpecialEnergy(U=3)
se

Out[4]:

$$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. More details can be found here.

In [5]:

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.

In [6]:

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:

In [7]:

se = SpecialEnergy(U=5e-5)

In [8]:

se.U

Out[8]:

5e-05

In [9]:

se

Out[9]:

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

In [10]:

repr(se)

Out[10]:

'SpecialEnergy(U=5e-05)'