Dirac
*****

DIRAC is an *ab initio* quantum chemistry program for all-electron
relativistic calculations. 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".


Preparing a calculation
=======================

Preparing an instance of "DiracJob" follows general principles for
"SingleJob". Information adjusting the input file is stored in the
"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. The 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).


Input
-----

Input files for DIRAC are organized using blocks and subblocks with a
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 uppercase, 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":

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

  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:

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


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 your 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 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.


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 delimiter. 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.


API
===

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

   A class representing a single computational job with DIRAC.

   __init__(**kwargs)

   _get_ready()

      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()

      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()

      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()

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

class DiracResults(job)

   A class for result of computation done with DIRAC.

   Parameters:
      **job** (*Job*) --

   collect()

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