As of LOOS 2.2.0, how LOOS uses exceptions has changed significantly. This will probably not affect user code that relies on uncaught exceptions to terminate with an error, with a few exceptions (no pun intended).

In general, exceptions thrown by LOOS will derive from the LOOSError class, which in turn derives from std::exception. In cases where it would be more appropriate to return a standard exception, such as std::range_error from the operator[], LOOS will throw that instead.

The exceptions you are most likely to encounter are FileError and derived classes. These cover errors while reading and writing the various model and trajectory formats. The FileOpenError is associated with a problem opening the file (e.g. missing file or incorrect permissions). The FileReadError covers any number of errors while reading from a file. Since some classes (such as trajectory classes and most model classes) read from the file as part of instantiation, this exception may occur during the "opening" process. The FileReadErrorWithLine exception comes from classes that track the lines read and will report where in the file the error occured. Finally, the FileWriteError covers any error while writing to a file.

Once an exception has been thrown, expecially for the model and trajectory classes, the internal state of the object that threw is undefined. For example, suppose you are reading from a DCD and a FileReadError occurs. That DCD object should not be used again after the exception occured.

Changes Compared to pre-2.2.0 LOOS

The primary external change in LOOS-2.2 is that selectAtoms() will no longer throw an exception if no atoms are selected. Instead, it will return an empty AtomicGroup.

There are two major internal changes to how exceptions are handled compared to earlier versions of LOOS. Previously, the standard exceptions were more liberally used (e.g. std::runtime_error, std::logic_error, etc). Most exceptions that come from LOOS are now derived from LOOSError. Related to this, the exceptions that LOOS can throw have been streamlined.

The second major change is that the set of exceptions in LOOS have been flattened and placed in the loos namespace. Some classes defined exceptions that were specific to that class. These have either been flattened (e.g. are now in the loos namespace) or have been replaced with more general LOOS exceptions.

Translating Exceptions to PyLOOS

In most cases, Swig will convert the exceptions thrown by LOOS into the Python equivalent, or into the wrapped version of the LOOS exception. You can call the LOOSError::what() function to get the error string. Alternatively, the str() method is defined for all LOOS exceptions that are translated into Python.

The following illustrates catching PyLOOS exceptions...

try:
     model = createSystem(filename)
except loos.LOOSError as e:
     print('HELP!  There was a problem reading the model...')
     print(e.what())

While we have tried to ensure that exceptions that can be thrown by LOOS will be caught and translated for Python, it's possible that a few have been missed. Any exception not properly caught before it reaches Python will result in the Python interpreter exiting. If you find this happening, please file a bug report or email the developers at loos.maintainer [at] gmail.com