Skip to content

Commit 8c012e6

Browse files
shyuepshyuep
committed
Update dev docs
1 parent 3e1c605 commit 8c012e6

File tree

5 files changed

+273
-1
lines changed

5 files changed

+273
-1
lines changed

‎docs/custodian.gaussian.handlers.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
---
2+
layout: default
3+
title: custodian.gaussian.handlers.md
4+
nav_exclude: true
5+
---
6+
7+
# custodian.gaussian.handlers module
8+
9+
This module implements error handlers for Gaussian runs.
10+
11+
### *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)
12+
13+
Bases: `ErrorHandler`
14+
15+
Master GaussianErrorHandler class that handles a number of common errors that occur
16+
during Gaussian runs.
17+
18+
Initialize the GaussianErrorHandler class.
19+
20+
* **Parameters:**
21+
* **input_file** (*str*) – The name of the input file for the Gaussian job.
22+
* **output_file** (*str*) – The name of the output file for the Gaussian job.
23+
* **stderr_file** (*str*) – The name of the standard error file for the Gaussian job.
24+
Defaults to ‘stderr.txt’.
25+
* **cart_coords** (*bool*) – Whether the coordinates are in cartesian format.
26+
Defaults to True.
27+
* **scf_max_cycles** (*int*) – The maximum number of SCF cycles. Defaults to 100.
28+
* **opt_max_cycles** (*int*) – The maximum number of optimization cycles. Defaults to
29+
100.
30+
* **job_type** (*str*) – The type of job to run. Supported options are ‘normal’ and
31+
‘better_guess’. Defaults to ‘normal’. If ‘better_guess’ is chosen, the
32+
job will be rerun at a lower level of theory to get a better initial
33+
guess of molecular orbitals or geometry, if needed.
34+
* **lower_functional** (*str*) – The lower level of theory to use for a better guess.
35+
* **lower_basis_set** (*str*) – The lower basis set to use for a better guess.
36+
* **prefix** (*str*) – The prefix to use for the backup files. Defaults to error,
37+
which means a series of error.1.tar.gz, error.2.tar.gz, … will be
38+
generated.
39+
* **check_convergence** (*bool*) – Whether to check for convergence during an
40+
optimization job. Defaults to True. If True, the convergence data will
41+
be monitored and plotted (convergence criteria versus cycle number) and
42+
saved to a file called ‘convergence.png’.
43+
44+
#### GRID_NAMES *= ('finegrid', 'fine', 'superfinegrid', 'superfine', 'coarsegrid', 'coarse', 'sg1grid', 'sg1', 'pass0grid', 'pass0')*
45+
46+
#### MEM_UNITS *= ('kb', 'mb', 'gb', 'tb', 'kw', 'mw', 'gw', 'tw')*
47+
48+
#### activate_better_guess *= False*
49+
50+
#### check(directory: str = './')
51+
52+
Check for errors in the Gaussian output file.
53+
54+
#### 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\*)')}*
55+
56+
#### *static* convert_mem(mem: float, unit: str)
57+
58+
Convert memory size between different units to megabytes (MB).
59+
60+
* **Parameters:**
61+
* **mem** (*float*) – The memory size to convert.
62+
* **unit** (*str*) – The unit of the input memory size. Supported units include
63+
‘kb’, ‘mb’, ‘gb’, ‘tb’, and word units (‘kw’, ‘mw’, ‘gw’, ‘tw’), or an
64+
empty string for default conversion (from words).
65+
* **Returns:**
66+
The memory size in MB.
67+
* **Return type:**
68+
float
69+
70+
#### correct(directory: str = './')
71+
72+
Perform necessary actions to correct the errors in the Gaussian output.
73+
74+
#### 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'}*
75+
76+
#### 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)*
77+
78+
#### grid_patt *= re.compile('(-?\\\\d{5})')*
79+
80+
#### recom_mem_patt *= re.compile('Use %mem=([0-9]+)MW to provide the minimum amount of memory required to complete this step.')*
81+
82+
### *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')
83+
84+
Bases: `ErrorHandler`
85+
86+
Check if a run is nearing the walltime. If so, terminate the job and restart from
87+
the last .rwf file. A job is considered to be nearing the walltime if the remaining
88+
time is less than or equal to the buffer time.
89+
90+
Initialize the WalTimeErrorHandler class.
91+
92+
* **Parameters:**
93+
* **wall_time** (*int*) – The total wall time for the job in seconds.
94+
* **buffer_time** (*int*) – The buffer time in seconds. If the remaining time is less
95+
than or equal to the buffer time, the job is considered to be nearing the
96+
walltime and will be terminated.
97+
* **input_file** (*str*) – The name of the input file for the Gaussian job.
98+
* **output_file** (*str*) – The name of the output file for the Gaussian job.
99+
* **stderr_file** (*str*) – The name of the standard error file for the Gaussian job.
100+
Defaults to ‘stderr.txt’.
101+
* **prefix** (*str*) – The prefix to use for the backup files. Defaults to error,
102+
which means a series of error.1.tar.gz, error.2.tar.gz, … will be
103+
generated.
104+
105+
#### check(directory: str = './')
106+
107+
Check if the job is nearing the walltime. If so, return True, else False.
108+
109+
#### correct(directory: str = './')
110+
111+
Perform the corrections.
112+
113+
#### is_monitor*: bool* *= True*
114+
115+
This class property indicates whether the error handler is a monitor,
116+
i.e., a handler that monitors a job as it is running. If a
117+
monitor-type handler notices an error, the job will be sent a
118+
termination signal, the error is then corrected,
119+
and then the job is restarted. This is useful for catching errors
120+
that occur early in the run but do not cause immediate failure.

