v0.3.0

EarthSciASTDiff v0.3.0

Diff since v0.2.0

EarthSciASTDiff v0.3.0

The evaluation and product documents of a flattened (coupled) system now
load, flatten and build in every EarthSciAST binding, and every derived
document carries its source's time origin. A minor release: the Rust
SysView gains a public field (see Breaking changes).

Breaking changes

• Rust: SysView has a new public field domain: Option<&Domain>.
  Code that builds a SysView with a struct literal must add it (None, or
  the source's domain); sysview and sysview_flat fill it.
• Rust: sysview_flat returns Result<SysView, BandError>, since it
  now refuses a lifted state's shape that disagrees with lifted_shapes
  (below). Add ? or .unwrap() at the call.

Fixed

• The evaluation document of a flattened system (evaluation_document
  of a FlattenedSystem, spec §8.1). It declared every scoped name, such as
  SimpleOzone.O3, in the one model JacobianEval, which EarthSciAST reads
  as a reference into a missing component: Python refused to load it
  (reference 'SimpleOzone.O3' to undefined system 'SimpleOzone'), Rust
  refused to build it (unresolved_scoped_ref), and Julia refused to build
  its right-hand side (E_TREEWALK_UNKNOWN_STATE). The source's variables
  are now declared in the system's component tree: P.v as v in the model
  at component path P (nested subsystems for deeper paths), each equation
  in the model of the variable it is about, every reference still fully
  scoped. The band fields keep their names and order (J_k, in
  JacobianEval, so JacobianEval.J_k once flattened).
• The product documents of a flattened system (jvp_document,
  vjp_document, hvp_document, spec §9.1) are laid out the same way. Their
  inputs and outputs take the column's name with each . made _
  (_v_SimpleOzone_O3, so JvpEval._v_SimpleOzone_O3 once flattened); for
  a source with no scoped names they are unchanged.
• Sources a derived document cannot hold are refused with a BandError
  instead of giving a wrong document: a flattened system mixing scoped and
  unscoped names, a component named like the derived model (JacobianEval,
  JvpEval, …), a scoped name that is both a variable and a component
  (A.B beside A.B.c), and a source variable named like a band field
  (J_k).
• Python: pointwise-lifted states of a flattened system take their grid
  shape in sysview, as in Rust and the Julia reference. Python's flatten
  records the grid only in lifted_shapes, so sysview read every lifted
  state as a scalar and the bands of a lifted system could not be formed.
• A lifted state's index sets are EarthSciAST's (spec §8.1). From
  EarthSciAST 0.8 (EarthSciAST#623), every binding's flatten records a
  pointwise-lifted state's shape as the lift's index sets, named first by
  an operand declared on them and read at the lift's loops
  (esm-libraries-spec §4.7.5). The view (sysview of a flattened system in
  Julia and Python, sysview_flat in Rust), its context, the bands, the
  derived documents and the scatter plans all take that shape as recorded.
  The derivation from the extents alone (the one index set of that size,
  else a synthetic _liftdim<d>_<n>), which names a synthetic index set
  where EarthSciAST names the operand's, now applies only to a flatten
  that records no shape (Rust and Python before EarthSciAST 0.8). Every
  binding now admits EarthSciAST 0.8 (Julia 0.6, 0.7, 0.8, Rust
  >=0.5, <0.9, Python >=0.4,<0.9; the floors are unchanged); use 0.8
  for lifted documents that agree with EarthSciAST's naming in every
  binding.
• A lifted state's recorded shape is checked against lifted_shapes in
  every binding: the same rank, every entry an index set of the flattened
  system of that dimension's extent, or a BandError (Julia:
  ArgumentError). Julia's flatten before EarthSciAST 0.8 names a
  synthetic _liftdim<d>_<n> in the shape without adding it to
  index_sets, so a lift no operand names onto same-size index sets threw a
  KeyError in the view's context; the view now adds that set.
• The fallback follows esm-libraries-spec §4.7.5 rule 3 (Rust and
  Python): a document that declares _liftdim<d>_<n> with another size is
  refused with a dimension-promotion BandError instead of reusing it at
  that size, and only the document's own index sets are matched by size (a
  declared _liftdim* set counts; one added for an earlier lifted state
  does not).

New

• Every derived document carries the source's domain (spec §8.1,
  §9.1): temporal (start, end, reference_time), element_type and
  array_type, built from EarthSciAST's serialization of the domain, so the
  evaluation and product documents have the source's time origin, from which
  a runtime turns timestamps into model time. SysView holds the source's
  domain:
  • Julia: a fourth field domain; the three-argument constructor still
    works (domain = nothing).
  • Python: a domain field defaulting to None.
  • Rust: the public field above.

Unchanged

• The documents of one model of a document (no scoped names) are the same,
  plus domain when the document has one. No existing fixture has a domain,
  so every existing golden is unchanged.

Conformance

• New goldens coupled_chem_advection.evaldoc.json,
  coupled_chem_advection.evaldoc-nocse.json and
  coupled_chem_advection.jvals.json. Every binding byte-compares the
  documents and builds each with its EarthSciAST, with the native compiler
  and the interpreter, to check its band values; the Julia reference checks
  those values against ForwardDiff of the flattened source. Every binding
  also builds the flattened system's JvpEval and VjpEval documents and
  checks J v and Jᵀ λ against that golden; Julia and Python check the
  HvpEval document against a central difference of λᵀ J v.
• New fixture lift_same_size_index_sets.esm (EarthSciAST's pointwise-lift
  conformance case of that name) with goldens
  lift_same_size_index_sets.evaldoc.json and .jvals.json (nothing to
  hoist, so no .evaldoc-nocse.json): two index sets of size 3, and an
  operand that names the lifted state's grid [x, y]. Unlike EarthSciAST's
  copy, the operand differs in every cell, so the values also pin the cell
  layout. Every binding byte-compares the document (with and without
  hoisting) and checks the values; Python and Rust skip them when their
  flatten records no lifted shape (before EarthSciAST 0.8).
• scripts/regenerate-goldens.jl keeps a flattened fixture's
  .evaldoc-nocse.json only where it differs, as for every other fixture.

Breaking changes

None marked in the commit messages (type!: or BREAKING CHANGE:); see the changelog below.

Changelog

• chore(release): v0.3.0 (d07bb22)
• test(python): skip the flattened parameters band golden before earthsci-ast 0.6 (5e89692)
• test(bindings): pin the flattened coupled document's bands in every binding (58fa823)
• ci(docs): patch cargo to the EarthSciAST checkout for the Rust extract (312e498)
• fix(bindings): address PR #50 review of the recorded lift shape (cbbeff8)
• feat: take a lifted state's index sets from flatten (696f4a6)
• fix: lay product documents out as the component tree; address PR #49 review (f37d1b8)
• feat: carry the source's domain into the evaluation document (7215009)
• fix: lay a flattened system's evaluation document out as its component tree (0774d1f)

Merged pull requests:

• fix: lay a flattened system's evaluation document out as its component tree (#49) (@ctessum-claude)
• feat: take a lifted state's index sets from flatten (#50) (@ctessum-claude)
• test(bindings): pin the flattened coupled document's bands in every binding (#51) (@ctessum-claude)
• chore(release): v0.3.0 (#52) (@ctessum-claude)

Closed issues:

• python: jacobian_bands on a flattened coupled document fails with 'no derivative rule for op faq' (#36)

Installation

using Pkg; Pkg.add("EarthSciASTDiff")   # Julia
pip install earthsci-astdiff             # Python