Mercurial > repos > pointsource_pde / file comparison
comparison: README.md
README.md
- changeset 1
- a4137aedcb3a
- child 3
- c3a4f4bb87f7
equal
deleted
inserted
replaced
| 0:7ec1cfe19a24 | 1:a4137aedcb3a |
|---|---|
| 1 | |
| 2 # Pointsource-PDE | |
| 3 | |
| 4 ## Prerequisites | |
| 5 | |
| 6 ## Installation and usage | |
| 7 | |
| 8 ### Installing dependencies | |
| 9 | |
| 10 Python dependencies are managed Conda and by the Cargo build system of [Rust]. | |
| 11 On some platforms, you can use alternative methods. | |
| 12 | |
| 13 #### Phase 1: Python | |
| 14 | |
| 15 ##### Most platforms: | |
| 16 | |
| 17 - Fenicsx installed in Conda according to instructions | |
| 18 - SciFEM and SciPY (`conda install conda-forge::scifem conda-forge::scipy`) | |
| 19 | |
| 20 ##### Debian/Ubuntu | |
| 21 | |
| 22 You may br able to use the system package manager instead of Conda, but beware of obsolete versions. | |
| 23 | |
| 24 #### Phase 2: Rust | |
| 25 | |
| 26 You will only need to install the “nightly” Rust compiler and the | |
| 27 [GNU Scientific Library] manually. At the time of writing this README, | |
| 28 [alg_tools] also needs to be downloaded separately. | |
| 29 | |
| 30 1. Install the [Rust] infrastructure (including Cargo) with [rustup]. | |
| 31 2. Install a “nightly” release of the Rust compiler. With rustup, installed in | |
| 32 the previous step, this can be done with | |
| 33 ```console | |
| 34 rustup toolchain install nightly | |
| 35 ``` | |
| 36 3. Install [GNU Scientific Library]. On a Mac with [Homebrew] installed, | |
| 37 this can be done with | |
| 38 ```console | |
| 39 brew install gsl | |
| 40 ``` | |
| 41 For other operating systems, suggestions are available in the [rust-GSL] | |
| 42 crate documentation. If not correctly installed, you may need to pass | |
| 43 extra `RUSTFLAGS` options to Cargo in the following steps to locate the | |
| 44 library. | |
| 45 | |
| 46 4. Download [alg_tools] and unpack it under the same directory as this | |
| 47 package. | |
| 48 | |
| 49 [rustup]: https://rustup.rs | |
| 50 [alg_tools]: https://tuomov.iki.fi/software/alg_tools/ | |
| 51 [Rust]: https://www.rust-lang.org/ | |
| 52 [GNU Scientific Library]: https://www.gnu.org/software/gsl/ | |
| 53 [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/ | |
| 54 [Homebrew]: https://brew.sh | |
| 55 [arXiv:2212.02991]: https://arxiv.org/abs/2212.02991 | |
| 56 [arXiv:2502.12417]: https://arxiv.org/abs/2502.12417 | |
| 57 [doi:10.46298/jnsao-2023-10433]: http://doi.org/10.46298/jnsao-2023-10433 | |
| 58 | |
| 59 ### Building and running the experiments | |
| 60 | |
| 61 To compile and install the program, use | |
| 62 ```console | |
| 63 cargo install --path=. | |
| 64 ``` | |
| 65 When doing this for the first time, several dependencies will be downloaded. | |
| 66 Now you can run the default set of experiments with | |
| 67 ``` | |
| 68 pointsource_pde -o results | |
| 69 ``` | |
| 70 The `-o results` option tells `pointsource_pde` to write results in the | |
| 71 `results` directory. The option is required. | |
| 72 | |
| 73 Alternatively, you may build and run the program without installing with | |
| 74 ```console | |
| 75 cargo run --release -- -o results | |
| 76 ``` | |
| 77 The double-dash separates the options for the Cargo build system | |
| 78 and `pointsource_pde`. | |
| 79 | |
| 80 ### Documentation | |
| 81 | |
| 82 Use the `--help` option to get an extensive listing of command line options to | |
| 83 customise algorithm parameters and the experiments performed. | |
| 84 | |
| 85 ## Internals | |
| 86 | |
| 87 If you are interested in the program internals, the integrated source code | |
| 88 documentation may be built and opened with | |
| 89 ```console | |
| 90 cargo doc # build dependency docs | |
| 91 misc/cargo-d --open # build and open KaTeX-aware docs for this crate | |
| 92 ``` | |
| 93 The `cargo-d` script ensures that KaTeX mathematics is rendered in the | |
| 94 generated documentation through an ugly workaround. Unfortunately, | |
| 95 `rustdoc`, akin to Rust largely itself, is stuck in 80's 7-bit gringo ASCII | |
| 96 world, and does not support modern markdown features, such as mathematics. |
