README.md


# Non-Riemannian optimisation

This package contains [Rust] codes for the manuscript “_Forward-backward
methods in bilaterally bounded Alexandrov spaces_” ([arXiv:2503.24126])
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$ with sharp edges.
We have implemented the cube and the cylinder, 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 manually install the “stable” Rust system itself.
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. 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/
  [arXiv:2503.24126]: https://arxiv.org/abs/2503.24126

### 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.
After this, you may run the experiment with
```console
non-riemannian-opt
```

Alternatively, you may build (without installing) and run the experiments with
```console
cargo run --release
```

### Generating the graphical illustrations

We include LaTeX/PGFPLOTS files for graphically illustrating the numerical results.
To generate `cube.pdf` and `cylinder.pdf` that visualise the computations, after running
`non-riemannian-opt` as indicated above, you can use:
```console
cd visualisations
pdflatex cube
pdflatex cylinder
```

## Internals and auxiliary results

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.

In the `doc/` subdirectory, you can find `aux_results.pdf` (and `.tex`) that
includes additional detailed geodesic formulas that are not included in the
main manuscript.