underworld.function.exception module

This module provides functions which raise an exception when given conditions are encountered during function evaluations. Exception functions never modify query data.

Module Summary

classes:

underworld.function.exception.CustomException This function allows you to set custom exceptions within your model.
underworld.function.exception.SafeMaths This function checks if any of the following have been encountered during the evaluation of its argument function:

Module Details

classes:

class underworld.function.exception.CustomException(fn_input, fn_condition, fn_print=None, *args, **kwargs)[source]

Bases: underworld.function._function.Function

This function allows you to set custom exceptions within your model. You must pass it two functions: the first function is the pass through function, the second function is the required condition. You may also pass in a optional third function whose output will be printed if the condition evaluates to False.

A CustomException function will perform the following logic:

  1. Evaluate the condition function.
  2. If it evaluates to False, an exception is thrown and the simulation is halted. If a print function is provided, it will be evaluated and its results will be included in the exception message.
  3. If it evaluates to True, the pass through function is evaluated with the result then being return.
Parameters:

Example

>>> import underworld as uw
>>> import underworld.function as fn
>>> one = fn.misc.constant(1.)
>>> passing_one = fn.exception.CustomException( one, (one < 2.) )
>>> passing_one.evaluate()
array([[ 1.]])
>>> failing_one = fn.exception.CustomException( one, (one > 2.) )
>>> failing_one.evaluate()
Traceback (most recent call last):
...
RuntimeError: Error in function of class 'CustomException' constructed at:
   --- CONSTRUCTION TIME STACK ---
Error message:
CustomException condition function has evaluated to False for current input!

Now with printing

>>> failing_one_by_five = fn.exception.CustomException( one, (one*5. > 20.), one*5. )
>>> failing_one_by_five.evaluate()
Traceback (most recent call last):
...
RuntimeError: Error in function of class 'CustomException' constructed at:
   --- CONSTRUCTION TIME STACK ---
Error message:
CustomException condition function has evaluated to False for current input!
Print function returns the following values (cast to double precision):
    ( 5 )
class underworld.function.exception.SafeMaths(fn, *args, **kwargs)[source]

Bases: underworld.function._function.Function

This function checks if any of the following have been encountered during the evaluation of its argument function:

  • Divide by zero
  • Invalid domain was used for evaluation
  • Value overflow errors
  • Value underflow errors

If any of the above are encountered, an exception is thrown at the conclusion of the argument function evaluation.

Parameters:fn (underworld.function.Function) – The function that is subject to the testing.

Example

>>> import underworld as uw
>>> import underworld.function as fn
>>> one = fn.misc.constant(1.)
>>> zero  = fn.misc.constant(0.)
>>> fn_dividebyzero = one/zero
>>> safedividebyzero = fn.exception.SafeMaths(fn_dividebyzero)
>>> safedividebyzero.evaluate()
Traceback (most recent call last):
    ...
RuntimeError: Error in function of class 'SafeMaths' constructed at:
   --- CONSTRUCTION TIME STACK ---
Error message:
Floating point exception(s) encountered while evaluating SafeMaths argument function:
   Divide by zero