Skip to content
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.

Sign up for GitHub

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

Google-style doc strings for class attributes #3320

Merged
merged 1 commit into from
Sep 13, 2023
Merged

Google-style doc strings for class attributes #3320

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
11 changes: 5 additions & 6 deletions pymatgen/analysis/pourbaix_diagram.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -327,7 +327,7 @@ def as_dict(self):
def from_dict(cls, dct):
"""
Args:
d (dict): Dict representation.
dct (dict): Dict representation.

Returns:
MultiEntry
Expand All @@ -343,11 +343,10 @@ class IonEntry(PDEntry):
Object similar to PDEntry, but contains an Ion object instead of a
Composition object.

.. attribute:: name

A name for the entry. This is the string shown in the phase diagrams.
By default, this is the reduced formula for the composition, but can be
set to some other string for display purposes.
Attributes:
name (str): A name for the entry. This is the string shown in the phase diagrams.
By default, this is the reduced formula for the composition, but can be
set to some other string for display purposes.
"""

def __init__(self, ion: Ion, energy: float, name: str | None = None, attribute=None):
Expand Down
161 changes: 50 additions & 111 deletions pymatgen/analysis/surface_analysis.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,26 +68,13 @@ class SlabEntry(ComputedStructureEntry):
A ComputedStructureEntry object encompassing all data relevant to a
slab for analyzing surface thermodynamics.

.. attribute:: miller_index

Miller index of plane parallel to surface.

.. attribute:: label

Brief description for this slab.

.. attribute:: adsorbates

List of ComputedStructureEntry for the types of adsorbates

..attribute:: clean_entry

SlabEntry for the corresponding clean slab for an adsorbed slab

..attribute:: ads_entries_dict

Dictionary where the key is the reduced composition of the
adsorbate entry and value is the entry itself
Attributes:
miller_index (tuple): Miller index of plane parallel to surface.
label (str): Brief description for this slab.
adsorbates (list): List of ComputedStructureEntry for the types of adsorbates.
clean_entry (SlabEntry): SlabEntry for the corresponding clean slab for an adsorbed slab.
ads_entries_dict (dict): Dictionary where the key is the reduced composition of the
adsorbate entry and value is the entry itself.
"""

def __init__(
Expand Down Expand Up @@ -355,14 +342,13 @@ def from_computed_structure_entry(entry, miller_index, label=None, adsorbates=No
class SurfaceEnergyPlotter:
"""
A class used for generating plots to analyze the thermodynamics of surfaces
of a material. Produces stability maps of different slab configurations,
phases diagrams of two parameters to determine stability of configurations
(future release), and Wulff shapes.

.. attribute:: all_slab_entries
of a material. Produces stability maps of different slab configurations,
phases diagrams of two parameters to determine stability of configurations
(future release), and Wulff shapes.

Either a list of SlabEntry objects (note for a list, the SlabEntry must
have the adsorbates and clean_entry parameter pulgged in) or a Nested
Attributes:
all_slab_entries (dict | list): Either a list of SlabEntry objects (note for a list, the
SlabEntry must have the adsorbates and clean_entry parameter plugged in) or a Nested
dictionary containing a list of entries for slab calculations as
items and the corresponding Miller index of the slab as the key.
To account for adsorption, each value is a sub-dictionary with the
Expand All @@ -375,31 +361,19 @@ class SurfaceEnergyPlotter:
the adsorption energy (ie an adsorption site with a higher adsorption
energy will always provide a higher surface energy than a site with a
lower adsorption energy). An example parameter is provided:
{(h1,k1,l1): {clean_entry1: [ads_entry1, ads_entry2, ...],
clean_entry2: [...], ...}, (h2,k2,l2): {...}}
{(h1,k1,l1): {clean_entry1: [ads_entry1, ads_entry2, ...], clean_entry2: [...], ...}, (h2,k2,l2): {...}}
where clean_entry1 can be a pristine surface and clean_entry2 can be a
reconstructed surface while ads_entry1 can be adsorption at site 1 with
a 2x2 coverage while ads_entry2 can have a 3x3 coverage. If adsorption
entries are present (i.e. if all_slab_entries[(h,k,l)][clean_entry1]), we
consider adsorption in all plots and analysis for this particular facet.

..attribute:: color_dict

Dictionary of colors (r,g,b,a) when plotting surface energy stability. The
keys are individual surface entries where clean surfaces have a solid
color while the corresponding adsorbed surface will be transparent.

.. attribute:: ucell_entry

ComputedStructureEntry of the bulk reference for this particular material.

.. attribute:: ref_entries

List of ComputedStructureEntries to be used for calculating chemical potential.

.. attribute:: color_dict

