Added documentation to meshes

Author: davidcorteso

fidimag/atomistic/exchange.py

@@ -76,6 +76,9 @@ def my_exchange(pos):
     will not call array elements to compute the neighbours contribution but
     it will only use a constant, thus it should be faster
 
+    * If option 3. is pecified for the J parameter, this class will call the
+    full exchange calculation function from the C library
+
     """
 
     def __init__(self, J, name='Exchange'):

fidimag/atomistic/hexagonal_mesh.py

@@ -57,6 +57,8 @@ def __init__(self, radius, nx, ny,
             height  = sqrt(3) * radius
             width = 2 * radius.
 
+        radius ::
+
         The radius is for an incircle inside the hexagon, thus the distance
         between two lattice sites at the same y coordinate, is just 2 * radius,
         which can be seen as the triangular lattice constant.
@@ -68,15 +70,41 @@ def __init__(self, radius, nx, ny,
         distance, in terms of dx = 2 * radius, can be easily calculated as
         2 * dx / sqrt(3), since the hexagon height is: (3 / 4) * height
 
+        alignment ::
+
+        The alignment of the hexagons can be set to 'diagonal' or 'square'. In
+        both cases the matrix with the neighbours indexes will have the same
+        order for every row (see definition of shells)
+
+        periodicity ::
+
         By default, the mesh is not periodic along any axis, so the periodicity
         is set to (False, False). Passing a tuple with any combination of
         entries set to True will enable periodicity along the given axes.
+        Periodic boundaries are not defined when using a 'square' alignment.
 
-        The alignment of the hexagons can be set to 'diagonal' or 'square' In
-        both cases the matrix with the neighbours indexes will have the same
-        order for every row (lattice site):
+        unit_length ::
+
+        The scale unit for the lattice distances. Default is 1.0 but it is
+        commonly used a nm = 1e-9
+
+        shells ::
+
+        An integer specifying the number of shells of neighbours to be computed
+        and stored in the *ngbs array. By default, a value of 1 indicates
+        only nearest neighbours. The *ngbs array has the structure:
+
+        [ [ ngbs_1st_shell_0 negbs_2nd_shell_0 ...  ],      --> ngbs of spin 0
+          [ ngbs_1st_shell_1 negbs_2nd_shell_1 ...  ],      --> ngbs of spin 1
+          ...
+          [ ngbs_1st_shell_n negbs_2nd_shell_n ...  ]       --> ngbs of spin n
+        ]
+
+        where ngbs_1st_shell_i are the nearest neighbours of the i-th spin in
+        the order:
+            [ left right top_right bottom_left top_left bottom_right ]
 
-            | left right top_right bottom_left top_left bottom_right |
+        For the other shells see the *_ngbs_Xth_shell methods from this class
 
         """
 
@@ -315,7 +343,7 @@ def index(self, i, j):
                 i = 0            # to the left
         if self.periodicity[1]:
             if self.alignment == 'square':
-                raise Exception('PBCs Not well'
+                raise Exception('PBCs not well '
                                 'defined for a square arrangement')
                 # if j == -1:
                 #     i += int(self.ny / 2)
@@ -386,6 +414,9 @@ def hexagon_corners(self, x, y, radius):
                  0) for theta in angle_rad]
 
     # -------------------------------------------------------------------------
+    # Functions that return the number of neighbours at the n-th shell at
+    # a lattice site with position indexes (i, j). For example,
+    # the function _ngbs_first_shell returns the nearest neighbours
 
     def _ngbs_first_shell(self, i, j):
 

fidimag/common/cuboid_mesh.py

@@ -54,7 +54,7 @@ def __init__(self, dx=1, dy=1, dz=1, nx=1, ny=1, nz=1, x0=0, y0=0, z0=0,
 
         """
 
-        # total number of neighbours per lattice site
+        # Total number of neighbours per lattice site
         # (only nearest ngbs for now)
         self.n_ngbs = 6