AMS driver and engines

The AMS driver is a new program introduced in the 2018 release that unifies the way in which different computational engines of the Amsterdam Modeling Suite are called. You can find more information about the AMS driver in the corresponding part of the documentation.

Preparing input

Tip

Starting with AMS2024, you can also use PISA (Python Input System for AMS) to specify the input to AMS.

However, almost all PLAMS examples still use the input description described on this page.

Note

Input files handling in the AMS driver is case insensitive.

The input file for the AMS driver consists of keys and values organized in blocks and subblocks:

Task GeometryOptimization

GeometryOptimization
    Convergence
        Gradients 1.0e-4
    End
End

Properties
   NormalModes true
End

System
    Atoms
        C       0.00000000       0.00000000       0.00000000
        H       0.63294000      -0.63294000      -0.63294000
        H      -0.63294000       0.63294000      -0.63294000
        H       0.63294000       0.63294000       0.63294000
        H      -0.63294000      -0.63294000       0.63294000
    End
End

Engine DFTB
    Model DFTB3
    ResourcesDir DFTB.org/3ob-3-1
EndEngine

Such a structure can be reflected in a natural way by a multi-level character of Settings. The example input file presented above can be generated by:

s = Settings()
#AMS driver input
s.input.ams.Task = 'GeometryOptimization'
s.input.ams.GeometryOptimization.Convergence.Gradients = 1.0e-4
s.input.ams.Properties.NormalModes = 'true'
#DFTB engine input
s.input.DFTB.Model = 'DFTB3'
s.input.DFTB.ResourcesDir = 'DFTB.org/3ob-3-1'

m = Molecule('methane.xyz')
j = AMSJob(molecule=m, settings=s)
j.run()

If an entry is a regular key-value pair it is printed in one line (like Task GeometryOptimization above). If an entry is a nested Settings instance it is printed as a block and entries inside this instance correspond to the contents of that block.

One of the blocks is special: the engine block. It defines the computational engine used to perform the task defined in all other blocks. The contents of the engine block are not processed by the AMS driver, but rather passed to the corresponding engine instead. Because of that every AMS input file can be seen as composed of two distinct parts: the engine input (everything inside the engine block) and the driver input (everything apart from the engine block). That distinction is reflected by how a Settings instance for AMSJob is structured. As we can see, the input branch of job settings is divided into two branches: the ams branch for the driver input and the DFTB branch for the engine input.

Note

In general, PLAMS will use all the contents of the ams branch (spelling not case-sensitive) to construct the driver input and the contents of every other branch to construct a separate engine block with the same name as the branch (like DFTB in the example above). At present, only applications with a single engine block are implemented in the AMS driver, but that will most likely change in the near future.

The contents of each branch of myjob.settings.input are translated to a string using the same logic:

  • Entries within each block (including the top level) are listed in the alphabetical order.

  • Both keys and values are kept in their original case.

  • Strings used as values can contain spaces and all kinds of special characters, including new lines. They are printed in an unchanged form in the input file.

  • If you need to put a key without any value, you can use True or an empty string as a value:

    s.input.ams.block.key = True
s.input.ams.otherkey = ''

### translates to:

block
  key
end

otherkey

  • If a value of a key is False or None the key is omitted.

  • An empty Settings instance produces an empty block:

    s.input.ams.emptyblock = Settings()
s.input.ams.otherblock #short syntax equivalent to the line above

### translates to:

emptyblock
end

otherblock
end

  • More instances of the same key within one block can be achieved by using a list of values instead of a single value:

    s.input.ams.constraints.atom = [1,5,4]
s.input.ams.constraints.block = ['ligand', 'residue']

### translates to:

constraints
  atom 1
  atom 5
  atom 4
  block ligand
  block residue
end

  • Some blocks require (or allow) something to be put in the header line, next to the block name. Special key _h is helpful in these situations:

    s.input.ams.block._h = 'header=very important'
s.input.ams.block.key1 = 'value1'
s.input.ams.block.key2 = 'value2'

### translates to:

someblock header=very important
  key1 value1
  key2 value2
end

  • Another kind of special key can be used to override the default alphabetical ordering of entries within a block, or just to insert arbitrary strings into the block:

    s.input.ams.block._1 = 'entire line that has to be the first line of block'
s.input.ams.block._2 = 'second line'
s.input.ams.block._4 = 'I will not be printed'
s.input.ams.block.key1 = 'value1'
s.input.ams.block.key2 = 'value2'

### translates to:

block
  entire line that has to be the first line of block
  second line
  key1 value1
  key2 value2
end

  • If a value of a key needs to be a path to some KF file with results of a previous AMS calculation, an instance of AMSJob or AMSResults (or directly KFFile) can be used (see AMSJob.get_input() for details):

    oldjob = AMSJob(...)
oldjob.run()
newjob = AMSJob(...)
newjob.settings.input.ams.loadsystem.file = oldjob
newjob.settings.input.ams.loadengine = (oldjob, 'dftb')

### translates to:

loadengine /home/user/plams_workdir/oldjob/dftb.rkf

loadsystem
  file = /home/user/plams_workdir/oldjob/ams.rkf
end

  • Convert AMS text-style input to a Settings object (this requires that the SCM python package is installed):

    text = '''
Task GeometryOptimization
Engine DFTB
   Model GFN1-xTB
EndEngine
'''

sett = AMSJob.from_input(text).settings
print(sett)

# output:

input:
      dftb:
           model:       GFN1-xTB
      ams:
           task:        GeometryOptimization

Note

The algorithm translating Settings contents into an input file does not check the correctness of the given data - it simply takes keys and values from Settings and prints them in the text file. Due to that you are not going to be warned if you make a typo, use a wrong keyword or improper syntax.

Preparing runscript

Runscripts for the AMS driver are very simple (see AMSJob.get_runscript()). The only adjustable option (apart from usual pre, post, shebang and stdout_redirect which are common for all single jobs) is myjob.settings.runscript.nproc, indicating the number of parallel processes to run AMS with (like with -n flag or NSCM environmental variable).

Molecule handling

There are several ways in which the description of the simulated system can be supplied to AMSJob. The most convenient one is simply by passing a Molecule instance:

mol = Molecule('/path/to/some/file.xyz')
myjob = AMSJob(name='test', molecule=mol, settings=...)

or:

mol = Molecule('/path/to/some/file.xyz')
myjob = AMSJob(...)
myjob.molecule = mol

Note

Instead of passing a Molecule object to AMSJob, you have the option to use a Chemical System as well.

A Molecule instance stored as the molecule attribute is automatically processed during the input file preparation and printed in the proper format (see AMS manual for details). Various details of this process can be adjusted based on attributes of the supplied Molecule. If mol.lattice is nonempty, the information about periodicity vectors is printed to the lattice subblock of the system block. If the supplied lattice consists of 1 or 2 vectors that do not follow the convention required by AMS (1D – vector aligned with X axis; 2D – vectors aligned with XY plane) the whole system is rotated to meet these criteria. If mol.properties.charge exists, it is used as the charge key in the system block.

Moreover, each Atom present in the supplied Molecule has its own properties attribute that can be used to adjust the details of the line generated for this atom in the atoms block:

  • The atomic symbol is generated based on the atomic number stored in the atnum attribute of the Atom. The atomic number of 0 corresponds to the “dummy atom” for which the symbol is empty.

  • If atom.properties.ghost exists and is True, the atomic symbol is prefixed with Gh..

  • If atom.properties.name exists, the name is added after the atomic symbol, separated by a single dot.

  • Leading, trailing and double dots are removed from the atomic symbol.

  • If atom.properties.suffix exists, it is placed at the end of the line, after the numerical coordinates (it should ba a string)

Example:

