ORCA
****


Settings
========

The "input.main" branch of the "Settings" class corresponds to the
lines starting with the special character "!" in the ORCA input. See
the orcalibrary and the manual for details. The "input.molecule"
branch can be used to manually set the coordinate input line (e.g. to
use an external file), it overwrites any existing molecule of the
"ORCAJob". If not set, the molecule of the "ORCAJob" will be parsed
using the "xyz" option of ORCA.

An *end* keyword is mandatory for only a subset of sections. For
instance, the following ORCA input shows the keywords *methods* and
*basis* use of end:

   job = ORCAJob(molecule=Molecule(<Path/to/molecule>), copy="input.xyz")
   job.settings.input.main = "UKS B3LYP/G SV(P) SV/J TightSCF Direct Grid3 FinalGrid4"
   job.settings.input.maxcore = "2000"
   job.settings.input.method.SpecialGridAtoms = 26
   job.settings.input.method.SpecialGridIntAcc = 7

   job.settings.input.basis.NewGTO._end = '26 "CP(PPP)"'
   job.settings.input.basis.NewAuxGTO = '26 "TZV/J" end'

   job.settings.input.molecule = "xyzfile +2 1 input.xyz" #overwrites the molecule given above

The input generated during the execution of the ORCA job is similar
to:

   ! UKS B3LYP/G SV(P) SV/J TightSCF Direct Grid3 FinalGrid4
   %maxcore 2000
   %method SpecialGridAtoms 26
           SpecialGridIntAcc 7
           end
   %basis NewGTO 26 "CP(PPP)" end
          NewAuxGTO 26 "TZV/J" end
          end
   * xyzfile +2 1 input.xyz

Additional input files (molecules, restart files, ...) can be
automatically copied to the job's run directory by passing them to the
"ORCAJob" initialization under "copy" (string or list). To reduce disk
usage, symlinks can be used if the filesystem permits.


Loading jobs
============

Calculations done without PLAMS can be loaded using the
"load_external()" functionality. The "ORCAResults" class does not
support reading input files into "Settings" objects.


API
===

class ORCAJob(copy=None, copy_symlink=False)

   A class representing a single computational job with ORCA.

   In addition to the arguments of "SingleJob", "ORCAJob" takes a
   "copy_files" argument. "copy_files" can be a list or string,
   containing paths to files to be copied to the jobs directory. This
   might e.g. be a molecule, restart files etc. By setting
   "copy_symlink", the files are not copied, but symlinked with
   relative links. The same things can be passed using the "settings"
   instance of the job, i.e. "self.settings.copy_files" and
   "self.settings.copy_symlink". The former overwrites the latter.

   _result_type

      alias of "ORCAResults"

   __init__(copy_files=None, copy_symlink=False, **kwargs)

   _get_ready()

      Copy files to execution dir if self.copy_files is set.

   get_input()

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

   print_molecule()

      Print a molecule in the ORCA format using the xyz notation.

   get_runscript()

      Returned runscript is just one line: "orca myinput.inp"

   check()

      Look for the normal termination signal in the output.

