v1.0.0-pre-arxiv/README.md


# Proximal methods for point source localisation: the implementation

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$ 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

### 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 -- -o results
```
When doing this for the first time, several dependencies will be downloaded.
The double-dash (`--`) separates the arguments of Cargo and this software,
`pointsource_algs`. The `--release` option to Cargo is required for `rustc` to
build optimised high performance code. Without that flag the performance will
be significantly worse. The `-o results` option tells `pointsource_algs` to
write results in the `results` directory. The option is required.

Alternatively, you may build the executable with
```console
cargo build --release
```
and then run it with
```
target/release/pointsource_algs -o results
```

### Documentation

Use the `--help` option to get an extensive listing of command line options to
customise algorithm parameters and the experiments performed. As above with
`-o`, if using `cargo` to run the executable, you have to pass any arguments
to `pointsource_algs` after a double-dash:
```console
cargo run --release -- --help
```

## Internals

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.