Skip to content

Latest commit

 

History

History
214 lines (154 loc) · 6.74 KB

README.md

File metadata and controls

214 lines (154 loc) · 6.74 KB
Raw

r2ogs6

Pipeline Status Test Coverage DOI JOSS Submission

r2ogs6 provides a file--based interface of the multi--physics sub-surface process simulator OpenGeoSys 6 to the R programing and statistical computing environment. It enables geoscientist, hydrologists and engineers to perform and analyze simulation models of the sub--surface earth system with R. r2ogs6 provides means to:

  • pre-process (preparing input files) simulations with OpenGeoSys 6
  • execute single and ensemble simulations
  • output post-processing and visualization

Setup

r2ogs6 requires an installation of OpenGeoSys 6. Furthermore, Python including the libraries numpy and vtk is required to read in the .vtu and .pvd files produced by OpenGeoSys 6. These can be install after having installed r2ogs6. r2ogs6 was tested with the following environment: python==3.10.12, vtk==9.3.0, numpy==1.26.4

r2ogs6 Installation

First, open a terminal and clone the r2ogs6 repository to your local machine.

git clone https://gitlab.opengeosys.org/ogs/tools/r2ogs6.git

To install r2ogs6, you first need the R-packages remotes and BiocManager. remotes is used for installing r2ogs6 and BiocManager to set the URLs to search dependencies on CRAN and bioconductor.org. For instance, the dependency rhdf5 is only available on bioconductor.org. Open a R console in your specific project:

install.packages(c("remotes", "BiocManager"))

With remotes, you can now install r2ogs6 in your preferred library.

# Install r2ogs6. Change "path/to/r2ogs6" to that of the cloned repository!
remotes::install_local(
    path="path/to/r2ogs6", 
    dependencies="Imports",
    repos=BiocManager::repositories()
)

Set-up Python

OpenGeoSys 6 requires a Python installation of version 3.8--3.11.

Linux systems

If you do not have Python installed yet you can do so with the reticulate library from your R console.

reticulate::install_python(version = "3.10:latest")

Otherwise you can use the package manager of your linux distribution.

Windows

Ideally, install Python with a Python Windows installer. Of course you could also try:

reticulate::install_python(version = "3.10:latest")

Install Python dependencies and OpenGeoSys 6

Create a Python virtual environment with a specific name (e.g. "r2ogs6) and the path to the Python executable you just installed.

reticulate::virtualenv_create(
    envname="r2ogs6", 
    python="/path/to/python",
    packages = c("numpy", "vtk")
)

Make sure that reticulate::py_config()$python points to the python executable in the newly installed Python virtual environment. You can try to force reticulate to use the executable of your environment by:

reticulate::use_virtualenv(virtualenv="r2ogs6")

If that does not work, quit your R session and create a .Renviron file in your project folder where you can set the path to the created virtual python environment:

# .Renviron linux
RETICULATE_PYTHON=/path/to/your/virtualenv/bin/python

This file is read at the start-up of R and forces reticulate to use your specific Python executable. Double check if your python envrionment is now recognized:

reticulate::py_config()

Then you can install OpenGeoSys 6 (the Python dependencies numpy and vtk will be installed alongside) as Python module.

library(r2ogs6)
install_ogs(ogs_version = "6.4.4", envname = "r2ogs6")

Be aware, to install the OpenGeoSys 6 version compatible with the r2ogs6 version, see releases. Check if OpenGeoSys 6 was installed correctly.

reticulate::py_module_available("ogs")

The OpenGeoSys 6 binary should be located at /path/to/your/python_env/bin/ogs (Linux) or /path/to/your/python_env/Scripts/ogs (Windows). In your active R session you can temporarily set this path as default when using r2ogs6 (sets options("r2ogs6.default_ogs6_bin_path").)

set_ogs6_bin_path()

For setting this permanently, create a config.yml file in your project directory.

# config.yml for linux
default:
    r2ogs6.default_ogs6_bin_path: /path/to/python_env/bin/ogs

Alternative manual setup of Python environment

Alternatively, you can set up the python environment including OpenGeoSys 6 without reticulate; have a look here. Be aware, to download or install the OpenGeoSys 6 version compatible with the r2ogs6 version, see releases.

Nevertheless r2ogs6 uses reticulate under the hood. So make sure that reticulate::py_config() shows the correct Python environment that you configured.

Usage

To quickly test if your set up works just run a benchmark shipped with the package. Remember that if you closed your R session in between you may have to reset the ogs_bin_path by set_ogs6_bin_path(). Now you can setup an example by:

sim_path <- tempdir()

# Create new ogs object
ogs6_obj <- OGS6$new(
    sim_name = "my_simulation",
    sim_path = sim_path
)

# Read in a project setup file
prj_path <- system.file(
    "extdata/benchmarks/flow_no_strain/flow_no_strain.prj",
    package = "r2ogs6"
)
read_in_prj(ogs6_obj, prj_path = prj_path, read_in_gml = T)

Just start the simulation, check if it succeeds (returns a "0" exit status) and hav a look at the output.

ogs6_run_simulation(ogs6_obj)

ogs6_read_output_files(ogs6_obj)
result_df <- ogs6_obj$pvds[[1]]$get_point_data(keys = c("pressure"))
result_df

Further Reading

For tutorials on how to use the r2ogs6 package, have a look at its vignettes:

Corresponding HTML versions can be found here.

Links