datafiletoolbox 0.55.0

a set of utilities to deal with results from reservoir simulators and other sources of tabulated data.

datafiletoolbox

A set of classes and utilities to read different simulation output files, text files and Excel file in certain formats.
The package now uses resdata for Eclipse summary file support.
For detailed usage and examples see USER_MANUAL.md.

Development & Testing

The repository now includes a pytest-based test suite located under src/tests. Run pytest from the project root to execute the tests. Example fixtures are kept in src/tests/fixtures (ECL/VIP samples).

Documentation sources live in the docs/ directory and are prepared for building both HTML and PDF manuals using Sphinx. To generate docs:

cd docs
make html          # requires Sphinx
make latexpdf      # requires LaTeX

Formatting and linting

Use pre-commit hooks to enforce style and consistent checks:

pip install pre-commit
pre-commit install
pre-commit run --all-files

Or run directly (if tools are installed):

ruff check .
black --check .

If tools are missing, install with:

pip install ruff black

You can also generate quick code statistics with:

python scripts/code_stats.py

datafiletoolbox can also read eclipse-style input data deck, but this feature is not fully developed and is still a prototype.
It can be easily read include files of properties exported from Petrel to Eclipse and return a DataFrame with the data read from the file.

It takes care of the units of the data loaded and is able to convert them into other units.
In order to keep track of the units, a subclass of Pandas, is used to return the results.

load data

The easiest way to load data is using the function loadSimulationResults:
from datafiletoolbox import loadSimulationResults
data = loadSimulationResults( *path_to_file* )

get_data

To extract data from the loaded files the instances work in an analogous way to the Python dictionaries and Pandas DataFrames.
We can request a single Series using [*key_to_extract*] or DataFrames using [[*key_to_extract*]].
The instance can also be called using (*key_to_extract*) and in this case will return a NumPy array.

keys of VIP simulation results

The data from a VIP simulation can be accessed using regular eclipse nomenclature, like 'FOPT' meaning 'Qo' of 'ROOT' or 'WGPR:WELL1' meaning 'Qg' of 'WELL1'.

keys, wells, groups, regions

The properties .keys, .wells, .groups, .regions contain tuples with their corresponding list of values available in the loaded data. The method .find_Keys() can be used to find keys related to any well, group, region, attribute, or pattern (using ? * ...)

generic keys

The key does not need to be exact, it can be:

• a general property, like 'WOPR', and the class will return all the vectors matching the key
• the name of a well, region or group, like 'WELL1', and the class will return all the vectors for that key
• it can contain wildcards, like 'W?PR' or 'WELL*'

changing the index of the returned DataFrames

The default index is defined automatically based on the available data, usually the 'TIME' vector or the 'DATE' vector.
To change the index use the .set_index(key) method. It can be any key in the data.

reading a VFP file

To read and use a VFP table from eclipse keyword data, start by importing the VFP class:

• from datafiletoolbox.SimulationInput.VFP import VFP This class can read the include file containing the VFP data from the eclipse keyword and return an instance of VFP with the loaded data. The include file can be directly provided using the input_file parameter:
• well_vfp = VFP(input_file='path_to_vfp_include_file') Then, the VFP instance can be called providing the VFP table parameters (rate, thp, wfr, gfr, aql) that will be used to calculate the bhp. By example:
• well_vfp(RATE=500,THP=50,WFR=0,GFR=1000,ALQ=0) will return a single float for the corresponding bhp Multiple values for one of the parameters can be provided in a tuple:
• well_vfp(RATE=(100,250,500),THP=50,WFR=0,GFR=1000,ALQ=0) will return an array of floats for the corresponding bhps. Any of these parameters can be left empty (=None) and then the values defined in the VFP keyword definition will be used to calculate the bhp:
• well_vfp(RATE=None, THP=50, WFR=0, GFR=1000, ALQ=0) will return an array with the bhp for each one of the rates defined in the keyword parameter.

plotting

To make a plot from an instance of loaded data, simply use the .plot(keys) method and a matplotlib plot will be generated setting the color of the lines according to the fluid or data plotted.

X axis

By default, the X axis of the plot will be the index set to the instance.

comparing different results from different simulations

To compare the results of different simulations, simply pass the variable representing the instance of the other simulation to the .plot() method. The class will extract the data from both instances of data, convert the units of the other instances if required, and display the plot:

assume data0 is an eclipse binary result and data1 is a VIP simulation results
data0.plot('FOPR', data1)
will get the data from both results (converting the key from ECL style to VIP style to extract the data), convert units of data1 to corresponding units of data0, and show the plot.

further functionalities

Many more functions are available, not detailed in this readme.
A more detailed tutorial will be available sometime, in the meanwhile, please contact the author [e-mail] for further details.