Skip to content

UGRID Data Models#

Dataclasses for UGRID topology metadata, mesh variables, and dataset-level metadata summaries.

UgridMetadata is the dataset-level summary: it aggregates one MeshTopologyInfo per mesh and records the variable inventory as a data_variables: dict[str, str] map (variable name → mesh location). The MeshVariable records themselves are held by UgridDataset, not by UgridMetadata. A MeshVariable carries a lazy loader so its data is only materialised on access, and offers time-slicing helpers:

Hold "Ctrl" to enable pan & zoom 
classDiagram
    class UgridMetadata {
      data_variables : dict[str,str]
      global_attributes
      conventions
      n_nodes / n_faces / n_edges
    }
    class MeshTopologyInfo {
      mesh_name
      topology_dimension
      node_x_var / node_y_var
      face_node_var / edge_node_var
      crs_wkt
    }
    class MeshVariable {
      name · location · mesh_name
      shape · nodata · units
      +data
      +n_time_steps
      +sel_time(i)
      +sel_time_range(a, b)
      +with_data(arr)
    }
    UgridMetadata o-- MeshTopologyInfo : mesh_topologies
    note for UgridMetadata "data_variables is a name → location map, not MeshVariable records"
    note for MeshVariable "held by UgridDataset; data is loaded lazily on first access"

pyramids.netcdf.ugrid.MeshTopologyInfo dataclass #

Parsed UGRID topology metadata from a NetCDF file.

Represents the structure of a single mesh topology variable, including references to coordinate variables, connectivity arrays, and data variables defined on the mesh.

Attributes:

Name Type Description
mesh_name str

Name of the topology variable (e.g., "mesh2d").
topology_dimension int

Mesh dimensionality (1=network, 2=surface, 3=volume).
node_x_var str

Name of the node x-coordinate variable.
node_y_var str

Name of the node y-coordinate variable.
face_node_var str | None

Name of the face-node connectivity variable.
edge_node_var str | None

Name of the edge-node connectivity variable.
face_edge_var str | None

Name of the face-edge connectivity variable.
face_face_var str | None

Name of the face-face connectivity variable.
edge_face_var str | None

Name of the edge-face connectivity variable.
boundary_node_var str | None

Name of the boundary-node connectivity variable.
face_x_var str | None

Name of the face center x-coordinate variable.
face_y_var str | None

Name of the face center y-coordinate variable.
edge_x_var str | None

Name of the edge center x-coordinate variable.
edge_y_var str | None

Name of the edge center y-coordinate variable.
data_variables dict[str, str]

Mapping of variable name to mesh location (e.g., {"water_level": "face"}).
crs_wkt str | None

Well-Known Text representation of the CRS, if available.
Source code in src/pyramids/netcdf/ugrid/models.py 
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
@dataclass(frozen=True)
class MeshTopologyInfo:
    """Parsed UGRID topology metadata from a NetCDF file.

    Represents the structure of a single mesh topology variable,
    including references to coordinate variables, connectivity
    arrays, and data variables defined on the mesh.

    Attributes:
        mesh_name: Name of the topology variable (e.g., "mesh2d").
        topology_dimension: Mesh dimensionality (1=network, 2=surface, 3=volume).
        node_x_var: Name of the node x-coordinate variable.
        node_y_var: Name of the node y-coordinate variable.
        face_node_var: Name of the face-node connectivity variable.
        edge_node_var: Name of the edge-node connectivity variable.
        face_edge_var: Name of the face-edge connectivity variable.
        face_face_var: Name of the face-face connectivity variable.
        edge_face_var: Name of the edge-face connectivity variable.
        boundary_node_var: Name of the boundary-node connectivity variable.
        face_x_var: Name of the face center x-coordinate variable.
        face_y_var: Name of the face center y-coordinate variable.
        edge_x_var: Name of the edge center x-coordinate variable.
        edge_y_var: Name of the edge center y-coordinate variable.
        data_variables: Mapping of variable name to mesh location
            (e.g., {"water_level": "face"}).
        crs_wkt: Well-Known Text representation of the CRS, if available.
    """

    mesh_name: str
    topology_dimension: int
    node_x_var: str
    node_y_var: str
    face_node_var: str | None = None
    edge_node_var: str | None = None
    face_edge_var: str | None = None
    face_face_var: str | None = None
    edge_face_var: str | None = None
    boundary_node_var: str | None = None
    face_x_var: str | None = None
    face_y_var: str | None = None
    edge_x_var: str | None = None
    edge_y_var: str | None = None
    data_variables: dict[str, str] = field(default_factory=dict)
    crs_wkt: str | None = None

pyramids.netcdf.ugrid.MeshVariable dataclass #

Data variable defined on a mesh location.

Wraps a numpy array of values associated with mesh elements (nodes, faces, or edges). Supports lazy loading via a loader callable that defers reading until data is first accessed.

Attributes:

Name Type Description
name str

Variable name in the NetCDF file.
location str

Mesh location ("node", "face", or "edge").
mesh_name str

Name of the associated mesh topology variable.
shape tuple[int, ...]

Shape of the data array.
attributes dict[str, Any]

