Docs: improvements for Python API.

Reformatted some of the markdown docs of the Python API and added some missing information.
Also changed `io.chain_read` to read in the entire file by default.

core/python/spirit/chain.py

@@ -179,7 +179,7 @@ def setup_data(p_state, idx_chain=-1):
 _Get_Rx.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Rx.restype  = None
 def get_reaction_coordinate(p_state, idx_chain=-1):
-    """Returns an array of shape (NOI) containing the reaction coordinates of the images."""
+    """Returns an array of `shape(NOI)` containing the reaction coordinates of the images."""
     noi = get_noi(p_state, idx_chain)
     Rx = (noi*ctypes.c_float)()
     _Get_Rx(ctypes.c_void_p(p_state), Rx, ctypes.c_int(idx_chain))
@@ -206,7 +206,7 @@ def get_reaction_coordinate_interpolated(p_state, idx_chain=-1):
 _Get_Energy.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Energy.restype  = None
 def get_energy(p_state, idx_chain=-1):
-    """Returns an array of shape (NOI) containing the energies of the images."""
+    """Returns an array of `shape(NOI)` containing the energies of the images."""
     noi = get_noi(p_state, idx_chain)
     Energy = (noi*ctypes.c_float)()
     _Get_Energy(ctypes.c_void_p(p_state), Energy, ctypes.c_int(idx_chain))

core/python/spirit/configuration.py

@@ -3,6 +3,14 @@
 ====================
 
 Set various spin configurations, such as homogeneous domains, spirals or skyrmions.
+
+All configuration setters support the following arguments with default values:
+
+- `pos=[0,0,0]`: the centre of the configuration, relative to the centre of the system
+- `border_rectangular=[-1,-1,-1]`: values > 0 mean a restriction in `+` and `-` direction relative to the position
+- `border_cylindrical=-1`: restricts the initialisation to a z-aligned cylinder around the position
+- `border_spherical=-1`: restricts the initialisation to a sphere around the position
+- `inverted=False`: exactly inverts the above restrictions
 """
 
 import spirit.spiritlib as spiritlib
@@ -31,7 +39,7 @@ def domain(p_state, dir, pos=[0,0,0], border_rectangular=[-1,-1,-1], border_cyli
 _PlusZ.restype     = None
 def plus_z(p_state, pos=[0.0,0.0,0.0], border_rectangular=[-1.0,-1.0,-1.0], border_cylindrical=-1.0,
           border_spherical=-1.0, inverted=False, idx_image=-1, idx_chain=-1):
-    """Set a +z (homogeneous) configuration."""
+    """Set a `+z` (homogeneous) configuration."""
     vec3 = ctypes.c_float * 3
     _PlusZ(ctypes.c_void_p(p_state), vec3(*pos), vec3(*border_rectangular),
            ctypes.c_float(border_cylindrical), ctypes.c_float(border_spherical),
@@ -44,7 +52,7 @@ def plus_z(p_state, pos=[0.0,0.0,0.0], border_rectangular=[-1.0,-1.0,-1.0], bord
 _MinusZ.restype     = None
 def minus_z(p_state, pos=[0,0,0], border_rectangular=[-1,-1,-1], border_cylindrical=-1,
           border_spherical=-1, inverted=False, idx_image=-1, idx_chain=-1):
-    """Set a -z (homogeneous) configuration."""
+    """Set a `-z` (homogeneous) configuration."""
     vec3 = ctypes.c_float * 3
     _MinusZ(ctypes.c_void_p(p_state), vec3(*pos), vec3(*border_rectangular),
             ctypes.c_float(border_cylindrical), ctypes.c_float(border_spherical),
@@ -89,16 +97,19 @@ def skyrmion(p_state, radius, order=1, phase=1, up_down=False, achiral=False, ri
              pos=[0,0,0], border_rectangular=[-1,-1,-1], border_cylindrical=-1, border_spherical=-1,
              inverted=False, idx_image=-1, idx_chain=-1):
     """Set a skyrmion configuration.
