Python wrapper for JutulDarcy.jl, a fully differentiable reservoir simulator written in Julia. Key features:
- Immiscible, black-oil and compositional multiphase flow
- Geothermal simulation and simulation of CO2 sequestration
- Can read standard input files and corner-point grids, or make your own
This package facilitates automatic installation of JutulDarcy from Python, as well as a minimal interface that allows fast simulation of .DATA files in pure Python. For more details about JutulDarcy.jl, please see the Julia Documentation. If you want to run MPI accelerated simulations we recommend working either in Julia or the standalone compiled version.
For wrapper-specific installation, Python/Julia conversions and API reference, see the Python documentation.
The package also provides access to all the functions of the Julia version under jutuldarcy.jl.JutulDarcy, jutuldarcy.jl.GeoEnergyIO and jutuldarcy.jl.Jutul. These functions are directly wrapped using JuliaCall. For more details, see the JuliaCall Documentation on converting of types.
Requires Python 3.10 or newer.
python -m pip install jutuldarcyThe first import automatically installs Julia and the registered JutulDarcy dependencies. Initial installation and compilation take several minutes and need network access.
import jutuldarcy as jd
path = jd.test_file_path("SPE9", "SPE9.DATA")
output = jd.simulate_data_file(path, convert=True)
pressure = output["STATES"][-1]["Pressure"] # NumPy array in PaConverted results contain FIELD and WELLS summary dictionaries, a DAYS array
and one reservoir state dictionary per output time in STATES. Omit
convert=True to retain the native Julia result. Cell and well coordinates in
wrapper inputs are one-based; Python/NumPy array indexing is zero-based.
The Python documentation includes executed examples for building a model, running SPE9, plotting and computing gradients. Every documentation build runs these scripts and publishes their output and figures.
For interactive 3D plots, run jd.install_plotting() once (requires OpenGL).
For headless rendering, use jd.install_plotting("CairoMakie"). See the
user guide for results,
execution backends and Julia configuration, and the
Julia manual for model physics
and the complete simulator API.
The main paper describing JutulDarcy.jl is JutulDarcy.jl - a Fully Differentiable High-Performance Reservoir Simulator Based on Automatic Differentiation, available as open access from Springer:
@article{jutuldarcy,
title={JutulDarcy.jl - a fully differentiable high-performance reservoir simulator based on automatic differentiation},
author={M{\o}yner, Olav},
journal={Computational Geosciences},
volume={29},
number={30},
year={2025},
publisher={Springer}
}Contributions that expose additional functionality is welcome. See the contributor guide for tests and documentation builds.
The release workflow publishes a wheel and source
distribution when a tag named v<version> is pushed. The tag must exactly match
project.version in pyproject.toml, for example v1.2.2 for version 1.2.2.
Prereleases use the same convention, for example v1.3.0rc1.
To release, update project.version in pyproject.toml, merge the change into
main, then create and push an annotated tag for that commit:
git switch main
git pull --ff-only
git tag -a v1.2.2 -m "Release 1.2.2"
git push origin v1.2.2Use the version being released in place of 1.2.2. After the workflow builds and
validates the distributions, review the tagged commit and approve the pypi
environment deployment. Publishing uses short-lived OIDC credentials and creates
PyPI attestations; no PyPI API token or GitHub secret is needed. The publishing
job only downloads the artifacts built in the same workflow run and uploads them
to PyPI. Action dependencies are pinned to commit SHAs, and Dependabot proposes
updates monthly.
Each PyPI version can only be published once. If a release fails partway through uploading, inspect the files already on PyPI before retrying; the workflow fails on existing files rather than silently skipping them.