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 Annotations

Use Tensor for an unconstrained tensor or TensorField() to describe and validate a floating-point tensor with a minimum rank. The WellFormat uses three predefined annotations:

Annotation

Shape convention

Field order

T0_Tensor

T ...

Scalar (rank 0)

T1_Tensor

T ... i

Vector (rank 1)

T2_Tensor

T ... i j

Rank 2

Here, T is the time axis, ... represents zero or more spatial axes, and i and j are component axes. These annotations validate floating-point dtype and minimum tensor rank. The axis labels document the expected shape but do not enforce axis semantics or fixed dimension sizes.

nomad.well_format.Tensor

Pydantic annotation for an unconstrained torch.Tensor.

Validation preserves an existing tensor, decodes Nomad’s base64-encoded tensor representation, or converts other array-like input with torch.as_tensor(). Serialization produces a base64 zstd-compressed torch serialization and advertises the application/vnd.nomad.tensor media type in the generated JSON schema. Tensor does not constrain dtype, rank, or shape; use TensorField() or additional Pydantic validators when the tool interface requires those constraints.

alias of Annotated[Tensor, BeforeValidator(func=_to_tensor, json_schema_input_type=PydanticUndefined), PlainSerializer(func=_serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={‘contentEncoding’: ‘base64’, ‘contentMediaType’: ‘application/vnd.nomad.tensor’, ‘description’: ‘Serialized and compressed tensor data’, ‘type’: ‘string’}, mode=None)]

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

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

Parameters:

  • min_rank (int) – Minimum number of dimensions accepted by the runtime validator.

  • shape_str (str) – Human-readable description of the dimensions, included in the generated JSON schema.

nomad.well_format.T0_Tensor

Pydantic annotation for a floating-point, rank-0 field with shape T .... T is the time axis and ... represents zero or more spatial axes. The validator requires at least one dimension but does not assign meaning to axes.

alias of Annotated[Tensor, BeforeValidator(func=_to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=_check), PlainSerializer(func=_serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={‘contentEncoding’: ‘base64’, ‘contentMediaType’: ‘application/vnd.nomad.tensor’, ‘description’: ‘Floating torch.Tensor with shape “T …” encoded as a base64 zstd-compressed torch serialization’, ‘type’: ‘string’}, mode=None)]

nomad.well_format.T1_Tensor

Pydantic annotation for a floating-point, rank-1 field with shape T ... i. T is the time axis, ... represents zero or more spatial axes, and i is the component axis. The validator requires at least two dimensions but does not assign meaning to axes.

alias of Annotated[Tensor, BeforeValidator(func=_to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=_check), PlainSerializer(func=_serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={‘contentEncoding’: ‘base64’, ‘contentMediaType’: ‘application/vnd.nomad.tensor’, ‘description’: ‘Floating torch.Tensor with shape “T … i” encoded as a base64 zstd-compressed torch serialization’, ‘type’: ‘string’}, mode=None)]

nomad.well_format.T2_Tensor

Pydantic annotation for a floating-point, rank-2 field with shape T ... i j. T is the time axis, ... represents zero or more spatial axes, and i and j are the two component axes. The validator requires at least three dimensions but does not assign meaning to axes.

alias of Annotated[Tensor, BeforeValidator(func=_to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=_check), PlainSerializer(func=_serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={‘contentEncoding’: ‘base64’, ‘contentMediaType’: ‘application/vnd.nomad.tensor’, ‘description’: ‘Floating torch.Tensor with shape “T … i j” encoded as a base64 zstd-compressed torch serialization’, ‘type’: ‘string’}, mode=None)]

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