diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0e4a84d1..97e70f7e 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,7 +11,7 @@ ci: submodules: false repos: - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.6.0 + rev: v6.0.0 hooks: - id: check-yaml - id: end-of-file-fixer @@ -21,31 +21,31 @@ repos: - id: check-toml - id: check-added-large-files - repo: https://github.com/psf/black - rev: 24.4.2 + rev: 26.5.1 hooks: - id: black - repo: https://github.com/pycqa/flake8 - rev: 7.0.0 + rev: 7.3.0 hooks: - id: flake8 - repo: https://github.com/pycqa/isort - rev: 5.13.2 + rev: 9.0.0a3 hooks: - id: isort args: ["--profile", "black"] - repo: https://github.com/kynan/nbstripout - rev: 0.7.1 + rev: 0.9.1 hooks: - id: nbstripout - repo: https://github.com/pre-commit/pre-commit-hooks - rev: v4.4.0 + rev: v6.0.0 hooks: - id: no-commit-to-branch name: Prevent Commit to Main Branch args: ["--branch", "main"] stages: [pre-commit] - repo: https://github.com/codespell-project/codespell - rev: v2.3.0 + rev: v2.4.2 hooks: - id: codespell additional_dependencies: @@ -58,8 +58,8 @@ repos: additional_dependencies: - "prettier@^3.2.4" # docformatter - PEP 257 compliant docstring formatter - - repo: https://github.com/s-weigand/docformatter - rev: 5757c5190d95e5449f102ace83df92e7d3b06c6c + - repo: https://github.com/PyCQA/docformatter + rev: v1.7.8 hooks: - id: docformatter additional_dependencies: [tomli] diff --git a/devutils/sgtbx_extra_groups.py b/devutils/sgtbx_extra_groups.py index 48dfdb99..3eceb8df 100644 --- a/devutils/sgtbx_extra_groups.py +++ b/devutils/sgtbx_extra_groups.py @@ -10,7 +10,6 @@ Not to be included with code distributions. """ - import math import re diff --git a/news/CI-badge-fix.rst b/news/CI-badge-fix.rst index 2df63a8f..5fe4624b 100644 --- a/news/CI-badge-fix.rst +++ b/news/CI-badge-fix.rst @@ -2,6 +2,7 @@ * No News Added: fix CI badge and target in README.rst + **Changed:** * diff --git a/news/pre-commit_edits.rst b/news/pre-commit_edits.rst new file mode 100644 index 00000000..e4228a5b --- /dev/null +++ b/news/pre-commit_edits.rst @@ -0,0 +1,23 @@ +**Added:** + +* No news needed: updating docformatter not user facing + +**Changed:** + +* + +**Deprecated:** + +* + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/diffpy/structure/__init__.py b/src/diffpy/structure/__init__.py index 0b07bb8c..9c665cc2 100644 --- a/src/diffpy/structure/__init__.py +++ b/src/diffpy/structure/__init__.py @@ -33,7 +33,6 @@ * SymmetryError """ - import os import sys diff --git a/src/diffpy/structure/_legacy_importer.py b/src/diffpy/structure/_legacy_importer.py index 672d0835..354d07c5 100644 --- a/src/diffpy/structure/_legacy_importer.py +++ b/src/diffpy/structure/_legacy_importer.py @@ -27,7 +27,6 @@ This module is deprecated and will be removed in the future. """ - import importlib.abc import sys from warnings import warn diff --git a/src/diffpy/structure/apps/vesta_viewer.py b/src/diffpy/structure/apps/vesta_viewer.py index b90ae0f4..dde74344 100644 --- a/src/diffpy/structure/apps/vesta_viewer.py +++ b/src/diffpy/structure/apps/vesta_viewer.py @@ -72,12 +72,13 @@ def usage(style=None): - """Show usage info. for ``style=="brief"`` show only first 2 lines. + """Show usage info. - Parameters - ---------- - style : str, optional - The usage display style. + for ``style=="brief"`` show only first 2 lines. + Parameters + ---------- + style : str, optional + The usage display style. """ myname = Path(sys.argv[0]).name msg = __doc__.replace("vestaview", myname) diff --git a/src/diffpy/structure/atom.py b/src/diffpy/structure/atom.py index 75581454..45c98f5b 100644 --- a/src/diffpy/structure/atom.py +++ b/src/diffpy/structure/atom.py @@ -42,7 +42,7 @@ class Atom(object): - """Storage of structure information relevant for a single atom. + """The storage of structure information relevant for a single atom. This class manages atom information such as element symbol, position in fractional and Cartesian coordinates, atomic displacement parameters @@ -55,10 +55,10 @@ class Atom(object): By default an empty string. When of the `Atom` type, create a copy of `atype` and adjust it per other arguments. xyz : numpy.ndarray, Optional - Fractional coordinates within the associated `lattice`. + The fractional coordinates within the associated `lattice`. By default ``[0, 0, 0]``. label : str, Optional - A unique string `label` for referring to this `Atom`. + The unique string `label` for referring to this `Atom`. By default an empty string. occupancy : float, Optional The initial `occupancy` of this atom, by default ``1``. @@ -76,25 +76,25 @@ class Atom(object): *Uisoequiv* arguments may be provided at the same time. Assume zero atomic displacements when *U* and *Uisoequiv* are unset. lattice : Lattice, Optional - Coordinate system for the fractional coordinates `xyz`. + The coordinate system for the fractional coordinates `xyz`. Use the absolute Cartesian system when ``None``. Attributes ---------- element : str - The string type of the atom. An element or ion symbol. + The string type of the atom. An element or ion symbol, default "". xyz : numpy.ndarray The fractional coordinates in the associated `lattice`. label : str - A unique string label referring to this atom, for example, "C_1". + The unique string label referring to this atom, for example, "C_1". The *label* can be used to reference this atom when contained in - a `Structure` object. + a `Structure` object, default "". occupancy : float - The fractional occupancy of this atom. + The fractional occupancy of this atom, default 1.0. lattice : Lattice - Coordinate system for the fractional coordinates `xyz` and + The coordinate system for the fractional coordinates `xyz` and the tensor of atomic displacement parameters `U`. - Use the absolute Cartesian coordinates when ``None``. + Use the absolute Cartesian coordinates when ``None`` as the default. Note ---- @@ -104,21 +104,17 @@ class Atom(object): # Private attributes # # _U : 3-by-3 ndarray - # Internal storage of the displacement parameters. + # The internal storage of the displacement parameters. # instance attributes that have immutable default values element = "" - """str: Default values of `element`.""" label = "" - """str: Default values of `label`.""" occupancy = 1.0 - """float: Default values of `occupancy`.""" _anisotropy = False lattice = None - """None: Default values of `lattice`.""" def __init__( self, @@ -232,7 +228,7 @@ def msd_cart(self, vc): return msd def __repr__(self): - """String representation of this Atom.""" + """The string representation of this Atom.""" xyz = self.xyz s = "%-4s %8.6f %8.6f %8.6f %6.4f" % ( self.element, @@ -273,29 +269,29 @@ def __copy__(self, target=None): x = property( lambda self: self.xyz[0], lambda self, val: self.xyz.__setitem__(0, val), - doc="float : fractional coordinate *x*, same as ``xyz[0]``.", + doc="The fractional coordinate *x*, same as ``xyz[0]``, as a float", ) y = property( lambda self: self.xyz[1], lambda self, val: self.xyz.__setitem__(1, val), - doc="float : fractional coordinate *y*, same as ``xyz[1]``.", + doc="The fractional coordinate *y*, same as ``xyz[1]``, as a float", ) z = property( lambda self: self.xyz[2], lambda self, val: self.xyz.__setitem__(2, val), - doc="float : fractional coordinate *z*, same as ``xyz[2]``.", + doc="The fractional coordinate *z*, same as ``xyz[2]``, as a float", ) # xyz_cartn @property def xyz_cartn(self): - """numpy.ndarray: Atom position in absolute Cartesian - coordinates. + """Atom position in absolute Cartesian coordinates, as a + numpy.ndarray. This is computed from fractional coordinates `xyz` and the - current `lattice` setup. Assignment to *xyz_cartn* or - its components is applied on fractional coordinates `xyz`. + current `lattice` setup. Assignment to *xyz_cartn* or its + components is applied on fractional coordinates `xyz`. """ if not self.lattice: rv = self.xyz @@ -315,7 +311,8 @@ def xyz_cartn(self, value): @property def anisotropy(self): - """bool : Flag for allowing anisotropic displacement parameters. + """The flag for allowing anisotropic displacement parameters, as + a bool. When ``False`` the tensor of thermal displacement parameters `U` must be isotropic and only its diagonal elements are taken into @@ -340,8 +337,8 @@ def anisotropy(self, value): @property def U(self): - """numpy.ndarray : The 3x3 matrix of anisotropic atomic - displacements. + """The 3x3 matrix of anisotropic atomic displacements, as a + ndarray. For isotropic displacements (when `anisotropy` is ``False``) assignment to *U* uses only the first ``Unew[0, 0]`` element @@ -387,7 +384,7 @@ def _set_uij(self, i, j, value): # _doc_uii, _doc_uij are temporary local variables. _doc_uii = """ - float : The ``U[{0}, {0}]`` component of the displacement tensor `U`. + The ``U[{0}, {0}]`` component of the displacement tensor `U`, as a float When `anisotropy` is ``False`` setting a new value updates entire tensor *U*. @@ -410,7 +407,7 @@ def _set_uij(self, i, j, value): ) _doc_uij = """ - float : The ``U[{0}, {1}]`` element of the displacement tensor `U`. + The ``U[{0}, {1}]`` element of the displacement tensor `U`, as a float Sets ``U[{1}, {0}]`` together with ``U[{0}, {1}]``. Assignment has no effect when `anisotropy` is ``False``. @@ -439,7 +436,8 @@ def _set_uij(self, i, j, value): @property def Uisoequiv(self): - """float : The isotropic displacement parameter or an equivalent value. + """The isotropic displacement parameter or an equivalent value, + as a float. Setting a new value rescales tensor `U` so it yields equivalent direction-averaged displacements. @@ -481,14 +479,14 @@ def Uisoequiv(self, value): # _doc_bii, _doc_bij are local variables. _doc_bii = """ - float : The ``B{0}{0}`` element of the Debye-Waller matrix. + The ``B{0}{0}`` element of the Debye-Waller matrix, as a float This is equivalent to ``8 * pi**2 * U{0}{0}``. When `anisotropy` is ``False`` setting a new value updates entire tensor `U`. """ _doc_bij = """ - float : The ``B{0}{1}`` element of the Debye-Waller matrix. + The ``B{0}{1}`` element of the Debye-Waller matrix, as a float This is equivalent to ``8 * pi**2 * U{0}{1}``. Setting a new value updates `U` in a symmetric way. Assignment has no effect @@ -533,7 +531,8 @@ def Uisoequiv(self, value): @property def Bisoequiv(self): - """float : The Debye-Waller isotropic displacement or an equivalent value. + """The Debye-Waller isotropic displacement or an equivalent + value, as a float. This equals ``8 * pi**2 * Uisoequiv``. Setting a new value rescales `U` tensor to yield equivalent direction-average of @@ -553,7 +552,8 @@ def Bisoequiv(self, value): class _AtomCartesianCoordinates(numpy.ndarray): - """Specialized `numpy.ndarray` for accessing Cartesian coordinates. + """The specialized `numpy.ndarray` for accessing Cartesian + coordinates. Inplace assignments to this array are applied on the *xyz* position position of owner `Atom` as per the associated `Atom.lattice`. @@ -561,7 +561,7 @@ class _AtomCartesianCoordinates(numpy.ndarray): Parameters ---------- atom : Atom - `Atom` instance to be linked to these coordinate array. + The `Atom` instance to be linked to these coordinate array. """ def __new__(self, atom): @@ -575,7 +575,7 @@ def __init__(self, atom): @property def asarray(self): - """ndarray : This array viewed as standard numpy array.""" + """This array viewed as standard numpy array.""" return self.view(numpy.ndarray) def __setitem__(self, idx, value): diff --git a/src/diffpy/structure/expansion/shapeutils.py b/src/diffpy/structure/expansion/shapeutils.py index 0b1de0c0..abf00ec7 100644 --- a/src/diffpy/structure/expansion/shapeutils.py +++ b/src/diffpy/structure/expansion/shapeutils.py @@ -24,6 +24,8 @@ ) """Utilities for making shapes.""" +# FIXME: remove this line when `docformatter` fixes the blank line bug + @deprecated(findCenter_deprecation_msg) def findCenter(S): diff --git a/src/diffpy/structure/lattice.py b/src/diffpy/structure/lattice.py index bdef059a..8c173bdd 100644 --- a/src/diffpy/structure/lattice.py +++ b/src/diffpy/structure/lattice.py @@ -18,7 +18,7 @@ Attributes ---------- cartesian : Lattice - Constant instance of Lattice, default Cartesian system. + The default Cartesian lattice with a=b=c=1 and alpha=beta=gamma=90 degrees. """ import math diff --git a/src/diffpy/structure/parsers/p_auto.py b/src/diffpy/structure/parsers/p_auto.py index a0683d58..fa751a9b 100644 --- a/src/diffpy/structure/parsers/p_auto.py +++ b/src/diffpy/structure/parsers/p_auto.py @@ -55,10 +55,10 @@ class P_auto(StructureParser): Attributes ---------- format : str - Detected structure format. Initially set to "auto" and updated + The detected structure format. Initially set to "auto" and updated after successful detection of the structure format. pkw : dict - Keyword arguments passed to the parser. + The keyword arguments passed to the parser. """ def __init__(self, **kw): diff --git a/src/diffpy/structure/parsers/p_cif.py b/src/diffpy/structure/parsers/p_cif.py index 1dc39d7c..c05be566 100644 --- a/src/diffpy/structure/parsers/p_cif.py +++ b/src/diffpy/structure/parsers/p_cif.py @@ -17,9 +17,9 @@ Attributes ---------- rx_float : re.Pattern - Constant regular expression for `leading_float()`. + The constant regular expression for `leading_float()`. symvec : dict - Helper dictionary for `getSymOp()`. + The helper dictionary for `getSymOp()`. Note ---- @@ -79,26 +79,26 @@ class P_cif(StructureParser): Attributes ---------- format : str - Structure format name. + The structure format name. ciffile : CifFile - Instance of `CifFile` from `PyCifRW`. + The instance of `CifFile` from `PyCifRW`. stru : Structure - `Structure` instance used for CIF input or output. + The `Structure` instance used for CIF input or output. spacegroup : SpaceGroup - Instance of `SpaceGroup` used for symmetry expansion. + The instance of `SpaceGroup` used for symmetry expansion. eps : float - Resolution in fractional coordinates for non-equal positions. + The resolution in fractional coordinates for non-equal positions. Used for expansion of asymmetric unit. eau : ExpandAsymmetricUnit - Instance of `ExpandAsymmetricUnit` from `SymmetryUtilities`. + The instance of `ExpandAsymmetricUnit` from `SymmetryUtilities`. asymmetric_unit : list - List of `Atom` instances for the original asymmetric unit in the CIF file. + The list of `Atom` instances for the original asymmetric unit in the CIF file. labelindex : dict - Dictionary mapping unique atom label to index of `Atom` in `self.asymmetric_unit`. + The dictionary mapping unique atom label to index of `Atom` in `self.asymmetric_unit`. anisotropy : dict - Dictionary mapping unique atom label to displacement anisotropy resolved at that site. + The dictionary mapping unique atom label to displacement anisotropy resolved at that site. cif_sgname : str or None - Space group name obtained by looking up the value of + The space group name obtained by looking up the value of `_space_group_name_Hall`, `_symmetry_space_group_name_Hall`, `_space_group_name_H-M_alt`, @@ -151,8 +151,8 @@ class P_cif(StructureParser): _atom_setters[k] = _atom_setters[k.lower()] = k del k + # Conversion factor from B values to U values, as a float BtoU = 1.0 / (8 * numpy.pi**2) - """float: Conversion factor from B values to U values.""" def _tr_ignore(a, value): return diff --git a/src/diffpy/structure/parsers/p_discus.py b/src/diffpy/structure/parsers/p_discus.py index 3e77b55f..8016be33 100644 --- a/src/diffpy/structure/parsers/p_discus.py +++ b/src/diffpy/structure/parsers/p_discus.py @@ -39,23 +39,24 @@ class P_discus(StructureParser): - """Parser for DISCUS structure format. The parser chokes on molecule - and generator records. + """Parser for DISCUS structure format. + + The parser chokes on molecule and generator records. Attributes ---------- format : str - File format name, default "discus". + The file format name, default "discus". nl : int - Line number of the current line being parsed. + The line number of the current line being parsed. lines : list of str - List of lines from the input file. + The list of lines from the input file. line : str - Current line being parsed. + The current line being parsed. stru : PDFFitStructure - Structure being parsed. + The structure being parsed. ignored_lines : list of str - List of lines that were ignored during parsing. + The list of lines that were ignored during parsing. cell_read : bool ``True`` if cell record processed. ncell_read : bool diff --git a/src/diffpy/structure/parsers/p_pdb.py b/src/diffpy/structure/parsers/p_pdb.py index 98bc4b74..4d89ee3a 100644 --- a/src/diffpy/structure/parsers/p_pdb.py +++ b/src/diffpy/structure/parsers/p_pdb.py @@ -74,7 +74,11 @@ class P_pdb(StructureParser): Attributes ---------- format : str - Format name, default "pdb". + The format name, default "pdb". + orderOfRecords : list + The ordered list of PDB record labels. + validRecords : dict + The set of valid PDB record labels. """ # Static data members @@ -135,10 +139,8 @@ class P_pdb(StructureParser): "MASTER", "END", ] - """list: Ordered list of PDB record labels.""" validRecords = dict.fromkeys(orderOfRecords) - """dict: Dictionary of PDB record labels.""" def __init__(self): StructureParser.__init__(self) diff --git a/src/diffpy/structure/parsers/p_pdffit.py b/src/diffpy/structure/parsers/p_pdffit.py index 2347f3ff..3ed66947 100644 --- a/src/diffpy/structure/parsers/p_pdffit.py +++ b/src/diffpy/structure/parsers/p_pdffit.py @@ -40,11 +40,11 @@ class P_pdffit(StructureParser): Attributes ---------- format : str - Format name, default "pdffit". + The format name, default "pdffit". ignored_lines : list - List of lines ignored during parsing. + The list of lines ignored during parsing. stru : PDFFitStructure - Structure instance used for cif input or output. + The structure instance used for cif input or output. """ def __init__(self): diff --git a/src/diffpy/structure/parsers/p_rawxyz.py b/src/diffpy/structure/parsers/p_rawxyz.py index 2a8332b8..fdbb713c 100644 --- a/src/diffpy/structure/parsers/p_rawxyz.py +++ b/src/diffpy/structure/parsers/p_rawxyz.py @@ -48,7 +48,7 @@ class P_rawxyz(StructureParser): Attributes ---------- format : str - Format name, default "rawxyz". + The format name, default "rawxyz". """ def __init__(self): diff --git a/src/diffpy/structure/parsers/p_vesta.py b/src/diffpy/structure/parsers/p_vesta.py index 1be850c0..1ea38886 100644 --- a/src/diffpy/structure/parsers/p_vesta.py +++ b/src/diffpy/structure/parsers/p_vesta.py @@ -22,7 +22,7 @@ Attributes ---------- AtomicMass : dict - Dictionary of atomic masses for elements. + The dictionary of atomic masses for elements. """ import re @@ -47,8 +47,9 @@ class P_vesta(StructureParser): Attributes ---------- format : str - Format name, default "vesta". - + The format name, default "vesta". + cluster_boundary : int + The width of boundary around corners of non-periodic cluster, default 2. Notes ----- The ``cluster_boundary`` attribute is retained from the original @@ -57,10 +58,6 @@ class P_vesta(StructureParser): """ cluster_boundary = 2 - """int: Width of boundary around corners of non-periodic cluster. - Retained from the original AtomEye/XCFG parser for API compatibility. - VESTA handles periodicity natively so this value has no effect on output. - """ def __init__(self): StructureParser.__init__(self) diff --git a/src/diffpy/structure/parsers/p_xcfg.py b/src/diffpy/structure/parsers/p_xcfg.py index e94605c6..d6d5fe4e 100644 --- a/src/diffpy/structure/parsers/p_xcfg.py +++ b/src/diffpy/structure/parsers/p_xcfg.py @@ -17,7 +17,7 @@ Attributes ---------- AtomicMass : dict - Dictionary of atomic masses for elements. + The dictionary of atomic masses for elements. """ import re @@ -174,13 +174,13 @@ class P_xcfg(StructureParser): Attributes ---------- format : str - Format name, default "xcfg". + The format name, default "xcfg". + cluster_boundary : int + The width of boundary around corners of non-periodic + cluster to avoid PBC effects in atomeye, default 2. """ cluster_boundary = 2 - """int: Width of boundary around corners of non-periodic - cluster to avoid PBC effects in atomeye. - """ def __init__(self): StructureParser.__init__(self) diff --git a/src/diffpy/structure/parsers/p_xyz.py b/src/diffpy/structure/parsers/p_xyz.py index 60c8dd8a..5c8f39cd 100644 --- a/src/diffpy/structure/parsers/p_xyz.py +++ b/src/diffpy/structure/parsers/p_xyz.py @@ -48,7 +48,7 @@ class P_xyz(StructureParser): Attributes ---------- format : str - Format name, default "xyz". + The format name, default "xyz". """ def __init__(self): diff --git a/src/diffpy/structure/parsers/parser_index_mod.py b/src/diffpy/structure/parsers/parser_index_mod.py index 5f8c3ec7..3b049529 100644 --- a/src/diffpy/structure/parsers/parser_index_mod.py +++ b/src/diffpy/structure/parsers/parser_index_mod.py @@ -22,11 +22,11 @@ and the values are dictionaries with the following keys: module : str - Name of the module that defines the parser class. + The name of the module that defines the parser class. file_extension : str - File extension for the format, including the leading dot. + The file extension for the format, including the leading dot. file_pattern : str - File pattern for the format, using '|' as separator for multiple + The file pattern for the format, using '|' as separator for multiple patterns. has_input : bool ``True`` if the parser can read the format. diff --git a/src/diffpy/structure/parsers/structureparser.py b/src/diffpy/structure/parsers/structureparser.py index 270fbb32..d7b15d65 100644 --- a/src/diffpy/structure/parsers/structureparser.py +++ b/src/diffpy/structure/parsers/structureparser.py @@ -44,9 +44,9 @@ class StructureParser(object): Attributes ---------- format : str - Format name of particular parser. + The format name of particular parser. filename : str - Path to structure file that is read or written. + The path to structure file that is read or written. """ def __init__(self): diff --git a/src/diffpy/structure/pdffitstructure.py b/src/diffpy/structure/pdffitstructure.py index 2ee1f7ac..641f0914 100644 --- a/src/diffpy/structure/pdffitstructure.py +++ b/src/diffpy/structure/pdffitstructure.py @@ -14,7 +14,6 @@ ############################################################################## """Definition of PDFFitStructure class derived from Structure.""" - from diffpy.structure.structure import Structure from diffpy.utils._deprecator import build_deprecation_message, deprecated @@ -41,7 +40,7 @@ class PDFFitStructure(Structure): Attributes ---------- pdffit : dict - Dictionary for storing following extra parameters from + This stores the following extra parameters from PDFFit structure files: `'scale', 'delta1', 'delta2', 'sratio', 'rcut', 'spcgr', 'dcell', 'ncell'` diff --git a/src/diffpy/structure/sgtbxspacegroups.py b/src/diffpy/structure/sgtbxspacegroups.py index 30aacfcf..534de49c 100644 --- a/src/diffpy/structure/sgtbxspacegroups.py +++ b/src/diffpy/structure/sgtbxspacegroups.py @@ -19,10 +19,9 @@ Attributes ---------- sgtbxSpaceGroupList : list - List of space group instances defined in this module. + The list of space group instances defined in this module. """ - from diffpy.structure.spacegroupmod import ( Rot_mX_mY_mZ, Rot_mX_mY_Z, diff --git a/src/diffpy/structure/spacegroupmod.py b/src/diffpy/structure/spacegroupmod.py index 2403d32f..1848e34c 100644 --- a/src/diffpy/structure/spacegroupmod.py +++ b/src/diffpy/structure/spacegroupmod.py @@ -305,7 +305,6 @@ def check_group_name(self, name): names of this space group or if it equals its `number`. Return ``False`` otherwise. """ - if name == self.short_name: return True if name == self.pdb_name: diff --git a/src/diffpy/structure/spacegroups.py b/src/diffpy/structure/spacegroups.py index 8b6fb8c5..da13e87c 100644 --- a/src/diffpy/structure/spacegroups.py +++ b/src/diffpy/structure/spacegroups.py @@ -17,7 +17,7 @@ Attributes ---------- SpaceGroupList : list - List of all spacegroup definitions. + The list of all spacegroup definitions. """ import copy @@ -692,7 +692,7 @@ def get_space_group(sgid): Parameters ---------- sgid : str, int - space group symbol, either `short_name` or `pdb_name`, + The space group symbol, either `short_name` or `pdb_name`, whatever it means in mmlib. Can be also an integer. Returns @@ -789,7 +789,6 @@ def find_space_group(symops, shuffle=False): ValueError When `symops` do not match any known SpaceGroup. """ - tb = _get_sg_hash_lookup_table() hh = _hash_symop_list(symops) if hh not in tb: diff --git a/src/diffpy/structure/structure.py b/src/diffpy/structure/structure.py index a33f4643..a858efd2 100644 --- a/src/diffpy/structure/structure.py +++ b/src/diffpy/structure/structure.py @@ -77,17 +77,17 @@ class Structure(list): Parameters ---------- atoms : list of Atom or Structure, Optional - List of `Atom` instances to be included in this `Structure`. + The list of `Atom` instances to be included in this `Structure`. When `atoms` argument is an existing `Structure` instance, the new structure is its copy. lattice : Lattice, Optional - Instance of `Lattice` defining coordinate systems, property. + The instance of `Lattice` defining coordinate systems, property. title : str, Optional - String description of the structure. + The string description of the structure. filename : str, Optional - Name of a file to load the structure from. + The name of a file to load the structure from. format : str, Optional - `Structure` format of the loaded `filename`. By default + The `Structure` format of the loaded `filename`. By default all structure formats are tried one by one. Ignored when `filename` has not been specified. @@ -99,11 +99,112 @@ class Structure(list): Attributes ---------- title : str - String description of the structure. + The string description of the structure, default "". lattice : Lattice - Instance of `Lattice` defining coordinate systems. + The instance of `Lattice` defining coordinate systems. pdffit : None or dict - Dictionary of PDFFit-related metadata. + The dictionary of PDFFit-related metadata, default None. + element : ndarray of str + The character array of `Atom` types. + Assignment updates the element attribute of the respective + `Atoms`. Set the maximum length of the element string to 5 + characters. + xyz : ndarray + The array of fractional coordinates of all `Atoms`. + Assignment updates `xyz` attribute of all `Atoms` + x : ndarray + The array of fractional coordinate `x`. + Assignment updates the `xyz` attribute of all `Atoms`. + y : ndarray + The array of fractional coordinate `y`. + Assignment updates the `xyz` attribute of all `Atoms`. + z : ndarray + The array of fractional coordinate `z`. + Assignment updates the `xyz` attribute of all `Atoms`. + label : ndarray of str + The character array of `Atom` names. + Assignment updates the label attribute of all `Atoms`. Set the + maximum length of the label string to 5 characters. + occupancy : ndarray + The array of `Atom` occupancies. + Assignment updates the occupancy attribute of all `Atoms`. + xyz_cartn : ndarray + The array of absolute Cartesian coordinates of all `Atoms`. + Assignment updates the `xyz` attribute of all `Atoms`. + anisotropy : ndarray of bool + The boolean array for anisotropic thermal displacement flags. + Assignment updates the anisotropy attribute of all `Atoms`. + U : ndarray + The array of anisotropic thermal displacement tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + Uisoequiv : ndarray + The array of isotropic thermal displacement or equivalent values. + Assignment updates the U attribute of all `Atoms`. + U11 : ndarray + The array of `U11` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + U22 : ndarray + The array of `U22` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + U33 : ndarray + The array of `U33` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + U12 : ndarray + The array of `U12` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + U13 : ndarray + The array of `U13` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + U23 : ndarray + The array of `U23` elements of the anisotropic displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + Bisoequiv : ndarray + The array of Debye-Waller isotropic thermal displacement or + equivalent values for all `Atoms`. Assignment updates the + `U` attribute of all `Atoms`. + B11 : ndarray + The array of `B11` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + B22 : ndarray + The array of `B22` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + B33 : ndarray + The array of `B33` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + B12 : ndarray + The array of `B12` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + B13 : ndarray + The array of `B13` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. + B23 : ndarray + The array of `B23` elements of the Debye-Waller displacement + tensors. + Assignment updates the U and anisotropy attributes of all + `Atoms`. Examples -------- @@ -120,11 +221,9 @@ class Structure(list): # default values for instance attributes title = "" - """str: default values for `title`.""" _lattice = None pdffit = None - """None: default values for `pdffit`.""" def __init__(self, atoms=None, lattice=None, title=None, filename=None, format=None): # if filename is specified load it and return @@ -903,8 +1002,9 @@ def __mul__(self, n): __rmul__ = __mul__ def __imul__(self, n): - """Concatenate this `Structure` to n-times more `Atoms`. For - positive multiple the current `Atom` objects remain at the + """Concatenate this `Structure` to n-times more `Atoms`. + + For positive multiple the current `Atom` objects remain at the beginning of this `Structure`. Parameters @@ -959,150 +1059,149 @@ def _get_composition(self): element = _link_atom_attribute( "element", - """Character array of `Atom` types. Assignment updates - the element attribute of the respective `Atoms`. - Set the maximum length of the element string to 5 characters.""", + ( + "Character array of `Atom` types. Assignment updates " + "the element attribute of the respective `Atoms`. " + "Set the maximum length of the element string to 5 characters." + ), toarray=lambda items: numpy.char.array(items, itemsize=5), ) xyz = _link_atom_attribute( "xyz", - """Array of fractional coordinates of all `Atoms`. - Assignment updates `xyz` attribute of all `Atoms`.""", + "Array of fractional coordinates of all `Atoms`. " "Assignment updates `xyz` attribute of all `Atoms`.", ) x = _link_atom_attribute( "x", - """Array of all fractional coordinates `x`. - Assignment updates `xyz` attribute of all `Atoms`.""", + "Array of all fractional coordinates `x`. " "Assignment updates `xyz` attribute of all `Atoms`.", ) y = _link_atom_attribute( "y", - """Array of all fractional coordinates `y`. - Assignment updates `xyz` attribute of all `Atoms`.""", + "Array of all fractional coordinates `y`. " "Assignment updates `xyz` attribute of all `Atoms`.", ) z = _link_atom_attribute( "z", - """Array of all fractional coordinates `z`. - Assignment updates `xyz` attribute of all `Atoms`.""", + "Array of all fractional coordinates `z`. " "Assignment updates `xyz` attribute of all `Atoms`.", ) label = _link_atom_attribute( "label", - """Character array of `Atom` names. Assignment updates - the label attribute of all `Atoms`. - Set the maximum length of the label string to 5 characters.""", + ( + "Character array of `Atom` names. Assignment updates " + "the label attribute of all `Atoms`. " + "Set the maximum length of the label string to 5 characters." + ), toarray=lambda items: numpy.char.array(items, itemsize=5), ) occupancy = _link_atom_attribute( "occupancy", - """Array of `Atom` occupancies. Assignment updates the - occupancy attribute of all `Atoms`.""", + "Array of `Atom` occupancies. " "Assignment updates the occupancy attribute of all `Atoms`.", ) xyz_cartn = _link_atom_attribute( "xyz_cartn", - """Array of absolute Cartesian coordinates of all `Atoms`. - Assignment updates the `xyz` attribute of all `Atoms`.""", + "Array of absolute Cartesian coordinates of all `Atoms`. " + "Assignment updates the `xyz` attribute of all `Atoms`.", ) anisotropy = _link_atom_attribute( "anisotropy", - """Boolean array for anisotropic thermal displacement flags. - Assignment updates the anisotropy attribute of all `Atoms`.""", + "Boolean array for anisotropic thermal displacement flags. " + "Assignment updates the anisotropy attribute of all `Atoms`.", ) U = _link_atom_attribute( "U", - """Array of anisotropic thermal displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of anisotropic thermal displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) Uisoequiv = _link_atom_attribute( "Uisoequiv", - """Array of isotropic thermal displacement or equivalent values. - Assignment updates the U attribute of all `Atoms`.""", + "Array of isotropic thermal displacement or equivalent values. " + "Assignment updates the U attribute of all `Atoms`.", ) U11 = _link_atom_attribute( "U11", - """Array of `U11` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U11` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) U22 = _link_atom_attribute( "U22", - """Array of `U22` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U22` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) U33 = _link_atom_attribute( "U33", - """Array of `U33` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U33` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) U12 = _link_atom_attribute( "U12", - """Array of `U12` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U12` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) U13 = _link_atom_attribute( "U13", - """Array of `U13` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U13` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) U23 = _link_atom_attribute( "U23", - """Array of `U23` elements of the anisotropic displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `U23` elements of the anisotropic displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) Bisoequiv = _link_atom_attribute( "Bisoequiv", - """Array of Debye-Waller isotropic thermal displacement or equivalent - values. Assignment updates the U attribute of all `Atoms`.""", + "Array of Debye-Waller isotropic thermal displacement or equivalent values. " + "Assignment updates the U attribute of all `Atoms`.", ) B11 = _link_atom_attribute( "B11", - """Array of `B11` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B11` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) B22 = _link_atom_attribute( "B22", - """Array of `B22` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B22` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) B33 = _link_atom_attribute( "B33", - """Array of `B33` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B33` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) B12 = _link_atom_attribute( "B12", - """Array of `B12` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B12` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) B13 = _link_atom_attribute( "B13", - """Array of `B13` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B13` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) B23 = _link_atom_attribute( "B23", - """Array of `B23` elements of the Debye-Waller displacement tensors. - Assignment updates the U and anisotropy attributes of all `Atoms`.""", + "Array of `B23` elements of the Debye-Waller displacement tensors. " + "Assignment updates the U and anisotropy attributes of all `Atoms`.", ) # Private Methods -------------------------------------------------------- diff --git a/src/diffpy/structure/structureerrors.py b/src/diffpy/structure/structureerrors.py index f9a2aaec..3f3e1653 100644 --- a/src/diffpy/structure/structureerrors.py +++ b/src/diffpy/structure/structureerrors.py @@ -14,6 +14,8 @@ ############################################################################## """Exceptions used in Structure package.""" +# FIXME: remove this line when `docformatter` fixes the blank line bug + class StructureFormatError(Exception): """Exception for failed IO from Structure file.""" diff --git a/src/diffpy/structure/symmetryutilities.py b/src/diffpy/structure/symmetryutilities.py index 5e744fbd..5518de9d 100644 --- a/src/diffpy/structure/symmetryutilities.py +++ b/src/diffpy/structure/symmetryutilities.py @@ -18,11 +18,11 @@ Attributes ---------- epsilon : float - Default tolerance for equality of 2 positions, also + The default tolerance for equality of 2 positions, also used for identification of special positions. stdUsymbols : list - Standard symbols denoting elements of anisotropic thermal + The standard symbols denoting elements of anisotropic thermal displacement tensor. """ @@ -208,12 +208,12 @@ class _Position2Tuple(object): Parameters ---------- eps : float - Cutoff for equivalent coordinates. + The cutoff for equivalent coordinates. Attributes ---------- eps : float - Cutoff for equivalent coordinates. When two coordinates map to the + The cutoff for equivalent coordinates. When two coordinates map to the same tuple, they are closer than `eps`. """ @@ -517,35 +517,39 @@ class GeneratorSite(object): Attributes ---------- xyz : numpy.ndarray - Fractional coordinates of generator site. + The fractional coordinates of generator site. Uij : numpy.ndarray - Anisotropic thermal displacement at generator site. + The anisotropic thermal displacement at generator site. sgoffset : numpy.ndarray - Offset of space group origin ``[0, 0, 0]``. + The offset of space group origin ``[0, 0, 0]``. eps : float - Cutoff for equal positions. + The cutoff for equal positions. eqxyz : list - List of equivalent positions. + The list of equivalent positions. eqUij : list - List of displacement matrices at equivalent positions. + The list of displacement matrices at equivalent positions. symops : list - Nested list of operations per each `eqxyz`. + The nested list of operations per each `eqxyz`. multiplicity : int - Generator site multiplicity. + The generator site multiplicity. Uisotropy : bool - Bool flag for isotropic thermal factors. + The bool flag for isotropic thermal factors. invariants : list - List of invariant operations for generator site. + The list of invariant operations for generator site. null_space : numpy.ndarray - Null space of all possible differences of invariant + The null space of all possible differences of invariant rotational matrices, this is a base of symmetry allowed shifts. Uspace : numpy.ndarray - 3D array of independent components of U matrices. + The 3D array of independent components of U matrices. pparameters : list - List of ``(xyz symbol, value)`` pairs. + The list of ``(xyz symbol, value)`` pairs. Uparameters : list - List of ``(U symbol, value)`` pairs. + The list of ``(U symbol, value)`` pairs. + idx2Usymbol : dict + The mapping of index to standard U symbol. + Ucomponents : numpy.ndarray + The 6x3x3 array of independent components of U matrices. """ Ucomponents = numpy.array( @@ -559,8 +563,6 @@ class GeneratorSite(object): ], dtype=float, ) - """numpy.ndarray: 6x3x3 array of independent components of U - matrices.""" idx2Usymbol = { 0: "U11", @@ -573,7 +575,6 @@ class GeneratorSite(object): 7: "U23", 8: "U33", } - """dict: Mapping of index to standard U symbol.""" def __init__( self, @@ -944,24 +945,24 @@ class ExpandAsymmetricUnit(object): Attributes ---------- spacegroup : SpaceGroup - Instance of `SpaceGroup`. + The instance of `SpaceGroup`. corepos : array_like - List of positions in asymmetric unit, + The list of positions in asymmetric unit, it may contain duplicates. coreUijs : numpy.ndarray - Thermal factors for `corepos`. Defaults to zeros. + The thermal factors for `corepos`. Defaults to zeros. sgoffset : numpy.ndarray - Offset of space group origin ``[0, 0, 0]``. Default to zeros. + The offset of space group origin ``[0, 0, 0]``. Default to zeros. eps : float - Cutoff for equivalent positions. Default is ``1.0e-5``. + The cutoff for equivalent positions. Default is ``1.0e-5``. multiplicity : list - Multiplicity of each site in `corepos`. + The multiplicity of each site in `corepos`. Uisotropy : list - Bool flags for isotropic sites in `corepos`. + The bool flags for isotropic sites in `corepos`. expandedpos : list - List of equivalent positions per each site in `corepos`. + The list of equivalent positions per each site in `corepos`. expandedUijs : list - List of thermal factors per each site in `corepos`. + The list of thermal factors per each site in `corepos`. """ # By design Atom instances are not accepted as arguments to keep @@ -1113,37 +1114,37 @@ class SymmetryConstraints(object): Attributes ---------- spacegroup : SpaceGroup - Instance of `SpaceGroup`. + The instance of `SpaceGroup`. positions : numpy.ndarray All positions to be constrained. Uijs : numpy.ndarray - Thermal factors for all positions. Defaults to zeros. + The thermal factors for all positions. Defaults to zeros. sgoffset : numpy.ndarray - Optional offset of space group origin ``[0, 0, 0]``. + The optional offset of space group origin ``[0, 0, 0]``. eps : float - Cutoff for equivalent positions. Default is ``1.0e-5``. + The cutoff for equivalent positions. Default is ``1.0e-5``. corepos : list - List of of positions in the asymmetric unit. + The list of positions in the asymmetric unit. coremap : dict - Dictionary mapping indices of asymmetric core positions + The dictionary mapping indices of asymmetric core positions to indices of all symmetry related positions. poseqns : list - List of coordinate formula dictionaries per each site. + The list of coordinate formula dictionaries per each site. Formula dictionary keys are from ``("x", "y", "z")`` and the values are formatted as ``[[-]{x|y|z}%i] [{+|-}%g]``, for example: ``x0``, ``-x3``, ``z7 +0.5``, ``0.25``. pospars : list - List of ``(xyz symbol, value)`` pairs. + The list of ``(xyz symbol, value)`` pairs. Ueqns : list - List of anisotropic atomic displacement formula + The list of anisotropic atomic displacement formula dictionaries per each position. Formula dictionary keys are from ``('U11','U22','U33','U12','U13','U23')`` and the values are formatted as ``{[%g*][Uij%i]|0}``, for example: ``U110``, ``0.5*U2213``, ``0``. Upars : list - List of ``(U symbol, value)`` pairs. + The list of ``(U symbol, value)`` pairs. Uisotropy : list - List of bool flags for isotropic thermal displacements. + The list of bool flags for isotropic thermal displacements. """ def __init__(self, spacegroup, positions, Uijs=None, sgoffset=[0, 0, 0], eps=None): diff --git a/src/diffpy/structure/utils.py b/src/diffpy/structure/utils.py index 1e1a6deb..860a9628 100644 --- a/src/diffpy/structure/utils.py +++ b/src/diffpy/structure/utils.py @@ -53,7 +53,6 @@ def atomBareSymbol(smbl): Please use diffpy.structure.atom_bare_symbol instead. """ - return atom_bare_symbol(smbl) @@ -103,7 +102,7 @@ def _link_atom_attribute(attrname, doc, toarray=numpy.array): doc : str The docstring for the property wrapper. toarray : callable, Optional - Factory function that converts list of attributes to `numpy.ndarray`. + The factory function that converts a list of attributes to `numpy.ndarray`. Use `numpy.char.array` for string attributes. Return a property object. diff --git a/tests/test_atom.py b/tests/test_atom.py index 2d2b4f5e..76d11324 100644 --- a/tests/test_atom.py +++ b/tests/test_atom.py @@ -14,7 +14,6 @@ ############################################################################## """Unit tests for the Atom class.""" - import unittest import numpy diff --git a/tests/test_expansion.py b/tests/test_expansion.py index 481f7670..33e494fb 100644 --- a/tests/test_expansion.py +++ b/tests/test_expansion.py @@ -13,6 +13,7 @@ # ############################################################################## """Tests for the expansion module utilities.""" + import pytest from diffpy.structure.atom import Atom diff --git a/tests/test_spacegroups.py b/tests/test_spacegroups.py index de5fd69d..70d527a5 100644 --- a/tests/test_spacegroups.py +++ b/tests/test_spacegroups.py @@ -14,7 +14,6 @@ ############################################################################## """Unit tests for diffpy.structure.spacegroups.""" - import unittest from diffpy.structure.spacegroups import ( diff --git a/tests/test_structure.py b/tests/test_structure.py index 39591bc1..8e61e93e 100644 --- a/tests/test_structure.py +++ b/tests/test_structure.py @@ -14,7 +14,6 @@ ############################################################################## """Unit tests for Structure class.""" - import copy import pickle import unittest diff --git a/tests/test_utils.py b/tests/test_utils.py index 0c89ae09..60f304af 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -13,6 +13,7 @@ # ############################################################################## """Test for Structure utilities.""" + import pytest from diffpy.structure.utils import atom_bare_symbol, atomBareSymbol