-    
-    - radius: the extent of the skyrmion, at which it points approximately upwards
-    - order: the number of twists along a circle cutting the skyrmion
-    - phase: 0 corresponds to a Neel skyrmion, -90 to a Bloch skyrmion
-    - up_down: if `True`, the z-orientation is inverted
-    - achiral: if `True`, the topological charge is inverted
-    - right_left: if `True`, the in-plane rotation is inverted
-
-    The skyrmion only extends up to `radius`, meaning that `border_cylindrical` is
-    not usually necessary.
+
+    Arguments:
+
+    - `radius`: the extent of the skyrmion, at which it points approximately upwards. The skyrmion only extends up to `radius`, meaning that `border_cylindrical` is not usually necessary.
+
+    Keyword arguments:
+
+    - `order`: the number of twists along a circle cutting the skyrmion
+    - `phase`: 0 corresponds to a Neel skyrmion, -90 to a Bloch skyrmion
+    - `up_down`: if `True`, the z-orientation is inverted
+    - `achiral`: if `True`, the topological charge is inverted
+    - `right_left`: if `True`, the in-plane rotation is inverted
+
     """
     vec3 = ctypes.c_float * 3
     _Skyrmion(ctypes.c_void_p(p_state), ctypes.c_float(radius), ctypes.c_float(order),
@@ -116,8 +127,13 @@ def hopfion(p_state, radius, order=1, pos=[0,0,0], border_rectangular=[-1,-1,-1]
             border_cylindrical=-1, border_spherical=-1, inverted=False, idx_image=-1, idx_chain=-1):
     """Set a Hopfion configuration.
 
-    - radius: the distance from the center to the center of the corresponding tubular isosurface
-    - order: TODO
+    Arguments:
+
+    - `radius`: the distance from the center to the center of the corresponding tubular isosurface
+
+    Keyword arguments:
+
+    - `order`: the number of windings of the toroidal hopfion
 
     In contrast to the skyrmion, it extends over the whole allowed space.
     """
@@ -140,10 +156,11 @@ def spin_spiral(p_state, direction_type, q_vector, axis, theta, pos=[0,0,0],
     """Set a spin spiral configuration.
 
     TODO: document parameters
-    - direction_type:
-    - q_vector:
-    - axis:
-    - theta:
+
+    - `direction_type`:
+    - `q_vector`:
+    - `axis`:
+    - `theta`:
     """
     vec3 = ctypes.c_float * 3
     _SpinSpiral(ctypes.c_void_p(p_state), ctypes.c_char_p(direction_type.encode('utf-8')),

core/python/spirit/geometry.py

@@ -20,30 +20,41 @@
 
 ### Bravais lattice types
 BRAVAIS_LATTICE_IRREGULAR   = 0
+"""Irregular"""
+
 BRAVAIS_LATTICE_RECTILINEAR = 1
+"""Rectilinear"""
+
 BRAVAIS_LATTICE_SC          = 2
+"""Simple cubic"""
+
 BRAVAIS_LATTICE_HEX2D       = 3
+"""Hexagonal (60deg)"""
+
 BRAVAIS_LATTICE_HEX2D_60    = 4
+"""Hexagonal (60deg)"""
+
 BRAVAIS_LATTICE_HEX2D_120   = 5
+"""Hexagonal (120deg)"""
+
 BRAVAIS_LATTICE_HCP         = 6
+"""Hexagonal close packed"""
+
 BRAVAIS_LATTICE_BCC         = 7
+"""Body centered cubic"""
+
 BRAVAIS_LATTICE_FCC         = 8
+"""Face centered cubic"""
 
 ### ---------------------------------- Set ----------------------------------
 
 _Set_Bravais_Lattice_Type          = _spirit.Geometry_Set_Bravais_Lattice_Type
 _Set_Bravais_Lattice_Type.argtypes = [ctypes.c_void_p, ctypes.c_int]
 _Set_Bravais_Lattice_Type.restype  = None
 def set_bravais_lattice_type(p_state, lattice_type, idx_image=-1, idx_chain=-1):
-    """Set the bravais vectors to a pre-defined lattice type:
-
-    - sc:       simple cubic
-    - bcc:      body centered cubic
-    - fcc:      face centered cubic
-    - hex2d:    hexagonal (120deg)
-    - hed2d120: hexagonal (120deg)
-    - hex2d60:  hexagonal (60deg)
-    """
+    """Set the bravais vectors to one of the pre-defined lattice types.
+    
+    Note: `Irregular`, `Rectilinear` and `HCP` cannot be used."""
     _Set_Bravais_Lattice_Type(ctypes.c_void_p(p_state), ctypes.c_int(lattice_type))
 
 _Set_N_Cells          = _spirit.Geometry_Set_N_Cells
@@ -97,7 +108,7 @@ def set_lattice_constant(p_state, lattice_constant, idx_image=-1, idx_chain=-1):
 def get_bounds(p_state, idx_image=-1, idx_chain=-1):
     """Get the bounds of the system in global coordinates.
 
