.. index::
   single: Program; EMBQ
   single: EMBQ

.. _UG\:sec\:embq:

:program:`embq` |extramark|
===========================

.. warning::

   This program is not available in |openmolcas|

.. only:: html

  .. contents::
     :local:
     :backlinks: none

.. xmldoc:: <MODULE NAME="EMBQ">
            %%Description:
            <HELP>
            This program computes the electrostatic embedding potential
            from known lattice cell parameters and ionic charges
            </HELP>

.. _UG\:sec\:embq_description:

Description
-----------

The :program:`EMBQ` program of the |molcas| program system computes the geometrical positions and values of point charges, which reproduce the electrostatic potential in a finite volume. These point charges can be used in the embedded cluster calculations to mimic the electrostatic potential of an infinite lattice.

.. Electrostatic embedding potential
   ---------------------------------

In embedded cluster and quantum mechanics/molecular mechanics (QM/MM) methods, a QM description of a part of the system is combined with an empirical description of its surroundings. The QM region is said to be embedded into the potential produced by its surrounding. The :program:`EMBQ` program implements a method, which allows one to generate the electrostatic embedding potential for however complex crystalline lattice. To this end (i) a lattice unit cell is complemented with point charges which zero out all multipole moments of the unit cell up to any predefined :math:`M`-tupole and (ii) a finite nano-cluster is constructed from these redefined unit cells. As the size of this nano-cluster increases, the electrostatic potential in its inner region converges to that calculated using the Ewald's procedure.

The details of this method and examples are provided in the literature :cite:`Abarenkov:07,Sushko:10`.

.. * I. V. Abarenkov, "Unit cell for a lattice electrostatic potential", Phys. Rev. B **bf 76**, 165127 (2007).
   * P. V. Sushko, I. V. Abarenkov, "General purpose electrostatic embedding potential", J. Chem. Theory Comput. **6**, 1323-1333 (2010).

.. index::
   pair: Files; EMBQ

.. UG\:sec\:embq_files:

Files
-----

Input files
...........

.. class:: filelist

:file:`EMBQ.INP`
  This file contains keywords and control parameters for the :program:`EMBQ` program including information about the crystal lattice cell and atoms of the QM cluster. No point group symmetry is assumed.

Intermediate files
..................

All the intermediate files are created, used and removed
automatically.

Output files
............

In all output files coordinates are given in ångströms and the values of charges --- in atomic units.

.. class:: filelist

:file:`EMBQ_cell.xyz`
  .. :file:`EMBQ_UC.XYZ`

  Lattice cell: coordinates and ionic charges of the lattice cell atoms. No point group symmetry is assumed. Format: XYZ.

:file:`EMBQ_cell+Q.xyz`
  .. :file:`EMBQ_UCQ.XYZ`

  Modified cell: coordinates and charges of the lattice cell atoms and complementary point charges generated by :program:`EMBQ`. Format: XYZ. Note that the lattice atoms and complementary charges may coincide.

:file:`EMBQ_ncQ.xyz`
  .. :file:`EMBQ_NCQ.XYZ`

  Coordinates and charges of all species of the nano-cluster constructed using the modified unit cell. Format: XYZ.

:file:`EMBQ_ncQ.dat`
  .. :file:`EMBQ_NCQ.DAT`

  Coordinates and charges of all species of the nano-cluster constructed using the modified unit cell. Format: 4 columns containing Cartesian coordinates and the value of the charge.

:file:`EMBQ_ncQ-QM.xyz`
  .. :file:`EMBQ_VEX.XYZ`

  Coordinates and charges of all species of the nano-cluster *without* atoms of the QM cluster (if specified). Format: XYZ.

:file:`EMBQ_ncQ-QM.dat`
  .. :file:`EMBQ_VEX.DAT`

  Coordinates and charges of all species of the nano-cluster *without* atoms of the QM cluster (if specified). Format: 4 columns containing Cartesian coordinates and the value of the charge.

:file:`EMBQ_elpot.dat`
  .. :file:`EMBQ_EPF.OUT`

  Coordinates and charges of the nano-cluster, distance from the centre of the nano-cluster to each centre, centre number, on-site electrostatic potential and components of the field.

.. _UG\:sec\:embq_input:

Input
-----

Description of the input to :program:`EMBQ` is below. The keywords
are always significant to four characters, but in order to make the
input more transparent, it is recommended to use the full keywords.
The :program:`EMBQ` program section of the |molcas| input is bracketed by
a preceding dummy namelist reference ::

  &EMBQ
  End of Input

