Skip to content

Fix docstrings for API reference. #76

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,11 @@
# Display all warnings for missing links.
nitpicky = True

nitpick_ignore = [
("py:class", "array_like"),
("py:class", "Parser"),
]

# -- Options for HTML output ----------------------------------------------

# The theme to use for HTML and HTML Help pages. See the documentation for
Expand Down Expand Up @@ -287,3 +292,7 @@

# Example configuration for intersphinx: refer to the Python standard library.
# intersphinx_mapping = {'http://docs.python.org/': None}
intersphinx_mapping = {
"python": ("https://docs.python.org/3", None),
"numpy": ("https://numpy.org/doc/stable/", None),
}
17 changes: 12 additions & 5 deletions src/diffpy/structure/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,15 +13,22 @@
#
##############################################################################

"""classes related to structure of materials
"""
Classes related to the structure of materials.

Classes:
Atom

Lattice

Structure

PDFFitStructure
Exceptions:
StructureFormatError

LatticeError

SymmetryError
"""

Expand Down Expand Up @@ -51,13 +58,13 @@ def loadStructure(filename, fmt="auto", **kw):

filename : str
Path to the file to be loaded.
fmt : str, optional
Format of the structure file such as 'cif' or 'xyz'. Must be
fmt : str, Optional
Format of the structure file such as 'cif' or 'xyz'. Must be
one of the formats listed by the `parsers.inputFormats` function.
When 'auto', all supported formats are tried in a sequence.
kw : misc, optional
kw : Optional
Extra keyword arguments that are passed to `parsers.getParser`
function. These configure the dedicated Parser object that
function. These configure the dedicated Parser object that
is used to read content in filename.

Returns
Expand Down
39 changes: 26 additions & 13 deletions src/diffpy/structure/apps/anyeye.py
Original file line number Diff line number Diff line change
Expand Up @@ -13,24 +13,37 @@
#
##############################################################################

"""anyeye view structure file in atomeye
"""
anyeye view structure file in atomeye

Usage: anyeye [options] strufile

anyeye understands more structure formats than atomeye. It converts strufile
to a temporary XCFG file which is opened in atomeye. Supported file formats:
Anyeye understands more structure formats than atomeye. It converts strufile
to a temporary XCFG file which is opened in atomeye. Supported file formats:
inputFormats

Options:
-f, --formula override chemical formula in strufile, formula defines
elements in the same order as in strufile, e.g, Na4Cl4
-w, --watch watch input file for changes
--viewer=VIEWER the structure viewer program, by default "atomeye".
The program will be executed as "VIEWER structurefile"
--formats=FORMATS comma separated list of file formats that are understood
by the VIEWER, by default "xcfg,pdb". Files of other
formats will be converted to the first listed format.
-h, --help display this message and exit
-V, --version show script version and exit
-f, --formula
Override chemical formula in strufile. The formula defines
elements in the same order as in strufile, e.g., Na4Cl4.

-w, --watch
Watch input file for changes.

--viewer=VIEWER
The structure viewer program, by default "atomeye".
The program will be executed as "VIEWER structurefile".

--formats=FORMATS
Comma-separated list of file formats that are understood
by the VIEWER, by default "xcfg,pdb". Files of other
formats will be converted to the first listed format.

-h, --help
Display this message and exit.

-V, --version
Show script version and exit.
"""

from __future__ import print_function
Expand Down
22 changes: 11 additions & 11 deletions src/diffpy/structure/atom.py
Original file line number Diff line number Diff line change
Expand Up @@ -39,27 +39,27 @@ class Atom(object):

