******
NWChem
******

.. py:class:: NWChem

This interface supports energy and gradient evaluations with the
`NWChem <https://nwchemgit.github.io/>`_ electronic structure package
(version 7.0 or later)

As a QM interface, the options described in :doc:`qm` are available,
as well as the NWChem specific options outlined below.

An NWChem :ref:`Theory <theories>` object can be specified as follows::

  my_frag = Fragment(...)

  my_theory = NWChem(frag=my_frag,
                     method='hf',
                     basis='3-21g',
                     ...)

which would then be called as ``theory=my_theory`` in subsequent tasks 
(see :ref:`Tasks <tasks>`).


General options
===============

.. py:attribute:: zora

   (default: ``False``) Set to ``True`` to apply the relativistic all electron approximation ZORA

.. py:attribute:: zora_cutoff   

   (default: ``1.E-15``) Decreasing ``zora_cutoff`` can increases accuracy of ZORA calculations

.. py:attribute:: fragmovecs

   (default: ``''``) Initial wavefunction guess used in calculation

   Allowed values:

   * ``''``: Default NWChem guess (A superposition of atomic densities)
   * ``'elements'``: ChemShell will form an initial guess from isolated element wavefunctions
   * ``'atoms'``: ChemShell will form an initial guess from an isolated calculation on each atom in the system
   * ``'[[...], [...]]'``: ChemShell will form an initial guess from smaller user-defined subsections. The atom indexes should be grouped as lists. This can help speed up convergence when the system is made up of distinct regions


SCF options
===========

.. py:attribute:: tol_energy

   (default: ``1.E-6``) SCF energy convergence threshold.

.. py:attribute:: tol_density

   (default: ``1.E-5``) SCF density convergence threshold.

.. py:attribute:: tol_gradient

   (default: ``5.E-4``) SCF gradient convergence threshold.

.. py:attribute:: functional

   (default: ``'blyp'``) Choice of exchange-correlation functional in DFT calculations

.. note:: NWChem has a specific input style for range-seperated functionals, as documented `here <https://www.nwchem-sw.org/index-php/Release65_Density_Functional_Theory_for_Molecules.html#Range-Separated_Functionals>`_. The following options will automatically be expanded by ChemShell:

  * ``'CAM-B3LYP'``
  * ``'LC-BLYP'``
  * ``'LC-PBE'``
  * ``'LC-PBE0'`` (``'CAM-PBE0'``)

.. py:attribute:: cdft

   (default: ``''``) Constrained-DFT imposes constraints on the spin or charge density of atom(s) during SCF convergence. Calculations of gradients are not available during CDFT calculations, ChemShell will automatically disable this if required. 

   Allowed values are a Python :py:class:`str` of form: <n_atoms1 f_atom1 l_atom1> <n_atoms2 f_atom2 l_atom2] (charge/spin <real constraint_value>), f_atom and l_atom define the first and last atom of the group of containg n_atoms to be constrained. For example, ``3 1 3 spin 2.0``

.. py:attribute:: lshift

   (default: ``0.5``) Applies an energy level shift (in a.u.) to unoccupied orbitals, in order to improve the stability of a calculation. Level shifting is only applied when the HOMO-LUMO gap is less than :py:attr:`hl_tol`

.. py:attribute:: hl_tol

   (default: ``0.1``) HOMO-LUMO tolerance (in a.u.) for the activation of level shifting. See :py:attr:`hl_tol`

.. py:attribute:: nfock

   (default: 10) The size of the subspace for the DIIS extrapolation. Larger values may help the convergence of difficult DIIS calculations, but will also increase the memory usage

Global arrays options
=====================

NWChem uses the global arrays library to manage memory access. The following options are used to control the allocation of memory by NWChem and should be set to match the amount of RAM available on the system where NWChem is being run.

.. warning:: Please note that these options do not take effect on :ref:`directly linked NWChem <install_nwchem>` but only standalone NWChem via a :py:attr:`system call <path>`. When using directly linked NWChem, use the :ref:`command line argument <detailed>` to adjust the maximum memory that ChemShell-integrated global arrays (GA) can use for NWChem. For example, to request up to 1024 MB (default 1024, what is enough for most cases) global memory (2048 MB total memory)

    ``chemsh --ga-memory 1024 input.py > output.log``

    This command line option does not affect system calls to standalone NWChem

.. py:attribute:: memory

   (default: ``400`` MBytes) Maximum total memory (heap memory + stack memory + global memory) NWChem can request per process (MPI tasks)

.. py:attribute:: mem_heap

   (default: ``100`` MBytes) Maximum heap memory request per process: see :py:attr:`memory`

.. py:attribute:: mem_stack

   (default: ``100`` MBytes) Maximum stack memory request per process: see :py:attr:`memory`

.. py:attribute:: mem_global

   (default: ``200`` MBytes) Maximum global memory request per process: see :py:attr:`memory`