Solutes module¶

SolutesTask¶

class esteem.tasks.solutes.SolutesTask(**kwargs)[source]¶

run(namelist)[source]¶

Main routine for the Solutes task. Iterates through the sub-tasks, some of which are optional:

Geometry optimisation, rotamer checks, rotation to plane, excited state calculations, and vibrational frequency calculations.

namelist: list of str

Short names of the solutes to be optimised. Initial geometries should be present in ‘./xyz’ directory.

self: namespace or class

Member variables contain argument list for the whole job, with members including:

solvent, target, rotate, rotamers, vibrations, charges, directory solvent_settings, basis, func, nroots

Generate default arguments first with a call to solutes.make_parser(), then adjust the member variables as required.

wrapper: class

Wrapper for running components of the job, with members including:

singlepoint, geom_opt, excitations, freq

Outputs for each species:

In the directory ‘xyz’: initial geometries (either input, or from get_xyz_files)

In the directory ‘geom’: outputs of geometry optimisations.

In the directory ‘opt’: optimised gas-phase geometries.

In the directory ‘is_opt’: optimised implicit solvent geometries. These may be used as inputs for the Solvate task.

In the directory ‘is_tddft_{solvent}’: implicit solvent tddft results. These may be used as inputs for spectral warping in the Spectra task.

get_xyz_files(namelist, out_path)[source]¶

Downloads initial geometries from the NCI’s webserver cactus, based on their IUPAC names.

These geometries are usually not great, but are a reasonable starting point for optimisation.

Visit https://cactus.nci.nih.gov/chemical/structure to see what works and check your names before use.

Uses wget, so if the machine you are using does not have access to this command, this routine will fail, in which case put starting point geometries in the directory ‘xyz’.

namelist: dict: Keys are shortnames (eg “cate”), entries are full names (eg “catechol” or “1,2-dihydroxybenzene”)
out_path: str: String for directory name where xyz files will be written (eg “xyz”). Created if not present

geom_opt_all(solute_names, in_path, out_path, geom_opt_func, calc_params, driver_tol='default', solvent=None, charges={})[source]¶

Geometry optimise all of a list of solutes

solute_names: list of str: Short names of the solutes to be optimised
in_path: str: Directory where .xyz files are expected to be found. Any not present are skipped.
out_path: str: Directory where optimised structure .xyz files are written. Created if not present.
geom_opt_func: function: A function wrapping creation of an ASE calculator and using it to perform geometry optimisation.
calc_params: dict: Contents varies between different wrappers, but generally specifies basis, functional etc
driver_tol: str: Geometry optimisation tolerance level (eg in NWChem)
target: int: Excited state index, or None for ground state
solvent: str: Implicit solvent name, or None for gas-phase
charges: dict: Keys are strings corresponding to some or all of the entries in solute names, entries are net charges on each molecule

find_best_rotas(solute_names, in_path, out_path, singlepoint_func, geom_opt_func, calc_params, solvent=None, charges={})[source]¶

Finds the lowest energy rotamer for each of a list of solutes. Proceeds by identifying -OH groups attached to C-C units, and tries ‘flipping’ the dihedral, then optimising the resulting geometry if it within a certain tolerance of the original energy. If any lower energy structure is found, this will be returned instead of the original one.

solute_names: list of str: Short names of the solutes to be tested
in_path: str: Directory where .xyz files are expected to be found. Any not present are skipped.
out_path: str: Directory where best rotamer structure .xyz files are written. Created if not present.
singlepoint_func: function: A function wrapping creation of an ASE calculator and using it to perform a singlepoint calculation.
geom_opt_func: function: A function wrapping creation of an ASE calculator and using it to perform geometry optimisation.
calc_params: dict: Contents varies between different wrappers, but generally specifies basis, functional etc
solvent: str: Implicit solvent name, or None for gas-phase
charges: dict: Keys are strings corresponding to some or all of the entries in solute names, entries are net charges on each molecule

rotate_all_to_xy_plane(solute_names, in_path, out_path, target=None)[source]¶

Rotates each of a list of solutes so that the longest two C-C distances lie in the xy plane.

solute_names: list of str: Short names of the solutes to be tested
in_path: str: Directory where .xyz files are expected to be found. Any not present are skipped.
out_path: str: Directory where rotated structure .xyz files are written. Created if not present.
target: int: Excited state index, or None for ground state

