jacobian_bands

Julia

jacobian_bands(file::EarthSciAST.EsmFile, model_name; kw...)
jacobian_bands(flat::EarthSciAST.FlattenedSystem; kw...)
jacobian_bands(sv::SysView; wrt, forcing)

jacobian_bands(file::EsmFile, model_name; wrt = :states, forcing = nothing) -> Vector{JacEntry}
jacobian_bands(flat::FlattenedSystem;    wrt = :states, forcing = nothing) -> Vector{JacEntry}
jacobian_bands(sv::SysView;              wrt = :states, forcing = nothing) -> Vector{JacEntry}

Differentiate every differential equation of the system with respect to every state (wrt = :states), every parameter outside the forcing set (wrt = :parameters, scalar and array-valued alike), every forcing buffer (wrt = :forcing, the cells of the buffers forcing_names selects, their record axis included) that structurally occurs in its (observed-inlined) RHS — or with respect to time itself (wrt = :time, the single scalar site t; the integer-valued datetime.* calendar fields are piecewise-constant and differentiate to 0, the continuous datetime.julian_day to d[t]/86400, and interp.linear/interp.bilinear of t to the active-segment slope).

forcing names the forcing set explicitly; nothing infers it from the document (every array parameter with a data update). It also decides which parameters the :parameters axis leaves to the forcing axis.

The pattern implied by the result is GLOBAL: ifelse/min/max branches are unioned, so it is valid at every point and is a superset of any local (point-wise) pattern.

On the :parameters and :forcing axes every column index must be closed at build time (literals, folded metaparameters, const gathers, and the entry’s row and contracted index names); an unclosed one throws (esm-jacobian-spec.md §4.3). A model whose right-hand sides read the forcing set only where the derivative is identically zero (an ifelse condition, a piecewise-constant op) has an empty forcing list.

Source

Example (bands)

file = EarthSciAST.load_path(joinpath(FIXTURES, "bd_chem.esm"))
view = sysview(file, "Chem")
entries = jacobian_bands(view)
# One entry per (row variable, column variable) pair that occurs in the model.
@assert sort(unique([(en.u, en.v) for en in entries])) ==
    [("A", "A"), ("A", "B"), ("A", "C"), ("B", "A"), ("B", "B"), ("C", "B")]

From docs/api/examples/julia/jacobians.jl

Python

jacobian_bands(obj, model_name: str | None = None, wrt: str = 'states', forcing=None) -> list[JacEntry]

Differentiate a model’s right-hand side into a list of Jacobian bands.

Parameters

• obj — an EsmFile, a flattened system or a SysView .
• model_name — which model of an EsmFile; may be omitted when the file has exactly one.
• wrt — "states" (default), "parameters" (every parameter outside the forcing set, array-valued ones cell by cell), "forcing" (the cells of the forcing buffers, record axis included) or "time".
• forcing — the forcing set; None infers it (every array parameter with a data update, see forcing_names ).

Returns

One JacEntry per (row variable, column variable) pair that occurs in the model. The derivative is symbolic, so the result does not depend on the point where it is later evaluated.

On the "parameters" and "forcing" axes every column index must be closed at build time; an unclosed one raises BandError (spec §4.3). A model that reads the forcing set only where the derivative is identically zero (an ifelse condition, a piecewise-constant op) has an empty forcing list.

Source

Example (bands)

file = earthsci_ast.load_path(FIXTURES / "bd_chem.esm")
entries = earthsci_astdiff.jacobian_bands(file)
# One entry per (row variable, column variable) pair that occurs in the model.
assert sorted({(en.u, en.v) for en in entries}) == [
    ("A", "A"),
    ("A", "B"),
    ("A", "C"),
    ("B", "A"),
    ("B", "B"),
    ("C", "B"),
]
view = earthsci_astdiff.sysview(file)

From docs/api/examples/python/jacobians.py

Rust

pub fn jacobian_bands(file: &EsmFile, model_name: Option<&str>, wrt: Wrt) -> Result<Vec<JacEntry>, BandError>

Differentiate a model’s right-hand side into Jacobian bands with respect to wrt (states, parameters, forcing or time). model_name may be None when the file has exactly one model. The forcing set is inferred (see jacobian_bands_with_forcing to pass it explicitly).

One JacEntry is returned for each (row variable, column variable) pair that occurs in the model; the derivative is symbolic, so it does not depend on the point where it is later evaluated.

Source · Rust docs

Example (bands)

let file = load_path(fixture("bd_chem.esm"))?;
let entries = jacobian_bands(&file, None, Wrt::States)?;
// One entry per (row variable, column variable) pair that occurs in the model.
let mut pairs: Vec<(&str, &str)> =
    entries.iter().map(|en| (en.u.as_str(), en.v.as_str())).collect();
pairs.sort();
pairs.dedup();
assert_eq!(
    pairs,
    [("A", "A"), ("A", "B"), ("A", "C"), ("B", "A"), ("B", "B"), ("C", "B")]
);
let view = sysview(&file, None)?;

From docs/api/examples/rust/jacobians.rs