Adding Allen-Cahn reference test
3 changed files+127−0
cases/allencahn-ellipsoid.mdadded+127−0View file
@@ -0,0 +1,127 @@
1+# Case: Allen–Cahn on a triaxial ellipsoid
2+
3+A reference solution for validating reaction-diffusion solvers that operate
4+on curved surfaces, specifically the discretization of the surface
5+Laplace-Beltrami operator. Any solver capable of solving reaction-diffusion
6+systems on a closed surface can be checked against this case by starting
7+from the same initial condition, running to the same physical end time, and
8+comparing the resulting field in spherical-harmonic coefficient space.
9+
10+## Geometry
11+
12+A triaxial ellipsoid, parametrized by colatitude `θ ∈ [0, π]` and azimuth
13+`φ ∈ [0, 2π)`:
14+
15+```
16+x = ax · sin(θ) · cos(φ)
17+y = ay · sin(θ) · sin(φ)
18+z = az · cos(θ)
19+```
20+
21+with semi-axes `ax`, `ay`, `az` (reference defaults: `1.5, 1.0, 0.6`).
22+
23+**The surface is band-limited.** The reference solution was not computed on
24+the exact analytic ellipsoid above, but on its spherical-harmonic
25+reconstruction truncated at a finite degree `lmax`: the analytic `(x, y, z)`
26+was expanded in spherical harmonics and then re-synthesized from that
27+truncated expansion, which very slightly rounds off the surface relative to
28+the ideal ellipsoid. The truncated surface's own coefficients are included
29+in the data file (see below). **A solver being validated against this case
30+should reconstruct its working surface (and induced metric) from those
31+coefficients, not from the analytic formula**, so that any disagreement in
32+the final field reflects the reaction-diffusion solve and not a difference
33+in which surface was actually used.
34+
35+## Equations
36+
37+The Allen–Cahn equation, with `Δ_g` the Laplace-Beltrami operator of the
38+surface above. Unlike the Schnakenberg cases in this data set, Allen–Cahn is
39+a single-species phase-field equation: an interface forms between `u ≈ +1`
40+and `u ≈ −1` regions and then coarsens over time.
41+
42+```
43+∂u/∂t = eps2·Δ_g(u) + u − u³
44+```
45+
46+| parameter | meaning | reference value |
47+|---|---|---|
48+| `eps2` | interface-width parameter (`ε²`) | 0.01 |
49+
50+A solver is free to choose its own numerical method for `Δ_g` and its own
51+timestep — those are not part of what is being tested. What matters is
52+reaching the same physical end time `T`, computed as `steps × dt` from the
53+values stored in the data file's metadata (see below), starting from the
54+supplied initial condition.
55+
56+## Initial condition
57+
58+The initial `u` field is supplied as data — spherical-harmonic coefficients
59+at `t = 0` — rather than as a formula to regenerate. A solver should
60+synthesize its starting field directly from these coefficients. This
61+sidesteps any need to reproduce whatever pseudorandom process originally
62+generated the perturbation: the state at `t = 0` is simply data to load.
63+
64+## Comparison convention
65+
66+To compare against this reference, a solver's own final `u` field must be
67+expressed in the same spherical-harmonic convention used throughout this
68+data set:
69+
70+- **Orthonormal** spherical harmonics, **including the Condon-Shortley
71+ phase**.
72+- Because `u` is a real-valued field, only coefficients for `m ≥ 0` are
73+ stored, as complex numbers. The `m < 0` coefficients are implied by
74+ `Q(l, −m) = (−1)^m · conj(Q(l, m))`, and every `m = 0` coefficient has a
75+ zero imaginary part.
76+- **Ordering**: "m-major" — for `m = 0` up to `lmax`, and within each `m`,
77+ for `l = m` up to `lmax`. The flat index of coefficient `(l, m)` is:
78+
79+ ```
80+ index(l, m) = m·(lmax + 1) − m·(m − 1)/2 + (l − m)
81+ ```
82+
83+- The total coefficient count is `nlm = (lmax + 1)(lmax + 2)/2`. Coefficients
84+ are stored as a flat array of length `2·nlm`, with the real and imaginary
85+ part of each coefficient adjacent: `[re(0), im(0), re(1), im(1), ...]`.
86+
87+A solver's comparison output should be a flat array of the same length,
88+`2·nlm`, in the same ordering, for direct numerical comparison against the
89+reference.
90+
91+## Data file format
92+
93+Each reference run is stored as a single HDF5 file. All coefficient arrays
94+are 32-bit floats (the reference solution itself was computed in single
95+precision, so no comparison should expect agreement finer than that).
96+Scalar metadata is stored as HDF5 attributes, grouped by what they describe:
97+
98+```
99+/ (attrs: a short description of the run, and the
100+ name of the species stored under initial/ and
101+ final/, e.g. "U")
102+├─ spec/ run parameters as attributes: lmax, seed, steps,
103+│ warmup, and the iteration count used internally
104+│ by the reference solver's own Δ_g approximation
105+│ ├─ params/ the model's own parameters: eps2, dt
106+│ └─ geometry_params/ the geometry's own parameters: ax, ay, az
107+├─ grid/ the reference solver's own working grid, as
108+│ attributes: lmax, mmax, nlat, nphi, nlm
109+├─ geometry/
110+│ ├─ Gx dataset, float32[2·nlm] — the band-limited
111+│ ├─ Gy surface's own spherical-harmonic coefficients,
112+│ └─ Gz one per Cartesian component
113+├─ initial/ one dataset (U), float32[2·nlm] — the initial
114+│ condition at t = 0
115+└─ final/ one dataset (U), float32[2·nlm] — the solution
116+ after evolving to t = steps·dt
117+```
118+
119+`lmax` (under `spec/` and `grid/`) is the spherical-harmonic truncation
120+degree that defines `nlm` and the coefficient ordering above; it is the same
121+value everywhere it appears in a given file. `seed` identifies which
122+pseudorandom perturbation produced the initial condition, but is provenance
123+information only — the initial condition itself is fully specified by the
124+`initial/` coefficients, and does not need to be regenerated from the seed.
125+
126+Every dataset in `geometry/`, `initial/`, and `final/` has length `2·nlm`
127+and follows the ordering convention described above.
data/allencahn/2026-08-05_Lmax_127_high_aspect.h5added+0−0View file
Binary file not shown.
data/allencahn/2026-08-05_Lmax_63_high_aspect.h5added+0−0View file
Binary file not shown.