Randomly generated dictionary of colors associated with each facet.
color_dict (dict): Dictionary of colors (r,g,b,a) when plotting surface energy stability.
The keys are individual surface entries where clean surfaces have a solid color while
the corresponding adsorbed surface will be transparent.
ucell_entry (ComputedStructureEntry): ComputedStructureEntry of the bulk reference for
this particular material.
ref_entries (list): List of ComputedStructureEntries to be used for calculating chemical potential.
facet_color_dict (dict): Randomly generated dictionary of colors associated with each facet.
"""

def __init__(self, all_slab_entries, ucell_entry, ref_entries=None):
Expand All @@ -420,7 +394,7 @@ def __init__(self, all_slab_entries, ucell_entry, ref_entries=None):
be defined by a summation of the chemical potentials for each
element in the system. As the bulk energy is already provided,
one can solve for one of the chemical potentials as a function
of the other chemical potetinals and bulk energy. i.e. there
of the other chemical potentials and bulk energy. i.e. there
are n-1 variables (chempots). e.g. if your ucell_entry is for
LiFePO4 than your ref_entries should have an entry for Li, Fe,
and P if you want to use the chempot of O as the variable.
Expand Down Expand Up @@ -1348,49 +1322,21 @@ def entry_dict_from_list(all_slab_entries):

class WorkFunctionAnalyzer:
"""
A class used for calculating the work function
from a slab model and visualizing the behavior
of the local potential along the slab.

.. attribute:: efermi

The Fermi energy

.. attribute:: locpot_along_c

Local potential in eV along points along the axis

.. attribute:: vacuum_locpot

The maximum local potential along the c direction for
the slab model, ie the potential at the vacuum

.. attribute:: work_function

The minimum energy needed to move an electron from the
surface to infinity. Defined as the difference between
the potential at the vacuum and the Fermi energy.

.. attribute:: slab

The slab structure model

.. attribute:: along_c

Points along the c direction with same
increments as the locpot in the c axis

.. attribute:: ave_locpot

Mean of the minimum and maximmum (vacuum) locpot along c

.. attribute:: sorted_sites

List of sites from the slab sorted along the c direction

.. attribute:: ave_bulk_p

The average locpot of the slab region along the c direction
A class used for calculating the work function from a slab model and
visualizing the behavior of the local potential along the slab.

Attributes:
efermi (float): The Fermi energy.
locpot_along_c (list): Local potential in eV along points along the c axis.
vacuum_locpot (float): The maximum local potential along the c direction for the slab model,
i.e. the potential at the vacuum.
work_function (float): The minimum energy needed to move an electron from the surface to infinity.
Defined as the difference between the potential at the vacuum and the Fermi energy.
slab (Slab): The slab structure model.
along_c (list): Points along the c direction with same increments as the locpot in the c axis.
ave_locpot (float): Mean of the minimum and maximum (vacuum) locpot along c.
sorted_sites (list): List of sites from the slab sorted along the c direction.
ave_bulk_p (float): The average locpot of the slab region along the c direction.
"""

def __init__(self, structure: Structure, locpot_along_c, efermi, shift=0, blength=3.5):
Expand Down Expand Up @@ -1644,29 +1590,22 @@ def from_files(poscar_filename, locpot_filename, outcar_filename, shift=0, bleng
description="Nanoscale stabilization of sodium oxides: Implications for Na-O2 batteries",
)
class NanoscaleStability:
"""
A class for analyzing the stability of nanoparticles of different
polymorphs with respect to size. The Wulff shape will be the
model for the nanoparticle. Stability will be determined by
an energetic competition between the weighted surface energy
(surface energy of the Wulff shape) and the bulk energy. A
future release will include a 2D phase diagram (e.g. wrt size
vs chempot for adsorbed or non-stoichiometric surfaces). Based
on the following work:

Kang, S., Mo, Y., Ong, S. P., & Ceder, G. (2014). Nanoscale
stabilization of sodium oxides: Implications for Na-O2
batteries. Nano Letters, 14(2), 1016-1020.
https://doi.org/10.1021/nl404557w
"""A class for analyzing the stability of nanoparticles of different
polymorphs with respect to size. The Wulff shape will be the model for the
nanoparticle. Stability will be determined by an energetic competition between the
weighted surface energy (surface energy of the Wulff shape) and the bulk energy. A
future release will include a 2D phase diagram (e.g. wrt size vs chempot for adsorbed
or non-stoichiometric surfaces). Based on the following work:

.. attribute:: se_analyzers

List of SurfaceEnergyPlotter objects. Each item corresponds to a
different polymorph.
Kang, S., Mo, Y., Ong, S. P., & Ceder, G. (2014). Nanoscale
stabilization of sodium oxides: Implications for Na-O2
batteries. Nano Letters, 14(2), 1016-1020.
https://doi.org/10.1021/nl404557w

.. attribute:: symprec

See WulffShape.
Attributes:
se_analyzers (list[SurfaceEnergyPlotter]): Each item corresponds to a different polymorph.
symprec (float): Tolerance for symmetry finding. See WulffShape.
"""

def __init__(self, se_analyzers, symprec=1e-5):
Expand Down
79 changes: 24 additions & 55 deletions pymatgen/analysis/wulff.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -102,61 +102,30 @@ class WulffShape:
http://scipy.github.io/devdocs/generated/scipy.spatial.ConvexHull.html

Process:
1. get wulff simplices
1. get Wulff simplices
2. label with color
3. get wulff_area and other properties