mol = Molecule('xyz/Ethanol.xyz')
mol[1].properties.ghost = True
mol[2].properties.name = 'D'
mol[3].properties.ghost = True
mol[3].properties.name = 'T'
mol[4].properties.atnum = 0
mol[4].properties.name = 'J.XYZ'
mol[5].properties.atnum = 0
mol[5].properties.name = 'J.ASD'
mol[5].properties.ghost = True
mol[6].properties.suffix = 'whatever text'
myjob = AMSJob(molecule=mol)

The corresponding fragment of the input file produced by the above code:

system
  atoms
      1      Gh.C       0.01247       0.02254       1.08262
      2       C.D      -0.00894      -0.01624      -0.43421
      3    Gh.H.T      -0.49334       0.93505       1.44716
      4     J.XYZ       1.05522       0.04512       1.44808
      5  Gh.J.ASD      -0.64695      -1.12346       2.54219
      6         H       0.50112      -0.91640      -0.80440   whatever text
      7         H       0.49999       0.86726      -0.84481
      8         H      -1.04310      -0.02739      -0.80544
      9         O      -0.66442      -1.15471       1.56909
  end
end

Another, more cumbersome way to provide the system information to AMSJob is to manually populate the system block in job settings:

s = Settings()
s.input.ams.system.atoms._1 = 'H     0.0    0.0     0.0'
s.input.ams.system.atoms._2 = 'O     1.0    0.0     0.0'
s.input.ams.system.charge = 1.0
#other settings adjustments
myjob = AMSJob(settings=s)

An alternative way of supplying molecular coordinates is to use the GeometryFile key in the system block:

s = Settings()
s.input.ams.system.geometryfile = '/path/to/some/file.xyz'
#other settings adjustments
myjob = AMSJob(settings=s)

Currently only the extended XYZ format is supported.

Finally, one could use the LoadSystem top-level key and point to an existing .rkf file with results of some previous calculation:

s = Settings()
s.input.loadsystem = '/path/to/some/ams.rkf'
#other settings adjustments
myjob = AMSJob(settings=s)

Multiple molecules

The AMS driver allows multiple occurrences of the system block in the input file. Different system blocks are distinguished by their names defined in the header of the block:

system protein
    atoms
    ...
    end
end
system ligand
    atoms
    ...
    end
end

The system without such a name is considered the main system.

Multiple systems can be used in AMSJob by setting the molecule attribute to a dictionary, instead of a single Molecule. Such a dictionary should have strings as keys and Molecule instances as values. The main system should have '' (an empty string) as a key.

Other methods of providing the contents of the system block mentioned above can also be used to provide multiple system blocks. myjob.settings.input.ams.system can be a list containing multiple Settings instances, one for each system. Each such instance can be have manually filled atoms block or use the geometryfile key. Special header _h key can be used to set headers and hence names of different system blocks. Multiple instances of the LoadSystem key (also provided as a list, also with _h headers) can also be used.

All the methods mentioned above (molecule attribute, GeometryFile, LoadSystem, manual system block preparation) can be combined in any configuration. In case of a conflict, the data stored in settings.input.ams.system takes precedence over molecule. It is, however, the user’s responsibility to make sure that among all the systems provided there is exactly one main system (without a name).

AMSJob API

class AMSJob(name='plamsjob', molecule=None, settings=None, depend=None)[source]

A single computation with the AMS driver.

Parameters:

  • molecule (Molecule | Dict[str, Molecule] | ChemicalSystem | Dict[str, ChemicalSystem] | None) – input molecule, chemical system, or mapping of named systems

  • args (Any) – positional arguments forwarded to SingleJob

  • kwargs (Any) – keyword arguments forwarded to SingleJob

__init__(molecule=None, *args, **kwargs)[source]
Parameters:
run(jobrunner=None, jobmanager=None, watch=False, **kwargs)[source]

Run the job using jobmanager and jobrunner (or defaults, if None).

If watch is set to True, the contents of the AMS driver logfile will be forwarded line by line to the PLAMS logfile (and stdout), allowing for an easier monitoring of the running job. Note that forwarding the AMS driver logfile makes this method block until execution finishes, even when using a parallel JobRunner.

Other keyword arguments (**kwargs) are stored in run branch of job’s settings.

Parameters:

  • jobrunner (JobRunner | None) – runner used to execute the job, or None for the configured default

  • jobmanager (JobManager | None) – manager used for the job, or None for the configured default

  • watch (bool) – forward new AMS log lines while the job runs

  • kwargs (Any) – values stored in the run branch of the job settings

Returns:

results associated with this job

Return type:

AMSResults

get_input()[source]

Generate the input file. This method is just a wrapper around _serialize_input().

Each instance of AMSJob or AMSResults present as a value in settings.input branch is replaced with an absolute path to ams.rkf file of that job.

If you need to use a path to some engine specific .rkf file rather than the main ams.rkf file, you can to it by supplying a tuple (x, name) where x is an instance of AMSJob or AMSResults and name is a string with the name of the .rkf file you want. For example, (myjob, 'dftb') will transform to the absolute path to dftb.rkf file in myjob’s folder, if such a file is present.

Instances of KFFile are replaced with absolute paths to corresponding files.

Returns:

serialized AMS input

Return type:

str

get_runscript()[source]

Generate the runscript. Returned string is of the form:

unset AMS_SWITCH_LOGFILE_AND_STDOUT
AMS_JOBNAME=jobname AMS_RESULTSDIR=. $AMSBIN/ams [-n nproc] --input=jobname.in [>jobname.out]

-n flag is added if settings.runscript.nproc exists. [>jobname.out] is used based on settings.runscript.stdout_redirect. If settings.runscript.preamble_lines exists, those lines will be added to the runscript verbatim before the execution of AMS. If settings.runscript.postamble_lines exists, those lines will be added to the runscript verbatim after the execution of AMS.

Returns:

shell runscript for the job

Return type:

str

check()[source]

Check whether the main RKF file reports normal termination.

Returns:

whether the job terminated normally without reported errors

Return type:

bool

get_errormsg()[source]

Return an error message for a failed job.

Returns:

error message, or None for a successful job

Return type:

str | None

hash_input()[source]

Calculate the hash of the input file.

All instances of AMSJob or AMSResults present as values in settings.input branch are replaced with hashes of corresponding job’s inputs. Instances of KFFile are replaced with absolute paths to corresponding files.

Returns:

SHA-256 hash of the serialized input

Return type:

str

get_task()[source]

Return the AMS task from the job settings.

Returns:

task name, or None if it is not defined

Return type:

str | None

classmethod load_external(path, settings=None, molecule=None, finalize=False, fmt='ams')[source]

Load an external job from path.

In this context an “external job” is an execution of some external binary that was not managed by PLAMS, and hence does not have a .dill file. It can also be used in situations where the execution was started with PLAMS, but the Python process was terminated before the execution finished, resulting in steps 9-12 of Running a job not happening.

All the files produced by your computation should be placed in one folder and path should be the path to this folder or a file in this folder. The name of the folder is used as a job name. Input, output, error and runscript files, if present, should have names defined in _filenames class attribute (usually [jobname].in, [jobname].out, [jobname].err and [jobname].run). It is not required to supply all these files, but in most cases one would like to use at least the output file, in order to use methods like grep_output() or get_output_chunk(). If path is an instance of an AMSJob, that instance is returned.

This method is a class method, so it is called via class object and it returns an instance of that class:

>>> a = AMSJob.load_external(path='some/path/jobname')
>>> type(a)
scm.plams.interfaces.adfsuite.ams.AMSJob

You can supply Settings and Molecule instances as settings and molecule parameters, they will end up attached to the returned job instance. If you don’t do this, PLAMS will try to recreate them automatically using methods recreate_settings() and recreate_molecule() of the corresponding Results subclass. If no Settings instance is obtained in either way, the defaults from config.job are copied.

You can set the finalize parameter to True if you wish to run the whole _finalize() on the newly created job. In that case PLAMS will perform the usual check() to determine the job status (successful or failed), followed by cleaning of the job folder (Cleaning job folder), postrun() and pickling (Pickling). If finalize is False, the status of the returned job is copied.