‎docs/custodian.gaussian.jobs.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
---
2+
layout: default
3+
title: custodian.gaussian.jobs.md
4+
nav_exclude: true
5+
---
6+
7+
# custodian.gaussian.jobs module
8+
9+
This module implements basic kinds of jobs for Gaussian runs.
10+
11+
### *class* custodian.gaussian.jobs.GaussianJob(gaussian_cmd: str, input_file: str, output_file: str, stderr_file: str = 'stderr.txt', suffix: str = '', backup: bool = True)
12+
13+
Bases: `Job`
14+
15+
A basic Gaussian job.
16+
17+
* **Parameters:**
18+
* **gaussian_cmd** (*str*) – Command to run Gaussian.
19+
* **input_file** (*str*) – Name of the Gaussian input file.
20+
* **output_file** (*str*) – Name of the Gaussian output file.
21+
* **stderr_file** (*str*) – Name of the stderr file. Defaults to ‘stderr.txt’.
22+
* **suffix** (*str*) – String to append to the input and output files, e.g., to
23+
rename Gaussian input and output files from say gaussian.com and
24+
gaussian.out, to gaussian.com.guess1 and gaussian.out.guess1,
25+
respectively, provide “.guess1” as the suffix. . Defaults to ‘’.
26+
* **backup** (*bool*) – Whether to backup the input file. If True, the input will be
27+
copied with a “.orig” appended to the name. Defaults to True.
28+
29+
#### *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 = './')
30+
31+
Generate a better initial guess for a Gaussian calculation (optimization or
32+
SCF run). This is done by running the job at a lower level of theory
33+
(e.g., STO-3G). The geometry for this job is read from the checkpoint file
34+
generated by the previous job.
35+
36+
* **Parameters:**
37+
* **gaussian_cmd** (*str*) – Command to run Gaussian.
38+
* **input_file** (*str*) – Name of the Gaussian input file.
39+
* **output_file** (*str*) – Name of the Gaussian output file.
40+
* **stderr_file** (*str*) – Name of the stderr file. Defaults to ‘stderr.txt’.
41+
* **backup** (*bool*) – Whether to backup the input file. If True, the input will be
42+
copied with a “.orig” appended to the name. Defaults to True.
43+
* **cart_coords** (*bool*) – Whether to use Cartesian coordinates in the input file.
44+
Defaults to True.
45+
* **directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
46+
* **Yields:**
47+
*GaussianJob* – The Gaussian job instance.
48+
49+
#### postprocess(directory: str = './')
50+
51+
Perform any postprocessing of the Gaussian run. This includes making a copy
52+
of the input and output file if a suffix is specified.
53+
54+
* **Parameters:**
55+
**directory** (*str*) – Directory where the job was run. Defaults to ‘./’.
56+
57+
#### run(directory: str = './')
58+
59+
Perform the actual Gaussian run.
60+
61+
* **Parameters:**
62+
**directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
63+
* **Returns:**
64+
The process running the Gaussian job.
65+
* **Return type:**
66+
subprocess.Popen
67+
68+
#### setup(directory: str = './')
69+
70+
Perform initial setup for the job, i.e., make a backup of the input file if
71+
requested.
72+
73+
* **Parameters:**
74+
**directory** (*str*) – Directory where the job will be run. Defaults to ‘./’.
75+
76+
#### terminate(directory: str = './')
77+
78+
Terminate the Gaussian job.
79+
80+
* **Parameters:**
81+
**directory** (*str*) – Directory where the job was run. Defaults to ‘./’.

