jacobian_structure

Julia

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

jacobian_bands(file::EsmFile, model_name; wrt = :states, forcing = nothing, coefficients = true) -> Vector{JacEntry}
jacobian_bands(flat::FlattenedSystem;    wrt = :states, forcing = nothing, coefficients = true) -> Vector{JacEntry}
jacobian_bands(sv::SysView;              wrt = :states, forcing = nothing, coefficients = true) -> 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.

coefficients = false returns STRUCTURE-ONLY entries (esm-jacobian-spec.md §2.1): regions are clipped and sites found as in the full mode, but no derivative is taken, no coefficient simplified, and bands merge on (ridx, cidx, contracted, guard) alone. Every band.coef is nothing. Their points include the full mode’s, and equal them unless the full mode drops a band whose coefficient simplifies to zero. Use them where only the pattern is needed (jacobian_pattern , detect_structure ); a document or product needs the full mode.

Source

Python

jacobian_bands(obj, model_name: str | None = None, wrt: str = 'states', forcing=None, coefficients: bool = True) -> 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 ).
• coefficients — False returns structure-only entries (spec §2.1): regions are clipped and sites found as in the full mode, but no derivative is taken, no coefficient simplified, and bands merge on (ridx, cidx, contracted, guard) alone. Every band.coef is None. Their points include the full mode’s, and equal them unless a full band’s coefficient simplifies to zero. Through an active recurrence (§4.5) the pass runs in full and the coefficients are dropped.

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

Rust

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

jacobian_structure_view of a model of file (model_name may be None when the file has exactly one), its forcing set inferred.

Source · Rust docs