Parameters:

  • path (str) – results directory or a file within it

  • settings (Settings | None) – settings to attach, or None to reconstruct them when possible

  • molecule (Molecule | None) – molecule to attach, or None to reconstruct it when possible

  • finalize (bool) – run the normal job finalization steps after loading

  • fmt (str) – input format: ams, qe, gaussian, vasp, or any

Returns:

job representing the external results

Return type:

AMSJob

The available formats behave as follows:

  • ams loads a finished AMS job.

  • qe converts Quantum ESPRESSO output to ams.rkf and qe.rkf.

  • gaussian converts Gaussian output to AMS-compatible RKF files.

  • vasp converts a VASP OUTCAR to ams.rkf and vasp.rkf.

  • any detects the format automatically.

This method can also be used to convert a finished VASP job to an AMSJob. If you supply the path to a folder containing OUTCAR, then a subdirectory will be created in this folder called AMSJob. In the AMSJob subdirectory, two files will be created: ams.rkf and vasp.rkf, that contain some of the results from the VASP calculation. If the AMSJob subdirectory already exists, the existing ams.rkf and vasp.rkf files will be reused. NOTE: the purpose of loading VASP data this way is to let you call for example job.results.get_energy() etc., not to run new VASP calculations!

classmethod from_input(text_input, **kwargs)[source]

Create an AMS job from AMS-style text input.

Parameters:

  • text_input (str) – complete AMS input

  • kwargs (Any) – additional AMSJob constructor arguments

Returns:

job containing the parsed settings and systems

Raises:

  • ImportError – if the SCM input parser is unavailable

  • JobError – if molecules are supplied both in the input and as a keyword argument

Return type:

AMSJob

Example:

text = '''
Task GeometryOptimization
Engine DFTB
    Model GFN1-xTB
EndEngine
'''

job = AMSJob.from_input(text)

Note

If molecule is included in the keyword arguments to this method, the text_input may not contain any System blocks. In other words, the molecules to be used either need to come from the text_input, or the keyword argument, but not both.

If settings is included in the keyword arguments to this method, the Settings created from the text_input will be soft updated with the settings from the keyword argument. In other words, the text_input takes precedence over the settings keyword argument.

classmethod from_inputfile(filename, heredoc_delimit='eor', **kwargs)[source]

Construct an AMSJob instance from an AMS input or run file.

If a runscript is provided, this method attempts to extract the input based on the heredoc delimiter (see heredoc_delimit).

Parameters:

  • filename (str) – path to the input or run file

  • heredoc_delimit (str) – heredoc delimiter used by a run file

  • kwargs (Any) – additional arguments forwarded to from_input()

Returns:

job containing the parsed input

Return type:

AMSJob

static settings_to_mol(s)[source]

Remove the s.input.ams.system block and convert it to molecules.

The provided settings should be in the same style as the ones produced by the SCM input parser. Dictionary keys are taken from the header of each system block. The existing s.input.ams.system block is removed in the process, assuming it was present in the first place.

Parameters:

s (Settings) – settings produced by the SCM input parser

Returns:

molecules keyed by System-block header, or None if no System block is present

Raises:

KeyError – if multiple System blocks use the same header

Return type:

Dict[str, Molecule] | None

AMSResults API

class AMSResults(*args, **kwargs)[source]

Results from an AMS calculation.

Methods with a unit argument convert numerical results to that unit.

Methods that expose RKF variables directly, including readrkf(), read_rkf_section(), and get_history_property(), return values in their RKF storage units without conversion.

When running with amspython, use AKFReader to inspect the unit and metadata of an RKF variable:

from scm.akfreader import AKFReader

reader = AKFReader(results.rkfpath("engine"))
print(reader.units("AMSResults%Energy"))
print(reader.description("AMSResults%Energy"))
Parameters:

  • args (Any) –

  • kwargs (Any) –

class EnergyLandscape(results)[source]

Stationary points, fragments, and connectivity from a PES exploration.

Integer indexing uses one-based state identifiers; iteration follows landscape order.

Parameters:

results (AMSResults) – AMS results containing an EnergyLandscape section, or None to create an empty landscape

class Fragment(landscape, engfile, energy, mol)[source]

An isolated fragment represented in an energy landscape.

energy is in hartree, and molecule coordinates and lattice vectors are in angstrom. The id property is a one-based identifier.

Parameters:

  • landscape (AMSResults.EnergyLandscape) – containing energy landscape

  • engfile (str) – engine RKF identifier for this fragment

  • energy (float) – fragment energy in hartree

  • mol (Molecule) – fragment geometry

__str__()[source]

Return str(self).

Return type:

str

__weakref__

list of weak references to the object (if defined)

property id: int

Return the one-based fragment identifier.

class FragmentedState(landscape, energy, composition, connections=None, adsorptionPrefactors=None, desorptionPrefactors=None)[source]

A state composed of multiple isolated fragments.

energy is in hartree, and the id property is a one-based identifier. Composition and connection values are stored internally as zero-based indices. Adsorption prefactors are in (bar*s)^-1 and desorption prefactors are in s^-1.

Parameters:

  • landscape (AMSResults.EnergyLandscape) – containing energy landscape

  • energy (float) – fragmented-state energy in hartree

  • composition (Sequence[int]) – zero-based fragment indices

  • connections (Sequence[int] | None) – zero-based connected-state indices

  • adsorptionPrefactors (Sequence[float] | None) – adsorption prefactors in (bar*s)^-1 for the connections

  • desorptionPrefactors (Sequence[float] | None) – desorption prefactors in s^-1 for the connections

__str__()[source]

Return str(self).

Return type:

str

__weakref__

list of weak references to the object (if defined)

property fragments: List[Fragment]

Return the fragments that compose this state.

property id: int

Return the one-based fragmented-state identifier.

class State(landscape, engfile, energy, mol, count, isTS, reactantsID=None, productsID=None, prefactorsFromReactant=None, prefactorsFromProduct=None)[source]

A local minimum or transition state in an energy landscape.

energy is in hartree, and molecule coordinates and lattice vectors are in angstrom. id, display_id, reactantsID, and productsID are one-based identifiers.

Parameters:

  • landscape (AMSResults.EnergyLandscape) – containing energy landscape

  • engfile (str) – engine RKF identifier for this state

  • energy (float) – state energy in hartree

  • mol (Molecule) – state geometry

  • count (int) – number of times the state was found

  • isTS (bool) – whether the state is a transition state

  • reactantsID (int | None) – one-based reactant-state identifier

  • productsID (int | None) – one-based product-state identifier

  • prefactorsFromReactant (float | None) – forward rate prefactor in s^-1

  • prefactorsFromProduct (float | None) – backward rate prefactor in s^-1

  • originalID – identifier displayed for a state copied to a sub-landscape

__str__()[source]

Return str(self).

Return type:

str

__weakref__

list of weak references to the object (if defined)

property id: int

Return the one-based state identifier.

property products: State | None

Return the product state connected to this transition state.

property reactants: State | None

Return the reactant state connected to this transition state.

__str__()[source]

Return str(self).

Return type:

str

__weakref__

list of weak references to the object (if defined)

property fragmented_states: List[FragmentedState]

Return all fragmented states.

Returns:

fragmented states in landscape order

property fragments: List[Fragment]

Return all isolated fragments.

Returns:

isolated fragments in landscape order

property minima: List[State]

Return all local-minimum states.

Returns:

local minima in landscape order

property transition_states: List[State]

Return all transition states.

Returns:

transition states in landscape order

are_orbitals_fractionally_occupied(engine=None)[source]

Return whether fractional orbital occupations were detected.

In this case the HOMO and LUMO labels depend on an arbitrary occupied/empty demarcation.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

dimensionless boolean indicating whether fractional occupations are present

Return type:

bool

collect()[source]

