NumericEventHandler - Maple Programming Help

Online Help

All Products    Maple    MapleSim


Home : Support : Online Help : Mathematics : Numerical Computations : Maple Numerics : Functions : NumericEventHandler

NumericEventHandler

installs or queries numeric event handlers

 

Calling Sequence

Parameters

Description

Examples

Calling Sequence

NumericEventHandler(event ...)

NumericEventHandler(event = setting ...)

Parameters

event

-

symbol that represents one of six numeric events

setting

-

procedure, or the symbols default or exception

Description

• 

NumericEventHandler specifies or queries the event handling mechanism for one or more numeric events (see NumericEvent).  The six types of numeric events in Maple are:

invalid_operation

division_by_zero

overflow

underflow

inexact

real_to_complex

• 

The event handler settings are stored in the environment variable NumericEventHandlers, but should be set only by using the NumericEventHandler function. An event handler is always installed for each numeric event. The event handler is a user-supplied handler, the default handler, or the exception handler.

• 

Because the vector of event handlers is stored in an environment variable, handlers installed during the execution of a procedure are automatically removed when the procedure exits.  This allows, for instance, an event handler to trigger an exception by installing the exception handler for the event, and then retriggering the event, without disturbing the higher-level settings for event handling.

• 

When querying an event handler, NumericEventHandler returns either a procedure or one of the symbols default or exception.

• 

If called with an equation or expression sequence of equations of the form event=action, NumericEventHandler installs the specified action (or actions) for the specified event (or events). It also returns an equation or expression sequence of equations displaying  the previously installed action (or actions) for the specified event (or events), which can be used as an argument to a subsequent call to NumericEventHandler to restore the previous state.

  

When setting an event handler, the handler can be specified as a procedure (either directly or by name); as the symbol default, which installs the default event handler for the specified event; or as the symbol exception, which installs the exception-raising event handler for the event.

• 

If called with an event name or expression sequence of event names, NumericEventHandler returns an action or expression sequence of actions displaying the currently installed action (or actions) for the specified event (or events).

• 

If called with no arguments, NumericEventHandler returns an expression sequence of equations displaying the currently installed actions for all events.

• 

If called with the single argument default or exception, NumericEventHandler sets the actions for all events to the specified action, and returns an expression sequence of equations that gives the previously installed actions for all events, and which can be used as an argument to a subsequent call to NumericEventHandler to restore the previous state.

• 

Whenever a change is made to event handling, whether by installing an event handler or by setting event handling to default or exception, the evalf remember table is cleared, since a change in event handling might change the result that a computation produces, rendering all remembered results invalid. Note: This also takes place when a procedure call returns, if the act of restoring the environment would change event handling.

• 

The most recent Maple procedure in which an event was triggered (either explicitly by a call to NumericEvent, or implicitly by an internal numeric operation) is stored in the global variable NumericEventLocation. An event handler, or other code, can examine NumericEventLocation to help decide what to do next.  For example, one may want to install a handler that responds in a certain way to events in one's own code, but exhibits default behavior for events in library code.

• 

If an event occurs at the top level, NumericEventLocation has the value NULL. If an event occurs in an anonymous procedure, NumericEventLocation has the value unknown.  Otherwise, its value is the name with which the offending procedure was invoked (possibly an escaped local, module export, table reference, and so on).

• 

Computations within evalf impose a restriction on the type of the value returned by your handler. If a numeric event is triggered during an evalf operation and your handler is invoked, it must either raise an exception or return a floating-point value (including Floatinfinity and Floatundefined).  If the handler is invoked during complex floating-point computations and the handler is not raising an exception, it must return a complex floating-point value (including Floatinfinity+FloatinfinityI, 1.+FloatinfinityI, etc).

• 

If your handler does not raise an exception, it should generally clear the corresponding status flag (see NumericStatus).

• 

The routine NumericException can be used to ensure that the proper numeric exception is raised should you desire this behavior in your event handler.

• 

Numeric events are signaled for operations involving hardware floating-point numbers, arbitrary precision software floating-point numbers, and exact numbers in the regular Maple computation environment. However, in the evalhf environment, in Compiled code, and in code generated for other environments by the CodeGeneration package, non-default numeric event handling settings are not guaranteed to be respected.

Examples

fx→lnx1:

NumericEventHandlerdivision_by_zero

default

(1)

f1.0001

9.210340372

(2)

NumericStatusdivision_by_zero

false

(3)

f1.0

Float∞

(4)

NumericStatusdivision_by_zero

true

(5)

Clear the status flag

NumericStatusdivision_by_zero=false:

The default behavior of some of the numeric event handlers depends on whether exact or floating-point operations are involved.

f1

Error, (in ln) numeric exception: division by zero

NumericEventHandlerdivision_by_zero=exception

division_by_zero=default

(6)

f1.0

Error, (in `evalf/ln`) numeric exception: division by zero

MyHandler := proc(operator,operands,default_value)
   # MyHandler issues a warning, clears the status flag, and then
   # continues with the default value.
   WARNING("division by zero in %1 with argument(s) %2", operator, operands);
   NumericStatus( division_by_zero = false );
   return default_value;
end proc:

NumericEventHandlerdivision_by_zero=MyHandler

division_by_zero=exception

(7)

f1.0+0.0I

Warning, division by zero in evalf/ln with argument(s) [0.+0.*I]

Float∞+FloatundefinedI

(8)

NumericStatusdivision_by_zero

false

(9)

f1

Warning, division by zero in ln with argument(s) [0]

∞+undefinedI

(10)

NumericEventHandler

invalid_operation=default,division_by_zero=procoperator,operands,default_valueWARNINGdivision by zero in %1 with argument(s) %2,operator,operands;NumericStatusdivision_by_zero=false;returndefault_valueend proc,overflow=default,underflow=default,inexact=default,real_to_complex=default

(11)

g := proc(a,b) a / b end proc:

g3.0,0.0

Warning, division by zero in / with argument(s) [1, 0.]

Float∞

(12)

NumericEventLocation

g

(13)

f1.0

Warning, division by zero in evalf/ln with argument(s) [0.]

Float∞

(14)

NumericEventLocation

evalf/ln

(15)

See Also

error

evalf

NumericEvent

NumericException

NumericStatus

proc

remember

try

 


Download Help Document

Was this information helpful?



Please add your Comment (Optional)
E-mail Address (Optional)
What is ? This question helps us to combat spam