From e2ec4ff50531690ba3f2f6e532b9b224f3d4bd0f Mon Sep 17 00:00:00 2001 From: Gideon Date: Mon, 15 Jul 2019 11:52:26 +0200 Subject: [PATCH] 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 | 4 +- core/python/spirit/configuration.py | 53 ++++++++++++------- core/python/spirit/geometry.py | 41 +++++++++------ core/python/spirit/hamiltonian.py | 14 ++--- core/python/spirit/htst.py | 26 +++------- core/python/spirit/io.py | 75 ++++++++++++++++----------- core/python/spirit/log.py | 44 +++++++++++++--- core/python/spirit/parameters/gneb.py | 16 +++--- core/python/spirit/parameters/llg.py | 36 ++++++------- core/python/spirit/parameters/mc.py | 28 +++++----- core/python/spirit/parameters/mmf.py | 20 +++---- core/python/spirit/quantities.py | 8 +-- core/python/spirit/simulation.py | 12 ++--- 13 files changed, 220 insertions(+), 157 deletions(-) diff --git a/core/python/spirit/chain.py b/core/python/spirit/chain.py index c42c35468..496d75104 100644 --- a/core/python/spirit/chain.py +++ b/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)) diff --git a/core/python/spirit/configuration.py b/core/python/spirit/configuration.py index ca8166162..90c8188b8 100644 --- a/core/python/spirit/configuration.py +++ b/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')), diff --git a/core/python/spirit/geometry.py b/core/python/spirit/geometry.py index a917be4ac..2cdc274d4 100644 --- a/core/python/spirit/geometry.py +++ b/core/python/spirit/geometry.py @@ -20,14 +20,31 @@ ### 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 ---------------------------------- @@ -35,15 +52,9 @@ _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. """ diff --git a/core/python/spirit/hamiltonian.py b/core/python/spirit/hamiltonian.py index 0a42def44..4c1c0fe3d 100644 --- a/core/python/spirit/hamiltonian.py +++ b/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)() diff --git a/core/python/spirit/htst.py b/core/python/spirit/htst.py index 9a972178b..dd3c933d0 100644 --- a/core/python/spirit/htst.py +++ b/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)) diff --git a/core/python/spirit/io.py b/core/python/spirit/io.py index af7c350a5..17ed28221 100644 --- a/core/python/spirit/io.py +++ b/core/python/spirit/io.py @@ -40,8 +40,9 @@ def n_images_in_file(p_state, filename, idx_image_inchain=-1, idx_chain=-1): """Returns the number of segments or images in a given file. Arguments: - p_state -- state pointer - filename -- the name of the file to check + + - `p_state`: state pointer + - `filename`: the name of the file to check """ return int(_N_Images_In_File(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(idx_image_inchain), ctypes.c_int(idx_chain))) @@ -54,12 +55,14 @@ def image_read(p_state, filename, idx_image_infile=0, idx_image_inchain=-1, idx_ """Attempt to read a spin configuration from a file into an image of the chain. Arguments: - p_state -- state pointer - filename -- the name of the file to read + + - `p_state`: state pointer + - `filename`: the name of the file to read Keyword arguments: - idx_image_infile -- the index of the image in the file which should be read in (default: 0) - idx_image_inchain -- the index of the image in the chain into which the data should be read (default: active image) + + - `idx_image_infile`: the index of the image in the file which should be read in (default: 0) + - `idx_image_inchain`: the index of the image in the chain into which the data should be read (default: active image) """ _Image_Read(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(idx_image_infile), ctypes.c_int(idx_image_inchain), @@ -73,13 +76,15 @@ def image_write(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", i """Write an image of the chain to a file. Arguments: - p_state -- state pointer - filename -- the name of the file to write + + - `p_state`: state pointer + - `filename`: the name of the file to write Keyword arguments: - fileformat -- the format in which to write the data (default: OVF text) - comment -- a comment string to be inserted in the header (default: empty) - idx_image -- the index of the image to be written to the file (default: active image) + + - `fileformat`: the format in which to write the data (default: OVF text) + - `comment`: a comment string to be inserted in the header (default: empty) + - `idx_image`: the index of the image to be written to the file (default: active image) """ _Image_Write(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(fileformat), ctypes.c_char_p(comment.encode('utf-8')), @@ -95,13 +100,15 @@ def image_append(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", If the file does not exist, it is created. Arguments: - p_state -- state pointer - filename -- the name of the file to append to + + - `p_state`: state pointer + - `filename`: the name of the file to append to Keyword arguments: - fileformat -- the format in which to write the data (default: OVF text) - comment -- a comment string to be inserted in the header (default: empty) - idx_image -- the index of the image to be written to the file (default: active image) + + - `fileformat`: the format in which to write the data (default: OVF text) + - `comment`: a comment string to be inserted in the header (default: empty) + - `idx_image`: the index of the image to be written to the file (default: active image) """ _Image_Append(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(fileformat), ctypes.c_char_p(filename.encode('utf-8')), @@ -111,17 +118,19 @@ def image_append(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", _Chain_Read.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int, ctypes.c_int, ctypes.c_int, ctypes.c_int] _Chain_Read.restype = None -def chain_read(p_state, filename, starting_image=0, ending_image=0, insert_idx=-1, idx_chain=-1): +def chain_read(p_state, filename, starting_image=0, ending_image=-1, insert_idx=-1, idx_chain=-1): """Attempt to read a chain of images from a given file. Arguments: - p_state -- state pointer - filename -- the name of the file to read + + - `p_state`: state pointer + - `filename`: the name of the file to read Keyword arguments: - starting_image -- the index within the file at which to start reading (default: 0) - ending_image -- the index within the file at which to stop reading (default: 0) - insert_idx -- the index within the chain at which to start placing the images (default: active image) + + - `starting_image`: the index within the file at which to start reading (default: 0) + - `ending_image`: the index within the file at which to stop reading (default: -1, meaning the entire file) + - `insert_idx`: the index within the chain at which to start placing the images (default: active image) Images of the chain will be overwritten with what is read from the file. If the chain is not long enough for the number of images to be read, it is automatically set to the @@ -139,12 +148,14 @@ def chain_write(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", i """Write a chain of images to a file. Arguments: - p_state -- state pointer - filename -- the name of the file to write + + - `p_state`: state pointer + - `filename`: the name of the file to write Keyword arguments: - fileformat -- the format in which to write the data (default: OVF text) - comment -- a comment string to be inserted in the header (default: empty) + + - `fileformat`: the format in which to write the data (default: OVF text) + - `comment`: a comment string to be inserted in the header (default: empty) """ _Chain_Write(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(fileformat), ctypes.c_char_p(comment.encode('utf-8')), @@ -160,12 +171,14 @@ def chain_append(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", If the file does not exist, it is created. Arguments: - p_state -- state pointer - filename -- the name of the file to append to + + - `p_state`: state pointer + - `filename`: the name of the file to append to Keyword arguments: - fileformat -- the format in which to write the data (default: OVF text) - comment -- a comment string to be inserted in the header (default: empty) + + - `fileformat`: the format in which to write the data (default: OVF text) + - `comment`: a comment string to be inserted in the header (default: empty) """ _Chain_Append(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(fileformat), ctypes.c_char_p(comment.encode('utf-8')), @@ -185,7 +198,7 @@ def eigenmodes_read(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, idx_image _Eigenmodes_Write.argtypes = [ctypes.c_void_p, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_int] _Eigenmodes_Write.restype = None -def eigenmodes_write(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment=" ", idx_image=-1, idx_chain=-1): +def eigenmodes_write(p_state, filename, fileformat=FILEFORMAT_OVF_TEXT, comment="", idx_image=-1, idx_chain=-1): """Write the eigenmodes of a spin system to file, if they have been already calculated.""" _Eigenmodes_Write(ctypes.c_void_p(p_state), ctypes.c_char_p(filename.encode('utf-8')), ctypes.c_int(fileformat), ctypes.c_char_p(comment.encode('utf-8')), diff --git a/core/python/spirit/log.py b/core/python/spirit/log.py index 77ca6bfdc..0f72893a8 100644 --- a/core/python/spirit/log.py +++ b/core/python/spirit/log.py @@ -11,22 +11,50 @@ # Log levels LEVEL_ALL = 0 +"""Only log highest-level messages, as well as `Severe` and `Error` messages.""" + LEVEL_SEVERE = 1 +"""Only log highest-level messages, as well as `Severe` and `Error` messages.""" + LEVEL_ERROR = 2 +"""Only log highest-level messages, as well as `Severe` and `Error` messages.""" + LEVEL_WARNING = 3 +"""Accept log messages of `Warning` and higher levels.""" + LEVEL_PARAMETER = 4 +"""Accept log messages of `Parameter` and higher levels.""" + LEVEL_INFO = 5 +"""Accept log messages of `Info` and higher levels.""" + LEVEL_DEBUG = 6 +"""Accept log messages of `Debug` and higher levels.""" # Log message senders SENDER_ALL = 0 +"""General message sender.""" + SENDER_IO = 1 +"""Everything related to I/O.""" + SENDER_GNEB = 2 +"""GNEB method message sender.""" + SENDER_LLG = 3 +"""LLG method message sender.""" + SENDER_MC = 4 +"""Monte Carlo method message sender.""" + SENDER_MMF = 5 +"""MMF method message sender.""" + SENDER_API = 6 +"""API message sender.""" + SENDER_UI = 7 +"""User interface message sender.""" _Send = _spirit.Log_Send _Send.argtypes = [ctypes.c_void_p, ctypes.c_int, ctypes.c_int, ctypes.c_char_p, @@ -35,11 +63,15 @@ def send(p_state, level, sender, message, idx_image=-1, idx_chain=-1): """Add a message to the log. - - level: see integers defined above. The message may be printed to the console and/or written - to the log file, depending on the current log parameters - - sender: see integers defined above. Used to distinguish context - - message: a string which to log - - idx_image: can be used to specify to which image the message relates (default: active image) + Arguments: + + - `level`: see integers defined above. The message may be printed to the console and/or written to the log file, depending on the current log parameters + - `sender`: see integers defined above. Used to distinguish context + - `message`: a string which to log + + Keyword arguments: + + - `idx_image`: can be used to specify to which image the message relates (default: active image) """ _Send(ctypes.c_void_p(p_state), ctypes.c_int(level), ctypes.c_int(sender), ctypes.c_char_p(message.encode('utf-8')), ctypes.c_int(idx_image), ctypes.c_int(idx_chain)) @@ -78,7 +110,7 @@ def get_n_warnings(p_state): def set_output_file_tag(p_state, tag): """Set the tagging string which is placed in front of the log file. - If "