Mercurial > repos > alg_tools / changeset

--- 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 <tuomov@iki.fi>
+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.
+
+
 
-<!--## Installation
+  [nalgebra]: https://www.nalgebra.org
+  [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
+  [num_traits]: num_traits
+  [cubes]: crate::sets::Cube
 
-???
--->