Merge branch 'feat/hydrolib-core' (v0.1.0a2)

Brings the official Deltares Python stack integration into main:

- feat(hydrolib): optional integration with hydrolib-core 1.0
- feat(viz):      U/V vector overlay + dfm-tools integration
- feat(mesh):     MeshKernel/xugrid adapter + wireframe overlay
- chore(release): v0.1.0a2

129 tests passing, ruff + mypy strict green.

Author: ghvmof

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -47,7 +47,7 @@ body:
     attributes:
       label: DeltaSuite version
       description: Output of `deltasuite --version` (or the value shown in Help → About).
-      placeholder: "0.1.0a1"
+      placeholder: "0.1.0a2"
     validations:
       required: true
 

CHANGELOG.md

@@ -7,6 +7,65 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0a2] - 2026-05-13
+
+Second alpha. Adds the official **Deltares Python stack** integration
+(`hydrolib-core`, `dfm-tools`, `meshkernel` / `xugrid`) and three new
+visible features in the Map tab built on top of those libraries.
+
+### Added
+
+- **hydrolib-core integration (`core/hydrolib_adapter.py`)**
+  - `safe_load_fmmodel()` returns a `HydrolibLoadResult` that exposes
+    either a typed `FMModel` (when hydrolib-core is installed) or a
+    structured error, never raises through the GUI.
+  - `fmmodel_section_summary()` / `fmmodel_set_values()` so the Setup
+    tab can use the canonical schema without depending on the import
+    happening at GUI startup.
+  - Cached availability and version probes
+    (`is_hydrolib_available`, `hydrolib_version`).
+- **dfm-tools integration (`core/dfm_tools_adapter.py`) + U/V vector
+  overlay**
+  - `open_partitioned_smart()` / `open_curvilinear_smart()` wrap
+    `dfmt.open_partitioned_dataset` / `dfmt.open_dataset_curvilinear`
+    with graceful fallbacks to plain xarray when dfm-tools is not
+    installed.
+  - `find_uv_variables()` and `extract_uv_field()` produce a
+    library-agnostic `UVField` (x, y, u, v, magnitude, optional time).
+  - `MapViewerWidget.set_vector_overlay()` draws the `quiver` on top
+    of the colour mesh with configurable colour, scale and stride.
+  - `ResultControls` exposes a *Show U/V vectors* row with a stride
+    spin box that auto-disables when the dataset has no recognised
+    velocity pair.
+- **MeshKernel / xugrid integration (`core/mesh_adapter.py`)**
+  - Library-agnostic `MeshGeometry` dataclass (nodes, edges, optional
+    face-node connectivity) and `MeshLoadResult` wrapper.
+  - `load_mesh_from_dataset()` and `load_mesh_from_path()` with two
+    backends: `xugrid` when installed (canonical UGRID parser), and a
+    pure-numpy heuristic fallback that recognises the standard
+    `mesh2d_*` variable names (with automatic 1-based → 0-based
+    normalisation for both edge and face connectivity, preserving the
+    `-1` sentinel for ragged faces).
+  - Cached availability and version probes
+    (`is_xugrid_available`, `xugrid_version`,
+    `is_meshkernel_available`, `meshkernel_version`) so the GUI can
+    enable / disable the wireframe row without paying the cost of
+    importing the C++ extension.
+  - All eight new symbols re-exported from `deltasuite.core`.
+- **Mesh wireframe overlay in the Map tab**
+  - `MapViewerWidget.set_mesh_overlay()` adds a thin grey
+    `LineCollection` of mesh edges below the U/V quiver (so arrows
+    stay readable). Sentinel-padded edges (`-1` UGRID convention) are
+    filtered out.
+  - `ResultControls` exposes a *Show mesh wireframe* checkbox that
+    auto-disables when the open dataset has no detectable UGRID mesh.
+  - `ResultPanel` caches the parsed mesh per file so toggling the
+    overlay does not re-open the dataset.
+- **9 new tests** (`test_mesh_adapter.py`) covering availability /
+  version probes, missing-file handling, the xugrid path, the
+  heuristic fallback, the `MeshGeometry` count properties and a
+  full NetCDF round-trip on disk. Total: **129 tests** passing.
+
 ## [0.1.0a1] - 2026-05-11
 
 First public alpha release. Ships everything needed to open, edit, run
@@ -231,5 +290,6 @@ they affect anyone reusing this build pipeline:
   - Sphinx documentation skeleton with auto-generated API reference
   - GPL-3.0 license, CONTRIBUTING and CODE_OF_CONDUCT
 
