tcutility.job package

Subpackages

• tcutility.job.postscripts package
  • Submodules
  • tcutility.job.postscripts.clean_workdir module
  • tcutility.job.postscripts.split_crest_xyz module
  • tcutility.job.postscripts.write_converged_geoms module
  • Module contents

Submodules

tcutility.job.adf module

class ADFJob(*args, **kwargs)

Bases: AMSJob

basis_set(typ='TZ2P', core='None')

Set the basis-set type and frozen core approximation for this calculation.

Parameters:

• typ (str) – the type of basis-set to use. Default is TZ2P.

• core (str) – the size of the frozen core approximation. Default is None.

Raises:

ValueError – if the basis-set name or core is incorrect.

Note

If the selected functional is the r2SCAN-3c functional, then the basis-set will be set to mTZ2P.

See also

tcutility.data.basis_sets for an overview of the available basis-sets in ADF.

spin_polarization(val)

Set the spin-polarization of the system. If the value is not zero the calculation will also be unrestricted.

multiplicity(val)

Set the multiplicity of the system. If the value is not one the calculation will also be unrestricted. We use the following values:

1. singlet

2. doublet

3. triplet

4. …

The multiplicity is equal to 2*S+1 for spin-polarization S.

unrestricted(val)

Whether the calculation should be unrestricted.

occupations(strategy)

Set the orbital filling strategy for ADF.

Parameters:

strategy (str) – the name of the filling strategy. This can contain multiple of the options allowed.

See also

The SCM documentation can be found at https://www.scm.com/doc/ADF/Input/Electronic_Configuration.html#aufbau-smearing-freezing

quality(val='Good')

Set the numerical quality of the calculation.

Parameters:

val (str) – the numerical quality value to set to. This is the same as the ones used in the ADF GUI. Defaults to Good.

Raises:

ValueError – if the quality value is incorrect.

SCF_convergence(thresh=1e-08)

Set the SCF convergence criteria for the job.

Parameters:

thresh (float) – the convergence criteria for the SCF procedure. Defaults to 1e-8.

Deprecated since version 0.9.2: Please use ADFJob.SCF() instead of this method.

SCF(iterations=300, thresh=1e-08)

Set the SCF settings for this calculations.

Parameters:

• iterations (int) – number of iterations to perform for this calculation. Defaults to 300.

• thresh (float) – the convergence criteria for the SCF procedure. Defaults to 1e-8.

Note

When setting the number of iterations to 0 or 1 the AlwaysClaimSuccess key will also be set to Yes. This is to prevent the job from being flagged as a failure when reading it using tcutility.results.

functional(funtional_name, dispersion=None)

Set the functional to be used by the calculation. This also sets the dispersion if it is specified in the functional name.

Parameters:

• funtional_name (str) – the name of the functional. The value can be the same as the ones used in the ADF GUI.

• dispersion (str) – dispersion setting to use with the functional. This is used when you want to use a functional from LibXC.

Raises:

ValueError – if the functional name is not recognized.

Note

Setting the functional to r2SCAN-3c will automatically set the basis-set to mTZ2P.

See also

tcutility.data.functionals for an overview of the available functionals in ADF.

relativity(level='Scalar')

Set the treatment of relativistic effects for this calculation.

Parameters:

level (str) – the level to set. Can be the same as the values in the ADF GUI and documentation. By default it is set to Scalar.

Raises:

ValueError – if the relativistic correction level is not correct.

solvent(name=None, eps=None, rad=None, use_klamt=False)

Model solvation using COSMO for this calculation.

Parameters:

• name (str) – the name of the solvent you want to use. Please see the ADF manual for a list of available solvents.

• eps (float) – the dielectric constant of your solvent. You can use this in place of the solvent name if you need more control over COSMO.

• rad (float) – the radius of the solvent molecules. You can use this in place of the solvent name if you need more control over COSMO.

• use_klamt (bool) – whether to use the klamt atomic radii. This is usually used when you have charged species (?).

Raises:

ValueError – if the solvent name is given, but incorrect.

See also

tcutility.data.cosmo for an overview of the available solvent names and formulas.

symmetry(group)

Specify the symmetry group to be used by ADF.

Parameters:

group (str) – the symmetry group to be used.

class ADFFragmentJob(*args, **kwargs)

Bases: ADFJob

add_fragment(mol, name=None, charge=0, spin_polarization=0)

