Skip to main content

floating-point-underflow

floating-point-underflow Condition Type

Class Precedence List:

floating-point-underflow, arithmetic-error, error, serious-condition, condition, t

Description:

The type floating-point-underflow consists of error conditions that occur because of floating-point underflow.

Expanded Reference: floating-point-underflow​

Type Hierarchy​

The floating-point-underflow condition is a subtype of arithmetic-error. It is signaled when a floating-point operation produces a result that is too small (too close to zero) to be represented as a normalized floating-point number.

(subtypep 'floating-point-underflow 'arithmetic-error)
=> T
=> T
(subtypep 'floating-point-underflow 'error)
=> T
=> T

Triggering Underflow​

Underflow occurs when a computation produces a value smaller in magnitude than the smallest representable positive float.

(handler-case (exp -1000.0d0)
  (floating-point-underflow ()
    :underflow))
=> 0.0d0

(handler-case (/ least-positive-double-float 10.0d0)
  (floating-point-underflow ()
    :underflow))
=> 0.0d0

Inspecting the Error​

As with all arithmetic-error subtypes, the operation and operands can be inspected.

(handler-case (exp -1000.0d0)
  (floating-point-underflow (c)
    (list :op (arithmetic-error-operation c)
          :args (arithmetic-error-operands c))))
=> 0.0d0

Practical Note​

Many implementations flush underflow results to zero rather than signaling this condition, especially when hardware denormalized numbers are available. Whether underflow is signaled depends on the implementation and potentially on floating-point trap settings.

;; On many implementations, this silently returns 0.0d0:
(exp -1000.0d0)
=> 0.0d0

;; Portable code should handle both possibilities:
(defun safe-exp-small (x)
  (handler-case (exp x)
    (floating-point-underflow () 0.0d0)))

(safe-exp-small -1000.0d0)
=> 0.0d0