     [file macros.texinfo not included]

IEEE Std 1788-2015
******************

The IEEE standard for interval arithmetic is an important asset for the general use of interval arithmetic.  Several interval arithmetic libraries have been created (most popular for the language C++), which vary greatly in their philosophy, completeness and—most important—mathematical definition of certain functions and arithmetic evaluation.  The standard grants support for several interval arithmetic flavors, but fights incompatibilities on many layers: Interval arithmetic applications shall be portable, predictable, and reproducible.  This is especially important since interval arithmetic shall lead to reliable results.  Also a common standard is necessary to catalyze the availability of (fast) interval operations in hardware.

For all conforming implementations certain accuracy constraints must be satisfied and a good amount of interval functions must be implemented.  It is defined how to handle functions that are not globally defined or have limiting values.  Also such basic things like interval representation, many useful constructors, and interchange encoding are addressed.

The interval package for GNU Octave is the first complete implementation that claims to be standard conforming.

Function Names
==============

In terms of a better integration into the GNU Octave language, several operations use a function name which is different from the name proposed in the standard document. The following table translates and lists the implemented function names of the IEEE standard for interval arithmetic.

The implementation provides several additional functions, but this section lists only functions that are mentioned in IEEE Std 1788-2015.

Interval constants
------------------

See empty and entire.

Constructors
------------

The operations textToInterval (S), numsToInterval (L, U), and setDec (X) are implemented by the class constructors @infsup/infsup for bare intervals and @infsupdec/infsupdec for decorated intervals.

Required functions
------------------

Table: Required forward elementary functions

Operation
Implementation
Tightness

Basic operations
neg (X)
  @infsup/uminus
tightest
add (X, Y)
  @infsup/plus
tightest
sub (X, Y)
  @infsup/minus
tightest
mul (X, Y)
  @infsup/times
tightest
div (X, Y)
  @infsup/rdivide
tightest
recip (X)
  1 ./ X
tightest
sqr (X)
  X .^ 2
tightest
sqrt (X)
  @infsup/realsqrt
tightest
fma (X, Y, Z)
  @infsup/fma
tightest

Power functions
pown (X, P)
  @infsup/pown
tightest
pow (X, Y)
  @infsup/pow
tightest
exp (X)
  @infsup/exp
tightest
exp2 (X)
  @infsup/pow2
tightest
exp10 (X)
  @infsup/pow10
tightest
log (X)
  @infsup/log
tightest
log2 (X)
  @infsup/log2
tightest
log10 (X)
  @infsup/log10
tightest

Trigonometric / hyperbolic
sin (X)
  @infsup/sin
tightest
cos (X)
  @infsup/cos
tightest
tan (X)
  @infsup/tan
tightest
asin (X)
  @infsup/asin
tightest
acos (X)
  @infsup/acos
tightest
atan (X)
  @infsup/atan
tightest
atan2 (Y, X)
  @infsup/atan2
tightest
sinh (X)
  @infsup/sinh
tightest
cosh (X)
  @infsup/cosh
tightest
tanh (X)
  @infsup/tanh
tightest
asinh (X)
  @infsup/asinh
tightest
acosh (X)
  @infsup/acosh
tightest
atanh (X)
  @infsup/atanh
tightest

Integer functions
sign (X)
  @infsup/sign
tightest
ceil (X)
  @infsup/ceil
tightest
floor (X)
  @infsup/floor
tightest
trunc (X)
  @infsup/fix
tightest
roundTiesToEven (X)
  @infsup/roundb
tightest
roundTiesToAway (X)
  @infsup/round
tightest

Absmax functions
abs (X)
  @infsup/abs
tightest
min (X, Y)
  @infsup/min
tightest
max (X, Y)
  @infsup/max
tightest

Table: Required reverse functions

Operation
Implementation
Tightness

From unary functions
sqrRev (C, X)
  @infsup/sqrrev
tightest
absRev (C, X)
  @infsup/absrev
tightest
pownRev (C, X, P)
  @infsup/pownrev
valid (tightest for P ≥ -2)
sinRev (C, X)
  @infsup/sinrev
valid
cosRev (C, X)
  @infsup/cosrev
valid
tanRev (C, X)
  @infsup/tanrev
