# bp/resqpy architecture

> Architecture diagram of the GitHub repository bp/resqpy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bp/resqpy
- Repository: https://github.com/bp/resqpy

## Overview

resqpy is a Python API for reading, writing, and modifying RESQML reservoir models. The principal workflow is to open or create a model, import or construct model objects, work with grids and associated geology, wells, and properties, then persist the result. The map includes documented import and derived-model capabilities. Storage details and several subsystem connections are represented conservatively: only sampled excerpts support specific call edges, so unsampled wiring is not expanded.

Main entry points: [`resqpy/model/_model.py`](https://github.com/bp/resqpy/blob/master/resqpy/model/_model.py) (Model API), [`resqpy/grid/_grid.py`](https://github.com/bp/resqpy/blob/master/resqpy/grid/_grid.py) (IJK grids), [`resqpy/model/_context.py`](https://github.com/bp/resqpy/blob/master/resqpy/model/_context.py) (Model context), [`resqpy/grid_surface/_find_faces.py`](https://github.com/bp/resqpy/blob/master/resqpy/grid_surface/_find_faces.py) (Surface-grid intersections)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model and storage"]
  node_context["Model context<br/>[_context.py]"]
  node_model_api["Model API<br/>[_model.py]"]
  node_xml["XML model data<br/>[_xml.py]"]
  node_hdf5[("HDF5 arrays<br/>[_hdf5.py]")]
end

subgraph group_grid["Grid and properties"]
  node_derived["Derived models"]
  node_grid_ijk["IJK grids<br/>[_grid.py]"]
  node_grid_unstructured["Unstructured grids"]
  node_properties["Property collections"]
  node_gcs["Grid connections"]
  node_trans["Transmissibility<br/>[transmission.py]"]
end

subgraph group_geo["Geology and geometry"]
  node_surface["Surfaces<br/>[_surface.py]"]
  node_surface_faces["Surface-grid intersections<br/>[_find_faces.py]"]
  node_fault["Fault interpretation"]
  node_strata["Stratigraphy"]
end

subgraph group_well["Wells and import"]
  node_import["Format import"]
  node_trajectory["Well trajectories<br/>[_trajectory.py]"]
  node_blocked_well["Blocked wells<br/>[_blocked_well.py]"]
  node_well_props["Well properties"]
end

subgraph group_support["Model support"]
  node_crs["Coordinate systems<br/>[crs.py]"]
  node_time["Time series<br/>[_time_series.py]"]
  node_units["Units and measures"]
end

node_user(("API user"))

node_user -->|"opens model"| node_context
node_context -->|"creates or opens"| node_model_api
node_context -->|"stores on exit"| node_model_api
node_model_api -->|"manages XML"| node_xml
node_model_api -->|"manages arrays"| node_hdf5
node_user -->|"imports data"| node_import
node_user -->|"derives models"| node_derived
node_user -->|"works with grids"| node_grid_ijk
node_user -->|"works with grids"| node_grid_unstructured
node_grid_ijk -->|"writes geometry"| node_hdf5
node_grid_ijk -->|"exposes properties"| node_properties
node_grid_unstructured -->|"exposes properties"| node_properties
node_blocked_well -->|"adds well properties"| node_well_props
node_blocked_well -->|"creates time series"| node_time
node_surface_faces -->|"converts coordinates"| node_crs
node_surface_faces -->|"intersects grid"| node_grid_ijk
node_user -->|"works with surfaces"| node_surface
node_user -->|"works with connections"| node_gcs
node_user -->|"works with wells"| node_trajectory
node_user -->|"organizes geology"| node_fault
node_user -->|"defines stratigraphy"| node_strata
node_user -->|"calculates flow"| node_trans

click node_context "https://github.com/bp/resqpy/blob/master/resqpy/model/_context.py"
click node_model_api "https://github.com/bp/resqpy/blob/master/resqpy/model/_model.py"
click node_xml "https://github.com/bp/resqpy/blob/master/resqpy/model/_xml.py"
click node_hdf5 "https://github.com/bp/resqpy/blob/master/resqpy/model/_hdf5.py"
click node_import "https://github.com/bp/resqpy/tree/master/resqpy/rq_import"
click node_derived "https://github.com/bp/resqpy/tree/master/resqpy/derived_model"
click node_grid_ijk "https://github.com/bp/resqpy/blob/master/resqpy/grid/_grid.py"
click node_grid_unstructured "https://github.com/bp/resqpy/blob/master/resqpy/unstructured/_unstructured_grid.py"
click node_properties "https://github.com/bp/resqpy/blob/master/resqpy/property/property_collection.py"
click node_gcs "https://github.com/bp/resqpy/blob/master/resqpy/fault/_grid_connection_set.py"
click node_trans "https://github.com/bp/resqpy/blob/master/resqpy/olio/transmission.py"
click node_surface "https://github.com/bp/resqpy/blob/master/resqpy/surface/_surface.py"
click node_surface_faces "https://github.com/bp/resqpy/blob/master/resqpy/grid_surface/_find_faces.py"
click node_fault "https://github.com/bp/resqpy/blob/master/resqpy/organize/fault_interpretation.py"
click node_crs "https://github.com/bp/resqpy/blob/master/resqpy/crs.py"
click node_trajectory "https://github.com/bp/resqpy/blob/master/resqpy/well/_trajectory.py"
click node_blocked_well "https://github.com/bp/resqpy/blob/master/resqpy/well/_blocked_well.py"
click node_well_props "https://github.com/bp/resqpy/blob/master/resqpy/property/well_interval_property_collection.py"
click node_strata "https://github.com/bp/resqpy/blob/master/resqpy/strata/_stratigraphic_column.py"
click node_time "https://github.com/bp/resqpy/blob/master/resqpy/time_series/_time_series.py"
click node_units "https://github.com/bp/resqpy/blob/master/resqpy/weights_and_measures/weights_and_measures.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_context,node_model_api,node_xml,node_hdf5,node_user toneBlue
class node_derived,node_grid_ijk,node_grid_unstructured,node_properties,node_gcs,node_trans toneAmber
class node_surface,node_surface_faces,node_fault,node_strata toneMint
class node_import,node_trajectory,node_blocked_well,node_well_props toneRose
class node_crs,node_time,node_units toneIndigo
```

## Components

### Model and storage

- [Model context](https://github.com/bp/resqpy/blob/master/resqpy/model/_context.py): `resqpy/model/_context.py`
- [Model API](https://github.com/bp/resqpy/blob/master/resqpy/model/_model.py): `resqpy/model/_model.py`
- [XML model data](https://github.com/bp/resqpy/blob/master/resqpy/model/_xml.py): `resqpy/model/_xml.py`
- [HDF5 arrays](https://github.com/bp/resqpy/blob/master/resqpy/model/_hdf5.py): `resqpy/model/_hdf5.py`

### Grid and properties

- [Derived models](https://github.com/bp/resqpy/tree/master/resqpy/derived_model): `resqpy/derived_model`
- [IJK grids](https://github.com/bp/resqpy/blob/master/resqpy/grid/_grid.py): `resqpy/grid/_grid.py`
- [Unstructured grids](https://github.com/bp/resqpy/blob/master/resqpy/unstructured/_unstructured_grid.py): `resqpy/unstructured/_unstructured_grid.py`
- [Property collections](https://github.com/bp/resqpy/blob/master/resqpy/property/property_collection.py): `resqpy/property/property_collection.py`
- [Grid connections](https://github.com/bp/resqpy/blob/master/resqpy/fault/_grid_connection_set.py): `resqpy/fault/_grid_connection_set.py`
- [Transmissibility](https://github.com/bp/resqpy/blob/master/resqpy/olio/transmission.py): `resqpy/olio/transmission.py`

### Geology and geometry

- [Surfaces](https://github.com/bp/resqpy/blob/master/resqpy/surface/_surface.py): `resqpy/surface/_surface.py`
- [Surface-grid intersections](https://github.com/bp/resqpy/blob/master/resqpy/grid_surface/_find_faces.py): `resqpy/grid_surface/_find_faces.py`
- [Fault interpretation](https://github.com/bp/resqpy/blob/master/resqpy/organize/fault_interpretation.py): `resqpy/organize/fault_interpretation.py`
- [Stratigraphy](https://github.com/bp/resqpy/blob/master/resqpy/strata/_stratigraphic_column.py): `resqpy/strata/_stratigraphic_column.py`

### Wells and import

- [Format import](https://github.com/bp/resqpy/tree/master/resqpy/rq_import): `resqpy/rq_import`
- [Well trajectories](https://github.com/bp/resqpy/blob/master/resqpy/well/_trajectory.py): `resqpy/well/_trajectory.py`
- [Blocked wells](https://github.com/bp/resqpy/blob/master/resqpy/well/_blocked_well.py): `resqpy/well/_blocked_well.py`
- [Well properties](https://github.com/bp/resqpy/blob/master/resqpy/property/well_interval_property_collection.py): `resqpy/property/well_interval_property_collection.py`

### Model support

- [Coordinate systems](https://github.com/bp/resqpy/blob/master/resqpy/crs.py): `resqpy/crs.py`
- [Time series](https://github.com/bp/resqpy/blob/master/resqpy/time_series/_time_series.py): `resqpy/time_series/_time_series.py`
- [Units and measures](https://github.com/bp/resqpy/blob/master/resqpy/weights_and_measures/weights_and_measures.py): `resqpy/weights_and_measures/weights_and_measures.py`

### Other components

- **API user**

## Connections

- API user → Model context: opens model
- Model context → Model API: creates or opens
- Model context → Model API: stores on exit
- Model API → XML model data: manages XML
- Model API → HDF5 arrays: manages arrays
- API user → Format import: imports data
- API user → Derived models: derives models
- API user → IJK grids: works with grids
- API user → Unstructured grids: works with grids
- IJK grids → HDF5 arrays: writes geometry
- IJK grids → Property collections: exposes properties
- Unstructured grids → Property collections: exposes properties
- Blocked wells → Well properties: adds well properties
- Blocked wells → Time series: creates time series
- Surface-grid intersections → Coordinate systems: converts coordinates
- Surface-grid intersections → IJK grids: intersects grid
- API user → Surfaces: works with surfaces
- API user → Grid connections: works with connections
- API user → Well trajectories: works with wells
- API user → Fault interpretation: organizes geology
- API user → Stratigraphy: defines stratigraphy
- API user → Transmissibility: calculates flow