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.

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:

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

Bases: 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:

Evaluate the condition function.

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.

If it evaluates to True, the pass through function is evaluated with the result then being return.

Parameters:

fn_passthrough (underworld.function.Function) – The pass through function
fn_condition (underworld.function.Function) – The condition function
fn_print (underworld.function.Function) – The print function (optional).

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: Issue utilising 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: Issue utilising 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: 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: Issue utilising function of class 'SafeMaths' constructed at:

   --- CONSTRUCTION TIME STACK ---
Error message:
Floating point exception(s) encountered while evaluating SafeMaths argument function:
   Divide by zero