Dictionary of NetCDF variable attributes.
nodata float | None

No-data / fill value for masked elements.
units str | None

Physical units string (e.g., "m", "m/s").
standard_name str | None

CF standard name (e.g., "sea_surface_height").
_data ndarray | None

Eagerly loaded data array, or None if using lazy loading.
_loader Callable[[], ndarray] | None

Callable that returns the data array on first access.
Source code in src/pyramids/netcdf/ugrid/models.py 
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
@dataclass
class MeshVariable:
    """Data variable defined on a mesh location.

    Wraps a numpy array of values associated with mesh elements
    (nodes, faces, or edges). Supports lazy loading via a loader
    callable that defers reading until data is first accessed.

    Attributes:
        name: Variable name in the NetCDF file.
        location: Mesh location ("node", "face", or "edge").
        mesh_name: Name of the associated mesh topology variable.
        shape: Shape of the data array.
        attributes: Dictionary of NetCDF variable attributes.
        nodata: No-data / fill value for masked elements.
        units: Physical units string (e.g., "m", "m/s").
        standard_name: CF standard name (e.g., "sea_surface_height").
        _data: Eagerly loaded data array, or None if using lazy loading.
        _loader: Callable that returns the data array on first access.
    """

    name: str
    location: str
    mesh_name: str
    shape: tuple[int, ...]
    attributes: dict[str, Any] = field(default_factory=dict)
    nodata: float | None = None
    units: str | None = None
    standard_name: str | None = None
    _data: np.ndarray | None = field(default=None, repr=False)
    _loader: Callable[[], np.ndarray] | None = field(default=None, repr=False)
    _dtype: np.dtype | None = field(default=None, repr=False)

    @property
    def data(self) -> np.typing.NDArray | None:
        """Return the data array, triggering lazy load if needed."""
        if self._data is None and self._loader is not None:
            self._data = self._loader()
        return self._data

    @property
    def n_elements(self) -> int:
        """Number of mesh elements (last dimension of shape)."""
        result = self.shape[-1] if self.shape else 0
        return result

    @property
    def has_time(self) -> bool:
        """True if the data has a time dimension (2D or higher)."""
        result = len(self.shape) > 1
        return result

    @property
    def n_time_steps(self) -> int:
        """Number of time steps. Returns 0 if no time dimension."""
        result = self.shape[0] if self.has_time else 0
        return result

    @property
    def dtype(self) -> np.dtype:
        """Data type of the variable.

        Returns the explicitly set dtype if available, falls back to
        the loaded data's dtype, and defaults to float64.
        """
        if self._dtype is not None:
            result = self._dtype
        elif self._data is not None:
            result = self._data.dtype
        else:
            result = np.dtype("float64")
        return result

    def sel_time(self, index: int) -> np.typing.NDArray:
        """Select a single time step.

        Args:
            index: Time step index.

        Returns:
            1D array of values at the given time step.

        Raises:
            IndexError: If index is out of range.
            ValueError: If the variable has no time dimension, or has no
                loaded data array.
        """
        if not self.has_time:
            raise ValueError(f"Variable '{self.name}' has no time dimension.")
        data = self.data
        if data is None:
            raise ValueError(f"Variable '{self.name}' has no loaded data.")
        return cast("np.typing.NDArray", data[index])

    def sel_time_range(self, start: int, stop: int) -> MeshVariable:
        """Select a time range, returning a new MeshVariable.

        Args:
            start: Start time index (inclusive).
            stop: Stop time index (exclusive).

        Returns:
            New MeshVariable with the selected time range.

        Raises:
            ValueError: If the variable has no time dimension, or has no
                loaded data array.
        """
        if not self.has_time:
            raise ValueError(f"Variable '{self.name}' has no time dimension.")
        data = self.data
        if data is None:
            raise ValueError(f"Variable '{self.name}' has no loaded data.")
        return self.with_data(data[start:stop])

    def with_data(self, data: np.ndarray | None) -> MeshVariable:
        """Return a copy of this variable carrying ``data``, keeping all other metadata.

        The new variable is eager (``_data`` set, no loader); its ``shape`` is taken from
        ``data`` when provided, else the original ``shape`` is retained. Used wherever a
        derived dataset (time selection, spatial clip, …) replaces a variable's array while
        preserving its name / location / mesh / attributes.

        Args:
            data: The replacement data array, or ``None`` to keep the original shape with
                no eager data.

        Returns:
            MeshVariable: The copy carrying ``data``.
        """
        return MeshVariable(
            name=self.name,
            location=self.location,
            mesh_name=self.mesh_name,
            shape=data.shape if data is not None else self.shape,
            attributes=self.attributes,
            nodata=self.nodata,
            units=self.units,
            standard_name=self.standard_name,
            _data=data,
        )

data property #

Return the data array, triggering lazy load if needed.

n_elements property #

Number of mesh elements (last dimension of shape).

has_time property #

True if the data has a time dimension (2D or higher).

n_time_steps property #

Number of time steps. Returns 0 if no time dimension.

dtype property #

Data type of the variable.

Returns the explicitly set dtype if available, falls back to the loaded data's dtype, and defaults to float64.