Collect the job files and create an KFFile instance for each RKF file.

Engine result files are discovered through ams.rkf and stored in rkfs under their filenames without the .rkf extension. This method is called automatically when job execution finishes.

Return type:

None

collect_rkfs()[source]

Collect the RKF files referenced by the main ams.rkf file.

Populate rkfs with the main file under ams and engine files under their filename without the .rkf extension. Log a warning when ams.rkf is unavailable.

Return type:

None

engine_names()[source]

Return the identifiers of all engine-specific RKF files.

Returns:

engine result identifiers, excluding the main ams.rkf file

Return type:

List[str]

get_ase_atoms(section, file='ams')[source]

Return an ASE Atoms object stored in an RKF section.

Positions and cell vectors are in angstrom.

Parameters:

  • section (str) – name of the RKF section containing the system

  • file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

ASE atoms reconstructed from the RKF section

Return type:

AseAtoms

get_atom_types(engine=None)[source]

Return the force-field atom type of each atom.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

atom types in system order

Return type:

List[str]

get_atomic_temperatures_at_step(step, history_section='MDHistory')[source]

Return the atomic temperatures at a trajectory step.

Parameters:

  • step (int) – one-based trajectory step number

  • history_section (str) – section containing the velocities

Returns:

array of shape (n_atoms,) containing temperatures in kelvin, or None if ams.rkf is unavailable

Return type:

ndarray | None

get_band_structure(bands=None, unit='hartree', only_high_symmetry_points=False)[source]

Return the electronic band structure from a DFTB, BAND, or Quantum ESPRESSO calculation.

For unrestricted calculations, alternating stored bands belong to the spin-up and spin-down channels. The returned values can be passed to plot_band_structure.

Parameters:

  • bands (Sequence[int] | None) – zero-based band indices to return, or None for all bands

  • unit (str) – energy unit for band and Fermi energies, defaults to hartree

  • only_high_symmetry_points (bool) – return only the first point of each path edge

Returns:

path coordinates, spin-up energies, spin-down energies, point labels, and Fermi energy. Energy arrays have shape (len(x), len(bands)); for restricted calculations the two arrays are identical. Labels are empty for points that are not high-symmetry points.

Return type:

Tuple[ndarray, ndarray, ndarray, List[str], float]

get_bulkmodulus(unit='au', engine=None)[source]

Return the bulk modulus from AMSResults%BulkModulus.

Parameters:

  • unit (str) – pressure unit of the returned modulus, defaults to au (hartree/bohr^3); GPa is a commonly used alternative

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

bulk modulus as a scalar in unit

Return type:

float

get_charges(engine=None)[source]

Return the atomic charges in elementary-charge units.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_atoms,) in elementary-charge units, e

Return type:

ndarray

get_density_along_axis(axis='z', density_type='mass', start_fs=0, end_fs=None, every_fs=None, bin_width=0.1, atom_indices=None)[source]

Calculate the atomic density along a Cartesian coordinate axis.

This only works if the axis is perpendicular to the other two axes. The system must be 3D-periodic and the number of atoms cannot change during the trajectory.

Parameters:

  • axis (str) – Cartesian axis, one of x, y, or z

  • density_type (str) – mass for g/cm^3, number for angstrom^-3, or histogram for the mean number of atoms per frame and bin

  • start_fs (float) – start time in femtoseconds

  • end_fs (float | None) – end time in femtoseconds, or None for the end of the trajectory

  • every_fs (float | None) – sampling interval in femtoseconds, or None for every frame

  • bin_width (float) – target bin width in angstrom

  • atom_indices (Sequence[int] | None) – one-based atom indices, or None for all atoms

Returns:

bin-center coordinates in angstrom and the selected density

Return type:

Tuple[ndarray, ndarray]

get_diffusion_coefficient_from_velocity_acf(times=None, acf=None, n_dimensions=3)[source]

Integrate a velocity autocorrelation function to obtain a diffusion coefficient.

If times or acf is None, then a default velocity autocorrelation function will be calculated.

Parameters:

  • times (ndarray | None) – correlation times in femtoseconds

  • acf (ndarray | None) – velocity autocorrelation in angstrom^2/fs^2

  • n_dimensions (int) – number of spatial dimensions included in the autocorrelation

Returns:

times in femtoseconds and cumulative diffusion coefficients in m^2/s

Return type:

Tuple[ndarray, ndarray]

get_dipole_derivatives_acf(start_fs=0, end_fs=None, every_fs=None, max_dt_fs=None, x=True, y=True, z=True, normalize=False)[source]

Calculate the autocorrelation function of the dipole derivative.

Parameters:

  • start_fs (float) – start time in femtoseconds, defaults to 0

  • end_fs (float | None) – end time in femtoseconds, defaults to the end of the trajectory

  • every_fs (float | None) – sampling interval in femtoseconds, defaults to every frame

  • max_dt_fs (float | None) – maximum correlation time in femtoseconds

  • x (bool) – include the x component, defaults to True

  • y (bool) – include the y component, defaults to True

  • z (bool) – include the z component, defaults to True

  • normalize (bool) – normalize the autocorrelation function to one at time zero, defaults to False

Returns:

tuple containing the correlation times in femtoseconds and the dipole-derivative autocorrelation function. A normalized autocorrelation function is dimensionless; otherwise its unit is (e*bohr/fs)^2.

Return type:

Tuple[ndarray, ndarray]

get_dipole_history(dipole_unit='e*bohr')[source]

Return the molecular dipole moment for each saved frame.

Parameters:

dipole_unit (str) – dipole-moment unit of the returned values, defaults to e*bohr

Returns:

array of shape (n_frames, 3) in dipole_unit

Return type:

ndarray

get_dipolegradients(engine=None)[source]

Return the nuclear gradients of the electric dipole moment.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (3 * n_atoms, 3) in the atomic unit of dipole derivative, equivalent to e

Return type:

ndarray

get_dipolemoment(engine=None)[source]

Return the electric dipole moment in e*bohr.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (3,) containing the Cartesian components in e*bohr

Return type:

ndarray

get_elastictensor(engine=None)[source]

Return the elastic tensor in Voigt notation from AMSResults%ElasticTensor.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array with shape (1, 1), (3, 3), or (6, 6) for 1D, 2D, or 3D periodicity, respectively, in hartree/bohr^n_lattice_vectors

Return type:

ndarray

get_energy(unit='hartree', engine=None)[source]

Return the final energy from AMSResults%Energy.

The meaning of the final energy depends on the engine; see the corresponding engine documentation.

Parameters:

  • unit (str) – energy unit of the returned value, defaults to hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

final energy as a scalar in unit

Return type:

float

get_energy_landscape()[source]

Return the energy landscape from an AMS PES exploration.

The returned object is of the type AMSResults.EnergyLandscape and offers convenient access to the states’ energies, geometries as well as the information on which transition states connect which minima. State and fragment energies are in hartree, while molecular coordinates are in angstrom.

el = results.get_energy_landscape()
print(el)

for state in el:
    print(f"Energy = {state.energy} hartree")
    print(f"Is transition state = {state.isTS}")
    print("Geometry:", state.molecule)
    if state.isTS:
        print(f"Forward  barrier: {state.energy - state.reactants.energy} hartree")
        print(f"Backward barrier: {state.energy - state.products.energy} hartree")
Returns:

stationary points, fragments, and their connectivity

Return type:

EnergyLandscape

get_energy_uncertainty(unit='hartree', engine=None)[source]

Return the final energy uncertainty from AMSResults%EnergyUncertainty.

The meaning of the uncertainty depends on the engine; see the corresponding engine documentation.

Parameters:

  • unit (str) – energy unit of the returned value, defaults to hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

final energy uncertainty as a scalar in unit

Return type:

float

get_engine_properties(engine=None)[source]

Return the Properties section of an engine RKF file.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

mapping from property names to stored values, without unit conversion; each value’s type, shape, and unit depend on the property

