jacobian_bands

Stable function · Differentiate a model

Tier: stable · Kind: function · Topic: Differentiate a model

Julia	Python	Rust
`jacobian_bands`	`jacobian_bands`	`jacobian_bands`

Julia

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

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

Differentiate every differential equation of the system with respect to every state (wrt = :states) or every parameter (wrt = :parameters) 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).

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.

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') -> 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" or "time".

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.

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 or time). model_name may be None when the file has exactly one model.

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