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

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:
  • fn_passthrough (underworld.Function) – The pass through function
  • fn_condition (underworld.Function) – The condition function
  • fn_print (underworld.Function (optional)) – The print function

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(0.) # constant function, so eval anywhere
array([[ 1.]])
>>> failing_one = fn.exception.CustomException( one, (one > 2.) )
>>> failing_one.evaluate(0.) # constant function, so eval anywhere
Traceback (most recent call last):
...
RuntimeError: 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(0.) # constant function, so eval anywhere
Traceback (most recent call last):
...
RuntimeError: 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 subject function:

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

If any of the above are encountered, and exception is thrown immediately.

Parameters:fn (underworld.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(0.)  # constant function, so eval anywhere
Traceback (most recent call last):
...
RuntimeError: Divide by zero encountered while evaluating function.