# collect-errors <!-- omit in toc -->

This package provides an error collecting mechanism. Using `CN Double` instead of `Double` replaces NaNs and infinities with more informative error descriptions.

API documentation available on the [Hackage page](https://hackage.haskell.org/package/collect-errors).

## Table of contents <!-- omit in toc -->

- [1. Feature highlights](#1-feature-highlights)
  - [1.1. Error collecting](#11-error-collecting)
  - [1.2. Error investigation](#12-error-investigation)
  - [1.3. Undecided comparisons](#13-undecided-comparisons)
  - [1.4. Potential errors](#14-potential-errors)

## 1. Feature highlights

`CollectErrors es t` is a monad wrapper around values of type `t` which can accommodate (a list of)
(potential) errors of type `es` that have (maybe) occurred during the computation
of a value.  A value may be missing, leaving only the error(s).

The wrapper `CN t` is a special case of `CollectErrors es t` with `es` = `NumErrors`.

### 1.1. Error collecting

The `CN` wrapper propagates instances of `Floating`,
allowing us to write expressions with partial
functions (ie functions that fail for some inputs) instead of
branching after each application of such function:

```Text
$ stack ghci collect-errors:lib --no-load --ghci-options Numeric.CollectErrors
*Numeric.CollectErrors> a = 1 :: CN Double
*Numeric.CollectErrors> (1/(a-1))+(sqrt (a-2))
{{ERROR: division by 0; ERROR: out of domain: sqrt for negative arg -1.0}}
```

as opposed to:

```Text
*Prelude> a = 1 :: Double
*Prelude> (1/(a-1))+(sqrt (a-2))
NaN
```

### 1.2. Error investigation

Dealing with the errors can be moved outside the expression:

```Text
*Numeric.CollectErrors> a = 1 :: CN Double
*Numeric.CollectErrors> toEither $ 1/(a-1)
Left {ERROR: division by 0}

*Numeric.CollectErrors> toEither $ 1/a+(sqrt a)
Right 2.0
```

An alternative way to branch based on errors is provided by the function `withErrorOrValue`:

```Text
...> a = 2 :: CN Double
...> withErrorOrValue (const 0) id (1/a)
0.5
```

The `CN` wrapper can be forcibly removed as follows:

```Text
...> :t unCN (1/a)
... :: Double

...> unCN (1/a)
0.5

...> unCN (1/(a-2))
*** Exception: CollectErrors: {ERROR: division by 0}
```

### 1.3. Undecided comparisons

The following examples require the interval arithmetic package [aern2-mp](https://hackage.haskell.org/package/aern2-mp) and its dependency [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num):

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

Comparisons involving sets (such as intervals) are undecided when the intervals overlap:

```Text
...> pi100 = piBallP (prec 100)
...> :t pi100
pi100 :: MPBall
...> pi100
[3.1415926535897932384626433832793333156439620213... ± ~7.8886e-31 ~2^(-100)]

...> 0 < pi100
CertainTrue

...> pi100 == pi100
TrueOrFalse
```

The values `CertainTrue` and `TrueOrFalse` are part of the three-valued type `Kleenean` provided by  
[mixed-types-num](https://hackage.haskell.org/package/mixed-types-num).

The above equality cannot be decided since `pi100` is not a single number but a set of numbers spanning the interval and the comparison operator cannot tell if the two operands sets represent the same number or a different number.

The Prelude `Floating` instance for `CN` cannot be used reliably with interval arithmetic because the instance relies on true/false comparisons:

```Text
...> import qualified Prelude as P
... P> (cn pi100) P./ (cn pi100 - cn pi100)
*** Exception: Failed to decide equality of MPBalls.  If you switch to MixedTypesNumPrelude instead of Prelude, comparison of MPBalls returns Kleenean instead of Bool.
```

Using its Kleenean comparisons, package [mixed-types-num](https://hackage.haskell.org/package/mixed-types-num) provides alternative numerical type classes in which errors are detected and collected correctly when using the `CN` wrapper:

```Text
...> (cn pi100) / (cn pi100 - cn pi100)
{{POTENTIAL ERROR: division by 0}}
```

### 1.4. Potential errors

As we see in the above example, the `CN` wrapper supports potential errors that sometimes arise as a consequence of undecided comparisons.

When an error is present (which can be checked using `hasError`), the function `hasCertainError` can be used to further distinguish cases where the error is certain or potential:

```Text
...> import qualified Numeric.CollectErrors as CN
...> CN.hasCertainError $ (cn pi100) / (cn 0)
True

...> CN.hasCertainError $ (cn pi100) / (cn pi100 - cn pi100)
False
```

Sometimes the potential errors are *harmless*:

```Text
...> sqrt (cn pi100 - cn pi100)
[0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)]{{POTENTIAL ERROR: out of domain: negative sqrt argument}}
```

Such harmless potential errors can be ignored using `clearPotentialErrors`:

```Text
...> clearPotentialErrors $ sqrt (cn pi100 - cn pi100)
[0.0000000000000006280369834735100420368561502297... ± ~6.2804e-16 ~2^(-50)]
```