-[Unreleased]: https://github.com/ghvmof/deltasuite/compare/v0.1.0a1...HEAD
+[Unreleased]: https://github.com/ghvmof/deltasuite/compare/v0.1.0a2...HEAD
+[0.1.0a2]: https://github.com/ghvmof/deltasuite/compare/v0.1.0a1...v0.1.0a2
 [0.1.0a1]: https://github.com/ghvmof/deltasuite/releases/tag/v0.1.0a1

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "deltasuite"
-version = "0.1.0a1"
+version = "0.1.0a2"
 description = "Open source desktop suite for pre-processing, running and post-processing Delft3D models"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -81,10 +81,16 @@ science = [
   "pandas>=2.1",
 ]
 delft3d = [
-  "hydrolib-core>=0.7",
-  "dfm-tools>=0.27",
-  "meshkernel>=4.0",
-  "xugrid>=0.10",
+  # Official Deltares stack. ``hydrolib-core`` provides the canonical
+  # parsers/serialisers for D-Flow FM (.mdu, structures, boundary conditions);
+  # ``dfm-tools`` adds high-level post-processing (vector overlays,
+  # cross-sections, partitioned datasets); ``meshkernel`` is the C++ mesh
+  # engine that powers grid generation and editing; ``xugrid`` is the
+  # xarray extension we use for UGRID-aware I/O.
+  "hydrolib-core>=1.0",
+  "dfm-tools>=0.45",
+  "meshkernel>=8.2",
+  "xugrid>=0.11",
 ]
 dev = [
   "pytest>=8.0",
@@ -174,8 +180,12 @@ ignore = [
   "N803",    # argument name should be lowercase (Qt uses camelCase)
   "N806",    # variable in function should be lowercase (Qt uses camelCase)
   "PLC0415", # import-outside-top-level (we use lazy imports for Qt and to keep CLI snappy)
-  "TCH001",  # typing-only-first-party-import (we like having imports near usage)
-  "TCH003",  # typing-only-standard-library-import (extra noise for stdlib types)
+  # NOTE: TCH001/TCH003 are the names used by the ruff version pinned in
+  # pre-commit (0.5). Newer ruff (>=0.6) emits a deprecation warning and
+  # remaps to TC001/TC003 automatically, but rejects TC001/TC003 in 0.5,
+  # so we keep the old names here for compatibility with both.
+  "TCH001",
+  "TCH003",
   "SIM112",  # uncapitalized environment variables (Windows uses 'ProgramFiles')
 ]
 
@@ -206,13 +216,27 @@ strict = true
 warn_unused_ignores = false
 warn_return_any = true
 ignore_missing_imports = true
+# Disable mypy from following imports into third-party packages that ship
+# Python 3.12+ syntax (``zarr``, ``dask``, etc.) - we already have
+# ``ignore_missing_imports = true`` for stub-less packages, but mypy will
+# try to actually parse them when they are available; ``follow_imports =
+# silent`` keeps mypy from descending into their source files.
+follow_imports = "silent"
 plugins = ["pydantic.mypy"]
 exclude = ["build", "dist", "docs/_build"]
 
 [[tool.mypy.overrides]]
 module = "tests.*"
 disallow_untyped_defs = false
 
+# Third-party packages whose source uses Python 3.12+ syntax (PEP 695 type
+# parameter lists, etc.) which our ``python_version = "3.11"`` mypy refuses
+# to parse. We do not call into these directly with explicit type
+# annotations, so silencing their analysis is harmless.
+[[tool.mypy.overrides]]
+module = ["zarr.*", "numcodecs.*", "donfig.*"]
+follow_imports = "skip"
+
 # ----------------------------------------------------------------------
 # Pytest
 # ----------------------------------------------------------------------

src/deltasuite/core/__init__.py

@@ -12,9 +12,39 @@
     ConfigEntry,
     ConfigFormat,
     ConfigSection,
+    SmartLoadResult,
+    load_smart,
+)
+from deltasuite.core.dfm_tools_adapter import (
+    DfmDatasetResult,
+    UVField,
+    dfm_tools_version,
+    extract_uv_field,
+    find_uv_variables,
+    is_dfm_tools_available,
+    open_curvilinear_smart,
+    open_partitioned_smart,
+)
+from deltasuite.core.hydrolib_adapter import (
+    HydrolibLoadResult,
+    fmmodel_section_summary,
+    fmmodel_set_values,
+    hydrolib_version,
+    is_hydrolib_available,
+    safe_load_fmmodel,
 )
 from deltasuite.core.kernels import KernelInfo, KernelKind, KernelSet, detect_kernels
 from deltasuite.core.logging_setup import configure_logging
