diff --git a/README.md b/README.md --- a/README.md +++ b/README.md @@ -1,84 +1,120 @@ -# aern2-mp +# aern2-mp Variable-precision interval arithmetic -## Numeric data types +API documentation available on the [Hackage page](https://hackage.haskell.org/package/aern2-mp). +## Table of contents + +- [1. Numeric data types](#1-numeric-data-types) +- [2. Interval arithmetic with Prelude](#2-interval-arithmetic-with-prelude) +- [3. Interval arithmetic with MixedTypesNum](#3-interval-arithmetic-with-mixedtypesnum) +- [4. Internal types and backends](#4-internal-types-and-backends) +- [5. Specifications and tests](#5-specifications-and-tests) + +## 1. Numeric data types + This package provides the following two data types: -* `Dyadic`: variable-precision floats with exact ring operations +- `Dyadic`: variable-precision floats with exact ring operations -* `MPBall`: variable-precision interval (float centre ± error bound) with field & elementary interval operations +- `MPBall`: variable-precision interval (float centre ± error bound) with field & elementary interval operations The type `MPBall` has instances of both [mixed-types-num](https://hackage.haskell.org/package/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](../aern2-real/README.md) provides an arithmetic of exact real numbers as converging lazy sequences of `MPBall`s of increasing precision. Exact real numbers offer additional convenience and readability to validated numeric programming. +Package [aern2-real](../aern2-real) provides an arithmetic of exact real numbers as converging lazy sequences of `MPBall`s of increasing precision. Exact real numbers offer additional convenience and readability to validated numeric programming. -### Examples +## 2. Interval arithmetic with Prelude -First, let us test interval arithmetic with **Prelude** operations: +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> +```Text +$ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP +*AERN2.MP> import Prelude +*AERN2.MP Prelude> +``` - ...> pi100 = piBallP (prec 100) - ...> pi10000 = piBallP (prec 10000) +We can work with `MPBall`s whose center is computed with a given **precision**, roughly corresponding to the number of significant bits: - ...> pi100 ^ 2 - [9.8696044010893586188344909998725639610631902560... ± ~8.1120e-30 ~2^(-96)] +```Text +...> pi100 = piBallP (prec 100) +...> pi10000 = piBallP (prec 10000) - ...> pi100 ^ pi100 - :18:1: error: - • No instance for (Integral MPBall) arising from a use of ‘^’ +...> sin pi100 +[0.0000000000000000000000000000001694818351060767... ± ~7.8925e-31 ~2^(-99)] - ...> sin pi100 - [0.0000000000000000000000000000001694818351060767... ± ~7.8925e-31 ~2^(-99)] +...> sin pi10000 +[0.0000000000000000000000000000000000000000000000... ± ~0.0000 ~2^(-9999)] +(0.07 secs, 64,466,432 bytes) +``` - ...> sin pi10000 - [0.0000000000000000000000000000000000000000000000... ± ~0.0000 ~2^(-9999)] - (0.07 secs, 64,466,432 bytes) +The Prelude power operator works only for integral types: - ...> pi100 > 0 - True +```Text +...> pi100 ^ 2 +[9.8696044010893586188344909998725639610631902560... ± ~8.1120e-30 ~2^(-96)] - ...> 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. +...> pi100 ^ pi100 +:18:1: error: + • No instance for (Integral MPBall) arising from a use of ‘^’ +``` -Some things do not work with Prelude. Let us try using **MixedTypesNumPrelude** operations: +Numerical order cannot be decided when the compared intervals overlap: - $ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP - *AERN2.MP> import MixedTypesNumPrelude - *AERN2.MP MixedTypesNumPrelude> +```Text +...> pi100 > 0 +True - ...> pi100 = piBallP (prec 100) - ...> pi10000 = piBallP (prec 10000) +...> 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. +``` - ...> pi100 ^ pi100 - [36.4621596072079117709908260226198218149834948802... ± ~1.8696e-28 ~2^(-92)] +## 3. Interval arithmetic with MixedTypesNum - ...> pi10000 ^ pi10000 - [36.4621596072079117709908260226921236663655084022... ± ~0.0000 ~2^(-9992)] - (0.27 secs, 204,657,248 bytes) +We see that some things do not work with Prelude. Let us use **MixedTypesNumPrelude** operations instead: - ...> pi100 > 0 - CertainTrue +```Text +$ stack ghci aern2-mp:lib --no-load --ghci-options AERN2.MP +*AERN2.MP> import MixedTypesNumPrelude +*AERN2.MP MixedTypesNumPrelude> +``` - ...> pi100 == pi100 - TrueOrFalse +We get a more general power operator: -### Internal types and backends +```Text +...> pi100 = piBallP (prec 100) +...> pi10000 = piBallP (prec 10000) +...> pi100 ^ pi100 +[36.4621596072079117709908260226198218149834948802... ± ~1.8696e-28 ~2^(-92)] + +...> pi10000 ^ pi10000 +[36.4621596072079117709908260226921236663655084022... ± ~0.0000 ~2^(-9992)] +(0.27 secs, 204,657,248 bytes) +``` + +Interval comparison now returns a `Kleenean` instead of `Bool`, supporting undecided comparisons: + +```Text +...> 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 `*.` +- `MPFloat`: arbitrary-precision floats with both upwards and downwards-rounded arithmetic operations such as `*^` and `*.` The package uses [cdar-mBound](https://hackage.haskell.org/package/cdar-mBound), a fork of [cdar](https://github.com/jensblanck/cdar) as its backend for `Dyadic` and `MPFloat`. In previous versions, there was an MPFR backend via [rounded](https://hackage.haskell.org/package/rounded). This may be added again in future. -## Specifications and tests +## 5. Specifications and tests This package also provides a fairly complete hspec/QuickCheck specification of algebraic properties for the above types. diff --git a/aern2-mp.cabal b/aern2-mp.cabal --- a/aern2-mp.cabal +++ b/aern2-mp.cabal @@ -4,10 +4,10 @@ -- -- see: https://github.com/sol/hpack -- --- hash: 210a1027cd95f3ead272fe18229ed64036a8b1408d9ed7558c82f9655f6b8248 +-- hash: 1b1c633ecdc7ad7935778819abf62906d7d1002d0942466df287afb79ee1e593 name: aern2-mp -version: 0.2.0.0 +version: 0.2.1.0 synopsis: Multi-precision ball (interval) arithmetic description: Please see the README on GitHub at category: Math diff --git a/changelog.md b/changelog.md --- a/changelog.md +++ b/changelog.md @@ -1,5 +1,7 @@ # Change log for aern2-mp +* 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. diff --git a/src/AERN2/MP/WithCurrentPrec.hs b/src/AERN2/MP/WithCurrentPrec.hs --- a/src/AERN2/MP/WithCurrentPrec.hs +++ b/src/AERN2/MP/WithCurrentPrec.hs @@ -24,6 +24,7 @@ module AERN2.MP.WithCurrentPrec ( WithCurrentPrec(..), runWithPrec, HasCurrentPrecision(..) + , WithAnyPrec(..) -- , _example1 , _example2 , _example3 ) where @@ -51,6 +52,21 @@ instance KnownNat n => HasCurrentPrecision n where getCurrentPrecision p = max (prec 2) . min maximumPrecision $ prec (natVal p) + +{-| + +An existential type wrapper for convenient conversions, eg using aern2-real: + +> _x :: KnownNat p => WithCurrentPrec (CN MPBall) p +> _x = undefined +> +> _r_x :: CReal +> _r_x = creal $ WithAnyPrec _x + +-} + +newtype WithAnyPrec t = WithAnyPrec (forall p. (KnownNat p) => WithCurrentPrec t p) + -- data PrecAdd10 (p :: *)