From 7d3e43b822ac3baeb136d5c020efc5c6fcd7704f Mon Sep 17 00:00:00 2001 From: utf Date: Thu, 18 Jul 2024 16:02:09 +0100 Subject: [PATCH] Fix docs --- docs/about/license.md | 4 +- docs/conf.py | 7 +- docs/index.md | 2 + docs/user/install.md | 2 +- src/atomate2/amset/schemas.py | 5 +- src/atomate2/common/flows/defect.py | 50 +++++----- src/atomate2/common/jobs/eos.py | 118 ++++++++++++++--------- src/atomate2/common/schemas/magnetism.py | 10 +- src/atomate2/lobster/schemas.py | 4 +- src/atomate2/vasp/flows/defect.py | 63 ++++++------ src/atomate2/vasp/jobs/eos.py | 24 ++--- src/atomate2/vasp/run.py | 8 +- 12 files changed, 163 insertions(+), 134 deletions(-) diff --git a/docs/about/license.md b/docs/about/license.md index e302813d6d..4efbf3c1f9 100644 --- a/docs/about/license.md +++ b/docs/about/license.md @@ -1,5 +1,4 @@ -License -======= +# License `atomate2` is developed under a modified BSD license, reproduced below: @@ -51,3 +50,4 @@ modify, prepare derivative works, incorporate into other computer software, distribute, and sublicense such enhancements or derivative works thereof, in binary and source code form. ``` + diff --git a/docs/conf.py b/docs/conf.py index 24df470d11..aa2fee5d44 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -72,7 +72,7 @@ napoleon_use_ivar = True # The suffix(es) of source filenames. -source_suffix = [".rst", ".md"] +source_suffix = {'.rst': 'restructuredtext', '.md': 'restructuredtext'} mathjax3_config = { "tex": { @@ -92,10 +92,10 @@ """ } language = "en" -html_extra_path = ["images/badge.svg"] +#html_extra_path = ["images/badge.svg"] html_static_path = ["_static"] html_css_files = ["custom.css", "github.css"] -suppress_warnings = "etoc.toctree" +suppress_warnings = ["etoc.toctree"] # autodoc options autosummary_imported_members = False @@ -172,6 +172,5 @@ "python": ("https://docs.python.org/3.8", None), "matplotlib": ("https://matplotlib.org/stable/", None), "networkx": ("https://networkx.org/documentation/stable/", None), - "monty": ("https://materialsvirtuallab.github.io/monty/", None), "jobflow": ("https://materialsproject.github.io/jobflow", None), } diff --git a/docs/index.md b/docs/index.md index 646fad8693..32f20ccbb8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,6 +5,7 @@ user/index user/install user/running-workflows user/fireworks +user/atomate-1-vs-2 user/codes/index ``` @@ -20,6 +21,7 @@ reference/index dev/dev_install dev/workflow_tutorial dev/vasp_tests +dev/abinit_tests ``` ```{toctree} diff --git a/docs/user/install.md b/docs/user/install.md index 781dd2d9fd..9a209fcac3 100644 --- a/docs/user/install.md +++ b/docs/user/install.md @@ -296,7 +296,7 @@ This is the command that you would use to run VASP with parallelization The directory structure of `<>/config` should now look like -```txt +``` config ├── jobflow.yaml └── atomate2.yaml diff --git a/src/atomate2/amset/schemas.py b/src/atomate2/amset/schemas.py index 005cf7278d..7116614f9a 100644 --- a/src/atomate2/amset/schemas.py +++ b/src/atomate2/amset/schemas.py @@ -23,9 +23,6 @@ amset = None -if TYPE_CHECKING: - from typing_extensions import Self - logger = logging.getLogger(__name__) @@ -147,7 +144,7 @@ def from_directory( dir_name: Union[Path, str], additional_fields: dict[str, Any] = None, include_mesh: bool = False, - ) -> Self: + ): """Create a task document from a directory containing VASP files. Parameters diff --git a/src/atomate2/common/flows/defect.py b/src/atomate2/common/flows/defect.py index 1c34f0e0c5..dc2fd34575 100644 --- a/src/atomate2/common/flows/defect.py +++ b/src/atomate2/common/flows/defect.py @@ -182,6 +182,7 @@ class FormationEnergyMaker(Maker, ABC): lattice relaxation, you should manually set the grid size. .. code-block:: python + relax_set = MPRelaxSet(defect.get_supercell_structure()) ng, ngf = relax_set.calculate_ng() params = ["NGX", "NGY", "NGZ", "NGXF", "NGYF", "NGZF"] @@ -217,32 +218,35 @@ class FormationEnergyMaker(Maker, ABC): energy diagrams. .. note:: - Once we remove the requirement for explicit bulk supercell calculations, - this setting will be removed. It is only needed because the bulk supercell - locpot is currently needed for the finite-size correction calculation. + Once we remove the requirement for explicit bulk supercell calculations, + this setting will be removed. It is only needed because the bulk supercell + locpot is currently needed for the finite-size correction calculation. Output format for the DefectEntry data: + .. code-block:: python - [ - { - 'bulk_dir_name': 'computer1:/folder1', - 'bulk_locpot': {...}, - 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', - 'defect_dir_name': 'computer1:/folder2', - 'defect_entry': {...}, - 'defect_locpot': {...}, - 'defect_uuid': 'e9af2725-d63c-49b8-a01f-391540211750' - }, - { - 'bulk_dir_name': 'computer1:/folder3', - 'bulk_locpot': {...}, - 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', - 'defect_dir_name': 'computer1:/folder4', - 'defect_entry': {...}, - 'defect_locpot': {...}, - 'defect_uuid': 'a1c31095-0494-4eed-9862-95311f80a993' - } - ] + + [ + { + 'bulk_dir_name': 'computer1:/folder1', + 'bulk_locpot': {...}, + 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', + 'defect_dir_name': 'computer1:/folder2', + 'defect_entry': {...}, + 'defect_locpot': {...}, + 'defect_uuid': 'e9af2725-d63c-49b8-a01f-391540211750' + }, + { + 'bulk_dir_name': 'computer1:/folder3', + 'bulk_locpot': {...}, + 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', + 'defect_dir_name': 'computer1:/folder4', + 'defect_entry': {...}, + 'defect_locpot': {...}, + 'defect_uuid': 'a1c31095-0494-4eed-9862-95311f80a993' + } + ] + """ defect_relax_maker: Maker diff --git a/src/atomate2/common/jobs/eos.py b/src/atomate2/common/jobs/eos.py index 7c5886cbc6..7beee75eda 100644 --- a/src/atomate2/common/jobs/eos.py +++ b/src/atomate2/common/jobs/eos.py @@ -26,6 +26,8 @@ class EOSPostProcessor(MSONable): """ Fit data to an EOS. + Parameters + ---------- name : str Name of the class eos_attrs : tuple[str,...] @@ -72,16 +74,19 @@ def fit(self, eos_flow_output: dict[str, Any]) -> None: Parameters ---------- eos_flow_output : dict - Volume, energy, and (optionally) stress and pressure data in dict form, - { - "relax" and "static" : { - "energy": list, - "volume": list, - "stress": list - }, - "initial_": {"E0": float, "V0": float} , - for in ("relax", "static") - } + Volume, energy, and (optionally) stress and pressure data in dict + form:: + + { + "relax" and "static" : { + "energy": list, + "volume": list, + "stress": list + }, + "initial_": {"E0": float, "V0": float} , + for in ("relax", "static") + } + """ self.results.update(eos_flow_output) self._use_job_types = [key for key in self.job_types if self.results.get(key)] @@ -103,16 +108,19 @@ def make(self, eos_flow_output: dict[str, Any]) -> Job: Parameters ---------- eos_flow_output : dict - Volume, energy, and (optionally) stress and pressure data in dict form, - { - "relax" and "static" : { - "energy": list, - "volume": list, - "stress": list - }, - "initial_": {"E0": float, "V0": float} , - for in ("relax", "static") - } + Volume, energy, and (optionally) stress and pressure data in dict + form:: + + { + "relax" and "static" : { + "energy": list, + "volume": list, + "stress": list + }, + "initial_": {"E0": float, "V0": float} , + for in ("relax", "static") + } + """ self.fit(eos_flow_output) return self.results @@ -125,16 +133,19 @@ class PostProcessEosEnergy(EOSPostProcessor): Parameters ---------- eos_flow_output : dict - Volume, energy, and (optionally) stress and pressure data in dict form, - { - "relax" and "static" : { - "energy": list, - "volume": list, - "stress": list - }, - "initial_": {"E0": float, "V0": float} , - for in ("relax", "static") - } + Volume, energy, and (optionally) stress and pressure data in dict + form:: + + { + "relax" and "static" : { + "energy": list, + "volume": list, + "stress": list + }, + "initial_": {"E0": float, "V0": float} , + for in ("relax", "static") + } + name : str Name of the class eos_attrs : tuple[str,...] @@ -158,7 +169,7 @@ class PostProcessEosEnergy(EOSPostProcessor): ) def eval(self) -> None: - """Fit the input data to each EOS in `self.eos_models.""" + """Fit the input data to each EOS in ``self.eos_models``.""" for jobtype in self._use_job_types: self.results[jobtype]["EOS"] = {} for eos_name in self.eos_models: @@ -181,16 +192,19 @@ class PostProcessEosPressure(EOSPostProcessor): Parameters ---------- eos_flow_output : dict - Volume, energy, and (optionally) stress and pressure data in dict form, - { - "relax" and "static" : { - "energy": list, - "volume": list, - "stress": list - }, - "initial_": {"E0": float, "V0": float} , - for in ("relax", "static") - } + Volume, energy, and (optionally) stress and pressure data in dict + form:: + + { + "relax" and "static" : { + "energy": list, + "volume": list, + "stress": list + }, + "initial_": {"E0": float, "V0": float} , + for in ("relax", "static") + } + name : str Name of the class eos_attrs : tuple[str,...] @@ -201,8 +215,10 @@ class PostProcessEosPressure(EOSPostProcessor): Minimum number of data points needed to perform a fit. If only stresses are specified, it is assumed that the elements of "stress" - are 3 x 3 tensors, and the pressure is computed as + are 3 x 3 tensors, and the pressure is computed as:: + pressure = Trace(stress tensor)/3 + The overall sign is irrelevant for a successful fit, as the overall sign of the pressure indicates internal/external stress. """ @@ -232,14 +248,18 @@ def _birch_murnaghan_pressure( ------- float : the BM pressure - BM EOS for E(V) has the form + BM EOS for E(V) has the form:: + E(V) = E0 + 9 B0 V0 / 16 * ( (B1 - 4)*eta**6 + (14 - 3*B1)*eta**4 + (3*B1 - 16)*eta**2 + 6 - B1 ) eta = (V0/V)**(1/3). - This function computes p = - dE / dV via the chain rule, + + This function computes p = - dE / dV via the chain rule,:: + p = d E / d eta * (- d eta / dV) = eta**4/(3*V0) * d E / d eta + """ eta = (v0 / volume) ** (1.0 / 3.0) return ( @@ -253,7 +273,8 @@ def _birch_murnaghan_pressure( def _initial_fit(self) -> dict: """Generate initial polynomial fit for p(V) curve. - p(V) / V = a + b V + c V**2 + :: + p(V) / V = a + b V + c V**2 """ init_pars = {} for jobtype in self._use_job_types: @@ -337,9 +358,12 @@ def apply_strain_to_structure(structure: Structure, deformations: list) -> list: deformations: list[.Deformation] A list of deformations to apply **independently** to the input structure, in anticipation of performing an EOS fit. - Deformations should be of the form of a 3x3 matrix, e.g., + Deformations should be of the form of a 3x3 matrix, e.g.,:: + [[1.2, 0., 0.], [0., 1.2, 0.], [0., 0., 1.2]] - or + + or:: + ((1.2, 0., 0.), (0., 1.2, 0.), (0., 0., 1.2)) Returns diff --git a/src/atomate2/common/schemas/magnetism.py b/src/atomate2/common/schemas/magnetism.py index c63db089ea..5a313a247b 100644 --- a/src/atomate2/common/schemas/magnetism.py +++ b/src/atomate2/common/schemas/magnetism.py @@ -350,10 +350,12 @@ def from_outputs( def from_tasks(cls, tasks: list[dict]) -> MagneticOrderingsDocument: """Construct a MagneticOrderingsDocument from a list of task dicts. - .. Note:: this function assumes the tasks contain the keys "output" and - "metadata". These keys are automatically constructed when jobflow stores its - outputs; however, you may need to put the data in this format if using this - manually (as in a postprocessing job). + .. Note:: + + this function assumes the tasks contain the keys "output" and "metadata". + These keys are automatically constructed when jobflow stores its outputs; + however, you may need to put the data in this format if using this + manually (as in a postprocessing job). """ parent_structure = tasks[0]["metadata"]["parent_structure"] diff --git a/src/atomate2/lobster/schemas.py b/src/atomate2/lobster/schemas.py index 573e4506c5..293d2cfe15 100644 --- a/src/atomate2/lobster/schemas.py +++ b/src/atomate2/lobster/schemas.py @@ -729,7 +729,7 @@ class LobsterTaskDocument(StructureMetadata, extra="allow"): # type: ignore[cal @classmethod @requires( Analysis, - "LobsterTaskDocument requires `lobsterpy` and `ijson` to function properly. " + "LobsterTaskDocument requires lobsterpy and ijson to function properly. " "Please reinstall atomate2 using atomate2[lobster]", ) def from_directory( @@ -1320,7 +1320,7 @@ def read_saved_json( filename: str, pymatgen_objs: bool = True, query: str = "structure" ) -> dict[str, Any]: """ - Read the data from *.json.gz file corresponding to query. + Read the data from \*.json.gz files corresponding to query. Uses ijson to parse specific keys(memory efficient) diff --git a/src/atomate2/vasp/flows/defect.py b/src/atomate2/vasp/flows/defect.py index 55c58afb7c..fbc40861be 100644 --- a/src/atomate2/vasp/flows/defect.py +++ b/src/atomate2/vasp/flows/defect.py @@ -74,10 +74,11 @@ class FormationEnergyMaker(defect_flows.FormationEnergyMaker): this maker is the `relax_maker` which contains the settings for the atomic relaxations that each defect supercell will undergo. The `relax_maker` uses a `ChargeStateRelaxSetGenerator` by default but more complex makers - like the `HSE_DOUBLE_RELAX` can be used for more accurate (but expensive) + like the ``HSE_DOUBLE_RELAX`` can be used for more accurate (but expensive) calculations. - If the `validate_maker` is set to True, the maker will check for some basic - settings in the `relax_maker` to make sure the calculations are done correctly. + + If the ``validate_maker`` is set to True, the maker will check for some basic + settings in the ``relax_maker`` to make sure the calculations are done correctly. Attributes ---------- @@ -86,10 +87,10 @@ class FormationEnergyMaker(defect_flows.FormationEnergyMaker): states. Since these calculations are expensive and the settings might get messy, it is recommended for each implementation of this maker to check some of the most important settings in the `relax_maker`. Please see - `FormationEnergyMaker.validate_maker` for more details. + ``FormationEnergyMaker.validate_maker`` for more details. bulk_relax_maker: Maker - If None, the same `defect_relax_maker` will be used for the bulk supercell. + If None, the same ``defect_relax_maker`` will be used for the bulk supercell. A maker to used to perform the bulk supercell calculation. For marginally converged calculations, it might be desirable to perform an additional lattice relaxation on the bulk supercell to make sure the energies are more @@ -100,6 +101,7 @@ class FormationEnergyMaker(defect_flows.FormationEnergyMaker): lattice relaxation, you should manually set the grid size. .. code-block:: python + relax_set = MPRelaxSet(defect.get_supercell_structure()) ng, ngf = relax_set.calculate_ng() params = ["NGX", "NGY", "NGZ", "NGXF", "NGYF", "NGZF"] @@ -128,32 +130,37 @@ class FormationEnergyMaker(defect_flows.FormationEnergyMaker): energy diagrams. .. note:: - Once we remove the requirement for explicit bulk supercell calculations, - this setting will be removed. It is only needed because the bulk supercell - locpot is currently needed for the finite-size correction calculation. + + Once we remove the requirement for explicit bulk supercell + calculations, this setting will be removed. It is only needed because + the bulk supercell locpot is currently needed for the finite-size + correction calculation. Output format for the DefectEntry data: + .. code-block:: python - [ - { - 'bulk_dir_name': 'computer1:/folder1', - 'bulk_locpot': {...}, - 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', - 'defect_dir_name': 'computer1:/folder2', - 'defect_entry': {...}, - 'defect_locpot': {...}, - 'defect_uuid': 'e9af2725-d63c-49b8-a01f-391540211750' - }, - { - 'bulk_dir_name': 'computer1:/folder3', - 'bulk_locpot': {...}, - 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', - 'defect_dir_name': 'computer1:/folder4', - 'defect_entry': {...}, - 'defect_locpot': {...}, - 'defect_uuid': 'a1c31095-0494-4eed-9862-95311f80a993' - } - ] + + [ + { + 'bulk_dir_name': 'computer1:/folder1', + 'bulk_locpot': {...}, + 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', + 'defect_dir_name': 'computer1:/folder2', + 'defect_entry': {...}, + 'defect_locpot': {...}, + 'defect_uuid': 'e9af2725-d63c-49b8-a01f-391540211750' + }, + { + 'bulk_dir_name': 'computer1:/folder3', + 'bulk_locpot': {...}, + 'bulk_uuid': '48fb6da7-dc2b-4dcb-b1c8-1203c0f72ce3', + 'defect_dir_name': 'computer1:/folder4', + 'defect_entry': {...}, + 'defect_locpot': {...}, + 'defect_uuid': 'a1c31095-0494-4eed-9862-95311f80a993' + } + ] + """ defect_relax_maker: BaseVaspMaker = field( diff --git a/src/atomate2/vasp/jobs/eos.py b/src/atomate2/vasp/jobs/eos.py index ab2ea6b828..fecbf10618 100644 --- a/src/atomate2/vasp/jobs/eos.py +++ b/src/atomate2/vasp/jobs/eos.py @@ -2,25 +2,25 @@ Module to define EOS jobs using the default atomate2 parameters. Some jobs have prefixes to indicate their purpose: -- MPLegacy: for consistency with the atomate 1 implementation, or -[LDMWP] K. Latimer, S. Dwaraknath, K. Mathew, D. Winston, and K.A. Persson, -npj Comput. Materials 4, 40 (2018), -DOI: 10.1038/s41524-018-0091-x + +* MPLegacy: for consistency with the atomate 1 implementation, or + [LDMWP] K. Latimer, S. Dwaraknath, K. Mathew, D. Winston, and K.A. Persson, + npj Comput. Materials 4, 40 (2018), + DOI: 10.1038/s41524-018-0091-x Also see the original atomate workflows -- atomate.vasp.workflows.base.wf_bulk_modulus: -https://github.com/hackingmaterials/atomate/blob/main/atomate/vasp/workflows/presets/core.py#L564 -- atomate.vasp.workflows.base.bulk_modulus.get_wf_bulk_modulus: -https://github.com/hackingmaterials/atomate/blob/main/atomate/vasp/workflows/base/bulk_modulus.py#L21 +* atomate.vasp.workflows.base.wf_bulk_modulus: + https://github.com/hackingmaterials/atomate/blob/main/atomate/vasp/workflows/presets/core.py#L564 +* atomate.vasp.workflows.base.bulk_modulus.get_wf_bulk_modulus: + https://github.com/hackingmaterials/atomate/blob/main/atomate/vasp/workflows/base/bulk_modulus.py#L21 These WFs are interesting that the k-point density is **extremely** high despite the convergence tests in the SI of the Latimer et al. paper not -showing strong sensitivity when - "number of k-points per reciprocal atom" >= 3,000 +showing strong sensitivity when "number of k-points per reciprocal atom" >= 3,000 -- MPGGA: MP-compatible PBE-GGA jobs -- MPMetaGGA: MP-compatible r2SCAN meta-GGA jobs +* MPGGA: MP-compatible PBE-GGA jobs +* MPMetaGGA: MP-compatible r2SCAN meta-GGA jobs MPGGA and MPMetaGGA jobs use the highest k-point density in standard MP jobs, KSPACING = 0.22, which is comparable to diff --git a/src/atomate2/vasp/run.py b/src/atomate2/vasp/run.py index 23741a960f..0bb9370271 100644 --- a/src/atomate2/vasp/run.py +++ b/src/atomate2/vasp/run.py @@ -1,10 +1,4 @@ -""" -Functions to run VASP. - -Todo ----- -- Implement vasp_ncl and auto_ncl in custodian. -""" +"""Functions to run VASP.""" from __future__ import annotations