find_range_sep(solute_names, in_path, out_path, wrapper, calc_params, solvent=None, charges={}, rs_range=[0.1, 0.2, 0.3], all_readonly=False)[source]¶

Optimises the range separation parameter gamma in a range-separated Hybrid functional with Yukawa-switching. See ‘Using optimally tuned range separated hybrid functionals in ground-state calculations: Consequences and caveats’, Andreas Karolewski, Leeor Kronik, and Stephan Kümmel J. Chem. Phys. 138, 204115 (2013) https://aip.scitation.org/doi/10.1063/1.4807325 https://pubs.acs.org/doi/abs/10.1021/ct5000617 and ‘Electronic Band Shapes Calculated with Optimally Tuned Range-Separated Hybrid Functionals’ B. Moore, et al, D. Jacquemin, J. Chem. Theory Comput. 2014, 10, 10, 4599 https://pubs.acs.org/doi/10.1021/ct500712w

Minimises J^2 = Sum_i=0^1 [eps_H[N+i] + IP(N+i)))]^2 where IP(N) = E(N-1) - E(N) so J^2 = Sum_i=0^1 [eps_H[N+i] + E(N-1+i) - E(N+i)]^2

= [eps_H[N] + E(N-1) - E(N)]^2 + [eps_H[N+1] + E(N) - E(N+1)]^2

calc_all_excited_states(solute_names, in_path, out_path, excit_func, calc_params, nroots, solvent=None, charges={}, plot_homo=None, plot_lumo=None, plot_trans_den=None)[source]¶

Calculate excited states for each of a list of solutes

solute_names: list of str: Short names of the solutes to be tested
in_path: str: Directory where .xyz files are expected to be found. Any not present are skipped.
out_path: str: Directory where output files are written. Created if not present.
excit_func: function: A function wrapping creation of an ASE calculator and using it to perform a electronic excitation calculations.
calc_params: dict: Contents varies between different wrappers, but generally specifies basis, functional etc
nroots: int: Number of excitations to find
target: int: Excited state index, or None for ground state
solvent: str: Implicit solvent name, or None for gas-phase
charges: dict: Keys are strings corresponding to some or all of the entries in solute names, entries are net charges on each molecule

calc_vib_freq(solute_names, in_path, out_path, freq_func, calc_params, solvent=None, charges={})[source]¶

Calculate vibrational frequencies for each of a list of solutes

solute_names: list of str: Short names of the solutes to be tested
in_path: str: Directory where .xyz files are expected to be found. Any not present are skipped.
out_path: str: Directory where output files are written. Created if not present.
freq_func: function: A function wrapping creation of an ASE calculator and using it to perform a vibrational frequency calculation.
calc_params: dict: Contents varies between different wrappers, but generally specifies basis, functional etc
target: int: Excited state index, or None for ground state
solvent: str: Implicit solvent name, or None for gas-phase
charges: dict: Keys are strings corresponding to some or all of the entries in solute names, entries are net charges on each molecule

chdir()¶

Change the current working directory to the specified path.

path may always be specified as a string. On some platforms, path may also be specified as an open file descriptor.

If this functionality is unavailable, using it raises an exception.

getcwd()¶: Return a unicode string representing the current working directory.

makedirs(name [, mode=0o777][, exist_ok=False])¶: Super-mkdir; create a leaf directory and all intermediate ones. Works like mkdir, except that any intermediate path segment (not just the rightmost) will be created if it does not exist. If the target directory already exists, raise an OSError if exist_ok is False. Otherwise no exception is raised. This is recursive.

np = <module 'numpy' from '/home/docs/checkouts/readthedocs.org/user_builds/esteem/envs/latest/lib/python3.11/site-packages/numpy/__init__.py'>¶

path = <module 'posixpath' (frozen)>¶

read(index: Any = None, format: str = None, parallel: bool = True, do_not_split_by_at_sign: bool = False, **kwargs) → Union[ase.atoms.Atoms, List[ase.atoms.Atoms]]¶

Read Atoms object(s) from file.

filename: str or file

Name of the file to read from or a file descriptor.

index: int, slice or str

The last configuration will be returned by default. Examples:

index=0: first configuration