Return type:

Dict

get_engine_results(engine=None)[source]

Return the AMSResults section of an engine RKF file.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

mapping from variable names to stored values, without unit conversion; each value’s type, shape, and unit depend on the variable

Return type:

Dict

get_errormsg()[source]

Return an error message for the associated job.

See Job.get_errormsg for more information.

Returns:

error message, or None for a successful job

Return type:

str | None

get_exit_condition_message()[source]

Return the driver exit-condition message.

Returns:

stored message, or an empty string if none is available

Return type:

str

get_force_constants(engine=None)[source]

Return the vibrational force constants.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) in hartree/bohr^2

Return type:

ndarray

get_forcefield_params(engine=None)[source]

Return force-field information from an engine RKF file.

Parameters:

engine (str | None) – engine RKF file identifier, defaults to the unique main engine

Returns:

tuple containing the atomic charges in elementary-charge units, the force-field atom type for each atom, and the combined ForceFieldPatch. The patch is None when the RKF file contains no patches.

Return type:

Tuple[List[float], List[str], ForceFieldPatch | None]

get_frequencies(unit='cm^-1', engine=None)[source]

Return the vibrational frequencies.

Parameters:

  • unit (str) – unit for the returned frequencies, defaults to cm^-1

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) containing frequencies in unit

Return type:

ndarray

get_frequency_spectrum(engine=None, broadening_type='gaussian', broadening_width=40, min_x=0, max_x=4000, x_spacing=0.5, post_process=None)[source]

Return a broadened vibrational-frequency spectrum with unit mode intensities.

Height-normalized profiles produce a dimensionless spectrum. Area-normalized profiles produce a spectrum in (cm^-1)^-1. With max_to_1, the spectrum is dimensionless.

Parameters:

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

  • broadening_type (Literal['gaussian', 'lorentzian']) – line shape and whether unit weights define peak heights or integrated areas

  • broadening_width (int) – broadening width in cm^-1

  • min_x (int) – lower frequency-grid bound in cm^-1

  • max_x (int) – upper frequency-grid bound in cm^-1

  • x_spacing (float) – frequency-grid spacing in cm^-1

  • post_process (Literal['max_to_1'] | None) – normalize the spectrum maximum to one, or None

Returns:

frequency grid in cm^-1 and broadened unit-weight intensities

Return type:

Tuple[ndarray, ndarray]

get_gradients(energy_unit='hartree', dist_unit='bohr', engine=None)[source]

Return the final nuclear energy gradients from AMSResults%Gradients.

These values are energy gradients, not forces. Forces are the negative gradients.

Parameters:

  • energy_unit (str) – energy unit of the returned gradients, defaults to hartree

  • dist_unit (str) – distance unit of the returned gradients, defaults to bohr

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

gradient array of shape (n_atoms, 3) in energy_unit / dist_unit

Return type:

ndarray

get_gradients_magnitude_uncertainty(energy_unit='hartree', dist_unit='bohr', engine=None)[source]

Return the propagated uncertainty of each final-gradient magnitude.

The values are read from AMSResults%GradientsMagnitudeUncertainty.

Parameters:

  • energy_unit (str) – energy unit of the returned uncertainties, defaults to hartree

  • dist_unit (str) – distance unit of the returned uncertainties, defaults to bohr

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

uncertainty array of shape (n_atoms,) in energy_unit / dist_unit

Return type:

ndarray

get_gradients_uncertainty(energy_unit='hartree', dist_unit='bohr', engine=None)[source]

Return the final-gradient uncertainties from AMSResults%GradientsUncertainty.

Parameters:

  • energy_unit (str) – energy unit of the returned uncertainties, defaults to hartree

  • dist_unit (str) – distance unit of the returned uncertainties, defaults to bohr

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

uncertainty array of shape (n_atoms, 3) in energy_unit / dist_unit

Return type:

ndarray

get_green_kubo_viscosity(start_fs=0, end_fs=None, every_fs=None, max_dt_fs=None, xy=True, yz=True, xz=True, pressuretensor=None)[source]

Calculate viscosity from the off-diagonal pressure-tensor autocorrelation function.

Parameters:

  • start_fs (float) – start time in femtoseconds

  • end_fs (float | None) – end time in femtoseconds, or None for the end of the trajectory

  • every_fs (float | None) – sampling interval in femtoseconds, or None for every frame

  • max_dt_fs (float | None) – maximum correlation time in femtoseconds

  • xy (bool) – include the xy pressure-tensor component

  • yz (bool) – include the yz pressure-tensor component

  • xz (bool) – include the xz pressure-tensor component

  • pressuretensor (ndarray | None) – pressure tensors in hartree/bohr^3 with shape (n_frames, 6), or None to read them from ams.rkf

Returns:

integration times in femtoseconds and cumulative viscosity in mPa*s

Return type:

Tuple[ndarray, ndarray]

get_hessian(engine=None)[source]

Return the Cartesian nuclear Hessian from AMSResults%Hessian.

The matrix contains ordinary second derivatives of the total energy and is not mass-weighted.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (3 * n_atoms, 3 * n_atoms) in hartree/bohr^2

Return type:

ndarray

get_history_length(history_section='History')[source]

Return the number of entries in an ams.rkf history section.

Parameters:

history_section (str) – history section name

Returns:

value of nEntries in the selected section

Return type:

int

get_history_molecule(step)[source]

Return the molecule at a trajectory step from the History section of ams.rkf.

All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored. Coordinates and lattice vectors in the returned molecule are in angstrom.

Parameters:

step (int) – one-based history step number

Returns:

molecule at the requested step, or None if ams.rkf is unavailable

Raises:

  • KeyError – if the requested step is outside the stored history

  • ResultsError – if the stored coordinates and molecular system have different sizes

Return type:

Molecule | None

get_history_property(varname, history_section='History')[source]

Return all saved values of a history variable.

Parameters:

  • varname (str) – variable name without the entry index

  • history_section (str) – history section name

Returns:

stored values for all entries, without unit conversion, or None if the file or entry count is unavailable; each value’s type, shape, and unit depend on the variable

Raises:

KeyError – if the requested history section does not exist

Return type:

List | None

get_history_variables(history_section='History')[source]

Return the variable names stored in an ams.rkf history section.

Parameters:

history_section (str) – history section name, such as History or MDHistory

Returns:

variable names, or None if ams.rkf is unavailable

Return type:

Set[str] | None

get_homo_energies(unit='Hartree', engine=None)[source]

Return the HOMO energy of each spin channel.

See also are_orbitals_fractionally_occupied().

Parameters:

  • unit (str) – energy unit for the returned values, defaults to Hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_spin,) containing HOMO energies in unit

Return type:

ndarray

get_input_molecule()[source]

Return a Molecule instance with the initial coordinates.

All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored.

Returns:

input structure reconstructed from ams.rkf, with coordinates and lattice vectors in angstrom

Return type:

Molecule

get_input_molecules()[source]

Return a dictionary mapping the name strings from the AMS input file to Molecule instances.

The main molecule (aka the one that did not have a string in the block header in the input file) will be returned under the key of the empty string “”. All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored.

Returns:

input molecules keyed by their System-block names, with coordinates and lattice vectors in angstrom; the unnamed main system uses an empty key

Return type:

Dict[str, Molecule]

get_input_system()[source]

Return a ChemicalSystem instance with the initial coordinates.

All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored.

Note that ChemicalSystem is only available within AMS python. If unavailable, the call will raise an error.

Returns:

input system reconstructed from ams.rkf, with coordinates and lattice vectors in angstrom

Return type:

ChemicalSystem

get_ir_intensities(engine=None)[source]

Return the IR intensities in km/mol.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) in km/mol

Return type:

ndarray

get_ir_spectrum(engine=None, broadening_type='gaussian', broadening_width=40, min_x=0, max_x=4000, x_spacing=0.5, post_process=None)[source]

