# Crate matrixcompare[−][src]

Tools for comparing matrices for debugging purposes.

When testing and debugging linear algebra code, it is often necessary to compare two matrices
for equality. Moreover, more often than not, we can not expect exact pair-wise equality of the
numbers contained in the matrices. Most linear algebra libraries provide facilities to compare
matrices for approximate equality, but usually this only gives a binary answer: whether
the matrices are equal or not. This can be frustrating, as it gives no indication of which elements
in the matrix are not approximately equal, and how far away the numbers are from each other.
`matrixcompare`

remedies this problem by giving formatted output explaining exactly which entries
in the matrices failed to compare (approximately) equal.

Consider the following contrived example.

let a = mock_matrix![1.00, 2.00; 3.00, 4.00]; let b = mock_matrix![1.01, 2.00; 3.40, 4.00]; assert_matrix_eq!(a, b, comp = abs, tol = 1e-8);

The above example panics with the following error message

```
Matrices X and Y have 2 mismatched element pairs.
The mismatched elements are listed below, in the format
(row, col): x = X[[row, col]], y = Y[[row, col]].
(0, 0): x = 1, y = 1.01. Absolute error: 0.010000000000000009.
(1, 0): x = 3, y = 3.4. Absolute error: 0.3999999999999999.
Comparison criterion: absolute difference, |x - y| <= 0.00000001.
```

See the documentation for the assert_matrix_eq! macro for more information.

## Design and integration with linear algebra libraries

`matrixcompare`

is designed to be easy to integrate with any linear algebra library. In particular:

- The core traits are defined in
`matrixcompare-core`

. This crate has no dependencies other than the standard library, and only contains a very small amount of code that defines the interface through which the rest of`matrixcompare`

is able to access the data contained in matrices. - The
`core`

split allows the actual comparison logic and output format to evolve separately from the`core`

crate. This way we can minimize breaking changes in`matrixcompare-core`

and hopefully relatively soon stabilize it, without having to stabilize the entire`matrixcompare`

crate. - Linear algebra library authors should only depend on and implement the traits in
`matrixcompare-core`

, while end users can use any functionality provided in`matrixcompare`

. - Since access to the underlying structures are abstracted,
`matrixcompare`

can be used to compare matrices originating from different linear algebra libraries, provided that the libraries in question implement the traits found in`matrixcompare-core`

.

The design of `matrixcompare`

heavily favors ease of use/integration, correctness and
flexibility over performance. It is intended to be used for automated tests, and as such does
not belong in performance sensitive code. There are no particular guarantees about performance,
other than that the asymptotic complexity is roughly the same as a more optimized implementation.

`proptest`

integration

`proptest`

ships its own macros for use with its tests. Although it’s possible to directly
use `assert_matrix_eq!`

from `matrixcompare`

in proptests, every failing test will result in a
panic message being written to the error output, which causes unnecessary noise when debugging
a failing test. To overcome this situation, we provide the macro prop_assert_matrix_eq!, which
works exactly as assert_matrix_eq!, except that instead of panicing, it returns errors compatible
with `proptest`

.

To use this feature, the `proptest-support`

feature must be enabled. See also the `proptest`

example in the repository.

## Modules

comparators | Comparators used for element-wise comparison of matrix entries. |

ulp | Tools for ULP-based comparison of floating point numbers. |

## Macros

assert_matrix_eq | Compare matrices for exact or approximate equality. |

assert_scalar_eq | Compare scalars for exact or approximate equality. |

prop_assert_matrix_eq | A version of |

prop_assert_scalar_eq | A version of |

## Structs

DimensionMismatch | |

ElementsMismatch | |

MatrixElementComparisonFailure | |

ScalarComparisonFailure |

## Enums

Access | Defines how the elements of a matrix may be accessed. |

Entry | A coordinate in the left or right matrix being compared. |

MatrixComparisonFailure | The error type associated with matrix comparison. |

## Traits

DenseAccess | Access to a dense matrix. |

Matrix | Main interface for access to the elements of a matrix. |

SparseAccess | Access to a sparse matrix. |

## Functions

compare_matrices | Comparison of two matrices. |

compare_scalars | Comparison of two scalars. |

## Type Definitions

Coordinate | A pair of (row, column) coordinates in a matrix. |