https://github.com/ImperialCollegeLondon/StrataTrapper
Field scale model generation and upscaling toolkit
https://github.com/ImperialCollegeLondon/StrataTrapper
capillary-pressure carbon-dioxide co2 co2-storage heterogeneity matlab opm-flow pflotran porous-media-flow reservoir-simulation upscaling
Last synced: 2 months ago
JSON representation
Field scale model generation and upscaling toolkit
- Host: GitHub
- URL: https://github.com/ImperialCollegeLondon/StrataTrapper
- Owner: ImperialCollegeLondon
- License: bsd-3-clause
- Created: 2024-01-10T17:00:18.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-04-01T12:53:25.000Z (2 months ago)
- Last Synced: 2026-04-03T04:23:29.010Z (2 months ago)
- Topics: capillary-pressure, carbon-dioxide, co2, co2-storage, heterogeneity, matlab, opm-flow, pflotran, porous-media-flow, reservoir-simulation, upscaling
- Language: MATLAB
- Homepage: https://imperialcollegelondon.github.io/StrataTrapper
- Size: 20.6 MB
- Stars: 12
- Watchers: 2
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Citation: CITATION.cff
- Notice: NOTICE.txt
Awesome Lists containing this project
- open-sustainable-technology - StrataTrapper - Advanced modelling of CO2 migration and trapping. (Emissions / Carbon Capture)
README
# Field scale model generation and upscaling toolkit
Repository: [github.com/ImperialCollegeLondon/StrataTrapper](https://github.com/ImperialCollegeLondon/StrataTrapper)
[](https://opensource.org/licenses/BSD-3-Clause)
[](https://doi.org/10.5281/zenodo.15438164)
* [The StrataTrapper codes](#the-stratatrapper-codes)
* [Structure](#structure)
* [Running](#running)
* [Output compression](#output-compression)
* [MEX acceleration](#mex-acceleration)
* [Versions](#versions)
* [Contributing](#contributing)
* [References](#references)
## The StrataTrapper codes
This is the StrataTrapper **upscaling toolkit**.
It can also generate heterogeneous fine-scale models with specific correlation lengths
to re-upscale given coarse-scale two-phase flow models.
Another tool is the **reduced-physics model** [CO2GraVISim](https://github.com/ajobutler/CO2GraVISim).
In [`StrataTrapper-models`](https://github.com/ImperialCollegeLondon/StrataTrapper-models)
repository, we publish field-scale models upscaled with StrataTrapper.
## Structure
Top-level scripts and functions are in the repository root,
and the rest is in [`src/`](src) folder.
[`demo.m`](demo.m) script is an implementation of the running guideline below.\
Feel free to play with it and use as an example for your own scripts.
## Running
1. Run [`startup.m`](startup.m) to setup MATLAB Path.
1. Optional: start a parallel pool to run computations there.
2. Read or generate target coarse grid dimensions
and input fine-scale porosity and permeability for each coarse block.
3. Setup input rock-fluid properties and algorithm options represented by
[`Params`](src/Params.m) and [`Options`](src/Options.m) classes.
Pass an array of `Params` for multiple-region models.
4. Create integer `mask` to:
* filter out impermeable cells
and/or compute an arbitrary subset of cells by putting `0`s
* Put index `n` of the input array of `Params`
to map coarse cells to the corresponding regions
5. Run [`strata_trapper`](src/strata_trapper.m) function
with arbitrary number of parallel workers
optionally enabling a UI progress bar.
6. Visualise outputs with [`plot_result`](src/plot_result.m) function
7. Export the outputs to [PFLOTRAN-OGS](https://docs.opengosim.com/)
or [OPM Flow](https://opm-project.org/?page_id=19) format
using [`ogs_export`](src/export/ogs_export.m)
or [`opm_export`](src/export/opm_export.m) function, respectively.
Tips:
* Usually, MATLAB runs `startup.m` scripts automatically
if they are in a startup folder.
* The heaviest part of the algorithm is essentially parallel with no synchronisation.
So, using several parallel workers usually results
in a proportional performance boost.
## Output compression
By default, `strata_trapper` outputs one set of saturation tables
**per coarse cell per direction**.
Such a number might be found too big in some situations.
With [`quantize`](src/compress/quantize.m),
toolkit can now compress the set of saturation tables
if they are similar enough or the acceptable approximation error is high.
Read [compression README](src/compress/README.md) for more details.
## MEX acceleration
We provide the `CodeGenMex` class to automatically build
a MEX-accelerated version of computationally-demanding functions
such as [`upscale`](src/upscale.m).
```matlab
% 1. compile MEX functions
codegen_mex = CodeGenMex().config().build();
% 2. use strata_trapper normally
...
% 3. recompile MEX functions when the source code changes
codegen_mex.build();
% 4. delete MEX functions to use the original
codegen_mex.clear();
```
Requires [MATLAB Coder](https://uk.mathworks.com/products/matlab-coder.html).
## Versions
The original version of the toolkit is [v0.1.0](https://github.com/ImperialCollegeLondon/StrataTrapper/tree/v0.1.0).\
It has its own structure and some unique functionality,\
so it may worth attention as much as later versions.
[CHANGELOG.md](CHANGELOG.md) describes the version history and key changes.
Other versions can be accessed via
[tags](https://github.com/ImperialCollegeLondon/StrataTrapper/tags) and
[releases](https://github.com/ImperialCollegeLondon/StrataTrapper/releases)
sections of the repository.
## Contributing
Everyone is welcome to open
[issues](https://github.com/ImperialCollegeLondon/StrataTrapper/issues) and
[pull requests](https://github.com/ImperialCollegeLondon/StrataTrapper/pulls).
## References
The StrataTrapper algorithm as well as motivation
and theory behind it are in the paper:
> Samuel J. Jackson, Samuel Krevor\
> **Small-Scale Capillary Heterogeneity**
> **Linked to Rapid Plume Migration During CO2 Storage**\
> *Geophysical Research Letters* | 2020\
>