exception handling

doc/user/python.tex

@@ -92,10 +92,12 @@ things.  For instance, how about being able to define your own energy
 functions that can be used with the existing optimizers or dynamics
 package?
 
-Python has been extended with the following NWChem-specific commands.
-They all handle errors by throwing exceptions which may be handled in
-the standard Python manner.  The first four commands will be of the
-widest interest.
+Python has been extended with a module named \verb+"nwchem"+ which is
+automatically imported and contains the following NWChem-specific
+commands.  They all handle NWChem-related errors by raising the
+exception \verb+"NWChemError"+, which may be handled in the standard
+Python manner (see Section \ref{sec:pyerr}).  The first four commands
+will be of the widest interest.
 \begin{itemize}
 \item \verb+input_parse(string)+ --- invokes the standard NWChem input
 parser with the data in \verb+string+ as input.  Note that the usual
@@ -487,6 +489,38 @@ the reaction energies are put into the associative array
 
 This example illustrates how to access the database from Python.
 
+\subsection{Handling exceptions from NWChem}
+
+\begin{verbatim}
+  geometry; he 0 0 0; he 0 0 2; end
+  basis; he library 3-21g; end
+  scf; maxiter 1; end
+
+  python
+    try:
+      task_energy('scf')
+    except NWChemError, message:
+      print 'Error from NWChem ... ', message
+  end
+
+  task python
+\end{verbatim}
+
+The above test program shows how to handle exceptions generated by
+NWChem by forcing an SCF calculation on $He_2$ to fail due to
+insufficient iterations.
+
+If an NWChem command fails it will raise the exception
+\verb+"NWChemError+ (case sensitive) unless the error was fatal.
+If the exception is not caught, then it will cause the entire Python
+program to terminate with an error.  This Python program catches the
+exception, prints out the message, and then continues as if all was
+well since the exception has been handled.  
+
+If your Python program detects an error, raise an unhandled
+exception.  Do not call \verb+exit(1)+ since this may circumvent
+necessary clean-up of the NWChem execution environment.
+
 \section{Troubleshooting}
 
 Common problems with Python programs inside NWChem.
@@ -513,6 +547,6 @@ including the end of line.  Try terminating the string with
 \item Your program hangs or deadlocks --- most likely you have a piece
 of code that is restricted to executing on a subset of the processors
 (perhaps just node 0) but is calling (perhaps indirectly) a function
-that must execute on all nodes.
+that must execute on all nodes.  
 
 \end{enumerate}