-    Returns two arrays of shape (3) containing minimum and maximum bounds respectively.
+    Returns two arrays of `shape(3)` containing minimum and maximum bounds respectively.
     """
     _min = (3*ctypes.c_float)()
     _max = (3*ctypes.c_float)()
@@ -111,7 +122,7 @@ def get_bounds(p_state, idx_image=-1, idx_chain=-1):
 def get_center(p_state, idx_image=-1, idx_chain=-1):
     """Get the center of the system in global coordinates.
 
-    Returns an array of shape (3).
+    Returns an array of `shape(3)`.
     """
     _center = (3*ctypes.c_float)()
     _Get_Center(ctypes.c_void_p(p_state), _center, ctypes.c_int(idx_image), ctypes.c_int(idx_chain))
@@ -133,7 +144,7 @@ def get_bravais_lattice_type(p_state, idx_image=-1, idx_chain=-1):
 def get_bravais_vectors(p_state, idx_image=-1, idx_chain=-1):
     """Get the Bravais vectors.
 
-    Returns three arrays of shape (3).
+    Returns three arrays of `shape(3)`.
     """
     _a = (3*ctypes.c_float)()
     _b = (3*ctypes.c_float)()
@@ -148,7 +159,7 @@ def get_bravais_vectors(p_state, idx_image=-1, idx_chain=-1):
 def get_n_cells(p_state, idx_image=-1, idx_chain=-1):
     """Get the number of basis cells along the three bravais vectors.
 
-    Returns an array of shape (3).
+    Returns an array of `shape(3)`.
     """
     n_cells = (3*ctypes.c_int)()
     _Get_N_Cells(ctypes.c_void_p(p_state), n_cells, ctypes.c_int(idx_image), ctypes.c_int(idx_chain))
@@ -167,7 +178,7 @@ def get_dimensionality(p_state, idx_image=-1, idx_chain=-1):
 _Get_Positions.argtypes   = [ctypes.c_void_p, ctypes.c_int, ctypes.c_int]
 _Get_Positions.restype    = ctypes.POINTER(scalar)
 def get_positions(p_state, idx_image=-1, idx_chain=-1):
-    """Returns a `numpy.array_view` of shape (NOS, 3) with the components of each spins position.
+    """Returns a `numpy.array_view` of `shape(NOS, 3)` with the components of each spins position.
 
     Changing the contents of this array_view will have direct effect on the state and should not be done.
     """
@@ -193,7 +204,7 @@ def get_n_cell_atoms(p_state, idx_image=-1, idx_chain=-1):
 _Get_Atom_Types.argtypes   = [ctypes.c_void_p, ctypes.c_int, ctypes.c_int]
 _Get_Atom_Types.restype    = ctypes.POINTER(ctypes.c_int)
 def get_atom_types(p_state, idx_image=-1, idx_chain=-1):
-    """Get the types of all atoms as a `numpy.array_view` of shape (NOS).
+    """Get the types of all atoms as a `numpy.array_view` of `shape(NOS)`.
 
     If e.g. disorder is activated, this allows to view and manipulate the types of individual atoms.
     """

core/python/spirit/hamiltonian.py

@@ -99,10 +99,10 @@ def set_dmi(p_state, n_shells, D_ij, chirality=CHIRALITY_BLOCH, idx_image=-1, id
 def set_ddi(p_state, ddi_method, n_periodic_images=[4,4,4], radius=0.0, idx_image=-1, idx_chain=-1):
     """Set the dipolar interaction calculation method.
 
-    - ddi_method -- one of the integers defined above
-    - n_periodic_images -- the number of periodical images in the three translation directions, taken into account
-      when boundaries in the corresponding direction are periodical
-    - radius -- the cutoff radius for the direct summation method
+    - `ddi_method`: one of the integers defined above
+    - `n_periodic_images`: the number of periodical images in the three translation directions,
+      taken into account when boundaries in the corresponding direction are periodical
+    - `radius`: the cutoff radius for the direct summation method
     """
     vec3 = ctypes.c_int * 3
     _Set_DDI(ctypes.c_void_p(p_state), ctypes.c_int(ddi_method) , vec3(*n_periodic_images), ctypes.c_float(radius),
@@ -122,8 +122,8 @@ def get_name(p_state, idx_image=-1, idx_chain=-1):
                                      ctypes.c_int, ctypes.c_int]
 _Get_Boundary_Conditions.restype  = None
 def get_boundary_conditions(p_state, idx_image=-1, idx_chain=-1):
-    """Returns an array of shape (3) containing the boundary conditions in the
-    three translation directions [a, b, c] of the lattice.
+    """Returns an array of `shape(3)` containing the boundary conditions in the
+    three translation directions `[a, b, c]` of the lattice.
     """
     boundaries = (3*ctypes.c_bool)()
     _Get_Boundary_Conditions(ctypes.c_void_p(p_state), boundaries,
@@ -135,7 +135,7 @@ def get_boundary_conditions(p_state, idx_image=-1, idx_chain=-1):
                        ctypes.POINTER(ctypes.c_float), ctypes.c_int, ctypes.c_int]
 _Get_Field.restype  = None
 def get_field(p_state, idx_image=-1, idx_chain=-1):
