.. #
.. # @BEGIN LICENSE
.. #
.. # Psi4: an open-source quantum chemistry software package
.. #
.. # Copyright (c) 2007-2019 The Psi4 Developers.
.. #
.. # The copyrights for code used from other parties are included in
.. # the corresponding files.
.. #
.. # This file is part of Psi4.
.. #
.. # Psi4 is free software; you can redistribute it and/or modify
.. # it under the terms of the GNU Lesser General Public License as published by
.. # the Free Software Foundation, version 3.
.. #
.. # Psi4 is distributed in the hope that it will be useful,
.. # but WITHOUT ANY WARRANTY; without even the implied warranty of
.. # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.. # GNU Lesser General Public License for more details.
.. #
.. # You should have received a copy of the GNU Lesser General Public License along
.. # with Psi4; if not, write to the Free Software Foundation, Inc.,
.. # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
.. #
.. # @END LICENSE
.. #

.. include:: autodoc_abbr_options_c.rst

.. _`sec:sowreap`:

Embarrassing Parallelism
========================

Many of the tasks automated by Python wrappers consist of a number of
independent |PSIfour| calculations and are thus suited to an embarrassingly
parallel mode of operation. In Psithon, these have been dubbed sow/reap
procedures and have the following general structure.

    - Prepare an input file, simply adding ``mode='sow'`` to the
      argument list of an available Python function. Run this quick job to
      produce input files for lengthier calculations.

    - According to the instructions in the output file of the above step,
      run the generated input files in any order on any variety of computers
      and architectures. This is the time-intensive portion of the
      calculation.

    - The 'sow' stage also produces a *master* input file (with a
      ``mode='reap'`` directive). When all the jobs in the above step are
      completed, place their output files in the same location as the
      *master* input, and run this last, quick job to collect the results.

- Sow/reap procedures are governed by the **mode** keyword, choices being
  ``'continuous'``, ``'sow'``, and ``'reap'``. Only ``'sow'`` is likely to
  be used by the user, as ``'continuous'`` is always the default, and
  input files with ``'reap'`` are autogenerated.

- Embarrassingly parallel algorithm available at present for:

  - :ref:`sec:db()` 
  - finite difference operation of :ref:`sec:opt()` 
  - finite difference of energies of :ref:`sec:freq()`
  - finite difference of gradients of :ref:`sec:freq()`

.. caution:: Some features are not yet implemented. Buy a developer a coffee.

   - Local options (*e.g.*, ``set scf e_convergence 9``) will not get transmitted to the child jobs.

   - Array options (*e.g.*, ``set states_per_irrep [2, 1]``) will not get transmitted to the child jobs.

   - Function intercalls (*e.g.*, db(opt())) are not tested with sow/reap procedures.

