Skip to content

Commit

Permalink
Tweak wording
Browse files Browse the repository at this point in the history
  • Loading branch information
prckent committed Jul 21, 2023
1 parent 1856b26 commit d012330
Showing 1 changed file with 11 additions and 3 deletions.
14 changes: 11 additions & 3 deletions docs/developing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -776,9 +776,17 @@ memory shared by an SPOSet and all of its clones.
Log and error output
~~~~~~~~~~~~~~~~~~~~

``app_log``, ``app_warning``, ``app_err`` and ``app_debug`` print out messages only on rank 0 to avoid repetitive message from every MPI rank. For this reason, they are only suitable for outputing messages identical to all MPI ranks. ``app_debug`` prints only when ``--verbosity=debug`` command line option is used. Messages that come out from one or a few MPI ranks should use ``std::cout`` and ``std::cerr``.

If the code needs to be stopped after an unrecoverable error, a bad input for example, that happens uniformly on all the MPI ranks, avoid using ``app_err`` together with ``Communicate::abort(msg)`` or ``APP_ABORT(msg)`` because any MPI rank other than rank 0 may force stop the whole run before rank 0 gets a chance to print out the error message. To secure the printout before stopping, use ``Communicate::barrier_and_abort(msg)`` if an MPI communicator is avaiable or throw a custom exception ``UniformCommunicateError`` and capture it where ``Communicate::barrier_and_abort()`` can be used. Note that ``UniformCommunicateError`` can only be used for uniform error, improper use may cause QMCPACK hanging.
``app_log``, ``app_warning``, ``app_err`` and ``app_debug`` print out messages only on rank 0 to avoid repetitive messages from
every MPI rank. For this reason, they are only suitable for outputing messages identical to all MPI ranks. ``app_debug`` prints only
when ``--verbosity=debug`` command line option is used. Messages that come from only one or a few MPI ranks should use ``std::cout``
and ``std::cerr``.

If the code needs to be stopped after an unrecoverable error that happens uniformly on all the MPI ranks, a bad input for example,
avoid using ``app_err`` together with ``Communicate::abort(msg)`` or ``APP_ABORT(msg)`` because any MPI rank other than rank 0 may
stop the whole run before rank 0 is able to print out the error message. To secure the printout before stopping, use
``Communicate::barrier_and_abort(msg)`` if an MPI communicator is available or throw a custom exception ``UniformCommunicateError``
and capture it where ``Communicate::barrier_and_abort()`` can be used. Note that ``UniformCommunicateError`` can only be used for
uniform error, improper use may cause QMCPACK hanging.

In addition, avoid directly calling C function ``abort()``, ``exit()`` and ``MPI_Abort()`` for stopping the code.

Expand Down

0 comments on commit d012330

Please sign in to comment.