# 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.
``````

## 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 `assert_matrix_eq` suitable for use in `proptest` property-based tests. prop_assert_scalar_eq A version of `assert_scalar_eq` suitable for use in `proptest` property-based tests.

## 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.