scatter_plan (function)

Stable function · Evaluate the Jacobian

Tier: stable · Kind: function · Topic: Evaluate the Jacobian

Julia	Python	Rust
`scatter_plan`	`scatter_plan`	not exported

Julia

scatter_plan(input, layout::StorageLayout; model_name)
scatter_plan(entries::Vector{JacEntry}, sv::SysView, layout::StorageLayout)

scatter_plan(input, layout::StorageLayout; model_name = nothing) -> ScatterPlan
scatter_plan(entries, sv::SysView, layout) -> ScatterPlan

Build the scatter plan of a model’s state Jacobian for layout. Throws an ArgumentError naming the reason when the layout does not fit the Jacobian (a stencil under LaneBlocks, a periodic wrap under ColumnBanded, …), and always for an empty band list on a model with array states — that is the silent all-zero Jacobian, never a valid plan.

Source

Example (evaluate)

# EarthSciASTDiff evaluates nothing: it emits ESM documents that EarthSciAST
# evaluates. The band fields J_k, as a derived model whose right-hand side,
# run once, leaves every band value in `du`. `fields[k]` names entry k's field.
doc, fields = evaluation_document(file)
@assert length(fields) == length(entries)
prob = EarthSciAST.esm_problem(
    JSON3.read(stable_json(doc)), (0.0, 1.0)
)
du = zero(prob.u0)
prob.f!(du, prob.u0, prob.p, 0.0)            # at the document's initial state
k = findfirst(en -> (en.u, en.v) == ("A", "A"), entries)
@assert du[prob.var_map["JacobianEval.$(fields[k])[1]"]] == -0.04   # -k1
# J·v as a derived model: inputs `_v_<C>`, outputs `_jvp_<R>`.
jdoc, (model, v, jvp) = jvp_document(file)
@assert model == "JvpEval"
J = jac_prototype(file)                      # sparse matrix on the fixed pattern
@assert size(J) == (12, 12) && nnz(J) == 24
# A scatter plan places the band fields in your own storage (here CSR),
# checked against the source before it is used.
bound = bind_plan(file, scatter_plan(file, Csr()))
@assert bound.len == 24
@assert all(1 <= k <= length(fields) for (k, _, _) in bound.pairs)

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

Python

scatter_plan(obj, layout: StorageLayout, model_name: str | None = None, entries: list[JacEntry] | None = None) -> ScatterPlan

Build the scatter plan of a model’s state Jacobian for layout.

obj is an EsmFile, a flattened system or a SysView ; entries (the reference’s scatter_plan(entries, sv, layout)) is a state band list to plan instead of the model’s own. Raises ValueError naming the reason when the layout does not fit the Jacobian (a stencil under LaneBlocks, a periodic wrap under ColumnBanded, …), and always for an empty band list on a model with array states — that is the silent all-zero Jacobian, never a valid plan.

Source

Rust

Rust does not export this function.