valid
coshRev (C, X)
  @infsup/coshrev
tightest

From binary functions
mulRev (B, C, X)
  @infsup/mulrev
tightest
powRev1 (B, C, X)
  @infsup/powrev1
valid
powRev2 (A, C, X)
  @infsup/powrev2
valid
atan2Rev1 (B, C, X)
  @infsup/atan2rev1
valid
atan2Rev2 (A, C, X)
  @infsup/atan2rev2
valid

Two-output division
mulRevToPair (B, C)
  @infsup/mulrev
tightest

Cancellative addition
and subtraction
cancelMinus (X, Y)
  @infsup/cancelminus
tightest
cancelPlus (X, Y)
  @infsup/cancelplus
tightest

Table: Required set operations

Operation
Implementation
Tightness
intersection (X, Y)
  @infsup/intersect
tightest
convexHull (X, Y)
  @infsup/union
tightest

Table: Required numeric functions of intervals

Operation
Implementation
Rounding mode
inf (X)
  @infsup/inf

sup (X)
  @infsup/sup

mid (X)
  @infsup/mid
to nearest, ties to even
wid (X)
  @infsup/wid
toward +∞
rad (X)
  @infsup/rad
toward +∞
mag (X)
  @infsup/mag

mig (X)
  @infsup/mig

Table: Required boolean functions of intervals

Operation
Implementation
Description
isEmpty (X)
  @infsup/isempty
X is the empty set
isEntire (X)
  @infsup/isentire
X is the whole line
equal (A, B)
  @infsup/eq
A equals B
subset (A, B)
  @infsup/subset
A is a subset of B
less (A, B)
  @infsup/le
A is weakly less than B
precedes (A, B)
  @infsup/precedes
A is left of but may touch B
interior (A, B)
  @infsup/interior
A is interior to B
strictLess (A, B)
  @infsup/lt
A is strictly less than B
strictPrecedes (A, B)
  @infsup/strictprecedes
A is strictly left of B
disjoint (A, B)
  @infsup/disjoint
A and B are disjoint

Recommended functions
---------------------

Table: Recommended functions

Operation
Implementation
Tightness / Comments

Elementary functions
rootn (X, Q)
  @infsup/nthroot
valid (tightest for Q ≥ -2)
expm1 (X)
  @infsup/expm1
tightest
logp1 (X)
  @infsup/log1p
tightest
hypot (X, Y)
  @infsup/hypot
tightest
rSqrt (X)
  @infsup/rsqrt
tightest

Boolean functions
isCommonInterval (X)
  @infsup/iscommoninterval
(=bound and non-empty)
isSingleton (X)
  @infsup/issingleton
(=single real)
isMember (M, X)
  @infsup/ismember

Extended comparison
overlap (A, B)
  @infsup/overlap

Operations on/with decorations
------------------------------

See @infsup/newdec, @infsupdec/intervalpart, and @infsupdec/decorationpart.  The operation setDec is implemented by @infsupdec/infsupdec.

For comparison of decorations with respect to the propagation order com > dac > def > trv > ill use the numeric value returned by decorationpart (X, "uint8").

Reduction operations
--------------------

See mpfr_vector_sum_d and mpfr_vector_dot_d.  The operations sumAbs and sumSquare can be computed with mpfr_vector_sum_d (ROUNDING MODE, abs (X)) and mpfr_vector_dot_d (ROUNDING MODE, X, X) respectively.

Input
-----

The operation textToInterval is implemented by the class constructors @infsup/infsup for bare intervals and @infsupdec/infsupdec for decorated intervals.  Both are able to operate on interval literals provided as strings.

Output
------

See intervaltotext.

Exact text representation
-------------------------

See exacttointerval and @infsup/intervaltoexact.

Interchange representation and encoding
---------------------------------------

See interval_bitpack and @infsup/bitunpack.

Conformance Claim
=================

The inverval package version version for GNU Octave is conforming to IEEE Std 1788-2015, IEEE Standard for Interval Arithmetic.  It is conforming to the set-based flavor with IEEE 754 conformance for the infsup binary64 interval type and without compressed arithmetic.  Additionally it provides no further flavors.

