# HG changeset patch # User Tuomo Valkonen # Date 1670309929 -7200 # Node ID 703482dffd87aed16ccd64f8ee7d8a939e9e8f2f # Parent e03ce15643da4d39985b366cf6516d0a96e3507f README improvements diff -r e03ce15643da -r 703482dffd87 README.md --- a/README.md Tue Dec 06 08:32:57 2022 +0200 +++ b/README.md Tue Dec 06 08:58:49 2022 +0200 @@ -1,19 +1,61 @@ # AlgTools -Author: Tuomo Valkonen +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 mintained. Included are: -This crate/repository/package contains some general utility routines and tools for implementing -iterative algorithms and numerical computing in Rust. Former versions of the package were for Julia. -They are no longer mintained. 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. + * 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 - * [Linear operator](crate::linops), [Euclidean space][crate::euclidean], and [norm][crate::norms] abstractions with support for matrices and vectors via `nalgebra`. - * [Iteration abstraction](crate::iterate) for generically implementing intermittent verbosity and stopping rules in iterative algorithms. - * The iterators can employ a [logger](crate::logger) to store the intermittent results - (e.g. function values) in memory to later [write][crate::tabledump] into a `csv`-file. - * Geometrical [bisection trees](crate::bisection_tree) for efficient representations of sums of functions and branch-and-bound optimisation. +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. 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. Instead, to render mathematics, an ugly +workaround is needed together with lots of painful raw HTML escapes in the +documentation. + + -