Issue: FLOAT-UNDERFLOW (version 2)

[David A. Moon <Moon@STONY-BROOK.SCRC.Symbolics.COM>]

This is a new issue.  It arose from an investigation of features
that are plausibly needed but missing from draft ANSI Common Lisp.
This issue seems sufficiently simple and noncontroversial that
I would like to see it on the agenda for the June X3J13 meeting.
Let's use the cleanup subcommittee to test the assertion that this
is a simple and noncontroversial issue.  If it's controversial,
let's just drop it, otherwise let's give X3J13 a chance to vote
for or against it.

Issue:         FLOAT-UNDERFLOW
References:    CLtL p.231
Related issues:LEAST-POSITIVE-SINGLE-FLOAT-NORMALIZATION (not written up),
               ERROR-CHECKING-IN-NUMBERS-CHAPTER
Category:      ADDITION and CLARIFICATION
Edit history:  Version 1, 9-May-89, by Moon (suggested in January, but
                        the writeup was late)
               Version 2, 23-May-89, by Moon (final cleanup for post-CLtL
			changes to Common Lisp)

Problem description:
  
  In implementations with denormalized floating point numbers (as in IEEE
  floating point), which are closer to zero than any non-zero normalized
  floating point numbers, should the LEAST-POSITIVE- and
  MOST-POSITIVE-XXX-FLOAT constants be the normalized or denormalized
  values?  Which is preferred depends on the application.  Note that in
  IEEE floating point, denormalized results are normally only produced
  as a result of underflow.
  
  Also, there is no portable way to control what happens when a floating
  point number underflows.  Sometimes this is an error, sometimes not.
  Indeed there is no mention at all of underflow or overflow in CLtL.
  Pending issue ERROR-CHECKING-IN-NUMBERS-CHAPTER does not mention floating
  point overflow or underflow.  Draft ANSI Common Lisp specifies error
  conditions named FLOATING-POINT-OVERFLOW and FLOATING-POINT-UNDERFLOW
  but does not specify the circumstances in which they are signalled and
  does not provide any way to suppress underflow checking.

Proposal (FLOAT-UNDERFLOW:ADD-CONTROLS):
  
  Clarify that the existing LEAST-POSITIVE-XXX-FLOAT and
  LEAST-NEGATIVE-XXX-FLOAT constants are literally as defined, and
  therefore can be denormalized numbers in implementations that have
  denormalized numbers.
  
  Add the following constants, whose values are the normalized floating
  point numbers closest in value to (but not equal to) zero.  In
  implementations that don't have denormalized numbers, the values of
  these constants are the same as the values of the other constants.
  
    LEAST-NEGATIVE-NORMALIZED-DOUBLE-FLOAT [Constant]
    LEAST-NEGATIVE-NORMALIZED-LONG-FLOAT [Constant]
    LEAST-NEGATIVE-NORMALIZED-SHORT-FLOAT [Constant]
    LEAST-NEGATIVE-NORMALIZED-SINGLE-FLOAT [Constant]
    LEAST-POSITIVE-NORMALIZED-DOUBLE-FLOAT [Constant]
    LEAST-POSITIVE-NORMALIZED-LONG-FLOAT [Constant]
    LEAST-POSITIVE-NORMALIZED-SHORT-FLOAT [Constant]
    LEAST-POSITIVE-NORMALIZED-SINGLE-FLOAT [Constant]
  
  Add the WITHOUT-FLOATING-UNDERFLOW-TRAPS macro.  Within the dynamic
  extent of its body, the result of a computation which would otherwise
  underflow is a denormalized number or zero, whichever is closest to the
  mathematical result.

  Clarify that outside the dynamic extent of
  WITHOUT-FLOATING-UNDERFLOW-TRAPS, a computation that underflows should
  signal an error of type FLOATING-POINT-UNDERFLOW.

  Clarify that a computation that underflows should signal an error of
  type FLOATING-POINT-OVERFLOW.

Example: (not portable of course)

  (expt 0.1 40) => error
  
  (describe (without-floating-underflow-traps (expt 0.1 40))) => 
  1.0e-40 is a single-precision floating-point number.
  Sign 0, exponent 0, 23-bit fraction 213302 (denormalized)

Rationale:

  The ANSI Common Lisp standard should be compatible with the
  widely used IEEE Floating Point standard.

  WITHOUT-FLOATING-UNDERFLOW-TRAPS is provided as a macro to allow
  implementation flexibility.  It could expand into HANDLER-BIND for
  FLOATING-POINT-UNDERFLOW, but in most implementations it will probably
  expand into implementation-dependent code that sets a hardware mode bit.

  Specifying "should signal" rather than "signals" or "might signal" for
  floating-point overflows and underflows seems the best balance between
  safety and implementation freedom.  It wouldn't harm the proposal to
  change it to one of the other two phrases.

Current practice:

  The proposal exactly matches Symbolics Genera release 7.

Cost to Implementors:

  Adding the constants and the macro is easy.  Since it was never clarified
  that floating point underflow is to be detected in safe code, implementors
  who had not already implemented that might have to go to some expense.
  In the laissez-faire spirit of floating point in Common Lisp, we could
  relax the specification and say only that underflow might signal rather
  than should signal.

Cost to Users:

  None.

Cost of non-adoption:

  Each Common Lisp implementation that uses IEEE Floating Point will have
  to invent its own way to deal with underflow and denormalized numbers.

Performance impact:

  No effect on code optimized for speed.

Benefits:

  Increased portability and correctness of floating point code.

Esthetics:

  Neutral.

Discussion:

  None.