Update dev docs

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)

docs/custodian.vasp.utils.md

@@ -0,0 +1,36 @@
+---
+layout: default
+title: custodian.vasp.utils.md
+nav_exclude: true
+---
+
+# custodian.vasp.utils module
+
+Utility methods for VASP error handlers.
+
+### custodian.vasp.utils.increase_k_point_density(kpoints: Kpoints | dict | float, structure: Structure, factor: float = 0.1, max_inc: int = 500, min_kpoints: int = 1, force_gamma: bool = True)
+
+Inputs:
+: kpoints (Kpoints, dict, float, int) :
+  : If a dict or Kpoints object: original Kpoints used in the calculation
+    If a float: the original KSPACING used in the calculation
+  <br/>
+  structure (Structure) : associated structure
+  factor (float) : factor used to increase k-point density.
+  <br/>
+  > The first increase uses approximately (1 + factor) higher k-point density.
+  > The second increase: ~ (1 + 2\*factor) higher k-kpoint density, etc.
+  max_inc (int)
+  : before giving up
+  <br/>
+  min_kpoints (int): The minimum permitted number of k-points.
+  : Can be useful if using the tetrahedron method, where
+    at least 4 k-points are needed.
+  <br/>
+  force_gamma (bool) = True: whether to use Gamma-centered or
+  : Monkhorst-Pack grids
+
+Outputs:
+: dict :
+  : The new Kpoints object / KSPACING consistent with constraints.
+    If an empty dict, no new k-point mesh could be found.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "custodian"
-version = "2024.4.18"
+version = "2024.6.24"
 description = "A simple JIT job management framework in Python."
 authors = [
   { name = "Janosh Riebesell", email = "janosh.riebesell@gmail.com" },