agilescientific/welly

1. What this repository is

welly is a Python library for working with subsurface well data at the “well” level, not just raw LAS files. Its central abstraction is a Well object that can collect logs, metadata, deviation surveys, tops, striplogs, and synthetic/seismic-related products.

2. Core domain model

The main runtime objects appear to be:

- Well for a single well

- Curve for individual log curves

- Project for a collection of wells

- Location and CRS for spatial positioning and coordinate reference handling

- Header and LAS-related helpers for metadata

These objects form the user-facing API and are the main boundaries for the architecture diagram.

3. Data ingestion and LAS-centered I/O

LAS handling is the primary ingress/egress path. The package uses lasio conceptually and likely directly for parsing/writing LAS files, while welly.las and welly.header provide library-specific adaptation. Example files in tests/assets, tutorial/data, and docs/_userguide show that LAS is the dominant interchange format.

4. Well assembly flow

A typical flow is: LAS file or related survey data is loaded into a Well, which then exposes logs through w.data[...]. Additional files such as deviation surveys and tops can be associated with the same well. Project.from_las(...) indicates a batch-loading path that builds many Well objects from a file pattern.

5. Curve-centric processing

curve.py, scales.py, defaults.py, fields.py, and utils.py suggest a set of helpers for normalizing curve names, units, display scales, and default behaviors. This is the layer where raw log data is cleaned, standardized, and made plot-ready or analysis-ready.

6. Quality and validation

quality.py is a separate subsystem for assessing log or well data quality. This is important architecturally because validation is not embedded in ingestion alone; it is a distinct stage that can be run on already-created Well/Curve objects.

7. Spatial and directional context

location.py and crs.py handle position, coordinate system, and likely trajectory/deviation-related concerns. The presence of CSV/XLSX deviation survey examples in tests and tutorials shows that the library supports directional wells and needs a dedicated geometry/spatial boundary beyond simple log curves.

8. Derived products and analysis helpers

synthetic.py indicates support for generated or modeled outputs, likely synthetic seismograms or related well-based derived traces. canstrat.py and canstrat_codes.py suggest one specialized classification/encoding subsystem for lithostratigraphic or cuttings-related descriptions.

9. Visualization layer

plot.py is a distinct presentation subsystem. The README’s quick start shows plotting directly from a curve object, so plotting is designed as a first-class capability attached to the domain objects rather than a separate application layer.

10. Package structure and dependency boundaries

The package is organized as a single Python library under welly/, with a relatively clean separation between domain objects, I/O, plotting, and utilities. The main external integration point visible from the tree is lasio; beyond that, the architecture is mostly self-contained within the library.

11. Documentation and examples

docs/ and tutorial/ contain notebooks and Sphinx docs that double as executable architecture examples. They are not production subsystems, but they are important for understanding intended object flows: load well data, inspect curves, plot, relate wells in a project, and work with directional/location data.

12. Tests as behavioral contracts

The tests/ tree is broad and maps closely to the core modules: test_well, test_curve, test_project, test_las, test_location, test_quality, test_plots, test_synthetic, and test_canstrat. This indicates the architecture is organized around independently testable subsystems with explicit expected behavior at their boundaries.

13. Build and release plumbing

GitHub Actions workflows cover tests, documentation builds, and PyPI release. pyproject.toml and requirements.txt define packaging/dependency management. These are support systems rather than runtime architecture, but they indicate the library is meant to be distributable as a standard Python package.

14. Overall runtime shape

At runtime, the library is essentially a data-processing toolkit: ingest well files and auxiliary survey data, normalize into Well/Curve/Project objects, apply quality/utility/analysis functions, and optionally visualize or export results. The key architectural boundary is between external file formats and the internal well-domain object model.