Merge branch 'master' of github.com:computationalmodelling/fidimag

Author: rpep

doc/ipynb/runtimes.org

@@ -0,0 +1,17 @@
+* <2016-05-01 Sun>
+
+To see which tests run long:
+
+cd doc/ipynb && py.test . -v --nbval --duration=10 --sanitize-with sanitize_file
+
+========================== slowest 10 test durations ===========================
+17209.34s call     doc/ipynb/isolated_skyrmion.ipynb::Cell 13
+4098.12s call     doc/ipynb/standard_problem_4.ipynb::Cell 19
+967.73s call     doc/ipynb/spin-polarised-current-driven-skyrmion.ipynb::Cell 14
+703.63s call     doc/ipynb/standard_problem_4.ipynb::Cell 15
+20.86s call     doc/ipynb/tutorial-basics.ipynb::Cell 21
+6.32s call     doc/ipynb/spin-waves-in-periodic-system.ipynb::Cell 13
+6.16s call     doc/ipynb/isolated_skyrmion.ipynb::Cell 11
+5.76s call     doc/ipynb/current-driven-domain-wall.ipynb::Cell 24
+1.95s call     doc/ipynb/current-driven-domain-wall.ipynb::Cell 18
+1.67s call     doc/ipynb/spin-polarised-current-driven-skyrmion.ipynb::Cell 11

fidimag/atomistic/anisotropy.py

@@ -7,18 +7,49 @@
 class Anisotropy(Energy):
 
     """
-        compute the anisotropy field with the energy density E = - K (m.u)^2
+
+    This class provides an anisotropy term to the system energy, which
+    is defined as
+
+                  __         ->    ^     2
+         E =  -  \    K_i  ( S_i * u_i )
+                 /__
+                  i
+
+    with K_i the anisotropy constant at the i-th site and u_i the unitary
+    direction of the anisotropy vector at the i-th site, thus the magnitude and
+    axis can be space dependent.
+
+    OPTIONAL ARGUMENTS --------------------------------------------------------
+
+        Ku          :: The anisotropy constant. Can be a constant or a space
+                       dependent scalar field, given as a function or array.
+
+        axis        :: The unitary axis vector. It can be a 3 tuple, list
+                       or array (uniaxial anisotropy), or a space dependent
+                       vector field, gicen as a function or array.
+
+        name        :: Interaction name
+
+    USAGE ---------------------------------------------------------------------
+
+    Considering a simulation object *Sim*, an uniaxial anisotropy along
+    the z direction can be defined as
+
+            K = 1 * meV
+            Sim.add(Anisotropy(K, axis=(0, 0, 1)))
+
+    For a space dependent anisotropy along the x direction, we can define a
+    scalar field for the magnitude and a vector field for the anisotropy axes.
+
     """
 
-    def __init__(self, Ku, axis=(1, 0, 0), name='anis', direction=None):
+    def __init__(self, Ku, axis=(1, 0, 0), name='anis'):
         self.Ku = Ku
         self.name = name
         self.axis = axis
         self.jac = True
 
-        if direction is not None:
-            self.axis = direction
-
     def setup(self, mesh, spin, mu_s):
         super(Anisotropy, self).setup(mesh, spin, mu_s)
 

fidimag/atomistic/dmi.py

