# HG changeset patch # User Tuomo Valkonen # Date 1730948756 18000 # Node ID be0f9185b0759971dfd73d27e413fbf7113dc9c8 # Parent 9ac11616a2c51f23268de08c3e47ab1d7eab5146 README, LICENSE, doc-building. diff -r 9ac11616a2c5 -r be0f9185b075 LICENSE --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/LICENSE Wed Nov 06 22:05:56 2024 -0500 @@ -0,0 +1,43 @@ + +# Anti-abuse license + +## Rationale + +The purpose of this license is to give end-users and developers maximal +freedom to use this software while preventing the authors from being +abused by powerful middle-men that repackage software for convenient +installation by users. Such potentially abusive middle-men include in +particular Linux distributions and similar centralising software +distribution schemes developed for other operating systems. +The ethos of this license is *bollocks to copyright and distributions!* + +## Rules + +This software is distributed without any warranty whatsoever. + +If you redistribute modified versions of this software to the public, +you must clearly mark them as modified. + +If you redistribute this software to the public as part of a large +collection of software with the purpose of providing end-users with +a convenient installation method, you must do one of the following: + +(a) Always redistribute the **unmodified** and **latest** version +provided by the authors. If the lead author releases a new version (on a +specific branch, such as 'stable' or 'development'), you must promptly +make that new version the default version offered to your users (on +that specific branch). + +(b) Rename the software, and make it obvious that your modified or obsolete +software is in no way connected to the authors of the original software. +The users of your version should under no circumstances be under the +illusion that they can contact the lead author or any of the authors +of the original software if they have any complaints or queries. + +(c) Do not in any way directly expose this software to your users. + +Otherwise, do whatever you want with this software. In particular, you may +freely use the software as part of other projects, and redistribute to +the public archival copies of the software (as long as your archive cannot +be considered a “convenient installation method” that will be governed by +the rules above). diff -r 9ac11616a2c5 -r be0f9185b075 README.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/README.md Wed Nov 06 22:05:56 2024 -0500 @@ -0,0 +1,69 @@ + +# 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. + diff -r 9ac11616a2c5 -r be0f9185b075 misc/cargo-d --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/misc/cargo-d Wed Nov 06 22:05:56 2024 -0500 @@ -0,0 +1,4 @@ +#!/bin/sh +RUSTDOCFLAGS="--html-in-header misc/katex-header.html" cargo d --no-deps "$@" + + \ No newline at end of file diff -r 9ac11616a2c5 -r be0f9185b075 misc/katex-header.html --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/misc/katex-header.html Wed Nov 06 22:05:56 2024 -0500 @@ -0,0 +1,15 @@ + + + +