jacobian

Method of CPNTensor.

Consolidated entry point for any Jacobian sub-block of a CPN tensor.

Source: src/tensor/@CPNTensor/jacobian.m

Syntax

J = obj.jacobian(v, mtiBase)
J = obj.jacobian(v, mtiBase, equationIndex = E)
J = obj.jacobian(v, mtiBase, equationIndex = E, variableIndex = V, columnIndex = C)

Description

jacobian evaluates a rectangular sub-block of the Jacobian of the multilinear function stored in the tensor, at the operating point v. The three name-value arguments select the block:

Argument	Selects
`equationIndex`	rows — which equations
`variableIndex`	columns — which signals to differentiate with respect to
`columnIndex`	rank-1 terms to evaluate (an optimisation, normally left to the default)

The returned block has size numel(equationIndex)-by-numel(variableIndex). With no name-value arguments the full Jacobian is returned, and the call is equivalent to computeJacobian.

This is the tensor-level Jacobian used by both mss and mdss. Evaluating only the requested equations makes it substantially cheaper than forming the whole Jacobian when a sub-block is all that is needed — which is the common case in linearization, tearing and BLT ordering.

How the block is formed

The method is built entirely on the approved computeJacobian kernel, in three steps:

sliceTensor folds the equation and column selection into a reusable sub-tensor.
computeJacobian runs the math on that slice.
variableIndex is applied afterwards, as a slice of the result columns.

Step 3 is a post-slice, not an emit-set: the columns are computed and then discarded, so variableIndex narrows the result but does not save work. An emit-set optimisation would require a subset-aware kernel; this method deliberately reuses computeJacobian unchanged so that no bespoke math is involved. Worth revisiting once a subset-aware kernel is approved.

Because columnIndex defaults to the terms the selected equations actually use, restricting equationIndex alone already avoids evaluating unrelated rank-1 terms.

This operates on the raw decomposed matrices and is not the base-aware model level: the caller supplies mtiBase, and v is in structure-matrix row order.

Note. mtiBase is a required positional argument, validated as (1,1) logical. The syntax lines in the source header omit it; a two-argument call fails with MATLAB:minrhs.

Input arguments

Argument	Description
`obj`	`CPNTensor` to differentiate.
`v`	Operating point, one entry per structure-matrix row.
`mtiBase`	`false` monomial base, `true` literal base. Required.
`equationIndex`	(name–value, default `[]`) Equation rows to include. Empty means all.
`variableIndex`	(name–value, default `[]`) Signal columns to keep. Empty means all.
`columnIndex`	(name–value, default `[]`) Rank-1 terms to evaluate. Empty means those the selected equations use.

Output arguments

Output	Description
`J`	Jacobian block, `numel(equationIndex)`-by-`numel(variableIndex)`.

Example

%      x1  x2  x1x2
S = [   1   0    1     % x1
        0   1    1 ];  % x2
P = [ -10  10    0     % dx1 = -10*x1 + 10*x2
        0   0    1 ];  % dx2 = x1*x2

T = CPNTensor(S,P);
v = [0.3; 0.7];

full(T.jacobian(v, false))                                   % [-10 10 ; 0.7 0.3]
full(T.jacobian(v, false, equationIndex = 2, ...
                          variableIndex = 1))                % 0.7  = d(x1*x2)/dx1