Merge branch 'master' of github.com:materialsproject/custodian

README.md

@@ -1,7 +1,7 @@
-![Custodian logo](docs/assets/custodian_logo.png)
+![Custodian logo](https://raw.githubusercontent.com/materialsproject/custodian/master/docs/assets/custodian_logo.png)
 [![GitHub license](https://img.shields.io/github/license/materialsproject/custodian)](https://github.com/materialsproject/custodian/blob/main/LICENSE)
 [![Linting](https://github.com/materialsproject/custodian/workflows/Linting/badge.svg)](https://github.com/materialsproject/custodian/workflows/Linting/badge.svg)
-[![Testing](https://github.com/materialsproject/custodian/actions/workflows/pytest.yml/badge.svg)](https://github.com/materialsproject/custodian/actions/workflows/pytest.yml)
+[![Testing](https://github.com/materialsproject/custodian/actions/workflows/test.yml/badge.svg)](https://github.com/materialsproject/custodian/actions/workflows/test.yml)
 [![Downloads](https://pepy.tech/badge/custodian)](https://pepy.tech/project/custodian)
 [![codecov](https://codecov.io/gh/materialsproject/custodian/branch/master/graph/badge.svg?token=OwDQVJnghu)](https://codecov.io/gh/materialsproject/custodian)
 
@@ -46,14 +46,10 @@ version is likely to be more buggy, but may contain new features. The Github ver
 complete unit testing. After cloning the source, you can type
 
 ```sh
-python setup.py install
+pip install -e .
 ```
 
-or to install the package in developmental mode::
-
-```sh
-python setup.py develop
-```
+to install the package in editable mode.
 
 # Requirements
 
@@ -70,7 +66,7 @@ custodian.
 If you use custodian in your research, especially the VASP component, please
 consider citing the following work:
 
-```
+```txt
 Shyue Ping Ong, William Davidson Richards, Anubhav Jain, Geoffroy Hautier,
 Michael Kocher, Shreyas Cholia, Dan Gunter, Vincent Chevrier, Kristin A.
 Persson, Gerbrand Ceder. *Python Materials Genomics (pymatgen) : A Robust,

custodian/__init__.py

@@ -4,14 +4,19 @@
 """
 
 import os
+from importlib.metadata import PackageNotFoundError, version
 
 from .custodian import Custodian
 
 __author__ = (
     "Shyue Ping Ong, William Davidson Richards, Stephen Dacek, Xiaohui Qu, Matthew Horton, "
     "Samuel M. Blau, Janosh Riebesell"
 )
-__version__ = "2024.4.18"
+try:
+    __version__ = version("pymatgen")
+except PackageNotFoundError:  # pragma: no cover
+    # package is not installed
+    pass
 
 
 PKG_DIR = os.path.dirname(__file__)

docs/changelog.md

@@ -6,6 +6,9 @@ nav_order: 2
 
 # Change Log
 
+## 2024.6.24
+- Improved handling of ISMEAR for NKPT<4 (@Andrew-S-Rosen, @esoteric-ephemera)
+
 ## 2024.4.18
 - Enable export of environment variables plus lobster run as a command enhancement lobster (@JaGeo)
 - New Gaussian plugin (@rashatwi)

docs/custodian.gaussian.handlers.md

@@ -0,0 +1,120 @@
+---
+layout: default
+title: custodian.gaussian.handlers.md
+nav_exclude: true
+---
+
+# custodian.gaussian.handlers module
+
+This module implements error handlers for Gaussian runs.
+
+### *class* custodian.gaussian.handlers.GaussianErrorHandler(input_file: str, output_file: str, stderr_file: str = 'stderr.txt', cart_coords: bool = True, scf_max_cycles: int = 100, opt_max_cycles: int = 100, job_type: str = 'normal', lower_functional: str | None = None, lower_basis_set: str | None = None, prefix: str = 'error', check_convergence: bool = True)
+
+Bases: `ErrorHandler`
+
+Master GaussianErrorHandler class that handles a number of common errors that occur
+during Gaussian runs.
+
+Initialize the GaussianErrorHandler class.
+
+* **Parameters:**
+  * **input_file** (*str*) – The name of the input file for the Gaussian job.
+  * **output_file** (*str*) – The name of the output file for the Gaussian job.
+  * **stderr_file** (*str*) – The name of the standard error file for the Gaussian job.
+    Defaults to ‘stderr.txt’.
+  * **cart_coords** (*bool*) – Whether the coordinates are in cartesian format.
+    Defaults to True.
+  * **scf_max_cycles** (*int*) – The maximum number of SCF cycles. Defaults to 100.
+  * **opt_max_cycles** (*int*) – The maximum number of optimization cycles. Defaults to
+    100.
+  * **job_type** (*str*) – The type of job to run. Supported options are ‘normal’ and
+    ‘better_guess’. Defaults to ‘normal’. If ‘better_guess’ is chosen, the
+    job will be rerun at a lower level of theory to get a better initial
+    guess of molecular orbitals or geometry, if needed.
+  * **lower_functional** (*str*) – The lower level of theory to use for a better guess.
+  * **lower_basis_set** (*str*) – The lower basis set to use for a better guess.
+  * **prefix** (*str*) – The prefix to use for the backup files. Defaults to error,
+    which means a series of error.1.tar.gz, error.2.tar.gz, … will be
+    generated.
+  * **check_convergence** (*bool*) – Whether to check for convergence during an
+    optimization job. Defaults to True. If True, the convergence data will
+    be monitored and plotted (convergence criteria versus cycle number) and
+    saved to a file called ‘convergence.png’.
+
+#### GRID_NAMES *= ('finegrid', 'fine', 'superfinegrid', 'superfine', 'coarsegrid', 'coarse', 'sg1grid', 'sg1', 'pass0grid', 'pass0')*
+
+#### MEM_UNITS *= ('kb', 'mb', 'gb', 'tb', 'kw', 'mw', 'gw', 'tw')*
+
+#### activate_better_guess *= False*
+
+#### check(directory: str = './')
+
+Check for errors in the Gaussian output file.
+
+#### conv_criteria*: ClassVar* *= {'max_disp': re.compile('\\\\s+(Maximum Displacement)\\\\s+(-?\\\\d+.?\\\\d\*|.\*)\\\\s+(-?\\\\d+.?\\\\d\*)'), 'max_force': re.compile('\\\\s+(Maximum Force)\\\\s+(-?\\\\d+.?\\\\d\*|.\*)\\\\s+(-?\\\\d+.?\\\\d\*)'), 'rms_disp': re.compile('\\\\s+(RMS {5}Displacement)\\\\s+(-?\\\\d+.?\\\\d\*|.\*)\\\\s+(-?\\\\d+.?\\\\d\*)'), 'rms_force': re.compile('\\\\s+(RMS {5}Force)\\\\s+(-?\\\\d+.?\\\\d\*|.\*)\\\\s+(-?\\\\d+.?\\\\d\*)')}*
+
+#### *static* convert_mem(mem: float, unit: str)
+
+Convert memory size between different units to megabytes (MB).
+
+* **Parameters:**
+  * **mem** (*float*) – The memory size to convert.
+  * **unit** (*str*) – The unit of the input memory size. Supported units include
+    ‘kb’, ‘mb’, ‘gb’, ‘tb’, and word units (‘kw’, ‘mw’, ‘gw’, ‘tw’), or an
+    empty string for default conversion (from words).
+* **Returns:**
+  The memory size in MB.
+* **Return type:**
+  float
+
+#### correct(directory: str = './')
+
+Perform necessary actions to correct the errors in the Gaussian output.
+
+#### error_defs*: ClassVar* *= {'A syntax error was detected in the input line.': 'syntax', 'Atom specifications unexpectedly found in input stream.': 'found_coords', 'Bad file opened by FileIO': 'bad_file', 'Convergence failure': 'scf_convergence', 'End of file in ZSymb': 'zmatrix', 'End of file reading connectivity.': 'coords', 'Error in internal coordinate system': 'internal_coords', 'FileIO operation on non-existent file.': 'missing_file', 'FormBX had a problem': 'linear_bend', 'Inv3 failed in PCMMkU': 'solute_solvent_surface', 'Linear angle in Tors.': 'linear_bend', 'No data on chk file.': 'empty_file', 'Optimization stopped': 'opt_steps', 'Out-of-memory error in routine': 'insufficient_mem', 'The combination of multiplicity ([0-9]+) and \\\\s+? ([0-9]+) electrons is impossible.': 'charge', 'There are no atoms in this input structure !': 'missing_mol', 'Z-matrix optimization but no Z-matrix variables.': 'coord_inputs'}*
+
+#### error_patt *= re.compile('Optimization stopped|Convergence failure|FormBX had a problem|Linear angle in Tors.|Inv3 failed in PCMMkU|Error in internal coordinate system|End of file in ZSymb|There are no atoms in this input str)*
+
+#### grid_patt *= re.compile('(-?\\\\d{5})')*
+
+#### recom_mem_patt *= re.compile('Use %mem=([0-9]+)MW to provide the minimum amount of memory required to complete this step.')*
+
+### *class* custodian.gaussian.handlers.WallTimeErrorHandler(wall_time: int, buffer_time: int, input_file: str, output_file: str, stderr_file: str = 'stderr.txt', prefix: str = 'error')
+
+Bases: `ErrorHandler`
+
+Check if a run is nearing the walltime. If so, terminate the job and restart from
+the last .rwf file. A job is considered to be nearing the walltime if the remaining
+time is less than or equal to the buffer time.
+
+Initialize the WalTimeErrorHandler class.
+
+* **Parameters:**
+  * **wall_time** (*int*) – The total wall time for the job in seconds.
+  * **buffer_time** (*int*) – The buffer time in seconds. If the remaining time is less
+    than or equal to the buffer time, the job is considered to be nearing the
+    walltime and will be terminated.
+  * **input_file** (*str*) – The name of the input file for the Gaussian job.
+  * **output_file** (*str*) – The name of the output file for the Gaussian job.
+  * **stderr_file** (*str*) – The name of the standard error file for the Gaussian job.
+    Defaults to ‘stderr.txt’.
+  * **prefix** (*str*) – The prefix to use for the backup files. Defaults to error,
+    which means a series of error.1.tar.gz, error.2.tar.gz, … will be
+    generated.
+
+#### check(directory: str = './')
+
+Check if the job is nearing the walltime. If so, return True, else False.
+
+#### correct(directory: str = './')
+
+Perform the corrections.
+
+#### is_monitor*: bool* *= True*
+
+This class property indicates whether the error handler is a monitor,
+i.e., a handler that monitors a job as it is running. If a
+monitor-type handler notices an error, the job will be sent a
+termination signal, the error is then corrected,
+and then the job is restarted. This is useful for catching errors
+that occur early in the run but do not cause immediate failure.

docs/custodian.gaussian.jobs.md

@@ -0,0 +1,81 @@
+---
+layout: default
+title: custodian.gaussian.jobs.md
+nav_exclude: true
+---
+
+# custodian.gaussian.jobs module
+
+This module implements basic kinds of jobs for Gaussian runs.
+
+### *class* custodian.gaussian.jobs.GaussianJob(gaussian_cmd: str, input_file: str, output_file: str, stderr_file: str = 'stderr.txt', suffix: str = '', backup: bool = True)
+
+Bases: `Job`
+
+A basic Gaussian job.
+
+* **Parameters:**
+  * **gaussian_cmd** (*str*) – Command to run Gaussian.
+  * **input_file** (*str*) – Name of the Gaussian input file.
+  * **output_file** (*str*) – Name of the Gaussian output file.
+  * **stderr_file** (*str*) – Name of the stderr file. Defaults to ‘stderr.txt’.
+  * **suffix** (*str*) – String to append to the input and output files, e.g., to
+    rename Gaussian input and output files from say gaussian.com and
+    gaussian.out, to gaussian.com.guess1 and gaussian.out.guess1,
+    respectively, provide “.guess1” as the suffix. . Defaults to ‘’.
+  * **backup** (*bool*) – Whether to backup the input file. If True, the input will be
+    copied with a “.orig” appended to the name. Defaults to True.
+
+#### *classmethod* generate_better_guess(gaussian_cmd: str, input_file: str, output_file: str, stderr_file: str = 'stderr.txt', backup: bool = True, cart_coords: bool = True, directory: str = './')
+
+Generate a better initial guess for a Gaussian calculation (optimization or
+SCF run). This is done by running the job at a lower level of theory
+(e.g., STO-3G). The geometry for this job is read from the checkpoint file
+generated by the previous job.
+
+* **Parameters:**
+  * **gaussian_cmd** (*str*) – Command to run Gaussian.
+  * **input_file** (*str*) – Name of the Gaussian input file.
+  * **output_file** (*str*) – Name of the Gaussian output file.
+  * **stderr_file** (*str*) – Name of the stderr file. Defaults to ‘stderr.txt’.
+  * **backup** (*bool*) – Whether to backup the input file. If True, the input will be
+    copied with a “.orig” appended to the name. Defaults to True.
+  * **cart_coords** (*bool*) – Whether to use Cartesian coordinates in the input file.
+    Defaults to True.
+  * **directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
+* **Yields:**
+  *GaussianJob* – The Gaussian job instance.
+
+#### postprocess(directory: str = './')
+
+Perform any postprocessing of the Gaussian run. This includes making a copy
+of the input and output file if a suffix is specified.
+
+* **Parameters:**
+  **directory** (*str*) – Directory where the job was run. Defaults to ‘./’.
+
+#### run(directory: str = './')
+
+Perform the actual Gaussian run.
+
+* **Parameters:**
+  **directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
+* **Returns:**
+  The process running the Gaussian job.
+* **Return type:**
+  subprocess.Popen
+
+#### setup(directory: str = './')
+
+Perform initial setup for the job, i.e., make a backup of the input file if
+requested.
+
+* **Parameters:**
+  **directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
+
+#### terminate(directory: str = './')
+
+Terminate the Gaussian job.
+
+* **Parameters:**
+  **directory** (*str*) – Directory where the job was run. Defaults to ‘./’.

docs/custodian.gaussian.md

@@ -0,0 +1,35 @@
+---
+layout: default
+title: custodian.gaussian.md
+nav_exclude: true
+---
+
+# custodian.gaussian package
+
+This package implements various Gaussian Jobs and Error Handlers.
+
+
+* [custodian.gaussian.handlers module](custodian.gaussian.handlers.md)
+  * [`GaussianErrorHandler`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler)
+    * [`GaussianErrorHandler.GRID_NAMES`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.GRID_NAMES)
+    * [`GaussianErrorHandler.MEM_UNITS`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.MEM_UNITS)
+    * [`GaussianErrorHandler.activate_better_guess`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.activate_better_guess)
+    * [`GaussianErrorHandler.check()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.check)
+    * [`GaussianErrorHandler.conv_criteria`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.conv_criteria)
+    * [`GaussianErrorHandler.convert_mem()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.convert_mem)
+    * [`GaussianErrorHandler.correct()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.correct)
+    * [`GaussianErrorHandler.error_defs`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.error_defs)
+    * [`GaussianErrorHandler.error_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.error_patt)
+    * [`GaussianErrorHandler.grid_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.grid_patt)
+    * [`GaussianErrorHandler.recom_mem_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.recom_mem_patt)
+  * [`WallTimeErrorHandler`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler)
+    * [`WallTimeErrorHandler.check()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.check)
+    * [`WallTimeErrorHandler.correct()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.correct)
+    * [`WallTimeErrorHandler.is_monitor`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.is_monitor)
+* [custodian.gaussian.jobs module](custodian.gaussian.jobs.md)
+  * [`GaussianJob`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob)
+    * [`GaussianJob.generate_better_guess()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.generate_better_guess)
+    * [`GaussianJob.postprocess()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.postprocess)
+    * [`GaussianJob.run()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.run)
+    * [`GaussianJob.setup()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.setup)
+    * [`GaussianJob.terminate()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.terminate)