aern2-mp

Variable-precision interval arithmetic

API documentation available on the Hackage page.

Table of contents

1. Numeric data types

This package provides the following two data types:

  • Dyadic: variable-precision floats with exact ring operations

  • MPBall: variable-precision interval (float centre ± error bound) with field & elementary interval operations

The type MPBall has instances of both mixed-types-num type classes such as CanAdd, CanSqrt as well as with traditional Prelude type classes such as Ord, Num and Floating. The type Dyadic also has an appropriate subset of such instances.

Package aern2-real provides an arithmetic of exact real numbers as converging lazy sequences of MPBalls of increasing precision. Exact real numbers offer additional convenience and readability to validated numeric programming.

2. Interval arithmetic with Prelude

First, let us load the package with Prelude operations:

$ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP
*AERN2.MP> import Prelude
*AERN2.MP Prelude>

We can work with MPBalls whose center is computed with a given precision, roughly corresponding to the number of significant bits:

...> pi100 = piBallP (prec 100)
...> pi100
[3.14159265358979323846264338... ± ~7.8886e-31 ~2^(-100)]

...> pi10000 = piBallP (prec 10000)
...> pi10000
[3.14159265358979323846264338... ± ~0.0000 ~2^(-10000)]

...> sin pi100
[0.00000000000000000000000000... ± ~7.8925e-31 ~2^(-99)]

...> sin pi10000
[0.00000000000000000000000000... ± ~0.0000 ~2^(-9999)]
(0.08 secs, 64,529,960 bytes)

The Prelude power operator works only for integral types:

...> pi100 ^ 2
[9.86960440108935861883449099... ± ~1.5777e-29 ~2^(-95)]

...> pi100 ^ pi100
<interactive>:18:1: error:
    • No instance for (Integral MPBall) arising from a use of ‘^’

Numerical order cannot be decided when the compared intervals overlap:

...> pi100 > 0
True

...> pi100 == pi100
*** Exception: Failed to decide equality of MPBalls.  If you switch to MixedTypesNumPrelude instead of Prelude, comparison of MPBalls returns Kleenean instead of Bool.

3. Interval arithmetic with MixedTypesNum

We see that some things do not work with Prelude. Let us use MixedTypesNumPrelude operations instead:

$ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP
*AERN2.MP> import MixedTypesNumPrelude
*AERN2.MP MixedTypesNumPrelude>

We get a more general power operator:

...> pi100 = piBallP (prec 100)
...> pi10000 = piBallP (prec 10000)

...> pi100 ^ pi100
[36.46215960720791177099082602... ± ~1.8696e-28 ~2^(-92)]

...> pi10000 ^ pi10000
[36.46215960720791177099082602... ± ~0.0000 ~2^(-9992)]
(0.28 secs, 206,026,032 bytes)

Interval comparison now returns a Kleenean instead of Bool, supporting undecided comparisons:

...> pi100 > 0
CertainTrue

...> pi100 == pi100
TrueOrFalse

4. Internal types and backends

The type MPBall internally uses the type:

  • MPFloat: arbitrary-precision floats with both upwards and downwards-rounded arithmetic operations such as *^ and *.

The package uses cdar-mBound, a fork of cdar as its backend for Dyadic and MPFloat.

In previous versions, there was an MPFR backend via rounded. This may be added again in future.

5. Specifications and tests

This package also provides a fairly complete hspec/QuickCheck specification of algebraic properties for the above types.

For MPFloat, the properties are given mostly as approximate versions of algebraic equalities with a small rounding error tolerance.

For MPBall, the properties are given mostly as (interval) set over-approximations of the usual algebraic equalities.

Changes

Change log for aern2-mp

  • v 0.2.16.1 2024-10-06
    • adapt to int / rat conversion with sample
  • v 0.2.15 2023-04-11
    • add generic selectCountable, instance for Kleenean
  • v 0.2.14 2023-04-10
    • minor improvements supporting aern2-linear and aern2-real
  • v 0.2.11 2022-08-25
    • left-first Kleenean and/or
  • v 0.2.10 2022-08-20
    • add HasLimitsSameType, CanSelectBool, CanSelectCNBool
  • v 0.2.9 2022-07-13
    • testing basic ops produce valid MPBalls
    • more instances for CN Kleenean
    • Num MPFloat (unspecified rounding mode)
  • v 0.2.8 2021-08-04
    • compatibility with ghc 9.0.1
    • add limits for CN (WithCurrentPrec p (CN MPBall))
  • v 0.2.7 2021-06-02
    • make (WithCurrentPrec p (CN MPBall)) a Field
    • simplify WithCurrentPrec, swap its parameters
  • v 0.2.6 2021-05-29
    • adapt to new ppow operations
  • v 0.2.5 2021-05-27
    • add generic multivalued select + Kleenean instances
    • WithCurrentPrec: add MixedTypesNumPrelude class instances
  • v 0.2.4 2021-05-26
    • use endpoint multiplication in integer power to avoid crossing 0
  • v 0.2.3 2021-05-22
    • make MPBall “Very inaccurate” a potential error (important for CReal accuracy queries)
  • v 0.2.2 2021-05-21
    • move Kleenean from mixed-types-num to here
  • v 0.2.1 2021-05-18
    • add WithAnyPrec existential type wrapper for WithCurrentPrec
  • v 0.2.0 2021-05-17
    • switch to new simplified collect-errors, mixed-types-num 0.5.0
      • got rid of EnsureCE etc.
      • not introducing CN wrapper unless at least one parameter is already CN
    • using CDAR backend only, no MPFR for now
    • WithCurrentPrec for specifying default precision via types
  • v 0.1.4 2019-03-19
    • CDAR-based Integer-only backend
      • needs the mBound branch of CDAR
    • adapts to mixed-types-num 0.3.2 (new divI, mod)
  • v 0.1.3.1 2018-11-21
    • small fixes, mainly documentation
  • v 0.1.3.0 2018-11-20
    • only one MPFR backend - rounded
    • reduce backend-specific code
  • v 0.1.2.0 2017-11-14
    • fix compilation with haskell-mpfr
  • v 0.1.1.0 2017-11-14
    • using Claude Heiland-Allen’s Numeric.Rounded.Simple
  • v 0.1.0.1 2017-09-12
    • first release on Hackage
    • backends: hmpfr and (tweaked) rounded