Return a broadened IR spectrum.

Frequencies are in cm^-1. Height-normalized profiles produce intensities in km/mol; area-normalized profiles produce intensities in (km/mol)/(cm^-1). With all_intensities_to_1, the physical intensities are replaced by unit weights, giving a dimensionless height profile or an area profile in (cm^-1)^-1. With max_to_1, the spectrum is dimensionless.

Parameters:

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

  • broadening_type (Literal['gaussian', 'lorentzian']) – line shape and whether line intensities define peak heights or integrated areas

  • broadening_width (int) – broadening width in cm^-1

  • min_x (int) – lower frequency-grid bound in cm^-1

  • max_x (int) – upper frequency-grid bound in cm^-1

  • x_spacing (float) – frequency-grid spacing in cm^-1

  • post_process (Literal['all_intensities_to_1', 'max_to_1'] | None) – replace line intensities with one, normalize the spectrum maximum, or None

Returns:

frequency grid in cm^-1 and broadened intensities in the convention described above

Return type:

Tuple[ndarray, ndarray]

get_ir_spectrum_md(times=None, acf=None, max_dt_fs=None, max_freq=5000, number_of_points=None)[source]

Calculate an IR spectrum from a dipole-derivative autocorrelation function.

If times or acf is omitted, a normalized dipole-derivative autocorrelation function is calculated.

Parameters:

  • times (ndarray | None) – correlation times in femtoseconds, such as those returned by get_dipole_derivatives_acf()

  • acf (ndarray | None) – dipole-derivative autocorrelation function

  • max_dt_fs (float | None) – maximum correlation time in femtoseconds used when calculating the default autocorrelation function

  • max_freq (float | None) – maximum returned frequency in cm^-1, defaults to 5000

  • number_of_points (int | None) – number of spectrum points, defaults to a spacing of approximately 1 cm^-1

Returns:

tuple containing the frequencies in cm^-1 and the IR intensities. The internally generated normalized autocorrelation function gives arbitrary intensity units. When an autocorrelation function is supplied, the numerical scale follows that function.

Return type:

Tuple[ndarray, ndarray]

get_irc_results(molecules=True, unit='au')[source]

Return the converged points from an intrinsic reaction coordinate calculation.

IRCGradMax and IRCGradRms are returned in their RKF storage convention. AMS uses mass-weighted atomic units during IRC steps and ordinary atomic units during final minimization.

Parameters:

  • molecules (bool) – include Molecules with the converged structures

  • unit (str) – energy unit for energies and barriers, defaults to au

Returns:

dictionary containing Energies, RelativeEnergies, LeftBarrier, and RightBarrier in unit; PathLength and ArcLength in angstrom; dimensionless IRCIteration and one-based HistoryIndices; IRCDirection values; IRCGradMax and IRCGradRms in the convention above; and, when molecules is True, Molecules with coordinates in angstrom

Return type:

Dict[str, Any]

get_lumo_energies(unit='Hartree', engine=None)[source]

Return the LUMO energy of each spin channel.

See also are_orbitals_fractionally_occupied().

Parameters:

  • unit (str) – energy unit for the returned values, defaults to Hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_spin,) containing LUMO energies in unit

Return type:

ndarray

get_main_ase_atoms(get_results=False)[source]

Return an ASE Atoms instance with the final coordinates.

Positions and cell vectors are in angstrom. When results are attached, ASE conventions are used: energy is in eV, forces in eV/angstrom, stress in eV/angstrom^3, and charges in elementary-charge units.

Parameters:

get_results (bool) – attach available energy, forces, stress, and charges through an ASE SinglePointCalculator

Returns:

final structure as an ASE Atoms instance

Return type:

AseAtoms

get_main_engine_name()[source]

Return the identifier of the main engine result file.

Geometry-optimization step files and Hybrid subengine files are excluded. For molecular dynamics, the most recent MDStep file is selected.

Returns:

main engine result identifier

Raises:

ValueError – if no unique main engine result file can be determined

Return type:

str

get_main_molecule()[source]

Return a Molecule instance with the final coordinates.

All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored.

Returns:

final structure reconstructed from ams.rkf, with coordinates and lattice vectors in angstrom

Return type:

Molecule

get_main_system()[source]

Return a ChemicalSystem instance with the final coordinates.

All data used by this method is taken from ams.rkf file. The molecule attribute of the corresponding job is ignored.

Note that ChemicalSystem is only available within AMS python. If unavailable, the call will raise an error.

Returns:

final system reconstructed from ams.rkf, with coordinates and lattice vectors in angstrom

Return type:

ChemicalSystem

get_molecule(section, file='ams')[source]

Return a Molecule stored in an RKF section.

All data used by this method is taken from the chosen .rkf file. The molecule attribute of the corresponding job is ignored. Coordinates and lattice vectors in the returned molecule are in angstrom.

Parameters:

  • section (str) – name of the RKF section containing the molecule

  • file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

molecule reconstructed from the RKF section

Raises:

ValueError – if the section does not contain a molecule

Return type:

Molecule

get_n_spin(engine=None)[source]

Return the number of stored spin channels.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

dimensionless integer; one for restricted or spin-orbit calculations and two for unrestricted calculations

Return type:

int

get_neb_results(molecules=True, unit='au')[source]

Return results from a nudged elastic band calculation.

Parameters:

  • molecules (bool) – include Molecules with all structures, including endpoints

  • unit (str) – energy unit for Energies, barriers, and reaction energy, defaults to au

Returns:

dictionary containing dimensionless nImages and nIterations counts; the Climbing flag; HighestIndex; Energies, LeftBarrier, RightBarrier, and ReactionEnergy in unit; one-based HistoryIndices; and, when molecules is True, Molecules with coordinates in angstrom. nImages excludes the endpoints, while Energies and Molecules include them.

Return type:

Dict[str, Any]

get_normal_modes(engine=None, mass_weighted_hessian_eigenvectors=False)[source]

Return the normal-mode displacement vectors.

By default, return the unweighted Cartesian displacement vectors stored in Vibrations%NoWeightNormalMode. If mass_weighted_hessian_eigenvectors is enabled, scale each atomic displacement by the square root of the ratio between its atomic mass and the mode’s reduced mass.

Parameters:

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

  • mass_weighted_hessian_eigenvectors (bool | None) – return mass-weighted Hessian eigenvectors

Returns:

dimensionless array of shape (n_normal_modes, n_atoms, 3)

Return type:

ndarray

get_orbital_energies(unit='Hartree', engine=None)[source]

Return the orbital energies for each spin channel.

Parameters:

  • unit (str) – energy unit for the returned values, defaults to Hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_spin, n_orbitals) in unit

Return type:

ndarray

get_orbital_occupations(engine=None)[source]

Return the orbital occupations for each spin channel.

Restricted occupations range from zero to two; unrestricted and spin-orbit occupations range from zero to one.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

dimensionless array of shape (n_spin, n_orbitals)

Return type:

ndarray

get_pesscan_results(molecules=True)[source]

Return scan coordinates, energies, and convergence data for a PES scan.

Parameters:

molecules (bool) – include Molecules with one structure per PES point

Returns:

dictionary containing:

  • RaveledScanCoords and ScanCoords: flat and grouped scan-coordinate names

  • nRaveledScanCoords and nScanCoords: corresponding dimensionless counts

  • RaveledUnits and Units: corresponding units, chosen from bohr, bohr^2, bohr^3, and radian according to coordinate type

  • RaveledPESCoords: values for every flat coordinate in its RaveledUnits entry

  • OrigScanCoords: grouped names in their newline-separated RKF representation

  • nPESPoints: dimensionless number of PES points

  • PES: energies in hartree

  • Converged: geometry-optimization convergence flags

  • HistoryIndices: one-based indices into the History section

  • ConstrainedAtoms: one-based indices of atoms occurring in scan coordinates

  • Properties: engine properties in their RKF storage units; populated when CalcPropertiesAtPESPoints was enabled

  • Molecules: structures with coordinates in angstrom, present only when molecules is True

