README.md


# Proximal methods for point source localisation: the implementation

This package contains the [Rust] codes for the numerical experiments in the articles
* T. Valkonen, “_Proximal methods for
point source localisation_”, Journal of Nonsmooth Analysis and Optimization  4 (2023), 10433, [doi:10.46298/jnsao-2023-10433] ([arXiv:2212.02991])
* T. Valkonen, “_Point source localisation with unbalanced optimal transport_” (2025), submitted.

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.

## 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.

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]. 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. You may 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/
  [GNU Scientific Library]: https://www.gnu.org/software/gsl/
  [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/
  [Homebrew]: https://brew.sh
  [arXiv:2212.02991]: https://arxiv.org/abs/2212.02991
  [doi:10.46298/jnsao-2023-10433]: http://doi.org/10.46298/jnsao-2023-10433

### Building and running the experiments

To compile and install the program, use
```console
cargo install --path=.
```
When doing this for the first time, several dependencies will be downloaded.
Now you can run the default set of experiments with
```
pointsource_algs -o results
```
The `-o results` option tells `pointsource_algs` to write results in the
`results` directory. The option is required.

Alternatively, you may build and run the program without installing with
```console
cargo run --release -- -o results
```
The double-dash separates the options for the Cargo build system 
and `pointsource_algs`.

### Documentation

Use the `--help` option to get an extensive listing of command line options to
customise algorithm parameters and the experiments performed.

## 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 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.