@@ -6,11 +6,74 @@
 class DMI(Energy):
 
     """
-    Hamiltonian = D*[S_i x S_j]
-        ==> H = D x S_j
+
+    This class provides the Dzyaloshinskii-Moriya Interaction (DMI) energy
+    term, defined as
+
+                  __  ->         ->      ->
+         E =     \    D_ij   * ( S_i  X  S_j )
+                 /__
+                <i, j>
+                i != j
+
+    where D_ij is the Dzyaloshinskii vector, S_i and S_j are the total spin
+    vectors at the i-th and j-th lattice sites, and <i, j> means counting the
+    interaction between neighbouring spins only once. The Dzyaloshinskii vector
+    magnitude can vary with space.
+
+    Currently, there are implemented two kinds of DMI, that depend on the
+    Dzyaloshinskii vector definition. Calling D_i the Dzyaloshinskii vector
+    magnitude at the i-th site:
+
+    BULK:
+        ->         ^
+        D_ij = D_i r_ij   with r_ij as the unit vector pointing from the i-th
+                          towards the j-th site
+                          (only working for square lattices)
+
+    INTERFACIAL:
+
+        ->           ^       ^
+        D_ij = D_i ( r_ij X  z ) with r_ij as the unit vector pointing from the
+                                 i-th towards the j-th site and z the unitary
+                                 vector perpendicular to the magnetic material
+                                 plane which, in theory, is in contact with a
+                                 material with larger SOC (e.g. a metal).
+                                 Thus, this DMI is defined in 2D, for
+                                 interfaces or thin films.
+
+    For further details about the DMI calculations, take a look
+    to the C library documentation (dmi.c)
+
+
+    OPTIONAL ARGUMENTS: -------------------------------------------------------
+
+        dmi_type        :: 'bulk' or 'interfacial'
+        name            :: Interaction name
+
+    USAGE: --------------------------------------------------------------------
+
+    If the DMI is homogeneous, it can be specified in a simulation object
+    *Sim* as
+
+            Sim.add(DMI(D, dmi_type='bulk'))
+
+    where D is a float.
+
+    Otherwise, it can be specified as any Fidimag scalar field, passing a
+    function or an array. For example, a space dependent DMI that changes
+    linearly in the x-direction can be defined as:
+
+        def my_DMI(pos):
+            D = 0.01 * meV
+            return D * pos[0]
+
+        # Add DMI to Simulation object
+        Sim.add(DMI(my_DMI))
+
     """
 
-    def __init__(self, D, name='dmi', dmi_type='bulk'):
+    def __init__(self, D, name='DMI', dmi_type='bulk'):
         self.D = D
 
         self.name = name
@@ -32,20 +95,20 @@ def setup(self, mesh, spin, mu_s):
         # We will generate the Dzyaloshinskii vectors according
         # to the lattice, for the Interfacial DMI
         self.DMI_vector = self.compute_DMI_vectors(self.nneighbours)
-        
+
         if self.dmi_type == 'bulk':
             self._D = np.zeros(self.neighbours.shape)
             if isinstance(self.D, (int, float)):
-                self._D[:,:] = self.D
+                self._D[:, :] = self.D
             elif hasattr(self.D, '__call__'):
-                n =  self.mesh.n
+                n = self.mesh.n
                 for i in range(n):
                     value = self.D(self.coordinates[i])
                     if len(value) == 6:
-                        self._D[i,:] = value[:]
+                        self._D[i, :] = value[:]
                     else:
                         raise Exception('The given spatial function for D is not acceptable!')
-            
+
 
     def compute_field(self, t=0, spin=None):
 
@@ -55,7 +118,7 @@ def compute_field(self, t=0, spin=None):
             m = self.spin
 
         if self.dmi_type == 'bulk':