index=-2: second to last

index=':' or index=slice(None): all

index='-3:' or index=slice(-3, None): three last

index='::2' or index=slice(0, None, 2): even

index='1::2' or index=slice(1, None, 2): odd

format: str

Used to specify the file-format. If not given, the file-format will be guessed by the filetype function.

parallel: bool

Default is to read on master and broadcast to slaves. Use parallel=False to read on all slaves.

do_not_split_by_at_sign: bool

If False (default) filename is splited by at sign @

Many formats allow on open file-like object to be passed instead of filename. In this case the format cannot be auto-decected, so the format argument should be explicitly given.

rotate_and_center_solute(nat_solute=None, boxsize=None)¶: Rotates a cluster model so the solute is centered and lies in the xy plane

write(images: Union[ase.atoms.Atoms, Sequence[ase.atoms.Atoms]], format: str = None, parallel: bool = True, append: bool = False, **kwargs) → None¶

Write Atoms object(s) to file.

filename: str or file: Name of the file to write to or a file descriptor. The name ‘-’ means standard output.
images: Atoms object or list of Atoms objects: A single Atoms object or a list of Atoms objects.
format: str: Used to specify the file-format. If not given, the file-format will be taken from suffix of the filename.
parallel: bool: Default is to write on master only. Use parallel=False to write from all slaves.
append: bool: Default is to open files in ‘w’ or ‘wb’ mode, overwriting existing files. In some cases opening the file in ‘a’ or ‘ab’ mode (appending) is useful, e.g. writing trajectories or saving multiple Atoms objects in one file. WARNING: If the file format does not support multiple entries without additional keywords/headers, files created using ‘append=True’ might not be readable by any program! They will nevertheless be written without error message.

The use of additional keywords is format specific. write() may return an object after writing certain formats, but this behaviour may change in the future.

Task Arguments¶

usage: __main__.py [-h] [--namefile NAMEFILE] [--solvent SOLVENT]
                   [--nroots NROOTS] [--target TARGET] [--rotate ROTATE]
                   [--rotamers [ROTAMERS]] [--vibrations [VIBRATIONS]]
                   [--charges [CHARGES]] [--solvent_settings SOLVENT_SETTINGS]
                   [--plot_homo PLOT_HOMO] [--plot_lumo PLOT_LUMO]
                   [--plot_trans_den PLOT_TRANS_DEN] [--basis BASIS]
                   [--func FUNC] [--disp DISP]

Named Arguments¶

`--namefile, -N`	File from which to read a list of names of solvent or solute molecules. Each line should take the form “shortname: IUPACsystematicname” Default: “names”
`--solvent, -S`	Solvent for implicit solvent runs.
`--nroots, -n`	Number of TDDFT excitations to calculate. Default: 5
`--target, -t`	Targetted TDDFT excitation for geom opt.)
`--rotate, -r`	If True, attempt to rotate molecule so that the “flattest” part, defined by furthest-apart pairs of C atoms, lies in the xy-plane Default: True
`--rotamers, -R`	If True, attempt to find the lowest-energy rotamer by switching positions of all rotatable -OH groups. Default: False
`--vibrations, -V`
	If True, Calculate all vibrational frequencies for final level of theory. Default: False
`--charges, -Q`	Charges on molecular species. Not for command-line use Default: {}
`--solvent_settings`
	Solvent settings for implicit solvent runs.
`--plot_homo, -H`
	Number of orbitals from HOMO downwards to plot
`--plot_lumo, -L`
	Number of orbitals from LUMO downwards to plot
`--plot_trans_den, -T`
	Number of excitations for which to plot the transition density
`--basis, -b`	Basis set string for geom opt and TDDFT. Default: “6-311++G**”
`--func, -f`	XC Functional string for geom opt and TDDFT. Default: “PBE0”
`--disp, -d`	Grimme D3 Dispersion correction (set to True to activate) Default: True

Names are read in from the file provided in the “namefile” argument. All other arguments are optional and turn on other tasks. To provide pre-optimised inputs, put their structures in a pre-existing directory named “xyz”. If not present, an attempt will be made to download a structure from the NIH chemical name resolver (CACTUS).

Standalone module routines¶

Runs DFT and TDDFT calculations on Solute (or Solvent) molecules, in implicit solvent