A new X-MeshGraphNet example for reservoir simulation.

CHANGELOG.md

@@ -26,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   and three transient schemes.
 - Added a check to `stochastic_sampler` that helps handle the `EDMPrecond` model,
   which has a specific `.forward()` signature
+- Examples: added a new example for reservoir simulation using X-MeshGraphNet.
+  Accessible in `examples/reservoir_simulation`
 
 ### Changed
 

examples/reservoir_simulation/sim_utils/README.md

@@ -0,0 +1,125 @@
+# Simulation Utilities
+
+## Overview
+
+The `sim_utils` package provides utilities for processing ECL/IX style binary
+output files to prepare datasets for training. These scripts can read industry
+standard simulator output formats (ECLIPSE, IX, OPM) and convert them into
+various data structures suitable for different ML architectures.
+
+## Supported Formats
+
+- `.INIT`
+- `.EGRID`
+- `.UNRST` or `.X00xx`
+- `.UNSMRY` or `.S00xx`
+
+## Modules
+
+### `ecl_reader.py`
+
+Main class for reading ECLIPSE-style binary output files.
+
+**Usage**:
+
+```python
+from sim_utils import EclReader
+
+# Initialize reader with case name
+reader = EclReader("path/to/CASE.DATA")
+
+# Read static properties
+init_data = reader.read_init(["PORV", "PERMX", "PERMY", "PERMZ"])
+
+# Read grid geometry
+egrid_data = reader.read_egrid(["COORD", "ZCORN", "FILEHEAD", "NNC1", "NNC2"])
+
+# Read dynamic properties (all timesteps)
+restart_data = reader.read_restart(["PRESSURE", "SWAT", "SGAS"])
+```
+
+**Common Keywords**:
+
+Static properties (INIT):
+
+- `PORV`: Pore volume
+- `PERMX`, `PERMY`, `PERMZ`: Permeability in X, Y, Z directions
+- `PORO`: Porosity
+- `TRANX`, `TRANY`, `TRANZ`: Transmissibility in X, Y, Z directions
+
+Dynamic properties (UNRST):
+
+- `PRESSURE`: Cell pressure
+- `SWAT`: Water saturation
+- `SGAS`: Gas saturation
+- `SOIL`: Oil saturation
+
+Grid geometry (EGRID):
+
+- `COORD`: Grid pillar coordinates
+- `ZCORN`: Grid corner depths
+- `FILEHEAD`: File header information
+- `NNC1`, `NNC2`: Non-neighboring connections
+
+### `grid.py`
+
+**Grid** - Handles reservoir grid structure and operations.
+
+**Features**:
+
+- Grid dimensions and active cells
+- Cell center coordinates computation
+- Connection/edge computation for graph construction
+- Aggregating directional transmissibilities for edge features
+- Non-Neighboring Connections (NNC)
+- Well completion arrays
+
+**Usage**:
+
+```python
+from sim_utils import Grid
+
+# Initialize grid from simulation data
+grid = Grid(init_data, egrid_data)
+
+# Get connections and transmissibilities for graph construction
+connections, transmissibilities = grid.get_conx_tran()
+
+# Create completion arrays for wells
+completion_inj, completion_prd = grid.create_completion_array(wells)
+
+# Access grid properties
+print(f"Grid dimensions: {grid.nx} x {grid.ny} x {grid.nz}")
+print(f"Active cells: {grid.nact}")
+print(f"Cell coordinates: X={grid.X}, Y={grid.Y}, Z={grid.Z}")
+```
+
+### `well.py`
+
+**Well** and **Completion** - Well and completion data structures. Typically,
+use results from `UNRST` (well name, type, status, I, J, K, etc.) to
+instantiate the object.
+
+**Usage**:
+
+```python
+from sim_utils import Well, Completion
+
+# Create a well
+well = Well(name="INJ1", type_id=3, stat=1)  # Water injector
+
+# Add completions
+well.add_completion(
+    I=10,          # Grid I-index
+    J=10,          # Grid J-index
+    K=5,           # Grid K-index
+    dir=3,         # Direction (1=X, 2=Y, 3=Z)
+    stat=1,        # Status (1=OPEN)
+    conx_factor=1.0  # Connection factor
+)
+
+# Check well properties
+print(f"Well type: {well.type}")  # 'INJ' or 'PRD'
+print(f"Well status: {well.status}")  # 'OPEN' or 'SHUT'
+print(f"Number of completions: {len(well.completions)}")
+```

examples/reservoir_simulation/sim_utils/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: Copyright (c) 2023 - 2024 NVIDIA CORPORATION & AFFILIATES.
+# SPDX-FileCopyrightText: All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Reservoir Utilities
+
+Shared utilities for processing reservoir simulation data across different
+machine learning architectures (XMeshGraphNet, FNO, DeepONet, etc.).
+
+This package contains:
+- ecl_reader: Read ECLIPSE-style simulation output files (.INIT, .EGRID, .UNRST, etc.)
+- grid: Grid data structures and operations for reservoir simulations
+- well: Well and completion data structures
+"""
+
+from .ecl_reader import EclReader
+from .grid import Grid
+from .well import Well, Completion
+
+__all__ = ["EclReader", "Grid", "Well", "Completion"]
+
+__version__ = "1.0.0"