Reservoir Simulation Notebook
A Visual Studio Code extension providing comprehensive language support for reservoir simulation data files (.data, .inc) used in Eclipse, tNavigator, and other simulators.
Why This Extension?
This extension was developed as a first-of-its-kind simulation-deck "notebook reader" to help reservoir engineers work more efficiently with .DATA and .INC files. It auto-generates keyword-based descriptions and contextual comments, providing one-click access to detailed guidance and examples — bridging the gap between simulation manuals and daily workflows.
Features at a Glance
| Feature |
Description |
| Syntax Highlighting |
Color-coded keywords by category |
| Hover Documentation |
Instant keyword info on mouse hover |
| Definition Panel |
Detailed documentation in sidebar |
| Include Navigation |
Click to open .inc files |
| Theme Support |
Works with dark and light themes |
Supported Files
.data / .DATA - Main simulation files.inc / .INC - Include files
Syntax Highlighting
What You Get
Keywords are automatically highlighted based on their category:
| Color |
Category |
Examples |
| Orange |
Main Sections |
RUNSPEC, GRID, PROPS, SCHEDULE |
| Blue |
Definition/Init |
TITLE, DIMENS, START |
| Cyan |
Grid Properties |
DX, DY, DZ, PERMX, PORO |
| Purple |
PVT/Fluids |
PVTO, PVTW, DENSITY, SWOF |
| Yellow |
Schedule |
WELSPECS, COMPDAT, WCONPROD |
| Light Blue |
Output |
FOPR, FWCT, BPR |
Additional Highlighting
| Element |
Style |
Comments (--) |
Green italic |
Strings ('...') |
Brown |
| Numbers |
Light green, larger font |
Slashes (/) |
Gold, bold |
Asterisks (*) |
Red, bold |
| Include files |
Cyan, underlined (clickable) |
Inline Descriptions
Each keyword shows a brief description inline:
DIMENS // Specifies the dimensions of the grid
10 10 5 /
Hover Documentation
Hover over any keyword to see:
- Description - What the keyword does
- Data Format Support - Which simulators support it (tN, E1, E3, etc.)
- Sections - Where it can be used
- Examples - Sample code
| Icon |
Meaning |
| 🟢 |
Supported |
| 🔴 |
Not supported |
Supported Simulators
| Code |
Simulator |
| tN |
tNavigator |
| E1 |
Eclipse 100 |
| E3 |
Eclipse 300 |
Definition Panel
Get detailed documentation in a sidebar panel:
How to Open
- Right-click on a keyword → Select "Open Keyword Definition"
- Or hover on a keyword → Click "Open Full Definition" link
Panel Contents
- Full markdown-rendered description
- Data format compatibility badges
- Section applicability badges
- Category classification
- Code examples with explanations
Include File Navigation
Navigate between files easily:
How It Works
- Include file paths in quotes are detected:
'path/to/file.inc'
- They appear as cyan underlined links
- Click to open the referenced file
- Hover to see the file path
Example
INCLUDE
'../include/grid.inc' / -- Click to open
INCLUDE
'pvt/pvt_data.inc' / -- Relative paths work too
Right-click options:
| Option |
Action |
| Open Keyword Definition |
Opens documentation panel for selected keyword |
Theme Support
The extension adapts to your VS Code theme:
- Dark themes: Dark backgrounds with bright colors
- Light themes: Light backgrounds with darker colors
Colors automatically update when you switch themes.
Main Sections Reference
| Section |
Purpose |
RUNSPEC |
Problem definition, phases, dimensions |
GRID |
Grid geometry and static properties |
EDIT |
Modify grid properties |
PROPS |
Fluid and rock properties |
REGIONS |
Property regions |
SOLUTION |
Initial conditions |
SUMMARY |
Output requests |
SCHEDULE |
Wells and time steps |
Installation
From VS Code Marketplace
- Open VS Code
- Go to Extensions (
Ctrl+Shift+X)
- Search for "Reservoir Simulation Notebook"
- Click Install
Quick Start
- Open a
.data or .inc file
- See automatic syntax highlighting
- Hover over keywords for quick info
- Right-click keywords for full documentation
- Click on include file paths to navigate
Keyboard Shortcuts
| Action |
Shortcut |
| Open command palette |
Ctrl+Shift+P |
| Reload window |
Ctrl+Shift+P → "Reload Window" |
Tips & Tricks
1. Quick Keyword Lookup
Hover on any keyword for instant documentation without leaving your code.
2. Side-by-Side Documentation
The definition panel opens beside your editor, so you can code and read docs simultaneously.
3. Navigate Large Models
Use include file links to quickly jump between files in complex simulation models.
4. Spot Errors Quickly
Unrecognized keywords appear in default text color - easy to spot typos!
5. Number Readability
Numbers are displayed larger with separators between values for easier data verification.
Troubleshooting
| Problem |
Solution |
| No highlighting |
Check file extension is .data, .DATA, .inc, or .INC |
| Hover not working |
Ensure cursor is on a valid keyword |
| Definition panel empty |
Right-click directly on a keyword |
| Include links not working |
Ensure path is in single quotes |
Requirements
Feedback & Issues
Please send any feedback directly to reservoir_simulation_extention@amramadan.com.
License
Proprietary Source-Available License.
This software is made available for use only. Users may use the software for personal, academic, research, or internal purposes, provided that proper attribution is given to the author.
Users may not sell, sublicense, commercialize, modify, redistribute modified versions, or incorporate this software into commercial products without prior written permission from the author.
See the LICENSE file for full license terms.
About the Author
Amr Ramadan
Reservoir & Simulation Engineer | ML/Cloud Engineer | Technical Content Creator
Background
Reservoir Engineer with 12+ years of industry experience at HESS, OXY, APA, Pharos Energy, Kuwait Energy and APA Egypt JV, specializing in reservoir simulation, production optimization, and digital transformation.
Highlights
- 30+ peer-reviewed publications in SPEJ, MDPI, ATCE, OTC, URTeC, ADIPEC, OPES and other top-tier conferences/journals (170+ citations)
- Technical Reviewer for 100+ manuscripts across SPE Journal, Energies, and other reputable journals
- YouTube Creator @reswaves — 90+ tutorial videos, 7,000+ subscribers, 4,000+ viewing hours on reservoir simulation workflows
- SPE Leadership
— Technical Committee Member and Session Chair for multiple reputable industry conferences, including SPE ATCE, OTC, URTeC, and others.
— Active contributor to digital transformation initiatives within SPE GTTS and CCUS TS.
— Judge for international professional awards, including the SPE Data Science and Analytics Award and the Giovanni Paccaloni Young Professional Service Award.
- 2 Patents Filed at University of Houston on deep learning methods for hydraulic fracture detection
Technical Skills
| Category |
Skills |
| Simulation |
tNavigator, Eclipse, PETREL, KAPPA Suite, ResFrac, Whitson+, ComboCurve |
| Programming |
Python, TypeScript, C#, SQL, JS |
| ML/AI |
TensorFlow, PyTorch, Transformers, LLMs, MLflow |
| Cloud |
AWS, Azure, GCP, Snowflake, Databricks, Airflow |
| Visualization |
Power BI, Tableau, Spotfire |
Built for reservoir engineers, by a reservoir engineer.
