From 6bc47f01de79c031ae16f3140b3810e415487b06 Mon Sep 17 00:00:00 2001 From: lmoresi Date: Tue, 7 Jul 2026 09:49:16 +0100 Subject: [PATCH 1/2] docs(remesh): be honest about _write_var_data except breadth (Copilot review) The broad except Exception is pre-existing behaviour, unified verbatim from three identical try/except sites by the readability wave. The comment claimed the swallow only covers unallocated/size-0 storage; in fact the breadth also hides genuine write failures (shape/broadcast mismatches). Keep the behaviour (wave contract), state the breadth honestly, and add a TODO(DESIGN) to narrow once the unallocated-path exception types are established. Underworld development team with AI support from Claude Code --- src/underworld3/discretisation/remesh.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/src/underworld3/discretisation/remesh.py b/src/underworld3/discretisation/remesh.py index 51f27569..2cd4f046 100644 --- a/src/underworld3/discretisation/remesh.py +++ b/src/underworld3/discretisation/remesh.py @@ -235,11 +235,17 @@ def _write_var_data(var, values): try: np.asarray(var.data)[...] = values except Exception: - # Sanctioned swallow: a var whose storage is unallocated or size-0 - # on this rank (lazy allocation / empty local partition) has nowhere - # to write. Skipping leaves the variable exactly as the snapshot - # pass found it — the same vars are skipped by _snapshot_var_data, - # so no transfer is silently half-applied. + # Sanctioned swallow (pre-existing breadth: this helper unified + # three identical broad try/except sites). The INTENDED skip is a + # var whose storage is unallocated or size-0 on this rank (lazy + # allocation / empty local partition) — nowhere to write, and the + # same vars are skipped by _snapshot_var_data, so no transfer is + # silently half-applied. The breadth, however, also swallows + # genuine write failures (e.g. shape/broadcast mismatches), which + # would silently skip a transfer/zeroing for a non-empty variable. + # TODO(DESIGN): narrow this once the exception types raised by the + # unallocated-storage `.data` paths are established (probe lazy + # alloc / empty partitions), or report skips instead of passing. pass From 34d45ef8902d7406c4950ea4dbf7b39eb2a47dc1 Mon Sep 17 00:00:00 2001 From: lmoresi Date: Tue, 7 Jul 2026 09:49:16 +0100 Subject: [PATCH 2/2] docs(units): fix evaluate() Returns to match the gateway principle (Copilot review) The WE-04 Returns section said scaling-active evaluation returns a plain ndarray. The implementation (gateway principle) returns unit-aware values whenever the expression carries units, regardless of scaling state; plain ndarray only for unitless expressions. Docstring now matches unwrap_for_evaluate/_evaluate_impl reality. Underworld development team with AI support from Claude Code --- src/underworld3/function/functions_unit_system.py | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/src/underworld3/function/functions_unit_system.py b/src/underworld3/function/functions_unit_system.py index fa249914..d9289c6e 100644 --- a/src/underworld3/function/functions_unit_system.py +++ b/src/underworld3/function/functions_unit_system.py @@ -841,11 +841,14 @@ def evaluate( Returns ------- UWQuantity, UnitAwareArray, or numpy.ndarray - If non-dimensional scaling is active, a plain ndarray. If the - expression carries units, a ``UWQuantity`` (scalar) or - ``UnitAwareArray``. Otherwise a plain ndarray. With - ``check_extrapolated=True``, a ``(values, extrapolated_mask)`` - pair. + Unit-aware whenever the expression carries units, regardless of + whether non-dimensional scaling is active (gateway principle: + the user always sees dimensional values when units are known): + a ``UWQuantity`` for scalar results, a ``UnitAwareArray`` + otherwise, re-dimensionalised via the active scaling when one + applies. A plain ndarray when the expression carries no units. + With ``check_extrapolated=True``, a + ``(values, extrapolated_mask)`` pair. Examples --------