‎docs/custodian.gaussian.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
---
2+
layout: default
3+
title: custodian.gaussian.md
4+
nav_exclude: true
5+
---
6+
7+
# custodian.gaussian package
8+
9+
This package implements various Gaussian Jobs and Error Handlers.
10+
11+
12+
* [custodian.gaussian.handlers module](custodian.gaussian.handlers.md)
13+
* [`GaussianErrorHandler`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler)
14+
* [`GaussianErrorHandler.GRID_NAMES`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.GRID_NAMES)
15+
* [`GaussianErrorHandler.MEM_UNITS`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.MEM_UNITS)
16+
* [`GaussianErrorHandler.activate_better_guess`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.activate_better_guess)
17+
* [`GaussianErrorHandler.check()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.check)
18+
* [`GaussianErrorHandler.conv_criteria`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.conv_criteria)
19+
* [`GaussianErrorHandler.convert_mem()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.convert_mem)
20+
* [`GaussianErrorHandler.correct()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.correct)
21+
* [`GaussianErrorHandler.error_defs`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.error_defs)
22+
* [`GaussianErrorHandler.error_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.error_patt)
23+
* [`GaussianErrorHandler.grid_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.grid_patt)
24+
* [`GaussianErrorHandler.recom_mem_patt`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.GaussianErrorHandler.recom_mem_patt)
25+
* [`WallTimeErrorHandler`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler)
26+
* [`WallTimeErrorHandler.check()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.check)
27+
* [`WallTimeErrorHandler.correct()`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.correct)
28+
* [`WallTimeErrorHandler.is_monitor`](custodian.gaussian.handlers.md#custodian.gaussian.handlers.WallTimeErrorHandler.is_monitor)
29+
* [custodian.gaussian.jobs module](custodian.gaussian.jobs.md)
30+
* [`GaussianJob`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob)
31+
* [`GaussianJob.generate_better_guess()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.generate_better_guess)
32+
* [`GaussianJob.postprocess()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.postprocess)
33+
* [`GaussianJob.run()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.run)
34+
* [`GaussianJob.setup()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.setup)
35+
* [`GaussianJob.terminate()`](custodian.gaussian.jobs.md#custodian.gaussian.jobs.GaussianJob.terminate)

‎docs/custodian.vasp.utils.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
layout: default
3+
title: custodian.vasp.utils.md
4+
nav_exclude: true
5+
---
6+
7+
# custodian.vasp.utils module
8+
9+
Utility methods for VASP error handlers.
10+
11+
### 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)
12+
13+
Inputs:
14+
: kpoints (Kpoints, dict, float, int) :
15+
: If a dict or Kpoints object: original Kpoints used in the calculation
16+
If a float: the original KSPACING used in the calculation
17+
<br/>
18+
structure (Structure) : associated structure
19+
factor (float) : factor used to increase k-point density.
20+
<br/>
21+
> The first increase uses approximately (1 + factor) higher k-point density.
22+
> The second increase: ~ (1 + 2\*factor) higher k-kpoint density, etc.
23+
max_inc (int)
24+
: before giving up
25+
<br/>
26+
min_kpoints (int): The minimum permitted number of k-points.
27+
: Can be useful if using the tetrahedron method, where
28+
at least 4 k-points are needed.
29+
<br/>
30+
force_gamma (bool) = True: whether to use Gamma-centered or
31+
: Monkhorst-Pack grids
32+
33+
Outputs:
34+
: dict :
35+
: The new Kpoints object / KSPACING consistent with constraints.
36+
If an empty dict, no new k-point mesh could be found.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "custodian"
7-
version = "2024.4.18"
7+
version = "2024.6.24"
88
description = "A simple JIT job management framework in Python."
99
authors = [
1010
{ name = "Janosh Riebesell", email = "[email protected]" },

0 commit comments

Comments
 (0)