Well Format Reference

Nomad’s WellFormat is a structured schema for exchanging gridded scientific state. It packages coordinates, boundary conditions, scalar metadata, and rank-0, rank-1, and rank-2 tensor fields into a single validated object that models and tools can share. It closely follows the Polymathic’s The Well Data Format

This gives Nomad a common contract across three contexts: in-memory Python objects, JSON or MCP payloads, and on-disk HDF5 files following the Well-style layout. It is especially useful for rollout and surrogate models, where a tool needs to accept an initial physical state, evolve it over time, and return a new state with the same semantics.

Tensor Type Alias

nomad.well_format.Tensor

Pydantic annotation for a torch.Tensor encoded in JSON as Nomad’s application/vnd.nomad.tensor media type.

nomad.well_format.TensorField(*, min_rank, shape_str)

Return a Pydantic annotation for a floating tensor with minimum rank.

Parameters:

  • min_rank (int)

  • shape_str (str)

class nomad.well_format.BoundaryCondition(*, associated_dims=<factory>, associated_fields=<factory>, bc_type, sample_varying=False, time_varying=False, mask, values=None)

Boundary condition mask and optional values for one or more fields.

Parameters:
associated_dims: list[str]

Dimension names associated with this boundary condition.

associated_fields: list[str]

Field names associated with this boundary condition.

bc_type: str

Boundary condition type label, such as Dirichlet or Neumann.

sample_varying: bool

Whether the boundary condition varies across samples.

time_varying: bool

Whether the boundary condition varies across time steps.

mask: Tensor

Boolean tensor selecting boundary locations.

values: Tensor | None

Optional tensor of values applied at masked boundary locations.

validate_mask()
class nomad.well_format.Domain(*, spatial_dims=None, time=None, **extra_data)

Coordinate metadata for spatial and temporal dimensions.

Parameters:
spatial_dims: list[str] | None

Names of spatial coordinate dimensions.

time: list[float] | list[list[float]] | None

Time coordinates or per-sample time coordinates.

validate_spatial_dims()
class nomad.well_format.WellFormat(*, dataset_name, grid_type, n_spatial_dims, dimensions=<factory>, boundary_conditions=<factory>, scalars=<factory>, t0_fields=<factory>, t1_fields=<factory>, t2_fields=<factory>)

Serializable container for gridded scientific fields and metadata.

Parameters:

  • dataset_name (str)

  • grid_type (str)

  • n_spatial_dims (int)

  • dimensions (Domain)

  • boundary_conditions (dict[str, BoundaryCondition])

  • scalars (dict[str, float | int])

  • t0_fields (dict[str, TypeAliasForwardRef('nomad.well_format.T0_Tensor')])

  • t1_fields (dict[str, TypeAliasForwardRef('nomad.well_format.T1_Tensor')])

  • t2_fields (dict[str, TypeAliasForwardRef('nomad.well_format.T2_Tensor')])

dataset_name: str

Human-readable dataset name.

grid_type: str

Grid topology label for the dataset.

n_spatial_dims: int

Number of spatial dimensions represented by field tensors.

dimensions: Domain

Spatial and temporal coordinate metadata.

boundary_conditions: dict[str, BoundaryCondition]

Boundary conditions keyed by boundary name.

scalars: dict[str, float | int]

Scalar metadata values keyed by name.

t0_fields: dict[str, T0_Tensor]

Scalar fields keyed by field name.

t1_fields: dict[str, T1_Tensor]

Vector fields keyed by field name.

t2_fields: dict[str, T2_Tensor]

Rank-2 tensor fields keyed by field name.

get(item, default=None)
validate_dimensions_and_field_shapes()
static from_file(file)

Load a Well HDF5 file into a WellFormat instance.

Parameters:

file (str | TypeAliasForwardRef('pathlib.Path'))

to_file(file)

Write this instance to a Well HDF5 file.

Parameters:

file (str | TypeAliasForwardRef('pathlib.Path'))

class nomad.well_format.AutoRegressiveInput(*, duration, initial_state)

Input schema for models that roll out a Well state over time.

Parameters:
duration: int
initial_state: WellFormat