From 8c012e6c8a6cd821584ebec28a38fc9169b5f58d Mon Sep 17 00:00:00 2001 From: Shyue Ping Ong Date: Mon, 24 Jun 2024 14:07:08 -0700 Subject: [PATCH] Update dev docs --- docs/custodian.gaussian.handlers.md | 120 ++++++++++++++++++++++++++++ docs/custodian.gaussian.jobs.md | 81 +++++++++++++++++++ docs/custodian.gaussian.md | 35 ++++++++ docs/custodian.vasp.utils.md | 36 +++++++++ pyproject.toml | 2 +- 5 files changed, 273 insertions(+), 1 deletion(-) create mode 100644 docs/custodian.gaussian.handlers.md create mode 100644 docs/custodian.gaussian.jobs.md create mode 100644 docs/custodian.gaussian.md create mode 100644 docs/custodian.vasp.utils.md diff --git a/docs/custodian.gaussian.handlers.md b/docs/custodian.gaussian.handlers.md new file mode 100644 index 00000000..f1f6ad68 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/custodian.gaussian.jobs.md b/docs/custodian.gaussian.jobs.md new file mode 100644 index 00000000..c6fc4fe8 --- /dev/null +++ b/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 ‘./’. \ No newline at end of file diff --git a/docs/custodian.gaussian.md b/docs/custodian.gaussian.md new file mode 100644 index 00000000..cc867c56 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/docs/custodian.vasp.utils.md b/docs/custodian.vasp.utils.md new file mode 100644 index 00000000..c0182c69 --- /dev/null +++ b/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 +
+ structure (Structure) : associated structure + factor (float) : factor used to increase k-point density. +
+ > 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 +
+ 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. +
+ 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. \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index e7caa4b8..5223f312 100644 --- a/pyproject.toml +++ b/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" },