There is a newer version of the record available.

Published December 6, 2022 | Version 1.0.0-pre-arxiv
Software Open

Proximal methods for point source localisation: the implementation

  • 1. Escuela Politécnica Nacional

Description

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.

  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
    rustup toolchain install nightly
    
  3. 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.

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.

Source repository

A Mercurial repository is available; see https://tuomov.iki.fi/software/pointsource_algs/.

 

Files

pointsource_algs-1.0.0-pre-arxiv.zip

Files (186.1 kB)

Name Size Download all
md5:4ef30433ac26e55ca1f11b9dee3f1699
186.1 kB Preview Download

Additional details

Related works

Is cited by
Preprint: arXiv:2212.02991 (arXiv)

Funding

Decoupling preconditioners for non-smooth optimisation and inverse problems 314701
Academy of Finland