Return type:

Dict[str, Any]

get_phonons_band_structure(bands=None, unit='hartree', only_high_symmetry_points=False)[source]

Return the phonon band structure.

The returned values can be passed directly to plot_phonons_band_structure().

Parameters:

  • bands (Sequence[int] | None) – zero-based band indices to return, defaults to all bands

  • unit (str) – energy unit for the phonon bands, defaults to hartree

  • only_high_symmetry_points (bool) – return only the first point of each path edge, defaults to False

Returns:

tuple containing the one-dimensional reciprocal-path plotting coordinate, an array of shape (len(x), len(bands)) with the phonon band energies in unit, and the labels for the points in x. Each column in the energy array is a band. Non-high-symmetry points have an empty label.

Return type:

Tuple[ndarray, ndarray, List[str]]

get_phonons_dos(unit='hartree')[source]

Return the phonon density of states (DOS).

The returned values can be passed directly to plot_phonons_dos().

Parameters:

unit (str) – energy unit for the energy grid, defaults to hartree

Returns:

tuple containing the one-dimensional energy grid in unit, the total DOS in 1 / unit, the DOS per species in 1 / unit, and the DOS per atom in 1 / unit. The decomposed DOS values are dictionaries of one-dimensional arrays. They are empty when the corresponding decomposition is absent. Atom keys contain the species and one-based atom index.

Return type:

Tuple[ndarray, ndarray, Dict[str, ndarray], Dict[str, ndarray]]

get_phonons_thermodynamic_properties(temperature_unit='K', properties_unit=('hartree', 'kB'))[source]

Return phonon thermodynamic properties as functions of temperature.

Parameters:

  • temperature_unit (str) – unit for the returned temperatures, defaults to K. This may be K or an energy-equivalent unit supported by Units.

  • properties_unit (Sequence[str]) – two-element sequence containing the energy unit for internal and free energies, followed by the unit for specific heat and entropy, defaults to ("hartree", "kB"). The second value may be kB, J/K, J/K/mol, eV/K, or eV/K/mol.

Returns:

tuple containing a one-dimensional temperature array in temperature_unit, a dictionary of property arrays, and a dictionary specifying the unit of each property. Possible property keys are Internal Energy, Free Energy, Specific Heat, and Entropy.

Return type:

Tuple[ndarray, Dict[str, ndarray], Dict[str, str]]

get_poissonratio(engine=None)[source]

Return the dimensionless Poisson ratio from AMSResults%PoissonRatio.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

Poisson ratio as a dimensionless scalar

Return type:

float

get_polarizability(engine=None)[source]

Return the polarizability in (e * bohr)^2 / hartree.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

symmetric Cartesian tensor of shape (3, 3)

Raises:

ValueError – if the stored polarizability has an unsupported shape

Return type:

ndarray

get_power_spectrum(times=None, acf=None, max_dt_fs=None, max_freq=None, number_of_points=None)[source]

Calculate a power spectrum from the velocity autocorrelation function.

If times or acf is None, then a default velocity autocorrelation function will be calculated.

Parameters:

  • times (ndarray | None) – correlation times in femtoseconds, as returned by get_velocity_acf()

  • acf (ndarray | None) – velocity autocorrelation function

  • max_dt_fs (float | None) – maximum correlation time in femtoseconds used for the default autocorrelation function

  • max_freq (float | None) – maximum returned frequency in cm^-1, defaults to 5000

  • number_of_points (int | None) – number of spectrum points, defaults to approximately 1 cm^-1 spacing

Returns:

frequencies in cm^-1 and corresponding intensities. The internally generated normalized autocorrelation function gives arbitrary intensity units; for a supplied autocorrelation function, the numerical scale follows that function.

Return type:

Tuple[ndarray, ndarray]

get_property_at_step(step, varname, history_section='History')[source]

Return a history variable at one step.

Parameters:

  • step (int) – one-based history step number

  • varname (str) – variable name without the entry index

  • history_section (str) – history section name

Returns:

stored value without unit conversion, or None if ams.rkf is unavailable; its type, shape, and unit depend on the variable

Return type:

TRead | None

get_pvdos(engine=None)[source]

Return the partial vibrational density of states (PVDOS).

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

dimensionless array of shape (n_normal_modes, n_atoms) with values between zero and one

Return type:

ndarray

get_raman_intensities(engine=None)[source]

Return the Raman intensities in angstrom^4/amu.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) in angstrom^4/amu

Return type:

ndarray

get_raman_spectrum(engine=None, broadening_type='gaussian', broadening_width=40, min_x=0, max_x=4000, x_spacing=0.5, post_process=None)[source]

Return a broadened Raman spectrum.

Frequencies are in cm^-1. Height-normalized profiles produce intensities in angstrom^4/amu; area-normalized profiles produce intensities in (angstrom^4/amu)/(cm^-1). With all_intensities_to_1, the physical intensities are replaced by unit weights, giving a dimensionless height profile or an area profile in (cm^-1)^-1. With max_to_1, the spectrum is dimensionless.

Parameters:

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

  • broadening_type (Literal['gaussian', 'lorentzian']) – line shape and whether line intensities define peak heights or integrated areas

  • broadening_width (int) – broadening width in cm^-1

  • min_x (int) – lower frequency-grid bound in cm^-1

  • max_x (int) – upper frequency-grid bound in cm^-1

  • x_spacing (float) – frequency-grid spacing in cm^-1

  • post_process (Literal['all_intensities_to_1', 'max_to_1'] | None) – replace line intensities with one, normalize the spectrum maximum, or None

Returns:

frequency grid in cm^-1 and broadened intensities in the convention described above

Return type:

Tuple[ndarray, ndarray]

get_reduced_masses(engine=None)[source]

Return the vibrational reduced masses.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) in atomic mass units (amu)

Return type:

ndarray

get_rkf_skeleton(file='ams')[source]

Return the section and variable structure of an RKF file.

Parameters:

file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

mapping from section names to sets of variable names

Return type:

Dict[str, Set[str]]

get_shearmodulus(unit='au', engine=None)[source]

Return the shear modulus from AMSResults%ShearModulus.

Parameters:

  • unit (str) – pressure unit of the returned modulus, defaults to au (hartree/bohr^3); GPa is a commonly used alternative

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

shear modulus as a scalar in unit

Return type:

float

get_smallest_homo_lumo_gap(unit='Hartree', engine=None)[source]

Return the smallest HOMO-LUMO gap across spin channels.

See also are_orbitals_fractionally_occupied().

Parameters:

  • unit (str) – energy unit for the returned gap, defaults to Hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

min(LUMO) - max(HOMO) in unit

Return type:

float

get_stresstensor(engine=None)[source]

Return the clamped-ion Cartesian stress tensor from AMSResults%StressTensor.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_lattice_vectors, n_lattice_vectors) in hartree/bohr^n_lattice_vectors. This is energy per length for 1D periodicity, energy per area for 2D periodicity, and pressure for 3D periodicity.

Return type:

ndarray

get_system(section, file='ams')[source]

Return a ChemicalSystem stored in an RKF section.

All data used by this method is taken from the chosen .rkf file. The molecule attribute of the corresponding job is ignored.

Note that ChemicalSystem is only available within AMS python. If unavailable, the call will raise an error. Coordinates and lattice vectors in the returned system are in angstrom.

Parameters:

  • section (str) – name of the RKF section containing the system

  • file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

chemical system reconstructed from the RKF section

Return type:

ChemicalSystem

get_system_version(main, step)[source]

Return the chemical-system section number used at a history step.

Parameters:

  • main (KFFile) – RKF file containing the history

  • step (int) – one-based history step number

Returns:

chemical-system section number, or None if no version is stored

Return type:

int | None

get_time_step(history_section='MDHistory')[source]