.. attribute:: debug (bool)

.. attribute:: alpha
transparency

.. attribute:: color_set

.. attribute:: grid_off (bool)

.. attribute:: axis_off (bool)

.. attribute:: show_area

.. attribute:: off_color
color of facets off wulff

.. attribute:: structure
Structure object, input conventional unit cell (with H ) from lattice

.. attribute:: miller_list
list of input miller index, for hcp in the form of hkil

.. attribute:: hkl_list
modify hkill to hkl, in the same order with input_miller

.. attribute:: e_surf_list
list of input surface energies, in the same order with input_miller

.. attribute:: lattice
Lattice object, the input lattice for the conventional unit cell

.. attribute:: facets
[WulffFacet] for all facets considering symm

.. attribute:: dual_cv_simp
simplices from the dual convex hull (dual_pt)

.. attribute:: wulff_pt_list

.. attribute:: wulff_cv_simp
simplices from the convex hull of wulff_pt_list

.. attribute:: on_wulff
list for all input_miller, True is on wulff.

.. attribute:: color_area
list for all input_miller, total area on wulff, off_wulff = 0.

.. attribute:: miller_area
($hkl$): area for all input_miller

Attributes:
debug (bool): Whether to print debug information.
alpha (float): Transparency of the Wulff shape.
color_set (list): colors to use for facets.
grid_off (bool): Whether to turn off the grid.
axis_off (bool): Whether to turn off the axis.
show_area (bool): Whether to show the area of each facet.
off_color (str): Color of facets not on the Wulff shape.
structure (Structure): Input conventional unit cell (with H) from lattice.
miller_list (list): input Miller indices, for hcp in the form of hkil.
hkl_list (list): Modified Miller indices in the same order as input_miller.
e_surf_list (list): input surface energies in the same order as input_miller.
lattice (Lattice): Input lattice for the conventional unit cell.
facets (list): WulffFacet objects considering symmetry.
dual_cv_simp (list): Simplices from the dual convex hull (dual_pt).
wulff_pt_list (list): Wulff points.
wulff_cv_simp (list): Simplices from the convex hull of wulff_pt_list.
on_wulff (list): List for all input_miller, True if on the Wulff shape.
color_area (list): List for all input_miller, total area on the Wulff shape, off_wulff = 0.
miller_area (dict): Dictionary of Miller indices and their corresponding areas.
"""

def __init__(self, lattice: Lattice, miller_list, e_surf_list, symprec=1e-5):
Expand All @@ -165,7 +134,7 @@ def __init__(self, lattice: Lattice, miller_list, e_surf_list, symprec=1e-5):
lattice: Lattice object of the conventional unit cell
miller_list ([(hkl), ...]: list of hkl or hkil for hcp
e_surf_list ([float]): list of corresponding surface energies
symprec (float): for recp_operation, default is 1e-5.
symprec (float): for reciprocal lattice operation, default is 1e-5.
"""
if any(se < 0 for se in e_surf_list):
warnings.warn("Unphysical (negative) surface energy detected.")
Expand All @@ -190,8 +159,8 @@ def __init__(self, lattice: Lattice, miller_list, e_surf_list, symprec=1e-5):
dual_pts = [x.dual_pt for x in self.facets]
dual_convex = ConvexHull(dual_pts)
dual_cv_simp = dual_convex.simplices
# simplices (ndarray of ints, shape (nfacet, ndim))
# list of [i, j, k] , ndim = 3
# simplices (ndarray of ints, shape (n_facet, n_dim))
# list of [i, j, k] , n_dim = 3
# i, j, k: ind for normal_e_m
# recalculate the dual of dual, get the Wulff shape.
# corner <-> surface
Expand Down
5 changes: 2 additions & 3 deletions pymatgen/command_line/enumlib_caller.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -65,9 +65,8 @@
class EnumlibAdaptor:
"""An adaptor for enumlib.

.. attribute:: structures

List of all enumerated structures.
Attributes:
structures (list): all enumerated structures.
"""

amount_tol = 1e-5
Expand Down
7 changes: 3 additions & 4 deletions pymatgen/core/operations.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,8 @@ class SymmOp(MSONable):
translation. Implementation is as an affine transformation matrix of rank 4
for efficiency. Read: http://en.wikipedia.org/wiki/Affine_transformation.

.. attribute:: affine_matrix

A 4x4 numpy.array representing the symmetry operation.
Attributes:
affine_matrix (np.ndarray): A 4x4 array representing the symmetry operation.
"""

def __init__(self, affine_transformation_matrix: ArrayLike, tol: float = 0.01) -> None:
Expand All @@ -41,7 +40,7 @@ def __init__(self, affine_transformation_matrix: ArrayLike, tol: float = 0.01) -
Args:
affine_transformation_matrix (4x4 array): Representing an
affine transformation.
tol (float): Tolerance for determining if matrices are equal.
tol (float): Tolerance for determining if matrices are equal. Defaults to 0.01.

Raises:
ValueError: if matrix is not 4x4.
Expand Down
Loading