randCpn

Method of CPNTensor.

Static factory that builds a random CPNTensor for a multilinear state-space model.

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

Syntax

tensor = CPNTensor.randCpn(n, p, m, r)
tensor = CPNTensor.randCpn(n, p, m, r, boolean)
tensor = CPNTensor.randCpn(n, p, m, r, boolean, normtype)

Note the argument order n, p, m, r — the number of outputs p comes before the number of inputs m.

Description

randCpn draws a random multilinear model with n states, m inputs, p outputs and rank r, and returns it as a single CPNTensor. It is the tensor generator behind rmss, which wraps the result in an mss with the matching index vectors.

The state and output equations are given separate monomials. Two rank-r blocks are drawn — a state block F and an output block G, each with its own structure matrix — and laid side by side into the one tensor an mss carries:

Factor matrix	Size	Role
`F_U`	$(n+m)\times r$	structure of the state equation
`F_phi`	$n\times r$	parameter of the state equation
`G_U`	$(n+m)\times r$	structure of the output equation — its own monomials
`G_phi`	$p\times r$	parameter of the output equation

The four factor matrices stay internal; only the assembled tensor is returned:

$\texttt{structureMatrix} = [\,F_U \ \ G_U\,] \quad (n+m)\times 2r, \qquad \texttt{parameterMatrix} = \begin{bmatrix} F_\phi & 0 \\ 0 & G_\phi \end{bmatrix} \quad (n+p)\times 2r .$

State equations occupy structure/parameter columns 1..r and output equations columns r+1..2r. The tensor is built through the two-argument constructor CPNTensor(structureMatrix, parameterMatrix), so it is in the monomial base: structure entries equal to 1 become structureMatrixTrue, all other nonzeros structureMatrixContinuous, and there are no False factors.

F_U and F_phi carry exactly one nonzero per row (minimal sparsity, as many nonzeros as states), so the state monomials have degree $\sim(n+m)/r$ . The output block G_U is drawn at a fixed density of 0.2, so its monomials have degree $\sim0.2(n+m)$ — much higher — and it dominates the nonzero count of the tensor. The output block is deliberately given its own structure rather than reusing the state monomials; that keeps the model at full size for benchmarking rather than collapsing it to a smaller, tidier one.

Reproducibility

The draws follow the MTI 2.1 cpnTens.randCpn in the same order, so for a given rng seed the tensor reproduces the 2.1 model element for element. The order is load-bearing: removing or reordering any draw shifts the random stream and changes every matrix drawn after it.

Input arguments

Argument	Description
`n`	Number of states. Defaults to a positive random integer, `max(1, round(abs(10*randn)))`.
`p`	Number of outputs. Default `1`.
`m`	Number of inputs. Default `1`.
`r`	Rank of each equation block; the returned tensor has rank `2r`. Default `round(n + m/2)` — but `rmss` always supplies `r`, so this default never fires from there.
`boolean`	(default `false`) When `true`, the structure matrices are logical: every structural nonzero becomes the plain factor $v$ (a pure multilinear monomial) instead of the weighted factor $c\,v+(1-c)$ (a generic rank-1 multilinear function).
`normtype`	(default `'1'`) Normalization type of the structure matrices. `'1'` is the only value supported; it is validated but no normalization is actually performed.

Output arguments

Output	Description
`tensor`	`CPNTensor` of size $(n+m)$ signals $\times\ (n+p)$ equations, rank `2r`, in the monomial base.

Example

% 500 states, 1 output, 2 inputs, rank 10 per block (rank-20 tensor)
tensor = CPNTensor.randCpn(500, 1, 2, 10);

tensor.R          % 20
size(tensor)      % [2 ... 2  501]   -- 502 signal modes, 501 equations

For a full random model, use rmss:

sys = rmss(4, 1, 1, 6);   % n=4 states, m=1 input, p=1 output, r=6