--- a/README.md Thu Dec 01 23:46:09 2022 +0200
+++ b/README.md Thu Dec 01 23:37:14 2022 +0200
@@ -1,42 +1,95 @@
-# pointsource_algs
+# Proximal methods for point source localisation: the implementation
-This repository contains [Rust][] codes for the manuscript “_Proximal methods for point source localisation_” by Tuomo Valkonen ⟨tuomov@iki.fi⟩.
-It concerns solution of problems of the type
+This package contains [Rust][] codes for the manuscript “_Proximal methods for
+point source localisation_” by Tuomo Valkonen ⟨tuomov@iki.fi⟩. It concerns
+solution of problems of the type
$$
\min_{μ ∈ ℳ(Ω)}~ F(x) + λ \|μ\|_{ℳ(Ω)} + δ_{≥ 0}(x),
$$
-where $F(x)=\frac12\|Ax-b\|_2^2$ and $A \in 𝕃(ℳ(Ω); ℝ^m)$, and $ℳ(Ω)$ is the space of Radon measures on the (rectangular) domain $Ω ⊂ ℝ^n$.
+where $F$ is a data term, and $ℳ(Ω)$ is the space of Radon measures on the
+(rectangular) domain $Ω ⊂ ℝ^n$. Implemented are $F(x)=\frac12\|Ax-b\|_2^2$ and
+$F(x)=\|Ax-b\|_1$ for the forward operator $A \in 𝕃(ℳ(Ω); ℝ^m)$ modelling a
+simple sensor grid. For the 2-norm-squared data term implemented are the
+algorithms μFB, μFISTA, and μPDPS from the aforementioned manuscript along with
+comparison relaxed and fully corrective conditional gradient methods from the
+literature. For the 1-norm data term only the μPDPS is applicable.
## Installation and usage
-First install the Install [Rust][] compiler and `cargo`.
-Also install the [GNU Scientific Library][gsl]. On a Mac with [Homebrew][]
-installed, the latter can be done with
-```sh
-$ brew install gsl
+### Installing dependencies
+
+Most dependencies are managed by the Cargo build system of [Rust][]. You will
+only need to install the “nightly” Rust compiler and the
+[GNU Scientific Library][gsl] manually. At the time of writing this README,
+[alg_tools][] also needs to be downloaded separately.
+
+1. Install the [Rust][] infrastructure (including Cargo) with [rustup][].
+2. Install a “nightly” release of the Rust compiler. With rustup, installed in
+ the previous step, this can be done with
+ ```console
+ rustup toolchain install nightly
+ ```
+3. Install [GNU Scientific Library][gsl]. On a Mac with [Homebrew] installed,
+ this can be done with
+ ```console
+ brew install gsl
+ ```
+ For other operating systems, suggestions are available in the
+ [rust-GSL crate documentation][rust-GSL].
+ On Windows, you will likely need to pass extra `RUSTFLAGS` options to
+ Cargo in the following steps to locate the library.
+
+4. Download [alg_tools][] and unpack it under the same directory as this
+ package.
+
+ [rustup]: https://rustup.rs
+ [alg_tools]: https://tuomov.iki.fi/software/alg_tools/
+ [Rust]: https://www.rust-lang.org/
+ [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/
+ [gsl]: https://www.gnu.org/software/gsl/
+ [Homebrew]: https://brew.sh
+
+### Building and running the experiments
+
+To compile the code and run the experiments in the manuscript, use
+```console
+cargo run --release
```
-Then download [alg_tools][] and unpack it under the same directory as this package.
-To compile the code and run the experiments in the manuscript, use
-```sh
-$ cargo run --release
-```
+When doing this for the first time, several dependencies will be downloaded.
The `--release` flag is required to build optimised high performance code.
Without that flag the performance will be significantly worse.
-## Documentation
+Alternatively, you may build the executable with
+```console
+cargo build --release
+```
+and then run it with
+```
+target/release/pointsource_algs
+```
-The integrated documentation may be built and opened with
-```sh
-$ carg doc # build dependency docs
-$ . misc/doc-alias.sh # load KaTeX helper macro
-$ cargo-d --open # build and open KaTeX-aware docs for this crate
+### Documentation
+
+Use the `--help` option to get an extensive listing of command line options.
+If using `cargo` to run the executable, you have to pass any arguments to this
+program after a double-dash:
+```console
+cargo run --release -- --help
```
-The `cargo-d` alias ensures that KaTeX mathematics is rendered in the generated documentation. `Rustdoc` is obsolete rubbish that does not support modern markdown featues, so `cargo doc` does not render mathematics. Instead an ugly workaround is needed.
+
+## Internals
- [alg_tools]: https://tuomov.iki.fi/software/alg_tools/
- [Rust]: https://www.rust-lang.org/
- [gsl]: https://www.gnu.org/software/gsl/
- [Homebrew]: https://brew.sh
+If you are interested in the program internals, the 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.
-