Argument(s) to a keyword are always supplied on the next line of the
input file, except explicitly stated otherwise.

Compulsory keywords
...................

.. class:: keywordlist

:kword:`ELMOment`
  Keyword, followed by a single integer, which specifies the largest electric
  multipole to be eliminated.
  A non-negative integer has to be supplied as argument.
  Default value is 0.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="ELMO" APPEAR="Electric moment" KIND="INT" LEVEL="BASIC" DEFAULT_VALUE="0" MIN_VALUE="0">
              %%Keyword: ELMO <basic>
              <HELP>
              Keyword, followed by a single integer, which specifies the largest electric
              multipole to be eliminated.
              A non-negative integer has to be supplied as argument.
              Default value is 0.
              </HELP>
              </KEYWORD>

:kword:`UCVEctors`
  Specifies parameters of the crystal cell (in Å).
  Three lines, containing three real numbers each, have to be supplied:

  .. container:: list

    1st line --- components of the cell vector :math:`\vec{a}_1`;

    2nd line --- components of the cell vector :math:`\vec{a}_2`;

    3rd line --- components of the cell vector :math:`\vec{a}_3`.

  .. xmldoc:: <GROUP MODULE="EMBQ" NAME="VECTORS" APPEAR="Cell vectors" KIND="BOX" LEVEL="BASIC" WINDOW="INPLACE">

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="UCVE" APPEAR="Cell: a1, a2, a3" KIND="STRINGS" SIZE="3" LEVEL="BASIC" EXCLUSIVE="UCV1,UCV2,UCV3">
              %%Keyword: UCVE <basic>
              <HELP>
              Specifies parameters of the crystal cell (in angstroms).
              Three lines, containing three real numbers each, have to be supplied:

              1st line -- components of the cell vector a1;
              2nd line -- components of the cell vector a2;
              3rd line -- components of the cell vector a3.
              </HELP>
              </KEYWORD>

:kword:`UCV1`
  Keyword, followed by three real numbers.
  Specifies components of the crystallographic cell vector :math:`\vec{a}_1` (in Å).
  Can be used as an alternative to keyword :kword:`UCVEctors`.
  Should be used together with keywords :kword:`UCV2` and :kword:`UCV3`.
  There is no default value.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="UCV1" APPEAR="Cell: a1" KIND="REALS" SIZE="3" LEVEL="BASIC" EXCLUSIVE="UCVE">
              %%Keyword: UCV1 <basic>
              <HELP>
              Keyword, followed by three real numbers.
              Specifies components of the lattice cell vector a1 (in angstroms).
              Can be used as an alternative to keyword UCVEctors.
              Should be used together with keywords UCV2 and UCV3.
              There is no default value.
              </HELP>
              </KEYWORD>

:kword:`UCV2`
  Keyword, followed by three real numbers.
  Specifies components of the crystallographic cell vector :math:`\vec{a}_2` (in Å).
  Can be used as an alternative to keyword :kword:`UCVEctors`.
  Should be used together with keywords :kword:`UCV1` and :kword:`UCV3`.
  There is no default value.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="UCV2" APPEAR="Cell: a2" KIND="REALS" SIZE="3" LEVEL="BASIC" EXCLUSIVE="UCVE">
              %%Keyword: UCV2 <basic>
              <HELP>
              Keyword, followed by three real numbers.
              Specifies components of the lattice cell vector a2 (in angstroms).
              Can be used as an alternative to keyword UCVEctors.
              Should be used together with keywords UCV1 and UCV3.
              There is no default value.
              </HELP>
              </KEYWORD>

:kword:`UCV3`
  Keyword, followed by three real numbers.
  Specifies components of the crystallographic cell vector :math:`\vec{a}_3` (in Å).
  Can be used as an alternative to keyword :kword:`UCVEctors`.
  Should be used together with keywords :kword:`UCV1` and :kword:`UCV2`.
  There is no default value.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="UCV3" APPEAR="Cell: a3" KIND="REALS" SIZE="3" LEVEL="BASIC" EXCLUSIVE="UCVE">
              %%Keyword: UCV3 <basic>
              <HELP>
              Keyword, followed by three real numbers.
              Specifies components of the lattice cell vector a3 (in angstroms).
              Can be used as an alternative to keyword UCVEctors.
              Should be used together with keywords UCV1 and UCV2.
              There is no default value.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`UCAToms`
  Keyword, followed by a single integer equal to the number of atoms in the lattice cell
  and a list of the corresponding coordinates (in Å) and ionic charges (in atomic units).

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="UCAT" APPEAR="Atoms" KIND="REALS_COMPUTED" SIZE="4" LEVEL="BASIC">
              %%Keyword: UCAT <basic>
              <HELP>
              Keyword, followed by a single integer equal to the number of atoms in the lattice cell
              and a list of the corresponding coordinates and ionic charges.
              </HELP>
              </KEYWORD>

