From 5e759168ff009e90e50bf468213307bd183618b0 Mon Sep 17 00:00:00 2001
From: cekees <613654+cekees@users.noreply.github.com>
Date: Fri, 23 Oct 2026 05:33:54 +0200
Subject: [PATCH] Record that time and space may be nested the wrong way round

The document has one temporal collection per function space, each with its
own list of instants, which is XDMF's shape: a Temporal GridCollection
belongs to a grid type. The transpose -- one time collection with the
spaces inside each instant -- is likely the better model.

The objection is operator splitting, and cekees's answer is that it does
not hold: a fractional-step calculation has synchronization points where
every space is known, which are the logical archive points anyway, and
where it does not there are rational ways to write every space at the
finest-grained step. More to the point the archiving step is a separate
choice from the numerical step -- writing every space at every step it was
approximated at is not usually affordable -- so the archive already
samples at instants, which is what the transposed shape describes.

Noted rather than done: it is a format version, it changes both ends of
the reader and writer, and ymf2xmf would transpose on the way out.

Worth recording now because append_step, added in this branch, has to name
a collection in every record precisely because collections appear lazily
as models first archive. Under the transposed shape that problem does not
exist -- one record per instant, no names needed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docs/archive-format.md | 53 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/docs/archive-format.md b/docs/archive-format.md
index bda9520..dec86f3 100644
--- a/docs/archive-format.md
+++ b/docs/archive-format.md
@@ -460,6 +460,57 @@ XDMF XML with this model:
   rather than from an `.xmf`; only a ≤ 1.9 archive, which never recorded
   the order, still needs the `.xmf` written beside it.
 
+## Open: the nesting of time and space may be inverted
+
+Recorded 2026-10-23, from cekees. The document today has **one temporal
+collection per function space**, each holding its own list of instants:
+
+```yaml
+time_collections:
+- name: Mesh_c0p1_Lagrange
+  data: [{time: 0.0, ...}, {time: 0.5, ...}]
+- name: Mesh_c0p2_Lagrange
+  data: [{time: 0.0, ...}, {time: 0.5, ...}]
+```
+
+That shape is inherited from XDMF, where a `Temporal` `GridCollection`
+belongs to a grid type. The likely better model is the transpose — **one
+time collection, with the spaces nested inside each instant**:
+
+```yaml
+times:
+- time: 0.0
+  spaces:
+    Mesh_c0p1_Lagrange: {topology: ..., geometry: ..., attributes: ...}
+    Mesh_c0p2_Lagrange: {...}
+```
+
+The objection to it is operator splitting: sub-models advance on different
+time steps, so there is no single instant at which every space is current.
+It does not hold, for two reasons:
+
+- an operator-split or fractional-step calculation **has synchronization
+  points** where every space is known, and those are the logical places to
+  archive anyway;
+- where it does not, there are rational ways to write every space at the
+  finest-grained step.
+
+More to the point, **the archiving step is a separate choice from the
+numerical step**. Writing every space at every step it was approximated at
+is usually not affordable, so the archive already samples; and once it
+samples, it samples at instants, which is exactly what the transposed shape
+describes.
+
+What it would buy: "which instants does this archive hold?" becomes a
+direct question rather than a walk over every collection; and a writer
+appending one record per instant needs no lazily-created collections, so
+the records would not have to name a collection at all. The append support
+added for proteus had to name them precisely because collections appear as
+models first archive — see :func:`ymf.archive.append_step`.
+
+What it would cost: `ymf2xmf` transposes on the way out, both ends of the
+reader and writer change, and it is a format version.
+
 ## Limits
 
 - Fields carry no units. The archive says what shape and type a field is,
@@ -467,6 +518,8 @@ XDMF XML with this model:
   problem spec in `extra`.
 - One level of spatial nesting: a step is a single grid or a flat
   collection of subdomain grids.
+- Time is nested inside space rather than the other way round; see the
+  section above.
 - `extra` is stored as-is and not validated.
 - Format version 1 is the only one. A reader refuses any other version
   rather than guess.