curlew documentation|Stable (main)Development (dev)

Package curlew

A toolkit for building 2- and 3- dimensional geological models using neural fields.

Getting started

Installation

To install directly from github try: pip install git+https://github.com/samthiele/curlew.git.

This should run on most systems: numpy, pytorch and tqdm are the only required dependencies. Matplotlib is handy too, but not required.

Tutorials

To help get up to speed with curlew, we maintain a set of CoLab tutorial notebooks here. Note that these are written for the main branch of curlew so will likely not work out-of-the-box with the dev branch. And, if anyone knows a better (free) platform for these then do let us know!

Support and feedback

If you are using curlew, or even just think it's cool, then please give us a star. It makes a difference!

Any questions, ideas, feedback or issues can be raised via GitHub issues or on the discussions page. Don't be afraid to drop us a line.

Overview

curlew is a toolkit for building 2- and 3-dimensional geological models using neural fields and/or other learnable functions. The key idea is to use neural fields to learn the implicit representation of geological structures, which can then be used to generate synthetic models, interpolate sparse geological data, and perform joint inversion tasks.

When starting with curlew it is important to understand the following key classes, as these are the building blocks of a curlew model.

BaseSF (Scalar Fields)

All implementations of implicit (scalar) fields inherit from BaseSF. These are the basic building blocks of all implicit models. Currently, curlew supports a variety of learnable (complex/fitted) and analytical (simple, closed-form) fields. These are summarised below.

Neural fields (for interpolation tasks):

  • NFF for fourier-feature based neural fields
  • FSF for Fourier-series based neural fields (a simplified/faster version of NFF)

Analytical fields (generally for building synthetic models, but can be useful in real models too):

GeoEvent (Geological events)

Geological meaning is given to scalar fields through the GeoEvent class. This encapsulates one or more BaseSF instances and defines how they interact with older and younger fields in the model. Currently, two different relationships are supported:

  • Overprint defines overprinting relations (unconformities, onlaps, intrusions and domain boundaries) and determines how an event overprints (truncates) older geology.
  • OffsetBase defines deformations that transform (retro-deform) the points a model is being evaluated at prior to the evaluation of older events. This can be used to represent offset from folds, faults, and sheet-intrusions (each of which has a specific deformation formulation that inherits from the base OffsetBase class, e.g. FaultOffset).

GeoEvent instances are typically constructed using the factory functions in curlew.geology, including strati(), sheet(), fault(), fold(), etc.

Geologically meaningful isosurfaces (lithological contacts, fault surfaces, etc.) and volumes (regions between faults, reservoirs, finite faults, etc.) are also defined by the GeoEvent class, using the addIsosurface and addVolume methods. Importantly, and unlike most geological modelling tools, isosurfaces can be defined either as fixed values (e.g., 1.0) or by whichever value the model evaluates at a given seed point (or the average of multiple seed points). Crucially, the latter form allows isosurfaces to be defined independent of the underlying field values.

GeoModel (models)

The GeoModel class is used to construct the graph of GeoEvent instances that ultimately define model evaluation flow and topology. It also provides a high-level interface for evaluating model predictions at arbitrary points in space and defining global to local coordinate system transforms (i.e. local grids). Models can be saved and loaded using the saveModel() and loadModel() functions.

Geode (model outputs)

The Geode class is used to store the diverse outputs of a model. These include the scalar field values, lithology and structure IDs, predicted properties (e.g., density), and applied deformations (e.g., fault offset). The Geode class can also be used to store the model's grid, coordinate system transforms, and other metadata.

Pebble (losses and optimisers)

The Pebble class is used to store losses and optimisers. This includes the loss values, the weights (hyperparameters) used to balance each loss, and the optimisers used to update the model's parameters. Generally it is only necessary to create a new Pebble object if you want to create a custom loss function or new type of learnable object.

CSet (model constraints)

Geological information used to fit learnable fields (or offset/overprint objects) are stored in a CSet object. When constructing a new model it is typical to construct a CSet for each GeoEvent instance based on the available data. These data include (but are not limited to):

  • value constraints (target scalar values at specific points. Generally these should be avoided as neural fields are much better at fitting gradient and (in)equality constraints.)
  • gradient constraints (strike and dip measurements of bedding or other structural surfaces)
  • property constraints (arbitrary property values at specific points, like density or chemistry)
  • inequality constraints (known stratigraphic relationships between two sets of points)
  • equality constraints (traces or contact surfaces known to be tangential to a field)
  • grid constraints (grid covering the model domain, to sample global constraints from)
  • trend constraints (a preferred global gradient orientation)

HSet (model hyperparameters)

The dark-side of neural field interpolation. This class contains the various hyperparameters that can be used to balance/tune complex (multi-objective) loss functions. Most fields should use ~1-3 individual loss terms (with the remaining hyperparameters set to 0), as otherwise hyperparameter optimisation becomes very difficult. It is typical to create a new HSet object for each GeoEvent instance based on the available data and properties of the interpolated field.

Contributing and appreciation

Please star this repository if you found it useful. If you have fixed bugs or added new features then we welcome pull requests.

Authors and acknowledgment

curlew has been developed by Sam Thiele and Akshay Kamath, with valuable input from Mike Hillier, Lachlan Grose, Richard Gloaguen and Florian Wellmann.

If you use curlew we would appreciate it if you:

  1. Cite the following paper (for academic work)

    Kamath, A.V., Thiele, S.T., Moulard, M., Grose, L., Tolosana-Delgado, R., Hillier, M.J., Wellmann, R., & Gloaguen, R. Curlew 1.0: Implicit geological modelling with neural fields in python. Geoscientific Model Development (preprint online soon)

  2. Star this repository so that we get a rough idea of our user base

  3. Leave a GitHub issue if you have questions or comments (Issues do not strictly need to be related to bug reports).

Sub-modules

curlew.core

Define several core curlew types for storing data and hyperparameters.

curlew.fields

Import core neural field types from other python files, and define the "base" NF class that these all inherit from.

curlew.geology

Functions and objects used for creating and manipulating geological structures in Curlew.

curlew.geometry

Utility functions for generating basic geometries (grids, sections, etc.) and performing other simple geometric tasks.

curlew.io

Functions for performing common IO operations.

curlew.synthetic

Generate synthetic datasets and models for testing purposes.

curlew.text

Text summaries of curlew objects for logging, progress bars, and agent-side validation …

curlew.utils

Utility functions for using curlew. For plotting and 3D visualisation see :mod:curlew.visualise and :mod:curlew.visualise.napari_viewer. For …

curlew.visualise

Functions for performing crude 2D plotting using matplotlib. Useful for demonstrations, but will need to be extended at some point to be more usable …

Global variables

var batchSize

Divide arrays larger than this size into chunks (batches) to reduce memory usage and avoid out-of-memory crashes.

var ccmap

A colourful (custom) matplotlib (categorical) colormap taylored for curlew. Will only be set if matplotlib is installed.

var ccramp

A colourful (custom) matplotlib (continuous) colormap taylored for curlew. Will only be set if matplotlib is installed.

var ccstrat

A shuffled version of ccmap, useful for plotting stratigraphic fields as though they have many layers in them.

var compile

Whether to compile the model using torch.compile. This can significantly speed up larger models when using a GPU.

var default_dim

The default input dimensionality (2D or 3D) to use when creating new models. Default is 3.

var device

The device used to compute operations with pytorch tensors. Change to allow e.g. GPU parallelisation.

var dtype

The precision used during pytorch computations. Lower to float32 to save RAM.