~tuomov ⇝ Software ⇝

Proximal methods for point source localisation: the implementation

This package contains Rust codes for the manuscript “Proximal methods for point source localisation” (arXiv:2212.02991) by Tuomo Valkonen ⟨tuomov@iki.fi⟩. It concerns solution of problems of the type

$\min_{μ ∈ ℳ(Ω)}~ F(μ) + λ \|μ\|_{ℳ(Ω)} + δ_{≥ 0}(μ),$

where $F$ is a data term, and $ℳ(Ω)$ is the space of Radon measures on the (rectangular) domain $Ω ⊂ ℝ^n$ . Implemented are $F(μ)=\frac12\|Aμ-b\|_2^2$ and $F(μ)=\|Aμ-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 manually. At the time of writing this README, alg_tools also needs to be downloaded separately.

Install the Rust infrastructure (including Cargo) with rustup.
Install a “nightly” release of the Rust compiler. With rustup, installed in the previous step, this can be done with
```
rustup toolchain install nightly
```
Install GNU Scientific Library. On a Mac with Homebrew installed, this can be done with
```
brew install gsl
```
For other operating systems, suggestions are available in the rust-GSL crate documentation. On Windows, you will likely need to pass extra RUSTFLAGS options to Cargo in the following steps to locate the library.
Download alg_tools and unpack it under the same directory as this package.

Building and running the experiments

To compile the code and run the experiments in the manuscript, use

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

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:

cargo run --release -- --help

Internals

If you are interested in the program internals, the integrated source code documentation may be built and opened with

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.

Downloads

pointsource_algs is available from its Mercurial repository. You may either use Mercurial to clone the entire repository or you may download a snapshot as a zip or tarball. To clone use the command

hg clone https://tuomov.iki.fi/repos/pointsource_algs/

Contributing, distributing, derivative works

If you would like to contribute to this project, simply clone the repository and email me a hg bundle of your changes.

This software may be redistributed and derivate works may be created under the terms of the Anti-abuse License.