class ORCAResults

   A class for ORCA results.

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

   get_runtime()

      Return runtime in seconds from output.

   get_timings()

      Return timings section as dictionary. Units are seconds.

   check()

      Returns true if ORCA TERMINATED NORMALLY is in the output

   check_go_conv()

      Returns true if THE OPTIMIZATION HAS CONVERGED is in the output

   check_scf_conv()

      Returns true if SCF NOT CONVERGED AFTER is NOT in the output

   get_scf_iterations(index=-1)

      Returns Number of SCF Iterations from the Output File.

      Set "index" to choose the n-th occurence, *e.g.* to choose an
      certain step. Also supports slices. Defaults to the last
      occurence.

   get_energy(index=-1, unit='a.u.')

      Returns 'FINAL SINGLE POINT ENERGY:' from the output file.

      Set "index" to choose the n-th occurence of the total energy in
      the output, *e.g.* to choose an certain step. Also supports
      slices. Defaults to the last occurence.

   get_dispersion(index=-1, unit='a.u.')

      Returns 'Dispersion correction' from the output file.

      Set "index" to choose the n-th occurence of the dispersion
      energy in the output, *e.g.* to choose a certain step. Also
      supports slices. Defaults to the last occurence.

   get_zpe(index=-1, unit='a.u.')

      Returns 'Non-thermal (ZPE) correction' from the output file.

      Set "index" to choose the n-th occurence of the ZPE in the
      output, *e.g.* to choose a certain step. Also supports slices.
      Defaults to the last occurence.

   get_inner_energy(index=-1, unit='a.u.')

      Returns 'Total thermal energy' from the output file.

      Set "index" to choose the n-th occurence of the inner energy in
      the output, *e.g.* to choose a certain step. Also supports
      slices. Defaults to the last occurence.

   get_enthalpy(index=-1, unit='a.u.')

      Returns 'Total Enthalpy' from the output file.

      Set "index" to choose the n-th occurence of the enthalpy in the
      output, *e.g.* to choose a certain step. Also supports slices.
      Defaults to the last occurence.

   get_entropy(index=-1, unit='a.u.')

      Returns 'Final entropy term' from the output file.

      Set "index" to choose the n-th occurence of the entropy in the
      output, *e.g.* to choose a certain step. Also supports slices.
      Defaults to the last occurence.

   get_gibbs_free_energy(index=-1, unit='a.u.')

      Returns 'Final Gibbs free energy' from the output file.

      Set "index" to choose the n-th occurence of the Gibbs free
      energy in the output, *e.g.* to choose a certain step. Also
      supports slices. Defaults to the last occurence.

   get_electrons(index=-1, spin_resolved=False)

      Get Electron count from Output.

      Set "spins" to "True" to get a tuple of alpha and beta electrons
      instead of totals.  Set "index" to choose the n-th occurcence in
      the output, *e.g.* to choose a certain step. Also supports
      slices. Defaults to the last occurence.

   get_gradients(match=0, energy_unit='a.u.', dist_unit='bohr')

      Returns list of ndarrays with forces from the output (there the
      unit is a.u./bohr).

      "match" is passed to "get_output_chunk()", defaults to 0.

   get_dipole_vector(index=-1, unit='a.u.')

      Get the Dipole Vector Returns the dipole vector, expressed in
      *unit*.

   get_dipole(**kwargs)

      Get Hirshfeld Analysis from Output

      Uses "get_dipole_vector()" to calculate the total dipole. All
      options are passed on.

   get_atomic_charges(method='mulliken', match=0)

      Get Atomic Charges from Output

      Parameters:
         * **method** -- Can be any one that is available in the
           output, e.g. mulliken or loewdin.

         * **match** -- Select occurence in the output to use. E.g.
           when running multiple structures at once. Is passed to
           "get_output_chunk()", defaults to 0.

   get_hirshfeld(return_spin=False, match=0, skip=5)

      Get Hirshfeld Analysis from Output

      Parameters:
         * **return_spin** -- Return a tuple of (charge, spin) instead
           of just charge.

         * **match** -- Select occurence in the output to use. E.g.
           when running multiple structures at once. Is passed to
           "get_output_chunk()", defaults to 0.

         * **skip** -- Number of lines after the keyword in the
           outputfile to be skipped. Don't touch if you don't have
           trouble with your ORCA versions output.

   get_orbital_energies(unit='a.u.', return_occupancy=False, match=0)

      Returns Orbital Energies.

      Parameters:
         * **return_occupancy** -- Set to *True* to recieve a tuple
           (Energy, Occupation) for each MO.

         * **match** -- Select occurence in the output to use. E.g.
           when running multiple structures at once. Is passed to
           "get_output_chunk()", defaults to 0.