Optional keywords
.................

.. class:: keywordlist

:kword:`TETRahedra`
  Keyword, followed by a single line containing eight integers equal to either 0 or 1.
  Specifies which tetrahedra are used to complement the crystal cell with :program:`EMBQ` charges.
  Each integer correspond to a single tetrahedron associated with a single corner of the crystal cell.
  The tetrahedron is used if the corresponding parameter equals to 1 and not used if it equals to 0.
  Default: use all eight tetrahedra.

  Orientation of the tetrahedra are determined by their axes, which are either parallel (+) or anti-parallel (|-|) to the cell vectors
  :math:`\vec{a}_1`, :math:`\vec{a}_2`, :math:`\vec{a}_3` as shown in the table below.

  .. |a| replace:: :math:`\vec{a}_1`
  .. |b| replace:: :math:`\vec{a}_2`
  .. |c| replace:: :math:`\vec{a}_3`

  =========== === === ===
  Tetrahedron Orientation
  ----------- -----------
  |zws|       |a| |b| |c|
  =========== === === ===
  1           \+  \+  \+
  2           |-| \+  \+
  3           \+  |-| \+
  4           \+  \+  |-|
  5           |-| |-| \+
  6           |-| \+  |-|
  7           \+  |-| |-|
  8           |-| |-| |-|
  =========== === === ===

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="TETR" APPEAR="Tetrahedra" KIND="INTS" SIZE="8" LEVEL="ADVANCED" DEFAULT_VALUE="1">
              %%Keyword: TETR <advanced>
              <HELP>
              Keyword, followed by a single line containing eight integers equal to either 0 or 1.
              Specifies which tetrahedra are used to complement the crystal cell with EMBQ charges.
              Each integer corresponds to a single tetrahedron that is associated with a single corner
              of the crystal cell (see User's Guide for details).
              The tetrahedron is used if the corresponding parameter equals to 1 and not used if it equals to 0.
              Default: use all eight tetrahedra.
              </HELP>
              </KEYWORD>

:kword:`SHIFt`
  Keyword, followed by a single real number.
  Specifies the shift (in fractional coordinates) of the tetrahedra from the cell corners outwards.
  Default value is zero.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="SHIF" APPEAR="Shift" KIND="REAL" LEVEL="ADVANCED" DEFAULT_VALUE="0.0">
              %%Keyword: SHIF <advanced>
              <HELP>
              Keyword, followed by a single real number.
              Specifies the shift (in fractional coordinates) of the tetrahedra from the cell corners outwards.
              Default value is zero.
              </HELP>
              </KEYWORD>

:kword:`NANOcluster`
  Keyword followed by two input lines.
  The first line contains a single integer number (:math:`n`) which specifies the shape of a nano-cluster generated using the modified cells. Possible values of :math:`n`:

  .. container:: list

    1 --- to generate a *cubic* nano-cluster

    2 --- to generate a *block* nano-cluster

    3 --- to generate a *spherical* nano-cluster.

  .. compound::

    The size of the nano-cluster is defined in the following line.
    The number of input parameters depends on the shape of the nano-cluster.
    For a *cube*, provide one integer :math:`k` to generate a nano-cluster of :math:`(2k+1)^3` unit cells.
    For a *block*, provide six integers :math:`k_1`, :math:`k_2`, :math:`m_1`, :math:`m_2`, :math:`n_1`, :math:`n_2`
    to generate a nano-cluster of

    .. math:: (k_2 - k_1 + 1) \times ( m_2 - m_1 + 1) \times (n_2 - n_1 + 1)

    unit cells. For a *sphere*, provide one real number to generate a nano-cluster of radius :math:`R` (in Å).

  This keyword can be used instead of keywords :kword:`NCCube`, :kword:`NCBLock`, and :kword:`NCSPhere`. Note that only one nano-cluster will be generated.
  Default: the nano-cluster is not generated.

  .. xmldoc:: <GROUP MODULE="EMBQ" NAME="CLUSTER" APPEAR="Nano-cluster specification" KIND="BOX" LEVEL="BASIC" WINDOW="INPLACE">

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="NANO" APPEAR="Nano-cluster" KIND="STRINGS" SIZE="2" LEVEL="ADVANCED" EXCLUSIVE="NCCU,NCBL,NCSP">
              %%Keyword: NANO <advanced>
              <HELP>
              Keyword followed by two input lines.
              The first line contains a single integer number (n) which specifies the shape of a nano-cluster
              generated using the modified cells.
              Possible values of n:

              1 -- to generate a cubic nano-cluster;
              2 -- to generate a block nano-cluster;
              3 -- to generate a spherical nano-cluster.

              The size of the nano-cluster is defined in the following line.
              The number of input parameters depends on the shape of the nano-cluster.
              For a cube (n=1), provide one integer k to generate a nano-cluster of (2k+1)^3 unit cells.
              For a block (n=2), provide six integers k1 k2 m1 m2 n1 n2 to generate a nano-cluster of
                (k2-k1+1)×(m2-m1+1)×(n2-n1+1)
              unit cells.
              For a sphere (n=3), provide one real number to generate a nano-cluster of radius R (in angstroms).
              This keyword can be used instead of keywords NCCube, NCBLock, and NCSPhere.
              Note that only one nano-cluster will be generated.
              Default: the nano-cluster is not generated.
              </HELP>
              </KEYWORD>

:kword:`NCCUbe`
  .. compound::

    Keyword, followed by a single integer number :math:`k`.
    Specifies the shape and size of the nanocluster constructed from the modified unit cells.
    The nanocluster is generated as a block of

    .. math:: (2k+1)\times(2k+1)\times(2k+1)

    cells along the lattice vectors :math:`\vec{a}_1`, :math:`\vec{a}_2`, and :math:`\vec{a}_3`, respectively.
    Default: the nanocluster is not generated.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="NCCU" APPEAR="Nano-cube" KIND="INT" LEVEL="ADVANCED" DEFAULT_VALUE="0" EXCLUSIVE="NCBL,NCSP,NANO">
              %%Keyword: NCCU <advanced>
              <HELP>
              Keyword, followed by a single integer number k.
              Specifies the shape and size of the nanocluster constructed from the modified unit cells.
              The nanocluster is generated as a block of (2k+1)×(2k+1)×(2k+1) cells
              along the lattice vectors a1, a2, and a3, respectively.
              Default: the nanocluster is not generated.
              </HELP>
              </KEYWORD>

:kword:`NCBLock`
  .. compound::

    Keyword followed by six integers: :math:`k_1` :math:`k_2` :math:`m_1` :math:`m_2` :math:`n_1` :math:`n_2`.
    Specifies the shape and size of the nanocluster constructed from the modified unit cells.
    The nanocluster is generated as a block of

    .. math:: (k_2-k_1+1)\times(m_2-m_1+1)\times(n_2-n_1+1)

    cells along the lattice vectors :math:`\vec{a}_1`, :math:`\vec{a}_2`, and :math:`\vec{a}_3`, respectively.
    Default: the nanocluster is not generated.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="NCBL" APPEAR="Nano-block" KIND="INTS" SIZE="6" LEVEL="ADVANCED" DEFAULT_VALUE="0" EXCLUSIVE="NCCU,NCSP,NANO">
              %%Keyword: NCBL <advanced>
              <HELP>
              Keyword followed by six integers: k1 k2 m1 m2 n1 n2
              Specifies the shape and size of the nanocluster constructed from the modified unit cells.
              The nanocluster is generated as a block of [(k2-k1)+1]×[(m2-m1)+1]×[(n2-n1)+1] cells
              along the lattice vectors a1, a2, and a3, respectively.
              Default: the nanocluster is not generated.
              </HELP>
              </KEYWORD>

:kword:`NCSPhere`
  Keyword followed by a single real number.
  Specifies the shape and radius (in Å) of the nano-cluster constructed from
  the modified unit cells.
  Default: the nanocluster is not generated.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="NCSP" APPEAR="Nano-sphere" KIND="REAL" LEVEL="ADVANCED" EXCLUSIVE="NCCU,NCBL,NANO">
              %%Keyword: NCSP <advanced>
              <HELP>
              Keyword followed by a single real number.
              Specifies the shape and radius (in angstroms) of the nano-cluster constructed from
              the modified unit cells.
              Default: the nanocluster is not generated.
              </HELP>
              </KEYWORD>

  .. xmldoc:: </GROUP>

:kword:`PRINt`
  Keyword, followed by a single integer number.
  Specifies the general print level:

  .. container:: list

    0 --- minimal print out;

    1 --- intermediate print out;

    2 --- full print out.

  Default: use the global |molcas| print level.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="PRIN" APPEAR="Print level" KIND="CHOICE" LIST="0: Minimal,1: Intermediate,2: Full" LEVEL="ADVANCED">
              %%Keyword: PRIN <advanced>
              <HELP>
              Keyword, followed by a single integer number.
              Specifies the general print level:

              0 -- minimal print out;
              1 -- intermediate print out;
              2 -- full print out.

              Default: use the global MOLCAS print level.
              </HELP>
              </KEYWORD>

:kword:`CALCulate`
  Keyword, followed by a single integer number.
  Requests calculation of the electrostatic potential and field at all centres of the nano-cluster.
  Possible values are:

  .. container:: list

    0 --- calculate neither the potential nor components of the field vector (default);

    1 --- calculate the potential only;

    2 --- calculate the potential and components of the field vector.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="CALC" APPEAR="Calculate" KIND="CHOICE" LIST="0: None,1: Potential,2: Potential and field" LEVEL="ADVANCED" DEFAULT_VALUE="0">
              %%Keyword: CALC <advanced>
              <HELP>
              Keyword, followed by a single integer number.
              Requests calculation of the electrostatic potential and field at all centres of the nano-cluster.
              Possible values are:

              0 -- calculate neither the potential nor the field (default);
              1 -- calculate the potential only;
              2 -- calculate the potential and field.
              </HELP>
              </KEYWORD>

:kword:`QMCLuster`
  Keyword, followed by a single integer equal to the number of atoms in the QM cluster
  and a list of the corresponding Cartesian coordinates (in Å).
  Specifies geometrical structure of the QM cluster.
  Default: number of the QM cluster atoms is zero.

  .. xmldoc:: <KEYWORD MODULE="EMBQ" NAME="QMCL" APPEAR="QM atoms" KIND="REALS_COMPUTED" SIZE="3" LEVEL="ADVANCED">
              %%Keyword: QMCL <advanced>
              <HELP>
              Keyword, followed by a single integer equal to the number of atoms in the QM cluster
              and a list of the Cartesian corresponding coordinates (in angstroms).
              Default: number of the QM cluster atoms is zero.
              </HELP>
              </KEYWORD>

Limitations
...........

* The largest electric moment :kword:`ELMOment` is limited to 10.
* Number of atoms in :kword:`UCAToms` is limited to 1000.
* Number of atoms in :kword:`QMCLuster` is limited to 1000.
* Tetrahedra in :kword:`TETRahedra` are oriented so as three of their edges are parallel to the cell vectors.
* The value of :kword:`SHIFt` is the same for all tetrahedra.

Input example
.............

::

  &EMBQ &END
  Elmoment
  4                              Largest moment to eliminate
  Tetrahedra
  1 1 1 1 0 0 0 0                Use the tetrahedra (if 1) or not (if 0)
  Shift
  0.5                            Shift the tetrahedra from the corner sites outward by this value
  Nanocluster
  3                              Shape of the nano-cluster (1 --- cube, 2 --- cuboid, 3 --- sphere)
  30.0                           Size of the nano-cluster. Here, radius of the sphere (in Å).
  Print
  2                              Printing level
  Calculate
  2                              Calculate electrostatic potential and its derivatives.
  UCvectors
  4.593730 0.000000 0.000000     Unit cell vector a1 (in Å)
  0.000000 4.593730 0.000000     Unit cell vector a2 (in Å)
  0.000000 0.000000 2.958120     Unit cell vector a3 (in Å)
  UCatoms
  6                              Number of atoms in the cell
  0.000000000   0.000000000   0.000000000   4.0
  2.296865000   2.296865000   1.479060000   4.0
  1.402465769   1.402465769   0.000000000  -2.0
  3.699330769   0.894399231   1.479060000  -2.0
  3.191264231   3.191264231   0.000000000  -2.0
  0.894399231   3.699330769   1.479060000  -2.0
  QMatoms
  4                              Number of atoms in the QM cluster
  1.402465769   1.402465769   0.000000000
  2.296865000   2.296865000  -1.479060000
  2.296865000   2.296865000   1.479060000
  0.000000000   0.000000000   0.000000000
  End of Input

.. xmldoc:: </MODULE>