Crate argmin_math

Expand description

argmin-math provides mathematics related abstractions needed in argmin. It supports implementations of these abstractions for basic Vecs and for ndarray and nalgebra. The traits can of course also be implemented for your own types to make them compatible with argmin.

For an introduction on how to use argmin, please also have a look at the book.

Usage

Add the following line to your dependencies list:

[dependencies]
argmin-math = "0.3.0"

This will activate the primitives and vec features. For other backends see the section below.

Features

Support for the various backends can be switched on via features. Please read this section carefully to the end before choosing a backend.

Default features

Feature	Default	Comment
`primitives`	yes	basic integer and floating point types
`vec`	yes	`Vec`s (basic functionality)

`ndarray`

Feature	Default	Comment
`ndarray_latest`	no	latest supported version
`ndarray_latest-nolinalg`	no	latest supported version without `ndarray-linalg`
`ndarray_latest-serde`	no	latest supported version + serde support
`ndarray_latest-nolinalg-serde`	no	latest supported version without `ndarray-linalg` + serde support
`ndarray_v0_15`	no	version 0.15 with ndarray-linalg 0.16
`ndarray_v0_15-nolinalg`	no	version 0.15 without `ndarray-linalg`
`ndarray_v0_15-serde`	no	version 0.15 with ndarray-linalg 0.16 + serde support
`ndarray_v0_15-nolinalg-serde`	no	version 0.15 without `ndarray-linalg` + serde support
`ndarray_v0_14`	no	version 0.14 with ndarray-linalg 0.13
`ndarray_v0_14-nolinalg`	no	version 0.14 without `ndarray-linalg`
`ndarray_v0_14-serde`	no	version 0.14 with ndarray-linalg 0.13 + serde support
`ndarray_v0_14-nolinalg-serde`	no	version 0.14 without `ndarray-linalg` + serde support
`ndarray_v0_13`	no	version 0.13 with ndarray-linalg 0.12
`ndarray_v0_13-nolinalg`	no	version 0.13 without `ndarray-linalg`
`ndarray_v0_13-serde`	no	version 0.13 with ndarray-linalg 0.12 + serde support
`ndarray_v0_13-nolinalg-serde`	no	version 0.13 without `ndarray-linalg` + serde support

Note that the *-nolinalg* features do NOT pull in ndarray-linalg as a dependency. This avoids linking against a BLAS library. This will however disable the implementation of ArgminInv, meaning that any solver which requires the matrix inverse will not work with the ndarray backend. It is recommended to use the *-nolinalg* options if the matrix inverse is not needed in order to keep the compilation times low and avoid problems when linking against a BLAS library.

Using the ndarray_* features with ndarray-linalg support may require to explicitly choose the ndarray-linalg BLAS backend in your Cargo.toml (see the ndarray-linalg documentation for details):

ndarray-linalg = { version = "<appropriate_version>", features = ["<linalg_backend>"] }

`nalgebra`

Feature	Default	Comment
`nalgebra_latest`	no	latest supported version
`nalgebra_latest-serde`	no	latest supported version + serde support
`nalgebra_v0_32`	no	version 0.32
`nalgebra_v0_32-serde`	no	version 0.32 + serde support
`nalgebra_v0_31`	no	version 0.31
`nalgebra_v0_31-serde`	no	version 0.31 + serde support
`nalgebra_v0_30`	no	version 0.30
`nalgebra_v0_30-serde`	no	version 0.30 + serde support
`nalgebra_v0_29`	no	version 0.29
`nalgebra_v0_29-serde`	no	version 0.29 + serde support

Choosing a backend

It is not possible to activate two versions of the same backend.

The features labeled *latest* are an alias for the most recent supported version of the respective backend. It is however recommended to explicitly specify the desired version instead of using any of the *latest* features (see section about semantic versioning below).

Note that argmin by default compiles with serde support. Therefore, unless serde is deliberately turned off in argmin, it is necessary to activate the serde support in argmin-math as well.

The default features primitives and vec can be turned off in order to only compile the trait definitions. If another backend is chosen, primitives will automatically be turned on again.

Example

Activate support for the latest supported ndarray version:

[dependencies]
argmin-math = { version = "0.3.0", features = ["ndarray_latest-serde"] }

Semantic versioning

This crate follows semantic versioning. Adding a new backend or a new version of a backend is not considered a breaking change. However, your code may still break if you use any of the features containing *latest*. It is therefore recommended to specify the actual version of the backend you are using.

Development

For development and running the tests a backend for ndarray-linalg must be chosen. Normally one would add those as dev dependencies (the features would then be unified with the regular dependencies). However, linking somehow fails when the non-dev ndarra-linalg dependency is missing (which is the case for the *-nolinalg* features of the ndarray backend). To fix that, the _dev_linalg_* features were introduced. When testing and developing with one of the ndarray features with linalg support on, the appropriate _dev_linalg_* feature must be turned on as well. Note that the version number in _dev_linalg_* is always one below the ndarray version. For instance, for ndarray 0.15, one would use the _dev_linalg_0_14 feature.

Development Feature	Comment
`_dev_linalg_latest`	latest `ndarray-linalg` for latest `ndarray`
`_dev_linalg_0_16`	`ndarray-linalg` v0.16 for `ndarray` v0.15
`_dev_linalg_0_13`	`ndarray-linalg` v0.13 for `ndarray` v0.14
`_dev_linalg_0_12`	`ndarray-linalg` v0.12 for `ndarray` v0.13

Contributing

You found a bug? Your favorite backend is not supported? Feel free to open an issue or ideally submit a PR.

License

Licensed under either of

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.