README.md


# Non-Riemannian optimisation

This package contains [Rust] codes for the manuscript “_Forward-backward methods in bilaterally bounded Alenxandov spaces_” ([arXiv:????]) by Heikki von Koch and Tuomo Valkonen
⟨tuomov@iki.fi⟩. It concerns the solution of problems of the type
$$
    \min_{x ∈ M} F(x) + G(x)
$$
where $F$ is a smooth function and $G$ a possibly nonsmooth convex function
on a manifold $M$, which we do not assume to be Riemannian.
It may, for example, be an embedded manifold in $ℝ^3$, which sharp corners.
We have implemented the cube, as well as squared and non-squared distance functions.

## 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. 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:????]: https://arxiv.org/abs/????

### Building and running the experiments

To compile the code and run the experiments in the manuscript, use
```console
cargo run
```
When doing this for the first time, several dependencies will be downloaded.

Alternatively, you may build the executable with
```console
cargo build --release
```
and then run it with
```
target/release/non-riemannian-opt
```

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