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])

  • associated_fields (list[str])

  • bc_type (str)

  • sample_varying (bool)

  • time_varying (bool)

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

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

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, Annotated[Tensor, BeforeValidator(func=~nomad.well_format._to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=~nomad.well_format._check_float_and_min_rank.<locals>._check), PlainSerializer(func=~nomad.well_format._serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={'type': 'string', 'contentEncoding': 'base64', 'contentMediaType': 'application/vnd.nomad.tensor', 'description': 'Floating torch.Tensor with shape "T ..." encoded as a base64 zstd-compressed torch serialization'}, mode=None)]])

  • t1_fields (dict[str, Annotated[Tensor, BeforeValidator(func=~nomad.well_format._to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=~nomad.well_format._check_float_and_min_rank.<locals>._check), PlainSerializer(func=~nomad.well_format._serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={'type': 'string', 'contentEncoding': 'base64', 'contentMediaType': 'application/vnd.nomad.tensor', 'description': 'Floating torch.Tensor with shape "T ... i" encoded as a base64 zstd-compressed torch serialization'}, mode=None)]])

  • t2_fields (dict[str, Annotated[Tensor, BeforeValidator(func=~nomad.well_format._to_tensor, json_schema_input_type=PydanticUndefined), AfterValidator(func=~nomad.well_format._check_float_and_min_rank.<locals>._check), PlainSerializer(func=~nomad.well_format._serialize_tensor, return_type=PydanticUndefined, when_used=always), WithJsonSchema(json_schema={'type': 'string', 'contentEncoding': 'base64', 'contentMediaType': 'application/vnd.nomad.tensor', 'description': 'Floating torch.Tensor with shape "T ... i j" encoded as a base64 zstd-compressed torch serialization'}, mode=None)]])

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