README.md

Wed, 22 Mar 2023 20:37:49 +0200

author
Tuomo Valkonen <tuomov@iki.fi>
date
Wed, 22 Mar 2023 20:37:49 +0200
changeset 26
acf57c458740
parent 17
de8d43ebfd0d
child 18
4788081468d3
child 19
8e33af984434
permissions
-rw-r--r--

Bump version

0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
1
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
2 # Proximal methods for point source localisation: the implementation
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
3
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
4 This package contains [Rust] codes for the manuscript “_Proximal methods for
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
5 point source localisation_” ([arXiv:2212.02991]) by Tuomo Valkonen
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
6 ⟨tuomov@iki.fi⟩. It concerns solution of problems of the type
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
7 $$
12
861f6c033646 Oops, some μ were x in the README.
Tuomo Valkonen <tuomov@iki.fi>
parents: 9
diff changeset
8 \min_{μ ∈ ℳ(Ω)}~ F(μ) + λ \|μ\|_{ℳ(Ω)} + δ_{≥ 0}(μ),
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
9 $$
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
10 where $F$ is a data term, and $ℳ(Ω)$ is the space of Radon measures on the
12
861f6c033646 Oops, some μ were x in the README.
Tuomo Valkonen <tuomov@iki.fi>
parents: 9
diff changeset
11 (rectangular) domain $Ω ⊂ ℝ^n$. Implemented are $F(μ)=\frac12\|Aμ-b\|_2^2$ and
861f6c033646 Oops, some μ were x in the README.
Tuomo Valkonen <tuomov@iki.fi>
parents: 9
diff changeset
12 $F(μ)=\|Aμ-b\|_1$ for the forward operator $A \in 𝕃(ℳ(Ω); ℝ^m)$ modelling a
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
13 simple sensor grid. For the 2-norm-squared data term implemented are the
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
14 algorithms μFB, μFISTA, and μPDPS from the aforementioned manuscript along with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
15 comparison relaxed and fully corrective conditional gradient methods from the
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
16 literature. For the 1-norm data term only the μPDPS is applicable.
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
17
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
18 ## Installation and usage
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
19
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
20 ### Installing dependencies
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
21
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
22 Most dependencies are managed by the Cargo build system of [Rust]. You will
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
23 only need to install the “nightly” Rust compiler and the
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
24 [GNU Scientific Library] manually. At the time of writing this README,
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
25 [alg_tools] also needs to be downloaded separately.
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
26
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
27 1. Install the [Rust] infrastructure (including Cargo) with [rustup].
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
28 2. Install a “nightly” release of the Rust compiler. With rustup, installed in
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
29 the previous step, this can be done with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
30 ```console
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
31 rustup toolchain install nightly
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
32 ```
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
33 3. Install [GNU Scientific Library]. On a Mac with [Homebrew] installed,
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
34 this can be done with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
35 ```console
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
36 brew install gsl
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
37 ```
17
de8d43ebfd0d Oops, broke some README external links
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
38 For other operating systems, suggestions are available in the [rust-GSL]
de8d43ebfd0d Oops, broke some README external links
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
39 crate documentation. On Windows, you will likely need to pass extra
de8d43ebfd0d Oops, broke some README external links
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
40 `RUSTFLAGS` options to Cargo in the following steps to locate the library.
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
41
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
42 4. Download [alg_tools] and unpack it under the same directory as this
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
43 package.
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
44
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
45 [rustup]: https://rustup.rs
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
46 [alg_tools]: https://tuomov.iki.fi/software/alg_tools/
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
47 [Rust]: https://www.rust-lang.org/
17
de8d43ebfd0d Oops, broke some README external links
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
48 [GNU Scientific Library]: https://www.gnu.org/software/gsl/
de8d43ebfd0d Oops, broke some README external links
Tuomo Valkonen <tuomov@iki.fi>
parents: 13
diff changeset
49 [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
50 [Homebrew]: https://brew.sh
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
51 [arXiv:2212.02991]: https://arxiv.org/abs/2212.02991
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
52
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
53 ### Building and running the experiments
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
54
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
55 To compile the code and run the experiments in the manuscript, use
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
56 ```console
9
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
57 cargo run --release -- -o results
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
58 ```
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
59 When doing this for the first time, several dependencies will be downloaded.
9
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
60 The double-dash (`--`) separates the arguments of Cargo and this software,
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
61 `pointsource_algs`. The `--release` option to Cargo is required for `rustc` to
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
62 build optimised high performance code. Without that flag the performance will
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
63 be significantly worse. The `-o results` option tells `pointsource_algs` to
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
64 write results in the `results` directory. The option is required.
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
65
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
66 Alternatively, you may build the executable with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
67 ```console
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
68 cargo build --release
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
69 ```
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
70 and then run it with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
71 ```
9
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
72 target/release/pointsource_algs -o results
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
73 ```
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
74
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
75 ### Documentation
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
76
9
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
77 Use the `--help` option to get an extensive listing of command line options to
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
78 customise algorithm parameters and the experiments performed. As above with
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
79 `-o`, if using `cargo` to run the executable, you have to pass any arguments
21b0e537ac0e Command line parameter passing simplifications and make `-o` required.
Tuomo Valkonen <tuomov@iki.fi>
parents: 6
diff changeset
80 to `pointsource_algs` after a double-dash:
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
81 ```console
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
82 cargo run --release -- --help
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
83 ```
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
84
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
85 ## Internals
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
86
6
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
87 If you are interested in the program internals, the integrated source code
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
88 documentation may be built and opened with
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
89 ```console
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
90 cargo doc # build dependency docs
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
91 misc/cargo-d --open # build and open KaTeX-aware docs for this crate
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
92 ```
bcb508479948 README fine-tuning and build.rs for uglifying it for rustdoc.
Tuomo Valkonen <tuomov@iki.fi>
parents: 0
diff changeset
93 The `cargo-d` script ensures that KaTeX mathematics is rendered in the
13
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
94 generated documentation through an ugly workaround. Unfortunately,
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
95 `rustdoc`, akin to Rust largely itself, is stuck in 80's 7-bit gringo ASCII
bdc57366d4f5 arXiv links, README beautification
Tuomo Valkonen <tuomov@iki.fi>
parents: 12
diff changeset
96 world, and does not support modern markdown features, such as mathematics.
0
eb3c7813b67a Initial version
Tuomo Valkonen <tuomov@iki.fi>
parents:
diff changeset
97

mercurial