Add a fragment to this job. Optionally give the name, charge and spin-polarization of the fragment as well.

Parameters:

• mol (Molecule) – the molecule corresponding to the fragment.

• name (str) – the name of the fragment. By default it will be set to fragment{N+1} if N is the number of fragments already present.

• charge (int) – the charge of the fragment to be added.

• spin_polarization (int) – the spin-polarization of the fragment to be added.

guess_fragments()

Guess what the fragments are based on data stored in the molecule provided for this job. This will automatically set the correct fragment molecules, names, charges and spin-polarizations.

See also

tcutility.molecule.guess_fragments() for an explanation of the xyz-file format required to guess the fragments.

ADFFragmentJob.add_fragment() to manually add a fragment.

Note

This function will be automatically called if there were no fragments given to this calculation.

remove_virtuals(frag=None, subspecies=None, nremove=None)

Remove virtual orbitals from the fragments.

Parameters:

• frag – the fragment to remove virtuals from. If set to None we remove all virtual orbitals of all fragments.

• subspecies – the symmetry subspecies to remove virtuals from. If set to None we assume we have A subspecies.

• nremove – the number of virtuals to remove. If set to None we will guess the number of virtuals based on the basis-set chosen.

run()

Run the ADFFragmentJob. This involves setting up the calculations for each fragment as well as the parent job. It will also submit a calculation with the SCF iterations set to 0 in order to facilitate investigation of the field effects using PyOrb.

class DensfJob(*args, **kwargs)

Bases: Job

gridsize(size='medium')

Set the size of the grid to be used by Densf.

Parameters:

size – either “coarse”, “medium”, “fine”. Defaults to “medium”.

orbital(orbital)

Add a PyOrb orbital for Densf to calculate.

property output_cub_paths

The output cube file paths that will be/were calculated by this job.

can_skip()

Check whether the job can be skipped. We check this by loading the calculation and checking if the job status was fatal. Fatal in this case means that the job failed, canceled or could not be found. In those cases we want to run the job.

Note

This method works for the ADFJob, ADFFragmentJob, DFTBJob and ORCAJob objects, but not yet for CRESTJob and QCGJob. For the latter objects the job will always be rerun. This will be fixed in a later version of TCutility.

tcutility.job.ams module

class AMSJob(*base_jobs, test_mode=None, overwrite=None, wait_for_finish=None, delete_on_finish=None, delete_on_fail=None, use_slurm=True)

Bases: Job

This is the AMS base job which will serve as the parent class for ADFJob, DFTBJob and the future BANDJob. It holds all methods related to changing the settings at the AMS level. It also handles preparing the jobs, e.g. writing runfiles and inputs.

single_point()

Set the task of the job to single point.

transition_state(distances=None, angles=None, dihedrals=None, ModeToFollow=1)

Set the task of the job to transition state search. Optionally you can give some TS coordinates to accelerate convergence. By default also calculates the normal modes after convergence.

Parameters:

• distances (list) – sequence of tuples or lists containing [atom_index1, atom_index2, factor]. Atom indices start at 1.

• angles (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, factor]. Atom indices start at 1.

• dihedrals (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, atom_index4, factor]. Atom indices start at 1.

• ModeToFollow (int) – the vibrational mode to follow during optimization.

optimization()

Set the task of the job to geometry optimization. By default also calculates the normal modes after convergence.

IRC(direction='both', hess_file=None, step_size=0.2, min_path_length=0.1, max_points=300)

Set the task of the job to intrinsic reaction coordinate (IRC).

Parameters:

• direction (str) – the direction to take the first step into. By default it will be set to both.

• hess_file (str) – the path to a .rkf file to read the Hessian from. This is the adf.rkf file for ADF calculations. If set to None the Hessian will be calculated prior to starting the IRC calculation.

• step_size (float) – the size of the step taken between each constrained optimization. By default it will be set to 0.2 \(a_0\sqrt{Da}\).

• min_path_length (float) – the length of the IRC path before switching to minimization. By default it will be set to 0.1 \(\AA\).

• max_points (int) – the maximum number of IRC points in a direction. Be default it is set to 300.

PESScan(distances=None, angles=None, dihedrals=None, sumdists=None, difdists=None, npoints=10)

Set the task of the job to potential energy surface scan (PESScan).

Parameters:

• distances (list) – sequence of tuples or lists containing [atom_index1, atom_index2, start, end]. Atom indices start at 1. Distances are given in \(\AA\).