Parameters
----------
atype : str or Atom, optional
atype : str or Atom, Optional
The string atom type to be set as the `element` attribute.
By default an empty string. When of the *Atom* type, create
a copy of *atype* and adjust it per other arguments.
xyz : ndarray, optional
xyz : numpy.ndarray, Optional
Fractional coordinates within the associated `lattice`.
By default ``[0, 0, 0]``.
label : str, optional
label : str, Optional
A unique string `label` for referring to this Atom.
By default an empty string.
occupancy : float, optional
occupancy : float, Optional
The initial `occupancy` of this atom, by default ``1``.
anisotropy : bool, optional
anisotropy : bool, Optional
The flag for anisotropic thermal displacements parameters.
This overrides `anisotropy` implied by presence of the
*U* or *Uisoequiv* arguments. Defaults to ``False``
when not set in any other way.
U : ndarray, optional
U : numpy.ndarray, Optional
The 3x3 matrix of anisotropic thermal displacement parameters.
When present `anisotropy` defaults to ``True``.
Uisoequiv: float, optional
Uisoequiv: float, Optional
The isotropic atomic displacement parameter. The `anisotropy`
defaults to ``False`` when present. Only one of the *U* and
*Uisoequiv* arguments may be provided at the same time. Assume
Expand All @@ -72,7 +72,7 @@ class Atom(object):
----------
element : str
The string type of the atom. An element or ion symbol.
xyz : ndarray
xyz : numpy.ndarray
The fractional coordinates in the associated `lattice`.
label : str
A unique string label referring to this atom, for example, "C_1".
Expand Down Expand Up @@ -211,7 +211,7 @@ def __copy__(self, target=None):

Parameters
----------
target : Atom, optional
target : Atom, Optional
An already existing Atom object to be updated to a duplicate
of this Atom. Create a new Atom object when not specified.
This facilitates extension of the `__copy__` method
Expand Down Expand Up @@ -254,7 +254,7 @@ def __copy__(self, target=None):
@property
def xyz_cartn(self):
"""
ndarray: Atom position in absolute Cartesian coordinates.
numpy.ndarray: Atom position in absolute Cartesian coordinates.

This is computed from fractional coordinates `xyz` and the
current `lattice` setup. Assignment to *xyz_cartn* or
Expand Down Expand Up @@ -305,7 +305,7 @@ def anisotropy(self, value):
@property
def U(self):
"""
ndarray : The 3x3 matrix of anisotropic atomic displacements.
numpy.ndarray : The 3x3 matrix of anisotropic atomic displacements.

For isotropic displacements (when `anisotropy` is ``False``)
assignment to *U* uses only the first ``Unew[0, 0]`` element
Expand Down
31 changes: 20 additions & 11 deletions src/diffpy/structure/expansion/makeellipsoid.py
Original file line number Diff line number Diff line change
Expand Up @@ -36,17 +36,26 @@ def makeSphere(S, radius):


def makeEllipsoid(S, a, b=None, c=None):
"""Cut a structure out of another one.

Arguments
S -- A Structure instance
a -- primary equatorial radius (along x-axis)
b -- secondary equatorial radius (along y-axis). If b is None
(default) then it is set equal to a
c -- polar radius (along z-axis). If c is None (default), then it is
set equal to a.

Returns a new structure instance
"""
Cut a structure out of another one.

Parameters
----------
S :
A Structure instance.
a :
Primary equatorial radius (along x-axis).
b :
Secondary equatorial radius (along y-axis). If b is None
(default), then it is set equal to a.
c :
Polar radius (along z-axis). If c is None (default), then it is
set equal to a.

Returns
-------
Structure :
A new structure instance.
"""
if b is None:
b = a
Expand Down
27 changes: 20 additions & 7 deletions src/diffpy/structure/expansion/supercell_mod.py
Original file line number Diff line number Diff line change
Expand Up @@ -22,19 +22,32 @@


def supercell(S, mno):
"""Perform supercell expansion for a structure.
"""
Perform supercell expansion for a structure.

New lattice parameters are multiplied and fractional coordinates
divided by corresponding multiplier. New atoms are grouped with
their source in the original cell.

S -- an instance of Structure from diffpy.structure.
mno -- sequence of 3 integers for cell multipliers along
the a, b and c axes.
Parameters
----------
S :
An instance of Structure from diffpy.structure.
mno :
Sequence of 3 integers for cell multipliers along
the a, b and c axes.

Returns
-------
Structure
A new structure instance representing the expanded supercell.

Return a new expanded structure instance.
Raise TypeError when S is not Structure instance.
Raise ValueError for invalid mno argument.
Raises
------
TypeError
S is not a Structure instance.
ValueError
Invalid mno argument.
"""
# check arguments
if len(mno) != 3:
Expand Down
Loading
Loading