diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8a3282f..a410562 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -64,6 +64,7 @@ repos: additional_dependencies: - flake8-typing-imports==1.10.1 - flake8-rst==0.8.0 + - Flake8-pyproject - repo: https://github.com/pycqa/pydocstyle rev: 6.3.0 # pick a git hash / tag to point to diff --git a/WFacer/convergence.py b/WFacer/convergence.py index 8b1467c..a4892be 100644 --- a/WFacer/convergence.py +++ b/WFacer/convergence.py @@ -22,6 +22,7 @@ def compare_min_energy_structures_by_composition(min_e1, min_e2, matcher=None): matcher (StructureMatcher): optional A StructureMatcher used compare structures. wrangler.cluster_subspace._site_matcher is recommended. + Return: float, bool: maximum energy difference in eV/site, @@ -52,6 +53,7 @@ def compare_fitted_coefs(cluster_subspace, coefs_prev, coefs_now): Not ECIs because not divided by multiplicity! coefs_now(1d arrayLike): Cluster coefficients fitted in the latest iteration. + Returns: float: || ECI' - ECI ||_1 / ||ECI||_1. @@ -83,6 +85,7 @@ def ce_converged( must be equal to that of current iter_id - 1. convergence_options(dict): Pre-processed convergence criterion. + Returns: bool. """ diff --git a/WFacer/enumeration.py b/WFacer/enumeration.py index 2241bc1..22a1528 100644 --- a/WFacer/enumeration.py +++ b/WFacer/enumeration.py @@ -63,6 +63,7 @@ def enumerate_matrices( to 30, to prevent over-skewing. kwargs: keyword arguments to pass into SpaceGroupAnalyzer. + Returns: List of 2D lists. """ @@ -222,6 +223,7 @@ def enumerate_compositions_as_counts( Results will be returned in "counts" format (see smol.moca.CompositionSpace). + Args: sc_size(int): The super-cell size in the number of prim cells. @@ -239,6 +241,7 @@ def enumerate_compositions_as_counts( Default to 1. kwargs: Other keyword arguments to initialize CompositionSpace. + Returns: Enumerated possible compositions in "counts" format, not normalized: 2D np.ndarray[int] @@ -427,6 +430,7 @@ def generate_training_structures( before matching. It should be used with caution. kwargs: Keyword arguments for utils.selection.select_initial_rows. + Returns: list[Structure], list[3*3 list[list[int]]], list[list[float]]: Initial training structures, super-cell matrices, diff --git a/WFacer/fit.py b/WFacer/fit.py index 0de1878..339d322 100644 --- a/WFacer/fit.py +++ b/WFacer/fit.py @@ -28,6 +28,7 @@ def fit_ecis_from_wrangler( """Fit ECIs from a fully processed wrangler. No weights will be used. + Args: wrangler(CeDataWrangler): A CeDataWrangler storing all training structures. @@ -60,6 +61,7 @@ def fit_ecis_from_wrangler( Other keyword arguments to initialize an optimizer. kwargs: Keyword arguments used by estimator._fit. For example, solver arguments. + Returns: Estimator, 1D np.ndarray, float, float, float, 1D np.ndarray: Fitted estimator, coefficients (not ECIs), cross validation error (meV/site), diff --git a/WFacer/jobs.py b/WFacer/jobs.py index a95a3d2..9e071aa 100644 --- a/WFacer/jobs.py +++ b/WFacer/jobs.py @@ -195,6 +195,7 @@ def enumerate_structures(last_ce_document): Args: last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: dict: Newly enumerated structures, super-cell matrices @@ -266,6 +267,7 @@ def get_structure_calculation_flows(enum_output, last_ce_document): Output by enumeration job. last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: list[Flow], list[OutputReference]: Flows for each structure and their output references pointing @@ -325,6 +327,7 @@ def calculate_structures_job(enum_output, last_ce_document): Output by enumeration job. last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: list[TaskDoc]: Results of VASP calculations as TaskDoc. @@ -353,6 +356,7 @@ def parse_calculations(taskdocs, enum_output, last_ce_document): Output by enumeration job. last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: dict Updated wrangler, all entries before decoration, @@ -471,6 +475,7 @@ def fit_calculations(parse_output, last_ce_document): Output by parse job. last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: dict: Dictionary containing fitted CE information. @@ -506,6 +511,7 @@ def update_document(enum_output, parse_output, fit_output, last_ce_document): Output by parse job. last_ce_document(CeOutputsDocument): The last cluster expansion outputs document. + Returns: CeOutputDocument: The updated document. @@ -550,6 +556,7 @@ def initialize_document(prim, project_name="ace-work", options=None): In this job, a cluster subspace will be created, super-cells and compositions will also be enumerated. + Args: prim(structure): A primitive cell structure (no need to be reduced) with diff --git a/WFacer/maker.py b/WFacer/maker.py index a78cd16..f1529ea 100644 --- a/WFacer/maker.py +++ b/WFacer/maker.py @@ -22,6 +22,7 @@ def ce_step_trigger(last_ce_document): last_ce_document(CeOutputsDocument): The cluster expansion outputs document from the latest step. + Returns: Response: Either a CeOutputsDocument if converged, or a @@ -120,6 +121,7 @@ def make(self, prim, last_document=None, add_num_iterations=None): number of iterations, add this many more iterations. Default is None. When given None or 0, will simply double max_iter in options. + Returns: Flow: The iterative cluster expansion workflow. diff --git a/WFacer/preprocessing.py b/WFacer/preprocessing.py index 42d9cd6..a33c484 100644 --- a/WFacer/preprocessing.py +++ b/WFacer/preprocessing.py @@ -22,6 +22,7 @@ def reduce_prim(prim, **kwargs): A primitive cell with partial occupancy to be expanded. kwargs: Keyword arguments for SpacegroupAnalyzer. + Returns: Structure """ @@ -168,6 +169,7 @@ def get_cluster_subspace( for extensibility.) kwargs: Other keyword arguments for ClusterSubspace.from_cutoffs. + Returns: ClusterSubspace: A cluster subspace generated from cutoffs. @@ -194,6 +196,7 @@ def process_supercell_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing supercell matrix options, including the following keys: @@ -246,6 +249,7 @@ def process_composition_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing composition options, including the following keys: @@ -321,6 +325,7 @@ def process_structure_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing structure options, including the following keys: @@ -377,6 +382,7 @@ def process_calculation_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing calculation options, including the following keys: @@ -459,6 +465,7 @@ def process_decorator_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing calculation options, including the following keys: @@ -509,6 +516,7 @@ def process_subspace_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing fit options, including the following keys: @@ -541,6 +549,7 @@ def process_fit_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing fit options, including the following keys: @@ -603,6 +612,7 @@ def process_convergence_options(d): Args: d(dict): An input dictionary containing various options in the input file. + Returns: dict: A dict containing convergence options, including the following keys: @@ -658,9 +668,11 @@ def get_initial_ce_coefficients(cluster_subspace): Any coefficient, except those for external terms, will be initialized to 0. This guarantees that for ionic systems, structures with lower ewald energy are always selected first. + Args: cluster_subspace(ClusterSubspace): The initial cluster subspace. + Returns: np.ndarray[float]. """ diff --git a/WFacer/specie_decorators/base.py b/WFacer/specie_decorators/base.py index 8a49af5..79fa837 100644 --- a/WFacer/specie_decorators/base.py +++ b/WFacer/specie_decorators/base.py @@ -103,6 +103,7 @@ def group_site_by_species(entries): Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Return: (Entry index, site index) occupied by each species: defaultdict @@ -125,6 +126,7 @@ def is_trained(self): """Gives whether this decorator is trained before. If trained, will be blocked from training again. + Returns: bool. """ @@ -154,9 +156,11 @@ def decorate(self, entries): If an assigned entry is not valid, for example, in charge assignment, if an assigned structure is not charge neutral, then this entry will be returned as None. + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Returns: List[NoneType|ComputedStructureEntry] """ @@ -422,9 +426,11 @@ def decorate(self, entries): If an assigned entry is not valid, for example, in charge assignment, if an assigned structure is not charge neutral, then this entry will be returned as None. + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Returns: Entries with structures decorated. Returns None if decoration failed (not charge balanced, etc.) @@ -515,7 +521,7 @@ def __init__(self, labels, cuts=None, **kwargs): GuessChargeDecorator. Be sure to provide labels for all the species you wish to assign a property to, otherwise, you are the cause of your own error! - cuts(dict{str|Species: list}): optional + cuts(dict{str|Species: list}): optional Cuts to divide required property value into sectors, so as to decide the label they belong to. Keys are the same as argument "labels". @@ -547,6 +553,7 @@ def is_trained(self): """Gives whether this decorator is trained before. If trained, will be blocked from training again. + Returns: bool. """ @@ -657,6 +664,7 @@ def train(self, entries, reset=False, n_calls=50): First initialize with mixture of gaussian, then optimize some objective function with gaussian process. + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. @@ -707,9 +715,11 @@ def decorate(self, entries): If an assigned entry is not valid, for example, in charge assignment, if an assigned structure is not charge neutral, then this entry will be returned as None. + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Returns: List[NoneType|ComputedStructureEntry] """ @@ -796,6 +806,7 @@ def get_site_property_query_names_from_decorator(decname): Args: decname(str): Decorator name. + Returns: list[str]: List of names of required site properties by the diff --git a/WFacer/specie_decorators/charge.py b/WFacer/specie_decorators/charge.py index f7f4f14..1150b8f 100644 --- a/WFacer/specie_decorators/charge.py +++ b/WFacer/specie_decorators/charge.py @@ -101,9 +101,11 @@ def decorate(self, entries): Warning: Do not use this with multi-valent elements, unless you know what you want clearly!!! + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Returns: List[NoneType|ComputedStructureEntry] """ @@ -143,9 +145,11 @@ def decorate(self, entries): Warning: Do not use this with multi-valent elements, unless you know what you want clearly!!! + Args: entries(List[ComputedStructureEntry]): Entries of computed structures. + Returns: List[NoneType|ComputedStructureEntry] """ diff --git a/WFacer/utils/convex_hull.py b/WFacer/utils/convex_hull.py index 46f1f2e..6637922 100644 --- a/WFacer/utils/convex_hull.py +++ b/WFacer/utils/convex_hull.py @@ -25,6 +25,7 @@ def get_min_energy_structures_by_composition(wrangler, max_iter_id=None): max_iter_id(int): optional Maximum iteration index included in the energy comparison. If none given, will read existing maximum iteration number. + Returns: defaultdict: element compositions as keys, energy per site and structure diff --git a/WFacer/utils/duplicacy.py b/WFacer/utils/duplicacy.py index 9fe123f..7db4021 100644 --- a/WFacer/utils/duplicacy.py +++ b/WFacer/utils/duplicacy.py @@ -9,9 +9,11 @@ def clean_up_decoration(s): """Remove all decoration from a structure. Used before comparing two structures before sending to compute. + Args: s(Structure): A structure. + Returns: Structure: The cleaned up structure containing only Element. @@ -55,6 +57,7 @@ def is_duplicate(s1, s2, remove_decorations=False, matcher=None): matcher(StructureMatcher): optional A StructureMatcher to compare two structures. Using the same _site_matcher as cluster_subspace is highly recommended. + Returns: bool """ @@ -80,6 +83,7 @@ def is_corr_duplicate(s1, proc1, s2=None, proc2=None, features2=None): faster that comparing two structures, because comparing two structures might involve reducing them to primitive cells in advance, which can occasionally be very slow. + Args: s1 (Structure): A structure to be checked. diff --git a/WFacer/utils/occu.py b/WFacer/utils/occu.py index 56fa4e4..72f7ef3 100644 --- a/WFacer/utils/occu.py +++ b/WFacer/utils/occu.py @@ -11,6 +11,7 @@ def get_random_occupancy_from_counts(ensemble, counts): counts(1D arrayLike): Species composition in "counts" format. See smol.moca.composition. + Returns: np.ndarray: An encoded occupancy array. diff --git a/WFacer/utils/query.py b/WFacer/utils/query.py index 8c22800..c3e7a74 100644 --- a/WFacer/utils/query.py +++ b/WFacer/utils/query.py @@ -13,6 +13,7 @@ def query_keypath(obj, keypath): The object to be queried. keypath(list[str]): A path of attribute names to query. + Returns: Any: the queried result. """ @@ -70,6 +71,7 @@ def query_name_iteratively(obj, name): The object to be queried. name(str): The attribute name. + Returns: Any: the queried result. Will always return the first one found at the shallowest reference level. @@ -156,8 +158,8 @@ def get_property_from_object(obj, query_string): If you decide to use special characters, please always make sure you have specified the exact full path to retrieve the desired item. - Returns: - any: value of the queried property. + Returns: + any: value of the queried property. """ # Add more special conversion rules if needed. query = query_string.split(".") diff --git a/WFacer/utils/selection.py b/WFacer/utils/selection.py index ee99b55..a9b4195 100644 --- a/WFacer/utils/selection.py +++ b/WFacer/utils/selection.py @@ -26,6 +26,7 @@ def select_initial_rows( keep_indices(list[int]): optional Indices of structures that must be selected. Usually those of important ground state structures. + Returns: List[int]: indices of selected structures. """ diff --git a/WFacer/utils/sparselm_estimators.py b/WFacer/utils/sparselm_estimators.py index 2b68c94..7718d95 100644 --- a/WFacer/utils/sparselm_estimators.py +++ b/WFacer/utils/sparselm_estimators.py @@ -19,6 +19,7 @@ def is_subclass(classname, parent_classname): Name of the sparselm estimator class. parent_classname(str): Name of the parent class. Also in sparselm.model. + Returns: bool. """ @@ -123,6 +124,7 @@ def prepare_estimator( """Prepare an estimator for the direct call of fit. No weights will be used. + Args: cluster_subspace(ClusterSubspace): A cluster subspace to expand with. @@ -147,6 +149,7 @@ def prepare_estimator( Other keyword arguments to initialize an estimator. optimizer_kwargs(dict): optional Other keyword arguments to initialize an optimizer. + Returns: GridSearchCV/LineSearchCV, StepwiseEstimator, or OrdinaryLeastSquares. diff --git a/WFacer/utils/supercells.py b/WFacer/utils/supercells.py index 781b48a..b0f0124 100644 --- a/WFacer/utils/supercells.py +++ b/WFacer/utils/supercells.py @@ -72,6 +72,7 @@ def is_proper_sc(sc_matrix, lat, max_cond=8, min_angle=30): min_angle(float): optional Minimum allowed angle of the supercell lattice. By default, set to 30, to prevent over-skewing. + Returns: Boolean. """ @@ -99,6 +100,7 @@ def is_duplicate_sc(m1, m2, prim): Supercell matrices to compare. prim(pymatgen.Structure): Primitive cell object. + Returns: bool. """ diff --git a/WFacer/utils/task_document.py b/WFacer/utils/task_document.py index 5a8557d..5a55010 100644 --- a/WFacer/utils/task_document.py +++ b/WFacer/utils/task_document.py @@ -18,6 +18,7 @@ def _merge_computed_structure_entry(entry, structure): A computed Entry given by taskdoc. structure(Structure): A structure given by taskdoc. + Return: ComputedStuctureEntry. """ @@ -51,6 +52,7 @@ def get_entry_from_taskdoc(taskdoc, property_and_queries=None, decorator_names=N The name of decorators used in this CE workflow, used to determine what site properties to retrieve from TaskDoc and to include in the returned entry. + Returns: ComputedStructureEntry, dict: The computed structure entry, with each site having the site