• angles (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, start, end]. Atom indices start at 1. Angles are given in degrees

• dihedrals (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, atom_index4, start, end]. Atom indices start at 1. Angles are given in degrees

• sumdists (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, atom_index4, start, end]. Atom indices start at 1. Sum of distances is given in \(\AA\).

• difdists (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, atom_index4, start, end]. Atom indices start at 1. Difference of distances is given in \(\AA\).

• npoints (int) – the number of PES points to optimize.

Note

Currently we only support generating settings for 1-dimensional PESScans. We will add support for N-dimensional PESScans later.

vibrations(enable=True, NegativeFrequenciesTolerance=-5)

Set the calculation of vibrational modes.

Parameters:

• enable (bool) – whether to calculate the vibrational modes.

• NegativeFrequenciesTolerance (float) – the tolerance for negative modes. Modes with frequencies above this value will not be counted as imaginary. Use this option when you experience a lot of numerical noise.

geometry_convergence(gradients=1e-05, energy=1e-05, step=0.01, stress=0.0005)

Set the convergence criteria for the geometry optimization.

Parameters:

• gradients (float) – the convergence criteria for the gradients during geometry optimizations. Defaults to 1e-5.

• energy (float) – the convergence criteria for the energy during geometry optimizations. Defaults to 1e-5.

• step (float) – the convergence criteria for the step-size during geometry optimizations. Defaults to 1e-2.

• stress (float) – the convergence criteria for the stress-energy per atom during geometry optimizations. Defaults to 5e-4

charge(val)

Set the charge of the system.

electric_field(direction, magnitude=None)

Set an electric field for this system.

Parameters:

• direction (List[float]) – the vector with the direction and strength of the electric field.

• magnitude (float) – if given, the direction will be normalized and magnitude will be used as the field strength.

property output_mol_path

The default file path for output molecules when running ADF calculations. It will not be created for singlepoint calculations.

tcutility.job.crest module

class CRESTJob(*args, **kwargs)

Bases: Job

spin_polarization(val)

Set the spin-polarization of the system.

multiplicity(val)

Set the multiplicity of the system. If the value is not one the calculation will also be unrestricted. We use the following values:

1. singlet

2. doublet

3. triplet

4. …

The multiplicity is equal to 2*S+1 for spin-polarization of S.

charge(val)

Set the charge of the system.

md_temperature(val)

Set the temperature of the molecular dynamics steps. Defaults to 400K.

md_length(val)

Set the length of the molecular dynamics steps. The default length will be multiplied by this value, e.g. the default value is 1.

property best_conformer_path

property conformer_directory

property rotamer_directory

get_conformer_xyz(number=None)

Return paths to conformer xyz files for this job.

Parameters:

number (int) – the number of files to return, defaults to 10. If the directory already exists, for example if the job was already run, we will return up to number files.

get_rotamer_xyz(number=None)

Return paths to rotamer xyz files for this job.

Parameters:

number (int) – the number of files to return, defaults to 10. If the directory already exists, for example if the job was already run, we will return up to number files.

class QCGJob(*args, **kwargs)

Bases: CRESTJob

solvent(mol, nsolv=None)

nsolv(nsolv)

alpb(solvent)

ensemble_mode(mode)

nofix(enable=True)

property ensemble_directory

get_ensemble_xyz(number=None)

Return paths to conformer xyz files for this job.

Parameters:

number (int) – the number of files to return, defaults to 10. If the directory already exists, for example if the job was already run, we will return up to number files.

property best_ensemble_path

tcutility.job.dftb module

class DFTBJob(*args, **kwargs)

Bases: AMSJob

Setup and run a density functional with tight-binding (DFTB) calculation as implemented in the Amsterdam modelling suite (AMS). This class supports all methods of the parent AMSJob.

kspace(quality='Good')

Set the k-space integration quality for this job.

Parameters:

quality (str) – the type of basis-set to use. Default is Good.

model(name='GFN1-xTB', dispersion=None, parameter_dir=None)

Set the model Hamiltonian for the job to use.

Parameters:

name (str) – name of the model Hamiltonian. This is the same name as the one in the DFTB gui. Default is GFN1-xTB.

solvent(name=None, grid_size=974)

Model solvation using the GBSA model.

Parameters:

• name (str) – the name of the solvent you want to use. Must be None, Acetone, Acetonitrile, CHCl3, CS2, DMSO, Ether, H2O, Methanol, THF or Toluene.

