Mercurial > repos > pointsource_pde / file comparison

comparison: README.md

README.md

changeset 3
c3a4f4bb87f7
parent 1
a4137aedcb3a
child 5
3e164c024a01
equal deleted inserted replaced
1:a4137aedcb3a 3:c3a4f4bb87f7
1 1
2 # Pointsource-PDE 2 # Codes for “Leak localisation with a measure source convection--diffusion model”
3 3
4 ## Prerequisites 4 These are the codes for the numerical demonstrations of the manuscript
5 5 _“Leak localisation with a measure source convection--diffusion model”_
6 ## Installation and usage 6 ([arXiv:????.????](https://arxiv.org/abs/????.????)) by Thi Tam Dang and Tuomo Valkonen.
7 7 It should be relatively easy to to use this package and the algorithms it provides
8 ### Installing dependencies 8 for other PDE-based point source localisation problems.
9 9
10 Python dependencies are managed Conda and by the Cargo build system of [Rust]. 10 ## Building
11 On some platforms, you can use alternative methods. 11
12 12 Sorry, although the core of program is written in Rust with a modern dependency management and build process, we also have legacy C++ and Python dependencies, i.e., the Fenicsx PDE library. Therefore, the build process is difficult.
13 #### Phase 1: Python 13
14 14 (We admit it, we made a mistake by going with the crowd and using Fenicsx. In the end it would have been less effort to write low-level PDE code in Rust.)
15 ##### Most platforms: 15
16 16 ### Phase 1: Python and Fenics
17 - Fenicsx installed in Conda according to instructions 17
18 - SciFEM and SciPY (`conda install conda-forge::scifem conda-forge::scipy`) 18 #### Option 1.A that avoids Conda hell, but is more work (macOS and Linux)
19 19
20 ##### Debian/Ubuntu 20 ##### Phase 1.A.1: C++ dependencies of Fenics
21 21
22 You may br able to use the system package manager instead of Conda, but beware of obsolete versions. 22 First install C++ dependencies using [Homebrew](https://brew.sh).
23 23 Even on Linux, **use Homebrew**, or install from official sources; distribution packages are usually obsolete and buggy, often non-standard, and will cause problems (see above).
24 #### Phase 2: Rust 24
25 brew install openmpi boost pugixml fmt spdlog hdf5-mpi cmake kahip slepc petsc gsl
26
27 (Fenics recommends ParMETIS instead of Kahip, but only the latter is available from Homebrew at the time of writing this.)
28
29 There's no guarantee that this will install compatible versions of these packages. Homebrew, while better than most Linux distributions, is also obsolete in its philosophy: it does not allow easily installing specific versions of packages. Versions known to work are:
30
31 package | version
32 ---------|--------
33 boost | 1.90.0
34 cmake | 4.2.1
35 fmt | 12.1.0
36 hdf5-mpi | 1.14.6
37 kahip | 3.22
38 petsc | 3.24.3
39 pugixml | 1.15
40 slepc | 3.24.2
41 spdlog | 1.17.0
42 gsl | 2.8
43
44 You can get the list of installed versions with:
45
46 brew list --versions openmpi boost pugixml fmt spdlog hdf5-mpi cmake kahip slepc petsc gsl
47
48 ##### Phase 1.A.2: Python dependencies of Fenics
49
50 In this source directory, create and activate a virtual environment for Python, and
51 install Python packages:
52
53 python3 -m venv .venv
54 source .venv/bin/activate
55 PETSC_DIR=/opt/homebrew/ SLEPC_DIR=/opt/homebrew/ pip install -r requirements.lock
56
57 To not have to activate the virtual environment manually every time, and to not mess up your global settings, it is recommended to install [direnv](https://direnv.net) and put the following in `.envrc` in this directory:
58
59 source .venv/bin/activate
60 export PYTHONPATH=$(echo .venv/lib/python*/site-packages)
61 export PYO3_PYTHON="$(which python)"
62
63 (The last two lines are required later.)
64 This template is also available in `misc/_envrc`.
65 For changes `.envrc` to take effect, you should use
66
67 direnv allow
68
69 ##### Phase 1.A.3: Fenicx-basix
70
71 Install basix from <https://github.com/FEniCS/basix/releases/tag/v0.10.0.post0> according to
72 instructions. First do the C++ bit:
73
74 tar xzf basix-0.10.0.post0.tar.gz
75 cd basix-0.10.0.post0/cpp
76 mkdir build
77 cd build
78 cmake ..
79 make
80 make install
81
82 Then the Python bit. This has to be done with the `venv` created above, active.
83
84 cd ../../python
85 pip install .
86
87 ##### Phase 1.A.4: Fenicx-dolfinx
88
89 Install dolfinx from <https://github.com/FEniCS/dolfinx/releases/tag/v0.10.0.post5> according to
90 instructions. First do the C++ bit:
91
92 tar xzf dolfinx-0.10.0.post5.tar.gz
93 cd dolfinx-0.10.0.post5/cpp
94 mkdir build
95 cd build
96 cmake ..
97 make
98 make install
99
100 Skip the `source /usr/local/lib/dolfinx/dolfinx.conf` recommended at the end
101 of the compilation. It will likely break things.
102
103 Then the Python bit. This has to be done with the virtual environment created above, active.
104
105 cd ../../python
106 python -m scikit_build_core.build requires | python -c "import sys, json; print(' '.join(json.load(sys.stdin)))" | xargs pip install
107 pip install --check-build-dependencies --no-build-isolation .
108
109 If you didn't already do these steps with `direnv` above, you should:
110
111 export PYTHONPATH=$(echo .venv/lib/python*/site-packages)
112 export PYO3_PYTHON="$(which python)"
113
114
115 #### Option 1.B: Conda
116
117 You can *try to* install Fenicsx in Conda according to instructions on the Fenics website. Additionally you need to install `scipy`:
118
119 conda create -n fenicsx-env
120 conda activate fenicsx-env
121 conda install -c conda-forge fenics-dolfinx=0.10.0 scipy=1.17.1 mpich
122
123 This is, however, unlikely to not work, as Conda, despite its sandboxing separation attempts, conflicts with system packages, or Conda packages have weird ideas. You're likely to run into runtime problems with the FFCX form compiler (*bad* *bad* *bad* idea, running a C compiler runtime) failing due to something, somewhere, in the extremely fragile Conda setup, trying to load system libraries wrongly, etc.
124
125 #### Option 1.C: Debian/Ubuntu
126
127 You may be able to use the system package manager, but beware of obsolete and modified versions. As of 2026-03-23, the packages available in Debian/Ubuntu cause massive memory leaks and eventual system crash.
128
129 ### Phase 2: Rust
25 130
26 You will only need to install the “nightly” Rust compiler and the 131 You will only need to install the “nightly” Rust compiler and the
27 [GNU Scientific Library] manually. At the time of writing this README, 132 [GNU Scientific Library] manually. At the time of writing this README,
28 [alg_tools] also needs to be downloaded separately. 133 [alg_tools] also needs to be downloaded separately.
29 134
30 1. Install the [Rust] infrastructure (including Cargo) with [rustup]. 135 1. Install the [Rust] infrastructure (including Cargo) with [rustup].
31 2. Install a “nightly” release of the Rust compiler. With rustup, installed in 136 2. Install a “nightly” release of the Rust compiler. With rustup, installed in
32 the previous step, this can be done with 137 the previous step, this can be done with
33 ```console 138
34 rustup toolchain install nightly 139 rustup toolchain install nightly
35 ``` 140
36 3. Install [GNU Scientific Library]. On a Mac with [Homebrew] installed, 141 3. Download [alg_tools], [pointsource_algs], and [measures] and unpack them under
37 this can be done with 142 the same directory as this package.
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 143
49 [rustup]: https://rustup.rs 144 [rustup]: https://rustup.rs
50 [alg_tools]: https://tuomov.iki.fi/software/alg_tools/ 145 [alg_tools]: https://tuomov.iki.fi/software/alg_tools/
146 [pointsource_algs]: https://tuomov.iki.fi/software/pointsource_algs/
147 [measures]: https://tuomov.iki.fi/repos/measures/
51 [Rust]: https://www.rust-lang.org/ 148 [Rust]: https://www.rust-lang.org/
52 [GNU Scientific Library]: https://www.gnu.org/software/gsl/ 149 [GNU Scientific Library]: https://www.gnu.org/software/gsl/
53 [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/ 150 [rust-GSL]: https://docs.rs/GSL/6.0.0/rgsl/
54 [Homebrew]: https://brew.sh 151 [Homebrew]: https://brew.sh
55 [arXiv:2212.02991]: https://arxiv.org/abs/2212.02991 152 [arXiv:2212.02991]: https://arxiv.org/abs/2212.02991
56 [arXiv:2502.12417]: https://arxiv.org/abs/2502.12417 153 [arXiv:2502.12417]: https://arxiv.org/abs/2502.12417
57 [doi:10.46298/jnsao-2023-10433]: http://doi.org/10.46298/jnsao-2023-10433 154 [doi:10.46298/jnsao-2023-10433]: http://doi.org/10.46298/jnsao-2023-10433
58 155
59 ### Building and running the experiments 156 ### Linux / further patching
60 157
61 To compile and install the program, use 158 Due to both Fenics and typical Linux system being completely broken, you may need to do further patching to get things to compile:
62 ```console 159
63 cargo install --path=. 160 1. I had to set (in my [direnv](https://direnv.net) `.envrc`)
64 ``` 161
162 export PKG_CONFIG_PATH=/home/linuxbrew/.linuxbrew/lib/pkgconfig:/usr/local/lib/pkgconfig/:/usr/lib/aarch64-linux-gnu/pkgconfig/
163 export LD_LIBRARY_PATH=/home/linuxbrew/.linuxbrew/lib
164
165 2. Some libraries, in particular `libfmt` and `libspdlog` installed in Homebrew, may conflict with system versions, that must be removed.
166 Lack of proper sandboxing in legacy Linux distributions, effectively prohibits multiple versions of the same library.
167 2. I had to add `Libs` in `/usr/local/lib/pkgconfig/dolfinx.pc` the bit `-L/home/linuxbrew/.linuxbrew/lib/ -lopenblas`. Nothing in the fenics stack seems to explicitly require it. Basix, that depends on openblas, is entirely missing a `pkg-config` file.
168 3. Also `export export OMP_NUM_THREADS=1` (in `.envrc`). We don't do MPI. We cannot do MPI in Fenics' lame “it's all just parallel solution of PDEs, with no other computation, ever” aka “single-program multiple-data, with no controller at all” way. If you don't do this, you may have multiple threads wasting CPU just being there. We try to control the thread count in our code, but OpenMPI on Linux doesn't seem to respect it.
169
170 ## Building and running the experiments
171
172 To compile the program, run
173
174 cargo build --release
175
65 When doing this for the first time, several dependencies will be downloaded. 176 When doing this for the first time, several dependencies will be downloaded.
66 Now you can run the default set of experiments with 177 Now you can run the experiments in the article with
67 ``` 178
68 pointsource_pde -o results 179 cargo run --release -- \
69 ``` 180 -o results -a radon_sliding_fb -a radon_fb --max-iter 20000
70 The `-o results` option tells `pointsource_pde` to write results in the 181 experiments/laser_and_mirrors_aux.py experiments/laser_and_mirrors_aux2.py
71 `results` directory. The option is required. 182
72 183 The `-o results` option tells `pointsource_pde` to write results in the `results` directory.
73 Alternatively, you may build and run the program without installing with 184 The other options indicate the algorithms and experiments to run, as well as the maximum number
74 ```console 185 of iterations.
75 cargo run --release -- -o results 186 The double-dash separates the options for the Cargo build system and `pointsource_pde`.
76 ``` 187
77 The double-dash separates the options for the Cargo build system 188 ### Visualising the results
78 and `pointsource_pde`. 189
79 190 The results may be plotted with
80 ### Documentation 191
192 python3 ./plot.py results/laser_and_mirrors_aux/radon_sliding_fb
193
194 Vary the path to `laser_and_mirrors_aux2` and `radon_fb` for the alternative experiment and basic algorithm.
195
196 The script `misc/copy_results.sh` may be generate the images and copy the results in the manuscript
197 to `../gasleak`.
198
199 ## Documentation
81 200
82 Use the `--help` option to get an extensive listing of command line options to 201 Use the `--help` option to get an extensive listing of command line options to
83 customise algorithm parameters and the experiments performed. 202 customise algorithm parameters and the experiments performed.
84 203
85 ## Internals 204 ### Internals
86 205
87 If you are interested in the program internals, the integrated source code 206 If you are interested in the program internals, the integrated source code
88 documentation may be built and opened with 207 documentation may be built and opened with
89 ```console 208
90 cargo doc # build dependency docs 209 cargo doc # build dependency docs
91 misc/cargo-d --open # build and open KaTeX-aware docs for this crate 210 misc/cargo-d --open # build and open KaTeX-aware docs for this crate
92 ``` 211
93 The `cargo-d` script ensures that KaTeX mathematics is rendered in the 212 The `cargo-d` script ensures that KaTeX mathematics is rendered in the generated documentation through an ugly workaround. Unfortunately, `rustdoc` is stuck in 80's 7-bit gringo ASCII world,
94 generated documentation through an ugly workaround. Unfortunately, 213 and does not support modern markdown features, such as mathematics.
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.

Mercurial Repository: pointsource_pde

mercurial