-    """Returns the magnitude and an array of shape (3) containing the direction of
+    """Returns the magnitude and an array of `shape(3)` containing the direction of
     the external magnetic field.
     """
     magnitude = (1*ctypes.c_float)()

core/python/spirit/htst.py

@@ -38,9 +38,9 @@ def get_info(p_state, idx_chain=-1):
     """Returns a set of HTST information:
 
     - the exponent of the temperature-dependence
-    - `me`
-    - `Omega_0`
-    - `s`
+    - me
+    - Omega_0
+    - s
     - zero mode volume at the minimum
     - zero mode volume at the saddle point
     - dynamical prefactor
@@ -68,9 +68,7 @@ def get_info(p_state, idx_chain=-1):
 _Get_Eigenvalues_Min.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Eigenvalues_Min.restype  = None
 def get_eigenvalues_min(p_state, idx_chain=-1):
-    """Returns the eigenvalues at the minimum.
-    Shape (2*nos)
-    """
+    """Returns the eigenvalues at the minimum with `shape(2*nos)`."""
     nos             = system.get_nos(p_state, -1, idx_chain)
     eigenvalues_min = (2*nos*ctypes.c_float)()
     _Get_Eigenvalues_Min(ctypes.c_void_p(p_state), eigenvalues_min, ctypes.c_int(idx_chain))
@@ -81,9 +79,7 @@ def get_eigenvalues_min(p_state, idx_chain=-1):
 _Get_Eigenvectors_Min.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Eigenvectors_Min.restype  = None
 def get_eigenvectors_min(p_state, idx_chain=-1):
-    """Returns the eigenvectors at the minimum.
-    Shape (2*nos*nos)
-    """
+    """Returns the eigenvectors at the minimum with `shape(2*nos*nos)`."""
     nos              = system.get_nos(p_state, -1, idx_chain)
     eigenvectors_min = (2*nos*nos*ctypes.c_float)()
     _Get_Eigenvectors_Min(ctypes.c_void_p(p_state), eigenvectors_min, ctypes.c_int(idx_chain))
@@ -94,9 +90,7 @@ def get_eigenvectors_min(p_state, idx_chain=-1):
 _Get_Eigenvalues_SP.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Eigenvalues_SP.restype  = None
 def get_eigenvalues_sp(p_state, idx_chain=-1):
-    """Returns the eigenvalues at the saddle point.
-    Shape (2*nos)
-    """
+    """Returns the eigenvalues at the saddle point with `shape(2*nos)`."""
     nos            = system.get_nos(p_state, -1, idx_chain)
     eigenvalues_sp = (2*nos*ctypes.c_float)()
     _Get_Eigenvalues_SP(ctypes.c_void_p(p_state), eigenvalues_sp, ctypes.c_int(idx_chain))
@@ -107,9 +101,7 @@ def get_eigenvalues_sp(p_state, idx_chain=-1):
 _Get_Eigenvectors_SP.argtypes = [ctypes.c_void_p, ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Eigenvectors_SP.restype  = None
 def get_eigenvectors_sp(p_state, idx_chain=-1):
-    """Returns the eigenvectors at the saddle point.
-    Shape (2*nos*nos)
-    """
+    """Returns the eigenvectors at the saddle point with `shape(2*nos*nos)`."""
     nos                 = system.get_nos(p_state, -1, idx_chain)
     eigenvectors_sp     = (2*nos*nos*ctypes.c_float)()
     _Get_Eigenvectors_SP(ctypes.c_void_p(p_state), eigenvectors_sp, ctypes.c_int(idx_chain))
@@ -121,9 +113,7 @@ def get_eigenvectors_sp(p_state, idx_chain=-1):
                             ctypes.POINTER(ctypes.c_float), ctypes.c_int]
 _Get_Velocities.restype  = None
 def get_velocities(p_state, idx_chain=-1):
-    """Returns the velocities perpendicular to the dividing surface.
-    Shape (2*nos)
-    """
+    """Returns the velocities perpendicular to the dividing surface with `shape(2*nos)`."""
     nos        = system.get_nos(p_state, -1, idx_chain)
     velocities = (2*nos*ctypes.c_float)()
     _Get_Velocities(ctypes.c_void_p(p_state), velocities, ctypes.c_int(idx_chain))