• grid_size – the size of the grid used to construct the solvent accessible surface. Must be 230, 974, 2030 or 5810.

tcutility.job.generic module

class Job(*base_jobs, test_mode=None, overwrite=None, wait_for_finish=None, delete_on_finish=None, delete_on_fail=None, use_slurm=True)

Bases: object

This is the base Job class used to build more advanced classes such as AMSJob and ORCAJob. The base class contains an empty Result object that holds the settings. It also provides __enter__() and __exit__() methods to make use of context manager syntax.

All class methods are in principle safe to overwrite, but the _setup_job() method must be overwritten.

Parameters:

• test_mode (bool) – whether to enable the testing mode. If enabled, the job will be setup like normally, but the running step is skipped. This is useful if you want to know what the job settings look like before running the real calculations.

• overwrite (bool) – whether to overwrite a previously run job in the same working directory.

• wait_for_finish (bool) – whether to wait for this job to finish running before continuing your runscript.

• delete_on_finish (bool) – whether to remove the workdir for this job after it is finished running.

can_skip()

Check whether the job can be skipped. We check this by loading the calculation and checking if the job status was fatal. Fatal in this case means that the job failed, canceled or could not be found. In those cases we want to run the job.

Note

This method works for the ADFJob, ADFFragmentJob, DFTBJob and ORCAJob objects, but not yet for CRESTJob and QCGJob. For the latter objects the job will always be rerun. This will be fixed in a later version of TCutility.

in_queue()

Check whether the job is currently managed by slurm. We check this by loading the calculation and checking if the job status is ‘RUNNING’, ‘COMPLETING’, ‘CONFIGURING’ or ‘PENDING’.

sbatch(**kwargs)

Change slurm settings, for example, to change the partition or change the number of cores to use. The arguments are the same as you would use for sbatch (see sbatch manual). E.g. to change the partition to ‘tc’ call:

job.sbatch(p='tc') or job.sbatch(partition='tc').

Flags can be set as arguments with a boolean to enable or disable them:

job.sbatch(exclusive=True) will set the --exclusive flag.

Warning

Note that some sbatch options, such as --job-name contain a dash, which cannot be used in Python arguments. To use these options you should use an underscore, like job.sbatch(job_name='water_dimer_GO').

Note

When running the job using sbatch we add a few extra default options:

• -D/--chdir {self.workdir} to make sure the job starts in the correct directory

• -J/--job-name {self.rundir}/{self.name} to give a nicer job-name when calling squeue

• -o/--output {self.name}.out to redirect the output from the default slurm-{id}.out

You can still overwrite them if you wish.

run()

Run this job. We detect if we are using slurm. If we are we submit this job using sbatch. Otherwise, we will run the job locally.

add_preamble(line)

Add a preamble for the runscript. This should come after the shebang, but before the calculation is ran by the program (ADF or ORCA). This can used, for example, to load some modules. E.g. to load a specific version of AMS we can call: job.add_preamble(‘module load ams/2023.101’)

add_postamble(line)

Add a postamble for the runscript. This should come after the calculation is ran by the program (ADF or ORCA). This can be used, for example, to remove or copy some files. E.g. to remove all t12.* files we can call: job.add_postamble(‘rm t12.*’)

add_postscript(script, *args)

Add a post-script to this calculation. This should be either a Python module with a __file__ attribute or the path to a Python script. The post-script will be called with Python and any given args will be added as arguments when calling the script.

Parameters:

• script – a Python object with a __file__ attribute or the file-path to a script.

• *args – positional arguments to pass to the post-script.

dependency(otherjob)

Set a dependency between this job and otherjob. This means that this job will run after the other job is finished running succesfully.

property workdir

The working directory of this job. All important files are written here, for example the input file and runscript.

property runfile_path

The file path to the runscript of this job.

property inputfile_path

The file path to the input file of this job.

property output_mol_path

This method should return the name of the output molecule if it makes sense to give it back. E.g. for ADF it will be output.xyz in the workdir for optimization jobs.

molecule(mol)

Add a molecule to this calculation in various formats.

Parameters:

mol (Union[str, Molecule, Atom, List[Atom]]) – the molecule to read, can be a path (str). If the path exists already we read it. If it does not exist yet, it will be read in later. mol can also be a plams.Molecule object or a single or a list of plams.Atom objects.