Return the time between adjacent saved MD frames in femtoseconds.

This is the MD integration time step multiplied by the trajectory sampling frequency.

Parameters:

history_section (Literal['BinLog', 'MDHistory']) – history section containing the saved times, defaults to MDHistory

Returns:

time between the first two saved frames in femtoseconds

Raises:

PlamsError – if the time cannot be determined from the first two saved frames

Return type:

float

get_timings()[source]

Return job timing statistics.

Returns:

cpu, system, and elapsed times in seconds

Return type:

Dict[str, float]

get_vcd_rotational_strength(engine=None)[source]

Return the vibrational rotational strengths in 10^-44 esu^2 cm^2.

Parameters:

engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

array of shape (n_normal_modes,) in 10^-44 esu^2 cm^2

Return type:

ndarray

get_vcd_spectrum(engine=None, broadening_type='gaussian', broadening_width=40, min_x=0, max_x=4000, x_spacing=0.5, post_process=None)[source]

Return a broadened VCD rotational-strength spectrum.

Frequencies are in cm^-1. Height-normalized profiles produce intensities in 10^-44 esu^2 cm^2; area-normalized profiles produce intensities in (10^-44 esu^2 cm^2)/(cm^-1). With all_intensities_to_1, the physical intensities are replaced by unit weights, giving a dimensionless height profile or an area profile in (cm^-1)^-1. With max_to_1, the spectrum is dimensionless.

Parameters:

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

  • broadening_type (Literal['gaussian', 'lorentzian']) – line shape and whether line intensities define peak heights or integrated areas

  • broadening_width (int) – broadening width in cm^-1

  • min_x (int) – lower frequency-grid bound in cm^-1

  • max_x (int) – upper frequency-grid bound in cm^-1

  • x_spacing (float) – frequency-grid spacing in cm^-1

  • post_process (Literal['all_intensities_to_1', 'max_to_1'] | None) – replace line intensities with one, normalize the spectrum maximum, or None

Returns:

frequency grid in cm^-1 and broadened intensities in the convention described above

Return type:

Tuple[ndarray, ndarray]

get_velocity_acf(start_fs=0, end_fs=None, every_fs=None, max_dt_fs=None, atom_indices=None, x=True, y=True, z=True, normalize=False)[source]

Calculate the velocity autocorrelation function for a fixed-composition trajectory.

Parameters:

  • start_fs (float) – start time in femtoseconds

  • end_fs (float | None) – end time in femtoseconds, or None for the end of the trajectory

  • every_fs (float | None) – sampling interval in femtoseconds, or None for every frame

  • max_dt_fs (float | None) – maximum correlation time in femtoseconds

  • atom_indices (Sequence[int] | None) – one-based atom indices, or None for all atoms

  • x (bool) – include the x velocity component

  • y (bool) – include the y velocity component

  • z (bool) – include the z velocity component

  • normalize (bool) – normalize the autocorrelation function to one at time zero

Returns:

correlation times in femtoseconds and the autocorrelation function. The latter is dimensionless when normalized and otherwise in angstrom^2/fs^2.

Return type:

Tuple[ndarray, ndarray]

get_work_function_results(energy_unit='hartree', dist_unit='bohr')[source]

Return the results of a work-function calculation.

The two vacuum potentials and work functions correspond to the left and right sides of the slab, respectively. For Quantum ESPRESSO calculations using a dipole correction, the potential is evaluated immediately before the correction position.

Parameters:

  • energy_unit (str) – unit for potentials, Fermi energy, and work functions, defaults to hartree

  • dist_unit (str) – unit for the coordinate perpendicular to the surface, defaults to bohr

Returns:

coordinate in dist_unit; planar-average and macroscopic-average potentials, Fermi energy, and bulk potential in energy_unit; left and right vacuum potentials in energy_unit; and left and right work functions in energy_unit

Return type:

Tuple[ndarray, ndarray, ndarray, float, float, Tuple[float, float], Tuple[float, float]]

get_youngmodulus(unit='au', engine=None)[source]

Return Young’s modulus from AMSResults%YoungModulus.

Parameters:

  • unit (str) – pressure unit of the returned modulus, defaults to au (hartree/bohr^3); GPa is a commonly used alternative

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

Young’s modulus as a scalar in unit

Return type:

float

get_zero_point_energy(unit='hartree', engine=None)[source]

Return the vibrational zero-point energy from Vibrations%ZeroPointEnergy.

Parameters:

  • unit (str) – energy unit of the returned value, defaults to hartree

  • engine (str | None) – engine RKF identifier, or None to select the unique engine result file

Returns:

zero-point energy as a scalar in unit

Return type:

float

is_valid_stepnumber(main, step)[source]

Check whether a one-based step number is present in an RKF history.

Parameters:

  • main (KFFile) – RKF file containing the History section

  • step (int) – one-based history step number

Returns:

True when the step is present

Raises:

KeyError – if the history or requested step is absent

Return type:

bool

property name: str

Return the name of the associated job.

Returns:

job.name

ok()[source]

Check if the execution of the associated job was successful or not. See Job.ok for more information.

Returns:

whether the associated job completed successfully

Return type:

bool

read_hybrid_term_rkf(section, variable, term, file='engine')[source]

Read a variable from a Hybrid term’s subengine RKF file.

Parameters:

  • section (str) – name of the RKF section

  • variable (str) – name of the RKF variable

  • term (int) – one-based Hybrid term index

  • file (str) – identifier of the Hybrid engine RKF file

Returns:

value stored in the selected variable, without unit conversion; its type, shape, and unit depend on the variable

Return type:

TRead

read_rkf_section(section, file='ams')[source]

Return all variables from an RKF section.

Section and variable names are case-sensitive. A missing section produces an empty dictionary.

Parameters:

  • section (str) – name of the RKF section

  • file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

mapping from variable names to stored values, without unit conversion; each value’s type, shape, and unit depend on the variable

Return type:

Dict[str, TRead]

readrkf(section, variable, file='ams')[source]

Read a variable from a section of an RKF file.

Parameters:

  • section (str) – name of the RKF section; section names are case-sensitive

  • variable (str) – name of the RKF variable; variable names are case-sensitive

  • file (str) – RKF file identifier, defaults to ams. For example, use something to read something.rkf. If the job has a unique engine results file, use engine to select it.

Returns:

value stored in the RKF variable, without unit conversion; its type, shape, and unit depend on the variable

Raises:

KeyError – if the section or variable is not present in the selected RKF file

Return type:

TRead

recreate_molecule()[source]

Recreate the input molecule(s) for the corresponding job based on files present in the job folder.

This method is used by load_external(). If ams.rkf is present in the job folder, extract data from the InputMolecule and InputMolecule(*) sections.

Returns:

the input molecule or named input molecules, with coordinates and lattice vectors in angstrom; or None if they cannot be reconstructed

Return type:

None | Molecule | Dict[str, Molecule]

recreate_settings()[source]

Recreate the input Settings instance for the corresponding job based on files present in the job folder. This method is used by load_external().

If ams.rkf is present in the job folder, extract user input and parse it back to a Settings instance using scm.base module. Remove the system branch from that instance.

Returns:

reconstructed settings, or None if they cannot be reconstructed

Return type:

Settings | None

refresh()[source]

Refresh the contents of files list.

Also update the KFFile instances in rkfs if the job folder has moved since the results were pickled.

Return type:

None

rkfpath(file='ams')[source]

Return the absolute path of a chosen .rkf file.

Parameters:

file (str) – RKF file identifier. Use engine to select the unique engine result file.

Returns:

absolute path to the selected RKF file

Return type:

str

Other functions

hybrid_committee_engine_settings(settings_list)[source]

Create settings for a Hybrid committee that averages its subengines.

Parameters:

settings_list (List[Settings]) – top-level settings for each subengine

Returns:

top-level settings for the Hybrid committee engine

Return type:

Settings