CPNTensor

Norm-1 canonical-polyadic (CPN) tensor container for multilinear MTI models.

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

CPNTensor is the default mtiTensor used by mss and mdss models. It stores a multilinear model as a sum of rank-1 product terms in reduced norm-1 canonical-polyadic form, keeping the underlying matrices sparse.

Description

A CPNTensor stores the parameter tensor of a multilinear time-invariant (MTI) model in a sparse canonical polyadic normalized (CPN) representation. In CPN representation, the multilinear vector function $\mathbf{h}:\mathbb{R}^{n_v}\rightarrow\mathbb{R}^{N}$ of an MTI model with signals $\mathbf{v} = [v_1,\dots,v_{n_v}]^\top$ is evaluated as sums of products

$\mathbf{h}_j(\mathbf{v}) = \sum_{r=1}^{R} \Phi_{j,r}\prod_{i=1}^{n_v}\left(1-\lvert s_{i,r}\rvert\right)\left(1-bv_i\right) + s_{i,r}\,v_i, \quad j=1,\dots,N.$

The structure matrix $\mathbf{S}\in[-1,1]^{{n_v} \times R}$ selects which signals enter each product term. The parameter matrix $\mathbf{\Phi}\in\mathbb{R}^{n_x \times R}$ hold the weight of the terms; entry $\Phi_{j,r}$ is the coefficient of term $r$ in equation $j$ . The structure of the product term changes with the model base $b$ , more details in mss and here.

Internally CPNTensor never stores $\mathbf{S}$ and $\mathbf{\Phi}$ as single dense matrices. Each is split by value into three sparse components so that the common $\pm 1$ entries are held as logical masks:

Structure matrix ( $\mathbf{S}$ , rows = signals, columns = product terms)

Component	Meaning	Factor contributed
`structureMatrixTrue`	signal enters directly	$v_i$
`structureMatrixFalse`	signal enters complemented	$1 - v_i$
`structureMatrixContinuous`	complete product term	$\left(1-\lvert s_{i,r}\rvert\right)\left(1-bv_i\right) + s_{i,r}\,v_i$

Parameter matrix ( $\mathbf{\Phi}$ , rows = equations, columns = product terms)

Component	Meaning
`parameterMatrixOne`	coefficient $+1$
`parameterMatrixMinusOne`	coefficient $-1$
`parameterMatrixContinuous`	general weight

The three structure components must have disjoint support: every (row, column) entry is sourced from at most one of True / False / Continuous. This is checked at construction, which errors with the offending (row, column) positions if the supports overlap.

Construction

The most common form passes a single signed structure matrix and a single signed parameter matrix; CPNTensor splits each into its three components automatically. Structure entries equal to $1$ become structureMatrixTrue and all other entries go to structureMatrixContinuous; parameter entries equal to $+1$ and $-1$ become parameterMatrixOne / parameterMatrixMinusOne and the rest go to parameterMatrixContinuous.

Take the state equations of the Sprott B attractor $\dot x_1 = a\,x_2 x_3,\ \dot x_2 = x_1 - b\,x_2,\ \dot x_3 = c - x_1 x_2$ . With signals ordered $[\dot x_1,\dot x_2,\dot x_3,x_1,x_2,x_3]$ :

a = 0.4;  b = 1.2;  c = 1;

%                  xp1 xp2 xp3  x2x3  x1   x2  const x1x2
structureMatrix = [ 1   0   0    0    0    0    0    0 ;   % xp1
                    0   1   0    0    0    0    0    0 ;   % xp2
                    0   0   1    0    0    0    0    0 ;   % xp3
                    0   0   0    0    1    0    0    1 ;   % x1
                    0   0   0    1    0    1    0    1 ;   % x2
                    0   0   0    1    0    0    0    0 ];  % x3

parameterMatrix = [-1   0   0    a    0    0    0    0 ;   % eq1
                    0  -1   0    0    1   -b    0    0 ;   % eq2
                    0   0  -1    0    0    0    c   -1 ];  % eq3

T = CPNTensor(structureMatrix, parameterMatrix);
T.R    % tensor rank = number of monomial columns = 8

Syntax	Result
`T = CPNTensor()`	Empty tensor.
`T = CPNTensor(structureMatrix, parameterMatrix)`	Split both signed matrices into True/False/Continuous and One/MinusOne/Continuous components. Both arguments are required.
`T = CPNTensor(structureMatrixTrue, structureMatrixFalse, structureMatrixContinuous, parameterMatrixOne, parameterMatrixMinusOne, parameterMatrixContinuous)`	Set all six sparse components directly. All six arguments are required.
`T = CPNTensor(Name, Value, ...)`	Name–value form; give `structureMatrix`/`parameterMatrix` and/or the split component names.

The static factory methods fromRawMatrices and fromSparseComponents provide the same two construction routes with explicit name–value arguments.

Properties

Property	Description
`structureMatrixTrue`	Sparse logical mask of monomial factors $v_l$ .
`structureMatrixFalse`	Sparse logical mask of complemented factors $1-v_l$ .
`structureMatrixContinuous`	Sparse weights $s$ for general factors $\left(1-\lvert s_{i,r}\rvert\right)\left(1-bv_i\right) + s_{i,r}\,v_i$ .
`parameterMatrixOne`	Sparse logical mask of coefficient $+1$ .
`parameterMatrixMinusOne`	Sparse logical mask of coefficient $-1$ .
`parameterMatrixContinuous`	Sparse remaining coefficient values.
`R` (read-only)	Tensor rank = number of monomial columns of the structure matrix.

Methods

Method	Purpose
`fromRawMatrices`	Static factory from a signed structure and/or parameter matrix.
`fromSparseComponents`	Static factory from the six split components.
`trueFalseStructure`	Split a signed structure matrix into True/False/Continuous.
`trueFalseParameter`	Split a signed parameter matrix into One/MinusOne/Continuous.
`updateRank`	Refresh `R` from the current structure matrix.
`computeIncidenceMatrix`	Structural incidence of equations vs. signals.
`computeJacobian`	Jacobian of the equation system at an operating point.
`computeFunctionValue`	Evaluate the equation system at a point.
`sliceTensor`	Extract a subset of rows/monomials.

Additional background

Base: monomial vs literal

The model base is not stored in the CPNTensor — it is the mss property mtiBase (0 = monomial, 1 = literal) which is automatically accounted for when simulating with msim and is otherwise passed as a flag to the evaluation methods (e.g. computeFunctionValue and computeJacobian).

For mdss models, currently only monomial base is supported.

The True and False factors evaluate identical in both bases; only the continuous factor differs:

factor	monomial base (`mtiBase = 0`)	literal base (`mtiBase = 1`)
True	$v_i$	$v_i$
False	$1 - v_i$	$1 - v_i$
Continuous	$1 - \lvert s\rvert + s\,v_i$	$1 - \lvert s\rvert+(s+\lvert s\rvert-1)v_i$

So the same stored CPNTensor evaluates to different numbers depending on the base the model hands to the evaluation method. This is why the construction and storage methods on this page — fromRawMatrices, fromSparseComponents, trueFalseStructure, trueFalseParameter, updateRank — do not mention the base: they only split and hold the matrices and are base-independent. The base enters solely when the tensor is evaluated.