copy()

Make and return a copy of this object.

tcutility.job.nmr module

class NMRJob(*args, **kwargs)

Bases: Job

A job that handles calculation of Nuclear Magnetic Resonance (NMR) chemical shifts. The job will first run an tcutility.job.adf.ADFJob calculation at the SAOP/TZ2P level of theory to prepare for the NMR program of AMS. The NMR shifts will be calculated for all atoms and any additional coordinate (NICS). New NICS points can be given using the NMRJob.add_nics_point() method.

add_nics_point(coordinate)

Add a NICS point to be calculated.

Parameters:

coordinate (Tuple[float, float, float]) – the (x, y, z) coordinates of a NICS point to calculate the chemical shift for. Has to be given as cartesian coordinates and using unit angstrom.

tcutility.job.orca module

class ORCAJob(use_tmpdir=False, *args, **kwargs)

Bases: Job

main(val)

Add main options for this ORCA calculation, they will be added to the input prepended with exclamation marks.

Parameters:

val (Union[str, List[str]]) – the main options to add. This can be a string or a list of strings with the main options.

remove_main(val)

method(method)

reference(ref)

QRO(enable=True)

basis_set(value)

single_point()

transition_state()

optimization()

vibrations(enable=True, numerical=False)

charge(val)

spin_polarization(val)

multiplicity(val)

ghost_atoms(indices)

get_memory_usage()

molecule(mol, natoms=None)

Add a molecule to this calculation in various formats.

Parameters:

• mol (Union[str, Molecule, Atom, List[Atom]]) – the molecule to read, can be a path (str). If the path exists already we read it. If it does not exist yet, it will be read in later. mol can also be a plams.Molecule object or a single or a list of plams.Atom objects.

• natoms (int) – If the molecule is supplied as a path you should also give the number of atoms.

get_input()

property output_mol_path

The default file path for output molecules when running ADF calculations. It will not be created for singlepoint calculations.

tcutility.job.xtb module

class XTBJob(*args, **kwargs)

Bases: Job

model(method)

Set the method used by XTB. This includes GFN0-xTB, GFN1-xTB, GFN2-xTB and GFNFF.

Parameters:

method (Union[str, int]) – the method to use. Can be specified by its full name, e.g. ‘GFN2-xTB’, is the same as ‘GFN2’ or simply 2.

solvent(name=None, model='alpb')

Model solvation using the ALPB or GBSA model.

Parameters:

• name (str) – the name of the solvent you want to use. Must be None, Acetone, Acetonitrile, CHCl3, CS2, DMSO, Ether, H2O, Methanol, THF or Toluene.

• grid_size – the size of the grid used to construct the solvent accessible surface. Must be 230, 974, 2030 or 5810.

spin_polarization(val)

Set the spin-polarization of the system.

multiplicity(val)

Set the multiplicity of the system. If the value is not one the calculation will also be unrestricted. We use the following values:

1. singlet

2. doublet

3. triplet

4. …

The multiplicity is equal to 2*S+1 for spin-polarization of S.

charge(val)

Set the charge of the system.

vibrations(enable=True)

optimization(quality='Normal', calculate_hess=True)

Do a geometry optimization and calculate the normal modes of the input structure.

Parameters:

• quality (str) – the convergence criteria of the optimization. See https://xtb-docs.readthedocs.io/en/latest/optimization.html#optimization-levels.

• calculate_hess (bool) – whether to calculate the Hessian and do a normal mode analysis after optimization.

PESScan(distances=[], angles=[], dihedrals=[], npoints=20, quality='Normal', mode='concerted')

Set the task of the job to potential energy surface scan (PESScan).

Parameters:

• distances (list) – sequence of tuples or lists containing [atom_index1, atom_index2, start, end]. Atom indices start at 1. Distances are given in \(\AA\).

• angles (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, start, end]. Atom indices start at 1. Angles are given in degrees

• dihedrals (list) – sequence of tuples or lists containing [atom_index1, atom_index2, atom_index3, atom_index4, start, end]. Atom indices start at 1. Angles are given in degrees

• npoints (int) – the number of PES points to optimize.

Note

Currently we only support generating settings for 1-dimensional PESScans. We will add support for N-dimensional PESScans later.

property output_mol_path

This method should return the name of the output molecule if it makes sense to give it back. E.g. for ADF it will be output.xyz in the workdir for optimization jobs.

Module contents