Added update_field function to the atomistic Zeeman field class, using the micromagnetic one. Documented Zeeman field objects. Changed H0 to B0 in the atomistic Zeeman field since it uses Tesla rather than A / m as in the micromagnetic model.

Author: davidcorteso

fidimag/atomistic/zeeman.py

@@ -5,11 +5,50 @@
 class Zeeman(object):
 
     """
-    The time independent external field, can vary with space
+
+    A time independent external magnetic field that can be space dependent.
+    The field energy is computed as:
+
+                  __   ->         ->
+         E =  -  \    \mu_i \cdot B_i
+                 /__
+                  i
+
+    where mu_i = g \mu_B S_i is the magnetic moment vector at the i-th lattice
+    site, g is the Lande factor, \mu_B the Bohr magneton, S_i the average total
+    spin vector at the i-th site and B_i the bias field vector at the i-th
+    site, given in Tesla units.
+
+    If the field is homogeneous, it can be specified in a simulation object
+    *Sim* as
+
+            Sim.add(Zeeman((B_x, B_y, B_z)))
+
+    Otherwise, it can be specified as any Fidimag field, passing a function or
+    an array. For example, a space dependent field function that changes
+    linearly in the x-direction, and only has a x-component, can be defined as:
+
+        def my_Zeeman_field(pos):
+            B = 0.01  # T
+            return (B * pos[0], 0, 0)
+
+        # Add field to Simulation object
+        Sim.add(Zeeman(my_Zeeman_field))
+
+
+    For a hysteresis loop, the field can be updated using the *update_field*
+    function. For an already defined simulation object *Sim*, it is updated as
+
+        Sim.get_interaction('Zeeman').update_field(new_field)
+
+    where new_field is a 3-tuple, and array or a function, as shown before.
+    It is recommended to reset the integrator with *Sim.reset_integrator()*
+    to start a new relaxation after updating the field.
+
     """
 
-    def __init__(self, H0, name='Zeeman'):
-        self.H0 = H0
+    def __init__(self, B0, name='Zeeman'):
+        self.B0 = B0
         self.name = name
         self.jac = False
 
@@ -28,7 +67,11 @@ def setup(self, mesh, spin, mu_s):
         self.mu_s_long.shape = (-1,)
 
         self.field = np.zeros(3 * self.n)
-        self.field[:] = helper.init_vector(self.H0, self.mesh)
+        self.field[:] = helper.init_vector(self.B0, self.mesh)
+
+    def update_field(self, B0):
+        self.B0 = B0
+        self.field[:] = helper.init_vector(self.B0, self.mesh)
 
     def compute_field(self, t=0):
         return self.field
@@ -56,8 +99,8 @@ class TimeZeeman(Zeeman):
     The time dependent external field, also can vary with space
     """
 
-    def __init__(self, H0, time_fun, name='TimeZeeman'):
-        self.H0 = H0
+    def __init__(self, B0, time_fun, name='TimeZeeman'):
+        self.B0 = B0
         self.time_fun = time_fun
         self.name = name
         self.jac = False

fidimag/micro/zeeman.py

@@ -7,7 +7,50 @@
 class Zeeman(object):
 
     """
-    The time independent external field, can vary with space
+    A time independent external magnetic field that can be space dependent.
+    The field energy in the micromagnetic theory reads:
+                                 _
+                               /   ->       ->
+           E   =  - \mu_0     /    M  \cdot H   dV
+                           _ /
+
+    with H as the bias field in A / m, \mu_0 the vacuum permeability and M the
+    magnetisation vector. Using finite differences, this quantity is computed
+    through the summation
+
+                              __  ->        ->
+         E =  - \mu_0 * dV   \    M_i \cdot H_i
+                             /__
+                              i
+
+    where M_i is the magnetisation at the i-th position of the mesh
+    discretisation and dV = dx * dy * dz is the volume of a mesh unit cell.
+
+    If the field is homogeneous, it can be specified in a simulation object
+    *Sim* as
+
+            Sim.add(Zeeman((H_x, H_y, H_z)))
+
+    Otherwise, it can be specified as any Fidimag field, passing a function or
+    an array. For example, a space dependent field function that changes
+    linearly in the x-direction, and only has a x-component, can be defined as:
+
+        def my_Zeeman_field(pos):
+            H = 0.01 / (4 * np.pi * 1e-7)  # A / m
+            return (H * pos[0], 0, 0)
+
+        # Add field to Simulation object
+        Sim.add(Zeeman(my_Zeeman_field))
+
+    For a hysteresis loop, the field can be updated using the *update_field*
+    function. For an already defined simulation object *Sim*, it is updated as
+
+        Sim.get_interaction('Zeeman').update_field(new_field)
+
+    where new_field is a 3-tuple, and array or a function, as shown before.
+    It is recommended to reset the integrator with *Sim.reset_integrator()*
+    to start a new relaxation after updating the field.
+
     """
 
     def __init__(self, H0, name='Zeeman'):
@@ -29,6 +72,9 @@ def setup(self, mesh, spin, Ms):
         self.Ms = Ms
         self.Ms_long = np.zeros(3 * mesh.n)
 
+        # TODO: Check if it is necessary to define a 3D matrix for
+        # the Ms vectors. Maybe there is a way that uses less memory
+        # (see the calculation in the *compute_energy* function)
         self.Ms_long.shape = (3, -1)
         for i in range(mesh.n):
             self.Ms_long[:, i] = Ms[i]