-              clib.compute_dmi_field(m,
+            clib.compute_dmi_field(m,
                                    self.field,
                                    self.energy,
                                    self._D,

fidimag/atomistic/exchange.py

@@ -6,17 +6,39 @@
 class UniformExchange(Energy):
 
     """
-    The Hamiltonian is defined as
 
-        Hamiltonian = - J \sum_<i,j> S_i \cdot S_j
+    This class provides the Exchange Interaction energy term for a
+    homogeneous material, defined as
 
-    where the brackets represent the nearest neighbours and only evaluate once
-    for each pair, which means for two spins case, the total energy is
-    -J S_1 S_2. Therefore, the effective field at site i is,
+                  __        ->      ->
+         E =  -  \    J_ij  S_i  *  S_j
+                 /__
+                <i, j>
+                i != j
 
-        H_i = J \sum_<i,j> S_j
+    where J_ij is the exchange tensor, S_i and S_j are the total spin vectors
+    at the i-th and j-th lattice sites, and <i, j> means counting the
+    interaction between neighbouring spins only once (notice that there is no
+    factor of 2 associated with J)
+
+    This class only computes a uniform exchange field, thus J_ij is a
+    diagonal tensor with constant magnitude, J_ij -> J
+
+
+    OPTIONAL ARGUMENTS: -------------------------------------------------------
+
+        J               :: A number for the exchange tensor magnitude
+        name            :: Interaction name
+
+    USAGE: --------------------------------------------------------------------
+
+    For a homogeneous material, it can be specified in a simulation object
+    *Sim* as
+
+            Sim.add(UniformExchange(J))
+
+    where J is a float.
 
-    notice that there is no factor of 2 associated with J.
     """
 
     def __init__(self, J=0, name='exch'):
@@ -64,42 +86,84 @@ def compute_energy_directly(self):
 class Exchange(Energy):
 
     """
-    The Hamiltonian is defined as
+    This class provides the Exchange Interaction energy term, defined as
+
+                  __        ->      ->
+         E =  -  \    J_ij  S_i  *  S_j
+                 /__
+                <i, j>
+                i != j
+
+    where J_ij is the exchange tensor, S_i and S_j are the total spin vectors
+    at the i-th and j-th lattice sites, and <i, j> means counting the
+    interaction between neighbouring spins only once (notice that there is no
+    factor of 2 associated with J)
+
+    In general, J_ij is space dependent and must be specified for every
+    neighbour.  For a homogeneous material, J_ij is a diagonal tensor with
+    constant magnitude, i.e. J_ij -> J.
+
+
+    OPTIONAL ARGUMENTS: -------------------------------------------------------
+
+        J_fun           :: The exchange tensor which can be  a number (same
+                           magnitude for every neighbour at every lattice site)
+                           or a space dependent function that returns 6
+                           components, one for every nearest neighbour (NN).
+                           For a square lattice the NNs are defined in 3D as:
+                           [-x +x -y +y -z +z], thus the exchange components
+                           are specified in that order. In a hexagonal lattice
+                           the NNs are only in a 2D plane as the cardinal
+                           positions: [W E NE SW NW SE].
 
-        Hamiltonian = -  \sum_<i,j> J_ij S_i \cdot S_j
+        name            :: Interaction name
 
-    where the brackets represent the nearest neighbours and only evaluate once
-    for each pair, which means for two spins case, the total energy is
-    -J S_1 S_2. Therefore, the effective field at site i is,
+    USAGE: --------------------------------------------------------------------
+
+    For a homogeneous material, it can be specified in a simulation object
+    *Sim* as
+
+            Sim.add(Exchange(J))
+
+    where J is a float.
+
+    Otherwise, the exchange tensor is spatial dependent, and must be specified
+    using a function. For a cubic mesh, for example, if we want a linear
+    dependence only with in plane components:
+
+            def my_exchange(pos):
+                J = 1 * meV
+                x, y, z = pos[0], pos[1], pos[2]
+
+                return (x * J, x * J, y * J, y * J, 0, 0)
+
+            Sim.add(Exchange(my_exchange))
 
-        H_i = \sum_<i,j> J_ij S_j
 
-    notice that there is no factor of 2 associated with J_ij.
     """
 
     def __init__(self, J_fun, name='exch'):
         self.J_fun = J_fun
         self.name = name
         self.jac = False
-    
+
     def setup(self, mesh, spin, mu_s):
         super(Exchange, self).setup(mesh, spin, mu_s)
 
         self._J = np.zeros(self.neighbours.shape)
 
         if isinstance(self.J_fun, (int, float)):
-            self._J[:,:] = self.J_fun
+            self._J[:, :] = self.J_fun
         elif hasattr(self.J_fun, '__call__'):
-            n =  self.mesh.n
+            n = self.mesh.n
             for i in range(n):
                 value = self.J_fun(self.coordinates[i])
                 if len(value) == 6:
-                    self._J[i,:] = value[:]
+                    self._J[i, :] = value[:]
                 else:
                     raise Exception('The given spatial function for J is not acceptable!')
             pass
-        
-        
+
     def compute_field(self, t=0, spin=None):
 
         if spin is not None:
@@ -108,10 +172,10 @@ def compute_field(self, t=0, spin=None):
             m = self.spin
 
         clib.compute_exchange_field_spatial(m,
-                                    self.field,
-                                    self.energy,
-                                    self._J,
-                                    self.neighbours,
-                                    self.n)
+                                            self.field,
+                                            self.energy,
+                                            self._J,
+                                            self.neighbours,
+                                            self.n)
 
         return self.field * self.mu_s_inv