@@ -57,24 +57,38 @@ functions, which return different intervals at different
5757
5858@section{Interval Operations}
5959
60- Rival provides a large set of interval operations. All of these
61- operations are sound, meaning that the output interval always contains
62- all valid outputs from points in the input intervals.
63-
64- Most operations are also weakly complete, meaning that the endpoints
65- of the output interval come from some point in the input intervals
66- (rounded outwards). Not all operations are weakly complete, however.
60+ Rival aims to ensure three properties of all helper functions:
61+
62+ @itemlist[
63+ @item{
64+ @italic{Soundness} means output intervals contain any
65+ output on inputs drawn from the input intervals.
66+ IEEE-1788 refers to this as the output interval being @italic{valid}.
67+ }
68+
69+ @item{
70+ @italic{Refinement} means, moreover, that narrower input intervals
71+ lead to narrower output intervals. Rival's movability flags make this
72+ a somewhat more complicated property than typical.
73+ }
74+
75+ @item{
76+ @italic{Weak completeness} means, moreover, that Rival returns
77+ the narrowest possible valid interval. IEEE-1788 refers
78+ to this as the output interval being @italic{tight}.
79+ }
80+ ]
6781
68- These operations have their output precision determined by
69- @racket[bf-precision].
82+ Weak completeness (tightness) is the strongest possible property,
83+ while soundness (validity) is the weakest, with refinement somewhere
84+ in between.
7085
7186@deftogether[(
7287 @defproc[(ival-add [a ival?] [b ival?]) ival?]
7388 @defproc[(ival-sub [a ival?] [b ival?]) ival?]
7489 @defproc[(ival-neg [a ival?]) ival?]
7590 @defproc[(ival-mul [a ival?] [b ival?]) ival?]
7691 @defproc[(ival-div [a ival?] [b ival?]) ival?]
77- @defproc[(ival-fma [a ival?] [b ival?] [c ival?]) ival?]
7892 @defproc[(ival-fabs [a ival?]) ival?]
7993 @defproc[(ival-sqrt [a ival?]) ival?]
8094 @defproc[(ival-cbrt [a ival?]) ival?]
@@ -86,15 +100,10 @@ These operations have their output precision determined by
86100 @defproc[(ival-log2 [a ival?]) ival?]
87101 @defproc[(ival-log10 [a ival?]) ival?]
88102 @defproc[(ival-log1p [a ival?]) ival?]
89- @defproc[(ival-log1b [a ival?]) ival?]
90- @defproc[(ival-pow [a ival?] [b ival?]) ival?]
91- @defproc[(ival-sin [a ival?]) ival?]
92- @defproc[(ival-cos [a ival?]) ival?]
93- @defproc[(ival-tan [a ival?]) ival?]
103+ @defproc[(ival-logb [a ival?]) ival?]
94104 @defproc[(ival-asin [a ival?]) ival?]
95105 @defproc[(ival-acos [a ival?]) ival?]
96106 @defproc[(ival-atan [a ival?]) ival?]
97- @defproc[(ival-atan2 [a ival?] [b ival?]) ival?]
98107 @defproc[(ival-sinh [a ival?]) ival?]
99108 @defproc[(ival-cosh [a ival?]) ival?]
100109 @defproc[(ival-tanh [a ival?]) ival?]
@@ -103,10 +112,6 @@ These operations have their output precision determined by
103112 @defproc[(ival-atanh [a ival?]) ival?]
104113 @defproc[(ival-erf [a ival?]) ival?]
105114 @defproc[(ival-erfc [a ival?]) ival?]
106- @defproc[(ival-tgamma [a ival?]) ival?]
107- @defproc[(ival-lgamma [a ival?]) ival?]
108- @defproc[(ival-fmod [a ival?] [b ival?]) ival?]
109- @defproc[(ival-remainder [a ival?] [b ival?]) ival?]
110115 @defproc[(ival-rint [a ival?]) ival?]
111116 @defproc[(ival-round [a ival?]) ival?]
112117 @defproc[(ival-ceil [a ival?]) ival?]
@@ -118,15 +123,48 @@ These operations have their output precision determined by
118123 @defproc[(ival-fdim [a ival?] [b ival?]) ival?]
119124)]{
120125 These are all interval functions with arguments in the order
121- corresponding to the same-name @code{math.h} functions. Barring
122- bugs, all are sound. Most are weakly complete, though some more
123- complex functions aren't , including @racket[ival-pow],
124- @racket[ival-fma], @racket[ival-fmod], and @racket[ival-atan2]. Even
125- these fuctions still make a best-effort attempt to produce
126- relatively narrow intervals. For example, @racket[ival-fma] is
127- implemented via the formula @code{(fma a b c) = (+ (* a b) c)},
128- which that it accumulates multiple rounding errors. The result is
129- therefore not maximally tight, but typically still pretty close.
126+ corresponding to the same-name @code{math.h} functions. The
127+ precision of the output can be set with @racket[bf-precision].
128+ All of these functions are weakly complete, returning the tightest
129+ possible intervals for the strongest possible guarantees.
130+ }
131+
132+ @deftogether[(
133+ @defproc[(ival-fma [a ival?] [b ival?] [c ival?]) ival?]
134+ @defproc[(ival-pow [a ival?] [b ival?]) ival?]
135+ @defproc[(ival-sin [a ival?]) ival?]
136+ @defproc[(ival-cos [a ival?]) ival?]
137+ @defproc[(ival-tan [a ival?]) ival?]
138+ @defproc[(ival-atan2 [a ival?] [b ival?]) ival?]
139+ )]{
140+ These interval functions, like the previous set, are analogous to
141+ the same-name @code{math.h} functions and set their precision with
142+ @racket[bf-precision]. However, these functions are more complex and
143+ do not guarantee weak completeness. We do , however, have high
144+ confidence that they satisfy the refinement property.
145+ }
146+
147+ @deftogether[(
148+ @defproc[(ival-fmod [a ival?] [b ival?]) ival?]
149+ @defproc[(ival-remainder [a ival?] [b ival?]) ival?]
150+ )]{
151+ Like the others, these interval functions take arguments and return
152+ values analogous to the same-name @code{math.h} functions and
153+ produce output with @racket[bf-precision] precision. However,
154+ these functions do not guarantee refinement in all cases due to
155+ several subtle double-rounding cases.
156+ }
157+
158+ @deftogether[(
159+ @defproc[(ival-tgamma [a ival?]) ival?]
160+ @defproc[(ival-lgamma [a ival?]) ival?]
161+ )]{
162+ These two interval functions (which take arguments and return
163+ values analogous to the same-name @code{math.h} functions and
164+ produce output with @racket[bf-precision] precision) are extremely
165+ slow, and we have only moderate confidence that these functions
166+ satisfy soundness in all cases. We do not recommended using these
167+ functions in typical use cases or at high precision.
130168
131169 @history[#:changed "1.7 " @elem{Added @racket[ival-tgamma] and @racket[ival-lgamma]}]
132170}
0 commit comments