+from deltasuite.core.mesh_adapter import (
+    MeshGeometry,
+    MeshLoadResult,
+    is_meshkernel_available,
+    is_xugrid_available,
+    load_mesh_from_dataset,
+    load_mesh_from_path,
+    meshkernel_version,
+    xugrid_version,
+)
 from deltasuite.core.paths import AppPaths, get_app_paths
 from deltasuite.core.project import Project, ProjectMeta, ProjectType
 from deltasuite.core.project_detector import (
@@ -56,12 +86,16 @@
     "ConfigFormat",
     "ConfigSection",
     "DetectedProject",
+    "DfmDatasetResult",
     "Field2D",
     "Grid2D",
     "GridKind",
+    "HydrolibLoadResult",
     "KernelInfo",
     "KernelKind",
     "KernelSet",
+    "MeshGeometry",
+    "MeshLoadResult",
     "Project",
     "ProjectMeta",
     "ProjectType",
@@ -73,22 +107,42 @@
     "RunConfig",
     "RunConfigError",
     "Settings",
+    "SmartLoadResult",
     "StationSeries",
     "TimeSeriesDataset",
     "TimeSeriesFile",
     "TimeSeriesVariable",
+    "UVField",
     "build_run_config",
     "configure_logging",
     "detect_kernels",
     "detect_project",
+    "dfm_tools_version",
     "discover_projects",
+    "extract_uv_field",
     "find_history_files",
     "find_result_files",
+    "find_uv_variables",
+    "fmmodel_section_summary",
+    "fmmodel_set_values",
     "get_app_paths",
     "get_recent",
     "get_settings",
+    "hydrolib_version",
+    "is_dfm_tools_available",
+    "is_hydrolib_available",
+    "is_meshkernel_available",
+    "is_xugrid_available",
+    "load_mesh_from_dataset",
+    "load_mesh_from_path",
+    "load_smart",
+    "meshkernel_version",
     "open_bundled_sample",
+    "open_curvilinear_smart",
+    "open_partitioned_smart",
     "push_recent",
+    "safe_load_fmmodel",
     "save_recent",
     "save_settings",
+    "xugrid_version",
 ]

src/deltasuite/core/config_files.py

@@ -276,7 +276,6 @@ def parse_mdf(text: str, *, path: Path | None = None) -> ConfigDocument:
             entry = ConfigEntry(key=key.strip(), value=value.strip(), comment="")
             section.entries.append(entry)
             last_entry = entry
-        # Continuation line for the previous multi-value entry.
         elif last_entry is not None:
             last_entry.value = (last_entry.value + "\n" + line.strip()).strip()
         else:
@@ -305,12 +304,58 @@ def serialize_mdf(doc: ConfigDocument) -> str:
     return "\n".join(lines).rstrip() + "\n"
 
 
+# ---------------------------------------------------------------------------
+# Smart load helpers (optional ``hydrolib-core`` integration)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True)
+class SmartLoadResult:
+    """Combined result of a "best effort" .mdu / .mdf load.
+
+    ``document`` is always populated (we fall back to our lossless parser even
+    when hydrolib-core rejects the file). ``hydrolib_validated`` reflects
+    whether the file was *also* successfully validated against the official
+    Deltares schema; ``hydrolib_error`` carries the validation message
+    otherwise.
+    """
+
+    document: ConfigDocument
+    hydrolib_validated: bool = False
+    hydrolib_error: str | None = None
+
+
+def load_smart(path: Path) -> SmartLoadResult:
+    """Load a configuration file with extra validation when available.
+
+    For ``.mdu`` files this attempts a parallel parse with ``hydrolib-core``
+    (when installed) and surfaces any validation errors without losing the
+    primary, comment-preserving document. For ``.mdf`` files only our
+    parser runs (hydrolib-core does not handle Delft3D 4 ``.mdf``).
+    """
+    document = ConfigDocument.load(path)
+    if document.format is not ConfigFormat.MDU:
+        return SmartLoadResult(document=document)
+
+    # Lazy import: only touch hydrolib_adapter when actually needed.
+    from deltasuite.core.hydrolib_adapter import safe_load_fmmodel
+
+    result = safe_load_fmmodel(document.path)
+    return SmartLoadResult(
+        document=document,
+        hydrolib_validated=result.ok,
+        hydrolib_error=result.error,
+    )
+
+
 __all__ = (
     "ConfigDocument",
     "ConfigEntry",
     "ConfigFormat",
     "ConfigSection",
+    "SmartLoadResult",
     "detect_format",
+    "load_smart",
     "parse_mdf",
     "parse_mdu",
     "serialize_mdf",