Skip to main content

Interpretation models

Purpose

The interpretation-models repository provides a shared and executable semantic model for subsurface interpretation data and collections of interpretations. Its primary goal is to make it possible to exchange data from different source systems by mapping and bridging their different formats and data models. The intention is to:

  • Provide a neutral internal model with stable contracts and interface
  • Provide explicit mappings between objects of different source system models and the internal model
  • Provide table schemas for data storage based on the internal model
  • Provide functions for structured validation and basic automated QC of data
  • Preserve meaning and semantics while formats, schemas, and standards evolve

Scope

All interpretation objects handled in this repo are expected to have a model with dict-style metadata (tabular) and an array containing data points (values). An introduction to interpretations, the contents of these arrays, and the different data types can be found in this interpretations primer doc.

Data types

Interpretation objects expected to be supported:

  • surface grids
  • horizons
  • faults
  • polygons
  • point sets

Source systems

Source systems expected to be supported:

  • OpenWorks (as exposed by DSIS, supporting users of DSG application in the Landmark ecossystem)
  • Petrel Studio
  • OSDU (Core metadata and Reservoir DDMS / RESQML / RDDMS)

Collections

The models described here also assume grouping of interpretations into collections. The collections can map to different representations in different systems, for example:

  • OpenWorks InterpretationSet
  • Petrel Studio business projects and folders
  • OSDU PersistedCollection

This repository provides an internal representation of collections, explicit mappings from source system representations to it when applicable. This is crucial to many workflows supported by the mapping, frequently to help users group and filter the data they wish to transfer from one system to another.

Currently supported

Combinations of data type and source will be added here as they are progressively implemented in this repository. The current list of supported combinations is:

  • Coming soon... :)

Design

Components

This repo is mostly separated into four major components based on the different objects:

Interpretation models (src/interpretation_models/models)

Define the internal composable, hierarchical Python classes to describe interpretation metadata and structure.

Design rules in docs/models.md

Model mapping (src/interpretation_models/mappers)

Provide deterministic mappers between source-system models and the internal interpretation model.

Design rules in docs/mappers.md

Validation (src/interpretation_models/validations)

Apply schema- and content-level validation and recording the results, without blocking data flow.

Design rules in docs/validation.md

Table schemas and relationships (src/interpretation_models/tables)

This bridges the gap between pydantic models and the need to generate table schemas for representation of the internal model in storage. It includes flattening rules for attribute names, representing FKs, creating m:n relationship tables, especially for collections.

Design rules in docs/tables.md

Data flow

At a high level, this repository is organised around models and mappings. Those components are put together to build data flows for each supported combination of system and datatype. We encourage the reader to explore two of such suggested data flows in this data flows doc — one with a data lake medallion architecture pipeline approach and another with a simple ETL directly from source to OSDU using the internal model only as an in-memory bridge.

Considerations

The need for an internal model

Different systems represent interpretations differently. They expose different metadata, use different identifiers, group interpretations using different concepts. Grid geometry, for example, can be represented in multiple different ways, with parameters for rotation, with unit vectors, with corner points — all valid and different views of the same thing.

To map safely between them, we introduce an internal bridge model that captures the union of what we care about regardless of system, acting as a stable contract while mappings may change. We do acknowledge that creating our own "canonical" model leads effectively to yet another standard.

Standards

However, we accept that with a disclaimer: OSDU is intended to be the long-term canonical industry model. And the motivation for creating this repo is to map the models to OSDU so all the interpretations can be stored there long term. However, OSDU models are still evolving and currently do not cover everything we ingest from source systems or all the metadata we need to identify an object using data pipelines. Thus, mapping directly between source systems and OSDU would be a difficult approach at this point in time. This internal model exists as a bridge, not a replacement, allowing us to map safely while learning and iterating. It should be as close as possible to the OSDU model, so that at some point it can be just replaced by it.

The internal interpretation model should be:

  • authoritative only within this repository and storage based on its table schemas
  • neutral with respect to source systems
  • explicitly designed to be mapped to and from other models

xtgeo compatibility

Many of the interpretation datatypes are also represented by xtgeo. xtgeo is mainly used for manipulation and transformations on the arrays of data points (such as sampling, smoothing, etc) and their respective bulk files, while this is aimed at mapping and validating the models. Where applicable, we use xtgeo for transformations and aim to be compatible with it — it should be possible to generate, for example, an xtgeo.RegularSurface from the internal model's SurfaceGrid representation. The RegularSurface can be then used for plotting, validation and manual QC.

Storage formats and processing tools

This repository is intentionally not tied to any specific storage or transfer technology, framework, or tools. It is designed to be used anywhere interpretation data needs to be understood, transformed, validated, or exchanged.

That said, it is influenced by the design needs of data pipelines exchanging data between different source systems, especially from legacy source systems into OSDU. Thus, considerations regarding the data modelling and processing of this type of workflow are front and center in the design. This is why it includes, for example, helpers to create table schemas for intermediate storage.

Metadata

Release files for interpretation-models 1.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for interpretation-models 1.3.0
File Size Uploaded Provenance Actions
interpretation_models-1.3.0.tar.gz 27.2 kB With provenance Details for interpretation_models-1.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for interpretation-models 1.3.0
File Interpreter ABI Platform Actions
interpretation_models-1.3.0-py3-none-any.whl Python 3 none any Details for interpretation_models-1.3.0-py3-none-any.whl

Total release size: 61.2 kB

Release files / interpretation_models-1.3.0.tar.gz

Download URL interpretation_models-1.3.0.tar.gz
Size 27.2 kB
Tags Source
SHA-256 checksum
How to use checksums
1e3a221105b724e7b74fd947a3c1400b7f37a7ca8cae2278c0b925ae89a9bfcb
BLAKE2b-256 checksum
How to use checksums
d2c83ab3f4fad2a17fde3ed992c31c88d71604f865a9bb40aad2ab5e5c2cbe11
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / interpretation_models-1.3.0-py3-none-any.whl

Download URL interpretation_models-1.3.0-py3-none-any.whl
Size 34.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
36c2d624e75ab0881b1efecb4fd8e3cbe6b1e4629dcbf934f1d3a1af175f2df3
BLAKE2b-256 checksum
How to use checksums
c8074724acb1c49289bbbea2eabc4c1d0b2a2e59cf71b72ab38dab3279dc84ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for interpretation-models 1.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for interpretation_models-1.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page