pmgbergen
Published May 19, 2026 | Version v2
Software Open

Runscripts for the manuscript 'Data-driven linear solver selection and performance tuning for multiphysics simulations in porous media'

Authors/Creators

  • 1. ROR icon University of Bergen

Description

Data-driven linear solver selection and performance tuning for multiphysics simulations in porous media

The code in this branch implements a machine-learning-based preconditioned linear solver selection algorithm for multphysics simulations. Two model problems are considered:
- Coupled flow and heat transport in porous media with heterogeneous permeability.
- Coupled thermo-hydro-mechanics in porous media with fractures, governed by frictional contact mechanics.
The implementation is based on PorePy and PETSc.

Reproduce the experiments

Here you can find the information on how to:
- Prepare the environment
- Analyse and visualize the performance data of our numerical experiments
- Reproduce the numerical experiements

Step 1. Installation

To reproduce the experiments, PETSc, PorePy and all their dependencies must be installey. To skip this tedious process, it is highly recommended to use Docker. We provide a docker image, which has all the needed dependencies packed into it and ensures reproducibility of the experiments. You need to install Docker following the official instruction. The instructions below are hopefully agnostic to the operation system, but were tested on Windows 11 with Windows Subsystem for Linux 2 (WSL 2) installed.
 
When Docker is installed and running, download the image of this repository (below on this page). Note that it is a few gigabytes.
To start a docker container based on this image, navigate to the folder you've downloaded it and run these terminal commands:
docker load -i solver_selection_thm.tar.gz   # This may take a few minutes
docker run -dit --name solver_selection_thm solver_selection_thm:latest
docker exec -it solver_selection_thm /bin/bash
Please don't forget to pull the recent changes with git pull.
 
For the graphical user interface, it is recommended to use VSCode and attach to the running container, following the official instruction.
 
The repository root folder is located at /home/porepy/solver_selection_thm in the docker container file system.
 
The numerical experiments are tested using Python 3.11.7, PorePy commit 65199b1a609af269d3a44204a06f8c97f3891d65 and PETSc commit bff66efa9044f546ae447ed195723e21295eb6dd. All the other dependencies are listed in requirements.txt. The docker container has the correct versions pre-installed, so you don't need to do anything else.

Step 2. Accessing the data of our numerical experiments

The data of the experiments, used to generate figures and tables for the publications are commited to the stats/ folder. You can see the numerical experiment datasets in Pandas and reproduce the figures and the tables using these jupyter notebooks:
- Sequence A - coupled flow and heat transport: solver_selection_thm/spe_results.ipynb;
- Sequence B - contact-THM: solver_selection_thm/thm_results.ipynb.
 
It may take a few minutes to run the notebooks for the first time, as Numba needs to compile within PorePy. After that, running the notebooks typically takes seconds.
 
If you are experiencing problems with jupyter notebooks, the same can be done in python files (navigate to the directory solver_selection_thm/ before running them):
- cd solver_selection_thm; python spe_results.py;
- cd solver_selection_thm; python thm_results.py

Step 3. Re-running the numerical experiments

If you want re-run the simulations, we recommend you to delete the contents of the stats/ folder to avoid mixing our data with yours. You can always restore the original data using git.
 
To run all the simulations from the paper, use the following command from the root folder of this repository:
bash solver_selection_thm/runscript.sh
It will run the following experiments:
- Random selection experiment (Section 6.1 in the paper);
- Solver selection experiment (Section 6.2 in the paper);
- Expert selection experiment (Section 6.3 in the paper).
 
Each experiment will run for both Sequence A and Sequence B. Each experiment will be repeated 5 times to account for randomness. Each of 5 repetitions is assigned a run_id within [200, 201, 202, 203, 204] (successively). These run_ids are used in the file names and in the visualization notebooks.
 
Warning: Executing this command takes about a real world week on our machine, so you might not want to wait for it to complete.
 
You can instead run the experiments selectively. To run the experiments for Sequence A with only one repetition, use the following commands from the root folder of this repository:
python solver_selection_thm/spe_runscript.py 0 random            # section 6.1 experiment
python solver_selection_thm/spe_runscript.py 0 solver_selection  # section 6.2 experiment
The first command-line argument takes a value from 0 to 4 to account for the repetition index.
 
The commands above take about 2.5 hours on our machine.
 
For Sequence B, use these commands from the root folder of this repository:
 
python solver_selection_thm/thm_runscript.py 0 random            # section 6.1 experiment
python solver_selection_thm/thm_runscript.py 0 solver_selection  # section 6.2 experiment
The commands above take about 10 hours on our machine and its peak memory consumption is ~20 GBs. We recommend running only Sequence A if your machine has less RAM.
 
The experiments in Section 6.3 are based on the data, previously collected in Sections 6.1 and 6.2, so you need to restore our data with git, if you have deleted it before. Use the following commands from the root folder of this repository to run them:
python solver_selection_thm/spe_runscript.py 0 expert  # Sequence A
python solver_selection_thm/thm_runscript.py 0 expert  # Sequence B
When the experiments are complete, you can return to Step 2 to visualize and analyse the data.

Acknowledgement

This project has received funding from the VISTA program, The Norwegian Academy of Science and Letters and Equinor and from the European Research Council (ERC) under the European Union’s Horizon 2020 research and innovation program (grant agreement No 101002507).
 

Citing

If you want to cite this code in your research, we ask you to cite the following preprint: https://arxiv.org/abs/2510.04920 The link will be updated upon journal publication.

Files

Files (3.6 GB)

Name Size Download all
md5:3faca0beb10229e0f973d3b04b1c4a25
3.6 GB Download

Additional details

Related works

Is supplement to
Publication: 10.48550/arXiv.2510.04920 (DOI)

Software

Repository URL
https://github.com/Yuriyzabegaev/FTHM-Solver/tree/solver_selection
Programming language
Python
Development Status
Active