sel_time(index) #

Select a single time step.

Parameters:

Name Type Description Default
index int

Time step index.

 required

Returns:

Type Description
NDArray

1D array of values at the given time step.

Raises:

Type Description
IndexError

If index is out of range.
ValueError

If the variable has no time dimension, or has no loaded data array.
Source code in src/pyramids/netcdf/ugrid/models.py 
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
def sel_time(self, index: int) -> np.typing.NDArray:
    """Select a single time step.

    Args:
        index: Time step index.

    Returns:
        1D array of values at the given time step.

    Raises:
        IndexError: If index is out of range.
        ValueError: If the variable has no time dimension, or has no
            loaded data array.
    """
    if not self.has_time:
        raise ValueError(f"Variable '{self.name}' has no time dimension.")
    data = self.data
    if data is None:
        raise ValueError(f"Variable '{self.name}' has no loaded data.")
    return cast("np.typing.NDArray", data[index])

sel_time_range(start, stop) #

Select a time range, returning a new MeshVariable.

Parameters:

Name Type Description Default
start int

Start time index (inclusive).

 required
stop int

Stop time index (exclusive).

 required

Returns:

Type Description
MeshVariable

New MeshVariable with the selected time range.

Raises:

Type Description
ValueError

If the variable has no time dimension, or has no loaded data array.
Source code in src/pyramids/netcdf/ugrid/models.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def sel_time_range(self, start: int, stop: int) -> MeshVariable:
    """Select a time range, returning a new MeshVariable.

    Args:
        start: Start time index (inclusive).
        stop: Stop time index (exclusive).

    Returns:
        New MeshVariable with the selected time range.

    Raises:
        ValueError: If the variable has no time dimension, or has no
            loaded data array.
    """
    if not self.has_time:
        raise ValueError(f"Variable '{self.name}' has no time dimension.")
    data = self.data
    if data is None:
        raise ValueError(f"Variable '{self.name}' has no loaded data.")
    return self.with_data(data[start:stop])

with_data(data) #

Return a copy of this variable carrying data, keeping all other metadata.

The new variable is eager (_data set, no loader); its shape is taken from data when provided, else the original shape is retained. Used wherever a derived dataset (time selection, spatial clip, …) replaces a variable's array while preserving its name / location / mesh / attributes.

Parameters:

Name Type Description Default
data ndarray | None

The replacement data array, or None to keep the original shape with no eager data.

 required

Returns:

Name Type Description
MeshVariable MeshVariable

The copy carrying data.
Source code in src/pyramids/netcdf/ugrid/models.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
def with_data(self, data: np.ndarray | None) -> MeshVariable:
    """Return a copy of this variable carrying ``data``, keeping all other metadata.

    The new variable is eager (``_data`` set, no loader); its ``shape`` is taken from
    ``data`` when provided, else the original ``shape`` is retained. Used wherever a
    derived dataset (time selection, spatial clip, …) replaces a variable's array while
    preserving its name / location / mesh / attributes.

    Args:
        data: The replacement data array, or ``None`` to keep the original shape with
            no eager data.

    Returns:
        MeshVariable: The copy carrying ``data``.
    """
    return MeshVariable(
        name=self.name,
        location=self.location,
        mesh_name=self.mesh_name,
        shape=data.shape if data is not None else self.shape,
        attributes=self.attributes,
        nodata=self.nodata,
        units=self.units,
        standard_name=self.standard_name,
        _data=data,
    )

pyramids.netcdf.ugrid.UgridMetadata dataclass #

Full metadata summary for a UGRID dataset.

Aggregates topology information, data variable inventory, global attributes, and mesh element counts for display and inspection purposes.

Attributes:

Name Type Description
mesh_topologies tuple[MeshTopologyInfo, ...]

List of parsed mesh topologies in the file.
data_variables dict[str, str]

Mapping of variable name to location.
global_attributes dict[str, Any]

File-level NetCDF attributes.
conventions str | None

Conventions string (e.g., "CF-1.8 UGRID-1.0").
n_nodes int

Total number of mesh nodes.
n_faces int

Total number of mesh faces.
n_edges int

Total number of mesh edges.
Source code in src/pyramids/netcdf/ugrid/models.py 
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
@dataclass(frozen=True)
class UgridMetadata:
    """Full metadata summary for a UGRID dataset.

    Aggregates topology information, data variable inventory,
    global attributes, and mesh element counts for display
    and inspection purposes.

    Attributes:
        mesh_topologies: List of parsed mesh topologies in the file.
        data_variables: Mapping of variable name to location.
        global_attributes: File-level NetCDF attributes.
        conventions: Conventions string (e.g., "CF-1.8 UGRID-1.0").
        n_nodes: Total number of mesh nodes.
        n_faces: Total number of mesh faces.
        n_edges: Total number of mesh edges.
    """

    mesh_topologies: tuple[MeshTopologyInfo, ...] = ()
    data_variables: dict[str, str] = field(default_factory=dict)
    global_attributes: dict[str, Any] = field(default_factory=dict)
    conventions: str | None = None
    n_nodes: int = 0
    n_faces: int = 0
    n_edges: int = 0