ADF (pre-2020 version)¶
This page describes the old interface to the standalone ADF binary.
Starting from AMS2020, ADF is an AMS engine and should be run using
If you are running AMS2019.3 or older version, you should still use
ADF can be run from PLAMS using the
ADFJob class and the corresponding
The are subclasses of, respectively,
SCMResults, which gather common pre-AMS logic for all members of the former ADFSuite.
Input files for ADF consist of blocks and subblocks containg keys and values.
That kind of structure can be easily reflected by
Settings objects since they are built in a similar way.
The input file is generated based on
input branch of job’s
All data present there is translated to input contents.
Settings instances define blocks and subblocks, as in the example below:
myjob = ADFJob(molecule=Molecule('water.xyz')) myjob.settings.input.basis.type = 'DZP' myjob.settings.input.basis.core = 'None' myjob.settings.input.basis.createoutput = 'None' myjob.settings.input.scf.iterations = 100 myjob.settings.input.scf.converge = '1.0e-06 1.0e-06' myjob.settings.input.save = 'TAPE13'
Input file created during execution of
myjob looks like:
atoms #coordinates from water.xyz end basis createoutput None core None type DZP end save TAPE13 scf converge 1.0e-06 1.0e-06 iterations 100 end
As you can see, entries present in
myjob.settings.input. are listed in the alphabetical order.
If an entry is a regular key-value pair it is printed in one line (like
save TAPE13 above).
If an entry is a nested
Settings instance it is printed as a block and entries in this instance correspond to contents of a the block.
Both keys and values are kept in their original case.
Strings put as values can contain spaces like
converge above – the whole string is printed after the key.
That allows to handle lines that need to contain more than one key=value pair.
If you need to put a key without any value,
True or empty string can be given as a value:
>>> myjob.settings.input.geometry.SP = True >>> myjob.settings.input.writefock = '' # translates to: geometry SP end writefock
If a value of a particualr key is
False, that key is omitted.
To produce an empty block simply type:
>>> myjob.settings.input.geometry # this is equivalent to myjob.settings.input.geometry = Settings() # geometry end
The algorithm translating
Settings contents into input file does not check the correctness of the data - it simply takes keys and values from
Settings instance and puts them in the text file.
Due to that you are not going to be warned if you make a typo, use wrong keyword or improper syntax.
Beware of that.
>>> myjob.settings.input.dog.cat.apple = 'pear' # dog cat apple pear subend end
Some blocks require (or allow) some data to be put in the header line, next to the block name.
_h is helpful in these situations:
>>> myjob.settings.input.someblock._h = 'header=very important' >>> myjob.settings.input.someblock.key1 = 'value1' >>> myjob.settings.input.someblock.key2 = 'value2' # someblock header=very important key1 value1 key2 value2 end
The order of blocks within input file and subblocks within a parent block follows
Settings iteration order which is lexicographical (however,
SCMJob is smart enough to put blocks like DEFINE or UNITS at the top of the input).
In rare cases you would want to override this order, for example when you supply ATOMS block manually, which can be done when automatic molecule handling is disabled (see below).
That behavior can be achieved by another type of special key:
>>> myjob.settings.input.block._1 = 'entire line that has to be the first line of block' >>> myjob.settings.input.block._2 = 'second line' >>> myjob.settings.input.block._4 = 'I will not be printed' >>> myjob.settings.input.block.key1 = 'value1' >>> myjob.settings.input.block.key2 = 'value2' # block entire line that has to be the first line of block second line key1 value1 key2 value2 end
Sometimes one needs to put more instances of the same key within one block, like for example in CONSTRAINTS block in ADF. It can be done by using list of values instead of a single value:
>>> myjob.settings.input.constraints.atom = [1,5,4] >>> myjob.settings.input.constraints.block = ['ligand', 'residue'] # constraints atom 1 atom 5 atom 4 block ligand block residue end
Finally, in some rare cases key and value pair in the input needs to be printed in a form
key=value instead of
When value is a string starting with the equal sign, no space is inserted between key and value:
>>> myjob.settings.input.block.key = '=value' # block key=value end
Sometimes a value of a key in the input file needs to be a path to some file, usually KF file with results of some previous calculation.
Of course such a path can be given explicitly
newjob.restart = '/home/user/science/plams.12345/oldjob/oldjob.t21', but for user’s convenience instances of
SCMResults (or directly
KFFile) can be also used.
Algorithm will detect it and use an absolute path to the main KF file instead:
>>> myjob.settings.input.restart = oldjob >>> myjob.settings.input.fragment.frag1 = fragjob # restart /home/user/science/plams.12345/oldjob/oldjob.t21 fragment frag1 /home/user/science/fragmentresults/somejob/somejob.t21 end
Molecule instance stored in job’s
molecule attribute is automatically processed during the input file preparation and printed in the proper format, depending on the program.
It is possible to disable that and give molecular coordinates explicitly as entries in
Automatic molecule processing can be turned off by
myjob.settings.ignore_molecule = True.
Special atoms in ADF¶
In ADF atomic coordinates in
atoms block can be enriched with some additional information like special names of atoms (for example in case of using different isotopes) or block/fragment membership.
Since usually contents of
atoms block are generated automatically based on the
Molecule associated with a job, this information needs to be supplied inside the given
Details about every atom can be adjusted separately, by modifying attributes of a particular
Atom instance according to the following convention:
- Atomic symbol is generated based on atomic number stored in
atnumattribute of a corresponding
Atom. Atomic number 0 corresponds to the “dummy atom” for which the symbol is empty.
atom.properties.ghostexists and is
True, the above atomic symbol is prefixed with
atom.properties.nameexists, its contents are added after the symbol. Hence setting
atnumto 0 and adjusting
nameallows to put an arbitrary string as the atomic symbol.
atom.properties.adf.fragmentexists, its contents are added after atomic coordinates with
atom.properties.adf.blockexists, its contents are added after atomic coordinates with
The following example illustrates the usage of this mechanism:
>>> mol = Molecule('xyz/Ethanol.xyz') >>> mol.properties.ghost = True >>> mol.properties.name = 'D' >>> mol.properties.ghost = True >>> mol.properties.name = 'T' >>> mol.properties.atnum = 0 >>> mol.properties.name = 'J.XYZ' >>> mol.properties.atnum = 0 >>> mol.properties.name = 'J.ASD' >>> mol.properties.ghost = True >>> mol.properties.adf.fragment = 'myfragment' >>> mol.properties.adf.block = 'block1' >>> mol.properties.adf.fragment = 'frag' >>> mol.properties.adf.block = 'block2' >>> myjob = ADFJob(molecule=mol) # 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 f=myfragment 7 H 0.49999 0.86726 -0.84481 b=block1 8 H -1.04310 -0.02739 -0.80544 f=frag b=block2 9 O -0.66442 -1.15471 1.56909 end
Runscripts for ADF are very simple.
The only adjustable option (apart from usual
stdout_redirect which are common for all single jobs) is
myjob.settings.runscript.nproc, indicating the number of parallel processes to run ADF with (like with
-n flag or
NSCM environmental variable).
SCMResultssubclass for accessing the results of
Return a dictionary with all the entries from
Propertiessection in the main KF file (
Moleculeinstance based on the
Geometrysection in the main KF file (
For runs with multiple geometries (geometry optimization, transition state search, intrinsic reaction coordinate) this is the final geometry. In such a case, to access the initial (or any intermediate) coordinates please use
get_input_molecule()or extract coordinates from section
xyz 2and so on. Mind the fact that all coordinates written by ADF to
Historysection are in bohr and internal atom order:
mol = results.get_molecule(section='History', variable='xyz 1', unit='bohr', internal=True)
Moleculeinstance with initial coordinates.
All data used by this method is taken from
moleculeattribute of the corresponding job is ignored.
Return final bond energy, expressed in unit.
Return the dipole vector, expressed in unit.
Return the cartesian gradients from the ‘Gradients_InputOrder’ field of the ‘GeoOpt’ Section in the kf-file, expressed in given units. Returned value is a numpy array with shape (nAtoms,3).
_extract_hessian(section, variable, internal_order)¶
Extract Hessian from section/variable of the TAPE21 file. Reorder from internal to input order, if internal_order is
Try extracting Hessian, either analytical or numerical, whichever is present in the TAPE21 file, in the input order. Returned value is a square numpy array of size 3*nAtoms.
get_energy(unit=’au’) Return a dictionary with energy decomposition terms, expressed in unit.
The following keys are present in the returned dictionary:
XC. The sum of all the values is equal to the value returned by
get_energy(). Note that additional contributions might be included, those are up to now:
Return a numpy array of vibrational frequencies, expressed in unit.
Return a dictionary with timing statistics of the job execution. Returned dictionary contains keys
elapsed. The values are corresponding timings, expressed in seconds.
Return a list of atomic numbers, in the input order.
Get mapping from the internal atom order to the input atom order.
Recreate the input molecule for the corresponding job based on files present in the job folder. This method is used by
Parent abstract classes:
SCMJob(molecule=None, name='plamsjob', settings=None, depend=None)¶
Abstract class gathering common mechanisms for jobs with ADF Suite programs.
Initialize self. See help(type(self)) for accurate signature.
Generate the input file. This method is just a wrapper around
Generate a runscript. Returned string is of the form:
$AMSBIN/name [-n nproc] <jobname.in [>jobname.out]
nameis taken from the class attribute
-nflag is added if
[>jobname.out]is used based on
termination statusvariable from
Generalsection of main KF file equals
Calculate the hash of the input file.
Transform all contents of
setting.inputbranch into string with blocks, keys and values.
On the highest level alphabetic order of iteration is modified: keys occuring in attribute
_topare printed first. Special values can be indicated with special argument, which should be a dictionary having types of objects as keys and functions translating these types to strings as values.
Automatic handling of
moleculecan be disabled with
settings.ignore_molecule = True.
Moleculeinstance stored in
moleculeattribute and add it as relevant entries of
settings.inputbranch. Abstract method.
Return the atomic symbol of atom. Ensure proper formatting for ADFSuite input taking into account
from_inputfile(filename: str, heredoc_delimit: str = 'eor', **kwargs) → scm.plams.interfaces.adfsuite.scmjob.SCMJob¶
SCMJobinstance from an ADF inputfile.
If a runscript is provide than this method will attempt to extract the input file based on the heredoc delimiter (see heredoc_delimit).
Abstract class gathering common mechanisms for results of ADF Suite programs.
Refresh the contents of
fileslist. Use parent method from
Results, then look at all attributes that are instances of
KFFileand check if they point to existing files. If not, try to reinstantiate them with current job path (that can happen while loading a pickled job after the entire job folder was moved).
Read data from section/variable of the main KF file.
The type of the returned value depends on the type of variable defined inside KF file. It can be: single int, list of ints, single float, list of floats, single boolean, list of booleans or string.
KFFileinstance using file filename in the job folder.
>>> res = someadfjob.run() >>> tape13 = res.newkf('$JN.t13') >>> print(tape13.read('Geometry', 'xyz'))
Return a dictionary with all the entries from
Propertiessection in the main KF file.
get_molecule(section, variable, unit='bohr', internal=False, n=1)¶
Read molecule coordinates from section/variable of the main KF file.
Moleculeinstance is created by copying a molecule from associated
SCMJobinstance and updating atomic coordinates with values read from section/variable. The format in which coordinates are stored is not consistent for all programs or even for different sections of the same KF file. Sometimes coordinates are stored in bohr, sometimes in angstrom. The order of atoms can be either input order or internal order. These settings can be adjusted with unit and internal parameters. Some variables store more than one geometry, in those cases n can be used to choose the preferred one.
_get_single_value(section, variable, output_unit, native_unit='au')¶
A small method template for all the single number “get_something()” methods extracting data from main KF file. Returned value is converted from native_unit to output_unit.
Return a list of atomic numbers, in the input order. Abstract method.
Return the absolute path to the main KF file.
Check if this instance has a valid
If attr is a KF file take care of a proper path. Otherwise use parent method. See
Obtain mapping from internal atom order to the input one. Abstract method.
Reorder any iterable data from the internal atom order to the input atom order. The length of data must be equal to the number of atoms, otherwise an exception is raised. Returned value is a container of the same type as data.