Conformance Questionnaire
=========================

 a. Implementation-defined behavior

      1. What status flags or other means to signal the occurrence of certain decoration values in computations does the implementation provide if any?

          The implementation does not signal the occurrence of decoration values.

 b. Documentation of behavior

      1. If the implementation supports implicit interval types, how is the interval hull operation realized?

          The implementation supports explicit interval types only.

      2. What accuracy is achieved (i.e., tightest, accurate, or valid) for each of the implementation’s interval operations?

          The accuracy requirements of IEEE Std 1788-2015 are fulfilled.  Most operations achieve tightest accuracy, some operations (especially reverse operations) do not.  The tightness of each operation is documented in the function's documentation string and can be displayed with the help command.

      3. Under what conditions is a constructor unable to determine whether a Level 1 value exists that corresponds to the supplied inputs?

          When two different string boundaries for an interval both lie between the same two subsequent binary64 numbers, a PossiblyUndefined warning is created.

      4. How are ties broken in rounding numbers if multiple numbers qualify as the rounded result?

          Tie-breaking uses the IEEE Std 754 default: round ties to even.

      5. How are interval datums converted to their exact text representations?

          The binary64 boundaries are converted into hexadecimal-significand form as required by the standard.  It is also possible to convert interval datums to exact interval literals in decimal form, see optional arguments of function intervaltotext for that purpose.

 c. Implementation-defined behavior

          Does the implementation include the interval overlapping function?  If so, how is it made available to the user?

          Yes, the interval overlapping function is implemented under the name @infsup/overlap.

      1. Does the implementation store additional information in a NaI? What functions are provided for the user to set and read this information?

          No additional information is stored in a NaI.

      2. What means if any does the implementation provide for an exception to be signaled when a NaI is produced?

          The creation of a NaI is signaled with GNU Octave's warning mechanism.

      3. What interval types are supported besides the required ones?

          None.

      4. What mechanisms of exception handling are used in exception handlers provided by the implementation?  What additional exception handling is provided by the implementation?

          The exceptions described by IEEE Std 1788-2015 raise a warning, which can be handled with GNU Octave's warning mechanism.  The warning may be customized to produce an error instead and interrupt computation.  The implementation provides no additional exception handling.

      5. [Question does not apply to IEEE 754 conforming types.]

      6. Does the implementation include different versions of the same operation for a given type and how are these provided to the user?

          The interval matrix multiplication (see @infsup/mtimes) offers two implementations, with either tightest or valid accuracy.  The user may chose the desired version with an optional argument during the function call.

      7. What combinations of formats are supported in interval constructors?

          Any reasonable combination of the formats described in the standard document is supported.

      8. [Question does not apply to IEEE 754 conforming types.]

      9. What methods are used to read or write strings from or to character streams?  Does the implementation employ variations in locales (such as specific character case matching)?  This includes the syntax used in the strings for reading and writing.

          Input and output is implemented with GNU Octave string variables in UTF-8 encoding.  There is no discrimination between different locales. Character case is ignored during input.  The syntax for interval literals is used as described by the standard document.

      10. What is the tightness for the interval to string conversion for all interval types?

          The general-purpose interval to string conversion produces the tightest decimal infsup form which has no more digits than are necessary to separate two binary64 numbers.

      11. What is the result of Level 3 operations for invalid inputs?

          Interval constructors prevent the creation of invalid Level 3 interval datums.

          Any non-interval input to Level 3 operations is implicitly converted into an interval and the operation silently continues on interval inputs.

          If at least one input is a decorated interval, bare interval inputs are implicitly decorated as described by newDec in the standard document. Implicit promotion from a bare interval to a decorated interval is signaled with GNU Octave's warning mechanism.

          If implicit conversion fails (e.g., illegal interval literals), bare interval operations produce empty intervals, whereas the decorated interval operations continue on NaI inputs.

      12. [Question does not apply to IEEE 754 conforming types.]

      13. What decorations does the implementation provide and what is their mathematical definition?  How are these decorations mapped when converting an interval to the interchange format?

          The implementation provides the decorations com, dac, def, trv, and ill as described by the standard document.

      14. [Question does not apply to IEEE 754 conforming types.]

 d. [Question applies to compressed arithmetic only, which is not supported.]

 e. [Questions apply to non-standard flavors only, which are not supported.]