4.3. Dirac

DIRAC is an ab initio quantum chemistry program for all electron relativistic calculation. It features a variety of methods including HF, MP2, DFT, CI and CC. More information about DIRAC can be found on its official website.

PLAMS offers a simple DIRAC interface and is capable of running DIRAC calculations. The relevant classes are DiracJob and DiracResults.

ADF Suite

DIRAC is not a part of ADF Suite. To run DIRAC calculations with PLAMS you need to obtain and install DIRAC manually.

4.3.1. Preparing a calculation

Preparing an instance of DiracJob follows general principles for SingleJob. Information adjusting input file is stored in myjob.settings.input branch, whereas a runscript is created based on contents of myjob.settings.runscript. The geometry of your system can be supplied in two ways. Unlike ADF or BAND, DIRAC uses two separate files, one for input settings and the other for atomic coordinates. Geometry file needs to be in .xyz format and it can be either generated automatically based on myjob.molecule or given directly by the user (see below for details).

4.3.1.1. Input

Input files for DIRAC are organized using blocks and subblocks with three level hierarchy. On the top level there are blocks (indicated by keywords starting with **) which can contain keys (starting with .) or subblocks (starting with *), which in turn can contain more keys. This structure can be easily reflected with tree-like Settings objects. In general, the preparation process is quite similar to SCMJob, however, there are a few nuances. The details are explained below.

  • Each key present on the top level of myjob.settings.input is translated to a block. Values of those keys should be Settings instances. The block DIRAC is always printed as the first one, all other are ordered lexicographically (this behavior can be changed with DiracJob._top class attribute).

  • In each block various keys and subblocks can be present. Subblocks are indicated by nested Settings instances, all other values are interpreted as keys.

  • An empty value of a key can be obtained by setting its value to True.

  • An empty block or subblock can be obtained with an empty Settings instance.

  • If the value of a key is a list, each element of this list will be printed in a separate line.

  • All keywords are written to the input file with upper case, values remain unchanged.

  • Many DIRAC keywords contain spaces (for example WAVE FUNCTION or LINEAR RESPONSE) and thus cannot be used with convenient dot notation. Usual bracket notation has to be used in those cases (see Dot notation).

  • Some subblocks follow the special requirement - they need to be “enabled” by presence of the corresponding keyword in the parent block. For example, in **HAMILTONIAN block a subblock *FDE can be used to specify frozen density embedding parameters, but this subblock is taken into account only if a key .FDE is present in **HAMILTONIAN. This introduces a problem, since you cannot store two entries with the same name in Settings:

    >>> myjob.setting.input.hamiltonian.fde = True   #sets the .FDE key on the top level of HAMILOTNIAN block
>>> myjob.setting.input.hamiltonian.fde.frdens = 'value2'   #sets the *FDE subblock in the HAMILTONIAN block, but overwrites the key .FDE defined above

    To solve this problem a special “enabler” key _en can be used inside the subblock. If such a key is present, the parent block of this subblock will be enriched with corresponding key and value:

    >>> myjob.setting.input.hamiltonian.fde._en = True   #sets the .FDE key on the top level of HAMILOTNIAN block, its value can be set just like any other key
>>> myjob.setting.input.hamiltonian.fde.frdens = 'value2'   #sets the "proper" contents of *FDE subblock.

4.3.1.2. Runscript

Calculations with DIRAC are executed using a start script called pam. This script accepts a range of option flags adjusting various technical aspects of calculation, including input and geometry files. You can type pam -h in you command line for details.

A runscript calling pam is automatically generated by PLAMS. Its contents are based on myjob.settings.runscript branch and follow general rules described in Contents of job’s settings. Besides that, the subbranch myjob.settings.runscript.pam is used to store option flags. Every key-value pair present there is transformed to --key=value flag appended to pam execution command. Following the usual convention, True represents an “empty value” (to get flags like --key) and list can be used for keys with multiple values (--key="val1 val2 val3").

Initially, when an instance of DiracJob is created, the following pam options are set by default:

>>> self.settings.runscript.pam.noarch = True
>>> self.settings.runscript.pam.get = ['DFCOEF', 'GRIDOUT', 'dirac.xml']

Their role is to obtain from DIRAC scratch space all the files produced by your calculation (they can be later discarded with Cleaning job folder if not needed) and prevent creating a .tgz archive out of them (to allow PLAMS to process them). These two default flags can be changed or removed if needed, but this can hinder some Results functionalities, so make sure to know what you are doing.

You don’t need to manually set mandatory inp and mol flags, they are added automatically just before the runscript is generated. If, for some reason, you don’t want to use automatic molecule handling and wish to provide a geometry file by yourself, all you need to do is to set mol entry in myjob.settings.runscript.pam with the path of your geometry file. PLAMS will then ignore geometry stored in myjob.molecule and use the supplied path.

4.3.2. Results extraction

DIRAC produces two output files that can contain meaningful information. One is a “real” output of the calculation and the other is more technical output of pam script. For the sake of consistency PLAMS concatenates those two files into a single output file. The pam output is appended at the end of the “real” output, separated by a visual delimeter. Besides the regular text output some other files are produced by DIRAC. By default, DFCOEF, GRIDOUT and dirac.xml are fetched from the scratch space and renamed to, respectively, jobname.dfcoef, jobname.grid and jobname.xml.

General text processing methods from Results can be used to obtain data from results files. At the moment, no special tools are present for binary files. Contents of .xml files can be easily accessed with standard Python libraries present in xml package.

4.3.3. API

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

A class representing a single computational job with DIRAC.

_get_ready()[source]

Before generating runscript and input with parent method SingleJob._get_ready add proper mol and inp entries to self.settings.runscript.pam. If already present there, mol will not be added.

get_input()[source]

Transform all contents of input branch of settings into string with blocks, subblocks, keys and values.

On the highest level alphabetic order of iteration is modified: keys occuring in class attribute _top are printed first. See Input for details.

get_runscript()[source]

Generate a runscript. Returned string is a pam call followed by option flags generated based on self.settings.runscript.pam contents. See Runscript for details.

check()[source]

Check if the calculation was successful by examining the last line of pam output.

class DiracResults(job)[source]

A class for result of computation done with DIRAC.

collect()[source]

After collecting the files produced by job execution with parent method Results.collect append the pam output to the regular output file.