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

