Python library for reading, writing, and manipulating MIKE files (dfs0–dfs3, dfsu, mesh) from DHI (Danish Hydraulic Institute). Sits between the DHI/MIKE file-format world and the Python scientific stack (numpy, pandas, xarray).
This document defines the vocabulary used across mikeio's code, docs, and discussions. Read it if you're:
- using mikeio and want to understand the concepts behind the API
- contributing code or docs and want to use names consistently
- an LLM/agent working in this repo
If you only need to use mikeio, the user guide and API reference are the right entry points; come here when a term is unfamiliar.
A dfs file on disk holds one or more Items (named quantities with metadata) sampled along a Time axis over some Geometry (a structured Grid or a Flexible Mesh). Reading produces an in-memory Dataset of DataArrays — one DataArray per Item — all sharing the same time axis and geometry.
file on disk in memory
──────────── ─────────
dfs / dfsu ──read──▶ Dataset
└─ Item ├─ DataArray
├─ ItemInfo │ ├─ ItemInfo
└─ values │ ├─ values
├─ Time axis
└─ Geometry
The rest of this document defines each named box and the variants you may encounter.
DHI's own docs use DFS0/DFS1/DFS2/DFS3/DFSU (uppercase). mikeio uses lowercase dfs0–dfs3/dfsu for prose and file extensions, and PascalCase (Dfs0, Dfsu2DH, …) for Python classes. Both are accepted; uppercase is closer to DHI, lowercase matches mikeio convention.
DFS (uppercase): The DHI binary file-format family ("Data File System"). Refers to the format itself and its specification. Avoid: dfs (when meant as the format spec), MIKE format.
dfs file (lowercase):
A file in the DFS family — includes .dfs0, .dfs1, .dfs2, .dfs3, and .dfsu. Does not include .mesh.
Avoid: MIKE file (too broad), DHI file.
dfs0 / dfs1 / dfs2 / dfs3: Structured-grid dfs files. The digit is the spatial dimensionality: 0 = time series (point), 1 = line, 2 = area, 3 = volume. All carry a time axis even when single-snapshot. Avoid: 0D/1D/2D/3D dfs (informal — use dfs0..dfs3), dfs-N.
dfsu: Flexible-mesh dfs file. The "u" stands for unstructured. Subtypes are 2DH (horizontal), 2DV (vertical slice), 3D (layered), and Spectral. Avoid: unstructured dfs, FM dfs.
Mesh file:
A .mesh file containing only mesh topology (Nodes + Elements) with no dynamic data. Distinct from dfsu.
Avoid: mesh-only dfs (it's not a dfs file).
Element: A discrete area/volume in a flexible mesh (unstructured grid). Triangles and quads in 2D; prisms and hexahedra in 3D. Note: DHI's own docs sometimes use "Element" loosely to describe value location for structured grids too — mikeio does not, see Cell below. Avoid: cell, face, polygon (in FM context).
Cell:
A discrete area/volume in a structured grid (Grid1D, Grid2D, Grid3D).
Avoid: element, pixel (in Grid context).
Node: A mesh vertex — a point with coordinates referenced by Element connectivity. Avoid: vertex, point, corner.
Face: The interface between two Elements. Carries data for DFSU type 2004 (e.g. discharge across an interface). In layered 3D meshes, "layer face" is the horizontal interface between two stacked Elements. Avoid: edge, interface, side.
Geometry:
The spatial structure attached to a DataArray/Dataset. Abstract concept; concrete types are Grid1D, Grid2D, Grid3D, GeometryFM2D, GeometryFM3D, GeometryFMVerticalProfile, etc.
Avoid: grid (when meant generically), topology, domain.
Grid:
A structured (regular, axis-aligned) Geometry with uniform spacing — Grid1D, Grid2D, Grid3D. Backs dfs1/dfs2/dfs3.
Avoid: raster, lattice, mesh.
Flexible Mesh (FM):
An unstructured Geometry made of Nodes and Elements — GeometryFM2D, GeometryFM3D, etc. Backs dfsu and .mesh files. The codebase uses FM consistently in class names.
Avoid: unstructured grid, triangulation, "mesh" (when meant as a geometry concept — see below).
Mesh (file):
A .mesh file: mesh topology only, no dynamic data. Reserved for the file type, never for the geometry concept.
Avoid: using "Mesh" for the unstructured geometry concept — say "Flexible Mesh" or "FM" instead.
Projection:
The coordinate-system reference of a dfs file's spatial axis (e.g. LONG/LAT, UTM zone, custom). Held alongside Geometry.
Avoid: CRS (the code uses crs utilities but file-side concept is "projection"), coordinate system.
EUM ("Engineering Unit Manager"):
DHI's catalogue of physical quantities and their permissible units. Exposed in mikeio via EUMType (the kind, e.g. Water_Level) and EUMUnit (the unit, e.g. meter).
Avoid: unit system, quantity registry.
EUMType:
The physical-quantity kind of an Item (e.g. Water_Level, Wind_speed, Discharge). Constrains which EUMUnit values are valid.
Avoid: quantity, kind, item type.
EUMUnit:
The unit of measurement for an Item (e.g. meter, meter_per_sec). Must be compatible with the Item's EUMType.
Avoid: unit, units, uom.
ItemInfo:
The Python class bundling the metadata of one Item: name, EUMType, EUMUnit, DataValueType. When referring to the concept (e.g. in prose), prefer "Item metadata"; when referring to the class/object, use ItemInfo.
>>> from mikeio import ItemInfo, EUMType, EUMUnit
>>> ItemInfo("Water Level", EUMType.Water_Level, EUMUnit.meter)Avoid: item descriptor, item header, item spec.
DataValueType:
How a value relates to the time axis: Instantaneous, Accumulated, StepAccumulated, MeanStepBackward, MeanStepForward. Only meaningful for dfs0; dfs1/dfs2/dfs3 are always Instantaneous. Roughly analogous to CF Conventions' cell_methods along the time axis (time: point, time: sum, time: mean), but DHI does not formalise the mapping.
Avoid: cell method, sampling type, temporal aggregation.
Item:
A named quantity stored in a dfs file, carrying an ItemInfo (name, EUMType, EUMUnit). File-side concept.
Avoid: variable, column, channel, field.
DataArray: The in-memory representation of one Item's data after reading, with its time axis, geometry, and ItemInfo attached. Avoid: variable, array, series.
Dataset: An ordered collection of DataArrays sharing the same time axis and geometry — the in-memory result of reading a dfs file.
>>> import mikeio
>>> ds = mikeio.read("oresund.dfsu")
>>> ds["Surface elevation"] # → DataArrayAvoid: frame, table.
Time axis:
The sequence of timestamps a Dataset/DataArray is indexed by — a pandas.DatetimeIndex. Always present in dfs files, even single-snapshot ones.
Avoid: time dimension, time coord (when meant as the axis itself).
Timestep: Used in two senses, disambiguated by context:
- The interval between consecutive samples (a duration in seconds — e.g. the
.timestepproperty on a reader). - A single sample along the time axis (e.g.
n_timesteps, "read timestep 0"). When ambiguity matters, write "timestep duration" vs "timestep index" / "snapshot". Avoid: frame, record, tick.
Snapshot: A single sample along the time axis — unambiguous synonym for the second sense of "timestep". Useful when discussing single-time-step files. Avoid: frame, slice (which has its own meaning).
Equidistant: A time axis with uniform spacing between samples. DHI calls this an "equidistant calendar axis". Non-equidistant axes exist and require reading the data to obtain the timestamps. Avoid: uniform, regular (when meant as time-spacing).
PFS file: A DHI text-format file containing parameters and settings for MIKE tools and engines. Distinct subdomain from dfs/dfsu data files. Avoid: parameter file (too generic), config file, ini file.
Target: A root (out-most) Section in a PFS file. A PFS file contains one or more Targets. Avoid: root section (use "Target"), top-level block.
Section:
A named scope inside a PFS file. May contain nested Sections and Keywords. Represented in mikeio by PfsSection (a single class for any nesting depth).
Avoid: sub-section as a type (it's just a Section that happens to be nested), block, group.
Keyword: A named entry inside a Section. Holds one or more Parameters. Avoid: key, field, attribute.
Parameter (PFS context):
A value held by a Keyword. A Keyword can hold multiple Parameters (e.g. point = 1, 2.5, 'name' is one Keyword with three Parameters). Types: Integer, Double, Boolean, Text string, File name, CLOB.
Avoid: param, value (in PFS prose), entry. Note: "Parameter" in this PFS sense is not a key-value pair — that's a Keyword with its Parameters.
PfsDocument: The Python class representing a parsed PFS file. No direct DHI counterpart name. Avoid: pfs object, parsed pfs.
Spectrum (noun): A data distribution over a frequency axis, a direction axis, or both — typically wave energy density. The data held at one location. Avoid: spectral data (when meant as a thing rather than a property).
Spectral (adjective): Modifier for files, geometries, and items that carry Spectra (e.g. spectral file, spectral geometry). Avoid: using "spectral" as a noun.
Point / Line / Area spectrum:
The spatial arrangement of where Spectra live in a spectral dfsu — a single point (GeometryFMPointSpectrum), along a 1D line (GeometryFMLineSpectrum), or over a 2D mesh (GeometryFMAreaSpectrum).
Avoid: 0D/1D/2D spectrum.
Frequency axis: The frequency dimension of a Spectrum (Hz). May be equidistant or logarithmic. Avoid: freq axis (in prose).
Direction axis: The directional dimension of a Spectrum (degrees). Wave heading convention (from/to) is determined by the file. Avoid: angle axis, theta axis.
Spectral file:
A dfsu storing Spectra (rather than scalar fields per Element). Class: DfsuSpectral.
Avoid: spectrum file (singular noun); wave file.
Code (node code): An integer attached to each Node in a Flexible Mesh. Used to classify boundary membership. Avoid: flag, tag, marker.
Boundary code: A Code > 0 — i.e. a Node lies on the mesh boundary. Internal Nodes have code 0. Avoid: boundary marker, boundary flag.
Land boundary: Boundary code == 1. The closed/no-flux boundary of the mesh. Avoid: closed boundary, wall.
Open boundary: Boundary code > 1. The flow-through/forced boundary; multiple open boundaries are distinguished by distinct codes (2, 3, …). Avoid: forced boundary, inlet/outlet.
Internal node: A Node with code == 0 — strictly inside the mesh, not on any boundary. Avoid: interior node.
Track:
A moving observation — a (time, x, y[, z]) sequence (e.g. ship, buoy, satellite path). Has a time axis. Sampled from a dfsu via extract_track.
Avoid: trajectory, path, route.
Transect: A fixed cross-section through space (no time). Used for vertical-profile plots and similar 2D slices through a 3D mesh. Avoid: section, slice, cut.
Layer: A horizontal slab of Elements in a 3D Flexible Mesh. Stacked bottom-up; Elements in the same vertical column have consecutive indices. Avoid: level (CF/oceanography term, not used in mikeio), slice.
Sigma layer: A terrain-following layer (top portion of the water column). Sigma layers follow the free surface; their thickness varies in time. Avoid: terrain-following layer, surface layer.
z-layer (hyphenated):
A fixed-elevation layer (bottom portion). z-layers have constant Z; the count varies with depth (n_z_layers is a maximum).
Avoid: fixed layer, depth layer, z layer (no hyphen).
Sigma-z:
The hybrid layering mode where a 3D file mixes sigma layers (above) with z-layers (below). When n_sigma_layers < n_layers, the file is sigma-z.
Avoid: hybrid layers, mixed layers.
Column (vertical):
The vertical stack of Elements above a single horizontal (x, y) position — represented by GeometryFMVerticalColumn.
Avoid: water column (overloaded — physical concept), stack.
Vertical profile:
A 2D vertical slice through a 3D mesh (a transect with depth). Backed by Dfsu2DV files and GeometryFMVerticalProfile.
Avoid: vertical transect, vertical section.
The full binary specification lives in docs/FM_FileSpecification.pdf. The two terms below leak into user-facing docstrings, so they are defined here.
Static item: Time-independent metadata stored as an "item" in the dfs binary structure (e.g. node coordinates, element table, projection). Distinct from the user-visible Item concept above. Avoid: metadata item, header item, fixed item.
Dynamic item: A time-varying Item — what users mean when they say "Item" in everyday usage. The Item entry in the file's data block. Avoid: data item, time-varying item.
- A dfs file contains one or more Items; reading produces a Dataset of DataArrays, one per Item.
- A DataArray has exactly one ItemInfo; a Dataset has one ItemInfo per DataArray.
- A Flexible Mesh has Nodes and Elements; an Element references its Nodes via the element table (counter-clockwise).
- A Grid has Cells (no Nodes/Elements/Faces).
- A DataArray holds exactly one Geometry; a Dataset shares one Geometry across all its DataArrays.
User: "I've got a dfsu file with surface elevation and wind speed. How do I get just the wind speed at a specific location?" Maintainer: "Open the file with
mikeio.read()— that gives you a Dataset with two DataArrays, one per Item. Pick the wind-speed DataArray and use spatial selection on its Geometry (aGeometryFM2D) to get the Element containing your point."User: "And the surface-elevation values — are those at the corners or in the middle of the elements?" Maintainer: "Element-centered. dfsu data is always per-Element, never per-Node. mikeio has helpers to interpolate from element centres to Nodes when you need that."
User: "Got it. Now I have a 3D file. What's the difference between sigma layers and z-layers?" Maintainer: "Sigma layers are terrain-following — they sit at the top of the water column and stretch with the free surface. z-layers are fixed-elevation, at the bottom. A file mixing both is sigma-z. The vertical stack at one (x, y) is a Column."