Skip to content

Deviation File Specification

This page describes the format and usage of well deviation input files, which are used to specify the spatial trajectory of each well in a geothermal project.

File Format

A deviation file is a plain text file containing:

  • The well name (required, as WELLNAME: 'NAME')
  • A header line (optional, usually commented with #)
  • Multiple rows of well trajectory data:
    Each row contains four floating-point numbers:
    X, Y, TVDMSL, MDMSL
  • The end of the file is marked by a line containing -999

Example:

WELLNAME: 'INJ1'
#       X           Y      TVDMSL       MDMSL
2917.480000    4860.460000    0.000000    0.00000
2917.480000    4860.460000    500.000000    500.00000
2014.905693    5859.854755    2702.014954    4417.110301
...
2486.378463    5184.708355    2853.445038    5502.348472
-999

Column meanings: - X: X coordinate (e.g., meters, local grid) - Y: Y coordinate (e.g., meters, local grid) - TVDMSL: True Vertical Depth (meters below mean sea level) - MDMSL: Measured Depth (meters along well path, below mean sea level)

Usage in the Code

Deviation files are read using the DeviationFileReader class:

from pythermonomics.data.read_deviation_file import DeviationFileReader

reader = DeviationFileReader(filename="INJ1.dev")
well_name, deviation_data = reader.read_deviation_file()
  • well_name will be a string (e.g., 'INJ1')
  • deviation_data will be a NumPy array of shape (n_points, 4) with columns [X, Y, TVDMSL, MDMSL]

Notes

  • The file must contain the WELLNAME: line and end with -999.
  • Lines starting with # are ignored as comments.
  • Each data row must have exactly four numeric values.
  • If the file is malformed or missing data, an error will be raised.

Example Directory Structure

If you have multiple wells, place each deviation file in a directory and reference that directory in your configuration:

well_paths/
  INJ1.dev
  PRD1.dev
  ...

And you simply refer to that folder in your arguments when running either the CLI or use it directly in your python code:

For more details, see the DeviationFileReader API documentation.