default/README.md


# alg_tools

This package contains some general utility routines and tools for implementing
iterative algorithms and (abstract) numerical computing in [Rust]. Former versions
of the package were for Julia. They are no longer maintained. Included are:

  * [Linear operator], [mapping], [Euclidean space], and [norm] abstractions.
    Matrices and vectors are supported via [nalgebra].
    There is also abstraction for [`AXPY`][AXPY] and [`GEMV`][GEMV] operations.
  * A facility to create [`Instance`][Instance]s of other types, for easy application
    of functions to various concrete and reference types.
  * Abstraction of [Fenchel conjugates] and [proximal operators] of convex
    functions.
  * Small (on stack) [vectors] and [cubes] that implement the relevant
    abstractions and vector space operations.
  * Multi-dimensional [linear grids], including the familiar-from-Matlab
    one-dimensional [`linspace`][linspace].
  * [Algorithm iterator abstraction] for generically implementing
    intermittent verbosity and stopping rules in iterative algorithms.
  * The algorithm iterators can employ a [logger] to store intermittent results
    (e.g. function values) in memory to later [write] into a csv-file.
  * Additional [iterators and iteration tools], especially variants of `map`
    with predictable type signatures.
  * The `Float` and [associated traits] build upon [num_traits] to
    conveniently write code that works with any floating point number type.
  * Geometrical [bisection trees] for efficient representations of sums of
    functions and branch-and-bound optimisation.

## Building the documentation

Integrated source code documentation may be built and opened with
```console
cargo doc              # build dependency docs
misc/cargo-d --open    # build and open KaTeX-aware docs for this crate
```
The `cargo-d` script ensures that KaTeX mathematics is rendered in the
generated documentation through an ugly workaround. Unfortunately,
`rustdoc`, akin to Rust largely itself, is stuck in 80's 7-bit gringo ASCII
world, and does not support modern markdown features, such as mathematics.


  [Rust]: https://www.rust-lang.org
  [nalgebra]: https://www.nalgebra.org
  [num_traits]: https://docs.rs/num-traits/latest/num_traits/
  [norm]: crate::norms
  [linear grids]: crate::lingrid
  [Euclidean space]: crate::euclidean
  [Linear operator]: crate::linops
  [AXPY]: crate::linops::AXPY
  [GEMV]: crate::linops::GEMV
  [linspace]: crate::lingrid::linspace
  [Algorithm iterator abstraction]: crate::iterate
  [logger]: crate::logger
  [write]: crate::tabledump
  [iterators and iteration tools]: crate::iter
  [Float]: crate::types::Float
  [bisection trees]: crate::bisection_tree
  [mapping]: crate::mapping::Mapping
  [associated traits]: crate::types
  [vectors]: crate::loc::Loc
  [cubes]: crate::sets::Cube
  [Instance]: crate::instance::Instance
  [Fenchel conjugates]: crate::convex::Conjugable
  [proximal operators]: crate::convex::Prox