playbook/skills/tsl-api-reference/references/codegen/builtin/matrix.md

Builtin - 矩阵

矩阵运算

eye(size[, cols])

声明：function

创建单位矩阵。传入一个参数时创建 size x size 矩阵；传入两个相同的尺寸参数时结果相同

参数	类型	说明
size	integer	矩阵的行数和列数
cols	integer	可选。列数，省略时使用 size

返回：array

示例

范例01：创建三阶单位矩阵

value := eye(3);
echo mRows(value), ",", mCols(value), ",", value[0, 0], ",", value[0, 1];
// 输出：3,3,1,0

范例02：使用两个尺寸参数创建单位矩阵

value := eye(3, 3);
echo mRows(value), ",", mCols(value), ",", value[2, 2];
// 输出：3,3,1

mCols(matrix, ret_values)

声明：function

返回矩阵的列数或列下标

参数	类型	说明
matrix	array|fmarray	要读取列信息的矩阵
ret_values	boolean	可选。false 返回列数，true 返回列下标，默认 false

返回：integer|array

示例

范例01：返回 FMArray 的列数

value := fmarray[[1, 2], [3, 4], [5, 6]];
echo mCols(value);
// 输出：2

范例02：返回 FMArray 的列下标

value := fmarray[[1, 2], [3, 4], [5, 6]];
echo trim(toStn(mCols(value, 1)));
// 输出：array(0,1)

mFind(matrix, exp, ret_values, replace_value)

声明：function

查找矩阵中符合条件的元素，并可返回元素值或替换原矩阵中的匹配项

参数	类型	说明
matrix	array|fmarray	要查找的矩阵
exp	expression	可选。匹配条件，省略时查找值为真的元素
ret_values	boolean	可选。是否在位置结果后附加元素值，默认 false
replace_value	any	可选。用于替换匹配元素的值

返回：array

示例

范例01：查找一维数组中值为真的元素位置

value := array(0, 2, 0, 4);
echo trim(toStn(mFind(value)));
// 输出：array(1,3)

范例02：返回匹配元素的位置和值

value := array((1, 2), (3, 4));
result := mFind(value, mCell > 3, true);
echo result[0][0], ",", result[0][1], ",", result[0][2];
// 输出：1,1,4

mFindSparse(matrix, exp, ret_values, replace_value)

声明：function

深度遍历数组并查找或替换符合条件的元素

参数	类型	说明
matrix	array|fmarray	要查找的矩阵
exp	expression	可选。匹配条件，省略时查找值为真的元素
ret_values	boolean	可选。是否在位置结果后附加元素值，默认 false
replace_value	any	可选。用于替换匹配元素的值

返回：array

示例

范例01：查找嵌套数组中的元素

value := array(1, array(0, 2), 0);
result := mFindSparse(value, mCell = 2, true);
echo result[0][0], ",", result[0][1], ",", result[0][2];
// 输出：1,1,2

mInit(shape, init_value)

声明：function

按尺寸数组创建各单元格值相同的 FMArray

参数	类型	说明
shape	array	各维度长度组成的数组
init_value	integer|int64|double	填充值，值类型决定单元格类型

返回：fmarray

示例

范例01：通过尺寸数组创建二维 FMArray

value := mInit(array(2, 3), 1);
echo mRows(value), "\n", mCols(value), "\n", value[1, 2];
// 输出：
// 2
// 3
// 1

mInit(dimension, ..., init_value)

声明：function

按依次给出的维度长度创建各单元格值相同的 FMArray

参数	类型	说明
dimension	integer	第一维长度
...	integer	其余维度长度
init_value	integer|int64|double	填充值，值类型决定单元格类型

返回：fmarray

示例

范例01：通过维度参数创建三维 FMArray

value := mInit(2, 3, 4, 1.5);
echo mRows(value), "\n", mCols(value), "\n", value[1, 2, 3];
// 输出：
// 2
// 3
// 1.5

mInitDiag(shape, init_value)

声明：function

按尺寸数组创建对角元素值相同的 FMArray

参数	类型	说明
shape	array	各维度长度组成的数组
init_value	integer|int64|double	对角元素填充值，值类型决定单元格类型

返回：fmarray

示例

范例01：通过尺寸数组创建二维对角 FMArray

value := mInitDiag(array(3, 3), 2);
echo value[0, 0], "\n", value[0, 1], "\n", value[2, 2];
// 输出：
// 2
// 0
// 2

mInitDiag(dimension, ..., init_value)

声明：function

按依次给出的维度长度创建对角元素值相同的 FMArray

参数	类型	说明
dimension	integer	第一维长度
...	integer	其余维度长度
init_value	integer|int64|double	对角元素填充值，值类型决定单元格类型

返回：fmarray

示例

范例01：通过维度参数创建三维对角 FMArray

value := mInitDiag(2, 3, 4, 2);
echo value[1, 1, 1], "\n", value[1, 2, 1];
// 输出：
// 2
// 0

mRand(shape, random_info)

声明：function

按尺寸数组创建随机数 FMArray

参数	类型	说明
shape	array	各维度长度组成的数组
random_info	array	可选。随机数分布及其参数，省略时生成 0 到 1 之间的随机数

返回：fmarray

示例

范例01：通过尺寸数组创建随机数 FMArray

value := mRand(array(2, 3));
echo dataType(value), "\n", mRows(value), "\n", mCols(value);
// 输出：
// 27
// 2
// 3

mRand(dimension, ..., random_info)

声明：function

按依次给出的维度长度创建随机数 FMArray

参数	类型	说明
dimension	integer	第一维长度
...	integer	其余维度长度
random_info	array	可选。随机数分布及其参数，省略时生成 0 到 1 之间的随机数

返回：fmarray

示例

范例01：创建服从标准正态分布的二维 FMArray

value := mRand(2, 3, array("normal", 0, 1));
echo dataType(value), "\n", mRows(value), "\n", mCols(value);
// 输出：
// 27
// 2
// 3

mRows(matrix, ret_values)

声明：function

返回矩阵的行数或行下标

参数	类型	说明
matrix	array|fmarray	要读取行信息的矩阵
ret_values	boolean	可选。false 返回行数，true 返回行下标，默认 false

返回：integer|array

示例

范例01：返回 FMArray 的行数

value := fmarray[[1, 2], [3, 4], [5, 6]];
echo mRows(value);
// 输出：3

范例02：返回 FMArray 的行下标

value := fmarray[[1, 2], [3, 4], [5, 6]];
echo trim(toStn(mRows(value, 1)));
// 输出：array(0,1,2)

mSize(matrix, ret_values)

声明：function

返回矩阵各维度的长度或下标

参数	类型	说明
matrix	array|fmarray	要读取尺寸信息的矩阵
ret_values	boolean	可选。false 返回各维度长度，true 返回各维度下标，默认 false

返回：array

示例

范例01：返回三维 FMArray 的各维度长度

value := fmarray[
    [[1, 2], [3, 4]],
    [[5, 6], [7, 8]],
    [[9, 10], [11, 12]]
];
echo trim(toStn(mSize(value)));
// 输出：array(3,2,2)

范例02：返回三维 FMArray 的各维度下标

value := fmarray[
    [[1, 2], [3, 4]],
    [[5, 6], [7, 8]],
    [[9, 10], [11, 12]]
];
indexes := mSize(value, 1);
echo trim(toStn(indexes[0])), "\n";
echo trim(toStn(indexes[1])), "\n";
echo trim(toStn(indexes[2]));
// 输出：
// array(0,1,2)
// array(0,1)
// array(0,1)

mSwap(fm, first_dimension, second_dimension)

声明：function

交换多维 FMArray 的两个维度

参数	类型	说明
fm	fmarray	要转置的多维 FMArray
first_dimension	integer	第一个维度下标
second_dimension	integer	第二个维度下标

返回：fmarray

示例

范例01：交换二维 FMArray 的行列维度

value := fmarray[[1, 2], [3, 4], [5, 6]];
swapped := mSwap(value, 0, 1);
echo mRows(swapped), "\n", mCols(swapped), "\n", swapped[1, 2];
// 输出：
// 2
// 3
// 6

mt_Addition(a, b, c)

声明：function

求N×M阶矩阵A与N×M阶矩阵B的和矩阵，即C=A+B

参数	类型	说明
a	array	实型二维数组，体积为N×M。被加矩阵
b	array	实型二维数组，体积为N×M。加矩阵
c	array	实型二维数组，体积为N×M。返回的结果矩阵

返回：integer

示例

a := array((3.0, -3.0), (5.0, -5.0));
b := array((-2.0, 4.0), (1.0, 8.0));
c := nil;
status := mt_Addition(a, b, c);
writeLn(status);
writeLn(toStn(c[0][0]), ",", toStn(c[0][1]));
writeLn(toStn(c[1][0]), ",", toStn(c[1][1]));
// 输出：
// 0
// 1.0,1.0
// 6.0,3.0

mt_decompose_chol(a, ra, flag)

声明：function

cholesky分解基础函数;如果不担心效率可以使用公用函数chol

参数	类型	说明
a	array	待分解的方正矩阵(二维数字数组,行列数相同)
ra	array	分解结果返回
flag	bool	object

返回：integer

示例

a := array((4.0, 0.0), (0.0, 9.0));
factor := nil;
flag := nil;
status := mt_decompose_chol(a, factor, flag);
writeLn(status);
writeLn(toStn(factor[0][0]), ",", toStn(factor[0][1]));
writeLn(toStn(factor[1][0]), ",", toStn(factor[1][1]));
// 输出：
// 0
// 2.0,0.0
// 0.0,3.0

mt_decompose_eig(a, wr, wi, vr)

声明：function

计算特征值及特征向量

参数	类型	说明
a	array	需要被计算的n*m矩阵
wr	array	变参返回A的特征值的实部，一维数组
wi	array	变参返回A的特征值的虚部，一维数组
vr	array	变参返回A的特征向量，二维数组

返回：integer

示例

a := array((2.0, 0.0), (0.0, 3.0));
real_values := nil;
imag_values := nil;
vectors := nil;
status := mt_decompose_eig(a, real_values, imag_values, vectors);
writeLn(status);
writeLn(toStn(real_values[0]), ",", toStn(real_values[1]));
writeLn(toStn(imag_values[0]), ",", toStn(imag_values[1]));
writeLn(toStn(vectors[0][0]), ",", toStn(vectors[0][1]));
writeLn(toStn(vectors[1][0]), ",", toStn(vectors[1][1]));
// 输出：
// 0
// 2.0,3.0
// 0.0,0.0
// 1.0,0.0
// 0.0,1.0

mt_decompose_ldl(a, ra, p)

声明：function

ldl 分解基础函数,如果a正定L*D*`L=A;

参数	类型	说明
a	array	待分解的方正矩阵(二维数字数组,行列数相同)
ra	array	分解结果返回,包括,三角矩阵,对角矩阵
p	array	分解结果的行列信息.a如果为正定矩阵那么p为1到length(a)递增序列.此时,ra的下三角为 L矩阵,对角元为D矩阵.当p为非递增序列,时表示行列置换信息.如果p[i]=k>0 and k<> i+1,那么a的i行和k-1行互换,i列与k-1列互换,p[i]=k<0 那么d在此处为2*2的块,在ra的i-1,i行列的4个元,a的第i行和k-1行互换,i列和k-1列互换.

返回：integer

示例

a := array((4.0, 2.0), (2.0, 3.0));
factor := nil;
permutation := nil;
status := mt_decompose_ldl(a, factor, permutation);
writeLn(status);
writeLn(toStn(factor[0][0]), ",", toStn(factor[0][1]));
writeLn(toStn(factor[1][0]), ",", toStn(factor[1][1]));
writeLn(permutation[0], ",", permutation[1]);
// 输出：
// 0
// 4.0,2.0
// 0.5,2.0
// 1,2

Mt_decompose_lu(h, l, u)

声明：function

进行lu分解，H方阵，则可以得到下三角阵L，上三角矩阵U

参数	类型	说明
h	array	需要被分解的对称矩阵
l	array	下三角阵
u	array	上三角阵

返回：integer

示例

a := array((4.0, 3.0), (6.0, 3.0));
lower := nil;
upper := nil;
status := Mt_decompose_lu(a, lower, upper);
writeLn(status);
writeLn(toStn(lower[0][0]), ",", toStn(lower[0][1]));
writeLn(toStn(lower[1][0]), ",", toStn(lower[1][1]));
writeLn(toStn(upper[0][0]), ",", toStn(upper[0][1]));
writeLn(toStn(upper[1][0]), ",", toStn(upper[1][1]));
// 输出：
// 0
// 1.0,0.0
// 1.5,1.0
// 4.0,3.0
// 0.0,-1.5

mt_decompose_qr(m, q, r, e, qr_type)

声明：function

E缺省的时候，对矩阵进行QR分解,M=Q :*R，不缺省E的时候对矩阵进行QRe分解，M:*e=Q:*R.该分解使得R矩阵的对角元按绝对值从大倒小排列

参数	类型	说明
m	array	待分解矩阵
q	array	可选。变参返回正交矩阵Q
r	array	可选。变参返回上三角矩阵R
e	array	可选。变参返回列置换矩阵E，默认E的结构是一个方阵，当有qr_Type参数时，0:E方阵，1:E为1维数组，2:忽略E参数
qr_type	any	可选。整数，为0,1,2之一，用于设定E参数的行为

返回：integer

示例

a := array((1.0, 0.0), (0.0, 1.0));
q := nil;
r := nil;
e := nil;
status := mt_decompose_qr(a, q, r, e, 0);
writeLn(status);
writeLn(toStn(q[0][0]), ",", toStn(q[0][1]), ",", toStn(q[1][0]), ",", toStn(q[1][1]));
writeLn(toStn(r[0][0]), ",", toStn(r[0][1]), ",", toStn(r[1][0]), ",", toStn(r[1][1]));
writeLn(toStn(e[0][0]), ",", toStn(e[0][1]), ",", toStn(e[1][0]), ",", toStn(e[1][1]));
// 输出：
// 0
// 1.0,0.0,0.0,1.0
// 1.0,0.0,0.0,1.0
// 1.0,0.0,0.0,1.0

mt_decompose_svd(a, u, s, d)

声明：function

矩阵的奇异值(SVD)分解

参数	类型	说明
a	array	待分解的m*n矩阵
u	array	变参返回A的左奇异向量矩阵，二维数组
s	array	变参返回A的奇异值，一维数组
d	array	变参返回A的右奇异向量矩阵，二维数组

返回：integer

示例

a := array((3.0, 0.0), (0.0, 2.0));
left := nil;
singular_values := nil;
right := nil;
status := mt_decompose_svd(a, left, singular_values, right);
writeLn(status);
writeLn(toStn(left[0][0]), ",", toStn(left[0][1]), ",", toStn(left[1][0]), ",", toStn(left[1][1]));
writeLn(toStn(singular_values[0]), ",", toStn(singular_values[1]));
writeLn(toStn(right[0][0]), ",", toStn(right[0][1]), ",", toStn(right[1][0]), ",", toStn(right[1][1]));
// 输出：
// 0
// 1.0,0.0,0.0,1.0
// 3.0,2.0
// 1.0,0.0,0.0,1.0

mt_iv_Gauss_Jordan(a, x)

声明：function

用高斯-约当(Gauss-Jordan)法求解n阶方阵A的逆矩阵

参数	类型	说明
a	array	实型二维数组，体积为N×N。原矩阵
x	array	实型二维数组，体积为N×N。返回的逆矩阵

返回：integer

示例

a := array((4.0, 7.0), (2.0, 6.0));
inverse := nil;
status := mt_iv_Gauss_Jordan(a, inverse);
writeLn(status);
writeLn(toStn(inverse[0][0]), ",", toStn(inverse[0][1]));
writeLn(toStn(inverse[1][0]), ",", toStn(inverse[1][1]));
// 输出：
// 0
// 0.6,-0.7
// -0.2,0.4

mt_iv_Ldl(a, x)

声明：function

求n阶对称正定矩阵A的逆矩阵

参数	类型	说明
a	array	实型二维数组，体积为N×N。原矩阵，必须为一个对称矩阵
x	array	实型二维数组，体积为N×N。返回的逆矩阵

返回：integer

示例

a := array((4.0, 2.0), (2.0, 3.0));
inverse := nil;
status := mt_iv_Ldl(a, inverse);
writeLn(status);
writeLn(toStn(inverse[0][0]), ",", toStn(inverse[0][1]));
writeLn(toStn(inverse[1][0]), ",", toStn(inverse[1][1]));
// 输出：
// 0
// 0.375,-0.25
// -0.25,0.5

mt_Multiplication(a, b, c)

声明：function

求N×M阶矩阵A与M×L阶矩阵B的乘积矩阵，即C=A×B

参数	类型	说明
a	array	实型二维数组，体积为N×M。被乘矩阵
b	array	实型二维数组，体积为M×L。乘矩阵
c	array	实型二维数组，体积为N×L。返回的结果矩阵

返回：integer

示例

a := array((1.0, 2.0, 3.0, 4.0), (5.0, 6.0, 7.0, 8.0));
b := array((3.0, -3.0), (-2.0, 4.0), (1.0, 8.0), (-1.0, -3.0));
c := nil;
status := mt_Multiplication(a, b, c);
writeLn(status);
writeLn(toStn(c[0][0]), ",", toStn(c[0][1]));
writeLn(toStn(c[1][0]), ",", toStn(c[1][1]));
// 输出：
// 0
// -2.0,17.0
// 2.0,41.0

mt_Subtraction(a, b, c)

声明：function

求N×M阶矩阵A与N×M阶矩阵B的差矩阵，即C=A-B

参数	类型	说明
a	array	实型二维数组，体积为N×M。被减矩阵
b	array	实型二维数组，体积为N×M。减矩阵
c	array	实型二维数组，体积为N×M。返回的结果矩阵

返回：integer

示例

a := array((3.0, -3.0), (5.0, -5.0));
b := array((-2.0, 4.0), (1.0, 8.0));
c := nil;
status := mt_Subtraction(a, b, c);
writeLn(status);
writeLn(toStn(c[0][0]), ",", toStn(c[0][1]));
writeLn(toStn(c[1][0]), ",", toStn(c[1][1]));
// 输出：
// 0
// 5.0,-7.0
// 4.0,-13.0

mt_Transposition(a, c)

声明：function

求m×n阶矩阵A的转置矩阵，即C=

参数	类型	说明
a	array	实型二维数组，体积为N×M。转置前矩阵
c	array	实型二维数组，体积为M×N。返回转置后的结果矩阵

返回：integer

示例

a := array((3.0, -3.0, 11.0), (5.0, -5.0, 8.0));
transposed := nil;
status := mt_Transposition(a, transposed);
writeLn(status);
writeLn(toStn(transposed[0][0]), ",", toStn(transposed[0][1]));
writeLn(toStn(transposed[1][0]), ",", toStn(transposed[1][1]));
writeLn(toStn(transposed[2][0]), ",", toStn(transposed[2][1]));
// 输出：
// 0
// 3.0,5.0
// -3.0,-5.0
// 11.0,8.0

mt_va_Cholesky(a, v)

声明：function

求对称正定矩阵的行列式值平方根

参数	类型	说明
a	array	实型二维数组，体积为N×N。原矩阵，必须为一个对称矩阵
v	float	实型数。返回矩阵行列式值的平方根

返回：integer

示例

a := array((4.0, 0.0), (0.0, 9.0));
root_determinant := nil;
status := mt_va_Cholesky(a, root_determinant);
writeLn(status);
writeLn(toStn(root_determinant));
// 输出：
// 0
// 6.0

mt_va_Gauss_Jordan(a, v)

声明：function

用高斯-约当(Gauss-Jordan)法求解n阶方阵A的行列式值

参数	类型	说明
a	array	实型二维数组，体积为N×N。
v	float	实型数。返回的行列式值

返回：integer

示例

a := array((3.0, 1.0), (5.0, 2.0));
determinant := nil;
status := mt_va_Gauss_Jordan(a, determinant);
writeLn(status);
writeLn(toStn(determinant));
// 输出：
// 0
// 1.0

nils(size_or_rows[, cols_or_fields])

声明：function

创建元素为 nil 的一维或二维数组。传入一个参数时创建一维数组；传入两个参数时创建二维数组。第二个参数可以是列数或列名数组

参数	类型	说明
size_or_rows	integer|array	一维长度、二维行数或行标数组
cols_or_fields	integer|array	可选。二维列数或列名数组，省略时创建一维数组

返回：array

示例

范例01：创建一维空值数组

value := nils(3);
echo length(value), ",", value[2] = nil;
// 输出：3,1

范例02：创建二维空值数组

value := nils(2, 3);
echo mRows(value), ",", mCols(value), ",", value[1, 2] = nil;
// 输出：2,3,1

ones(size_or_rows[, cols_or_fields])

声明：function

创建元素为 1 的一维或二维数组。传入一个参数时创建一维数组；传入两个参数时创建二维数组。第二个参数可以是列数或列名数组

参数	类型	说明
size_or_rows	integer|array	一维长度、二维行数或行标数组
cols_or_fields	integer|array	可选。二维列数或列名数组，省略时创建一维数组

返回：array

示例

范例01：创建一维全一数组

value := ones(3);
echo length(value), ",", value[2];
// 输出：3,1

范例02：创建二维全一数组

value := ones(2, 3);
echo mRows(value), ",", mCols(value), ",", value[1, 2];
// 输出：2,3,1

rand(size_or_rows[, cols_or_fields])

声明：function

创建元素为随机数的一维或二维数组。传入一个参数时创建一维数组；传入两个参数时创建二维数组。随机数默认位于 0 到 1 之间。第二个参数可以是列数或列名数组

参数	类型	说明
size_or_rows	integer|array	一维长度、二维行数或行标数组
cols_or_fields	integer|array	可选。二维列数或列名数组，省略时创建一维数组

返回：array

示例

范例01：创建二维随机数组并检查取值范围

value := rand(2, 3);
echo mRows(value), ",", mCols(value), ",", value[0, 0] >= 0, ",", value[0, 0] <= 1;
// 输出：2,3,1,1

zeros(size_or_rows[, cols_or_fields])

声明：function

创建元素为 0 的一维或二维数组。传入一个参数时创建一维数组；传入两个参数时创建二维数组。第二个参数可以是列数或列名数组；第一个参数也可以使用行标数组

参数	类型	说明
size_or_rows	integer|array	一维长度、二维行数或行标数组
cols_or_fields	integer|array	可选。二维列数或列名数组，省略时创建一维数组

返回：array

示例

范例01：创建一维全零数组

value := zeros(3);
echo length(value), ",", value[2];
// 输出：3,0

范例02：创建二维全零数组

value := zeros(2, 3);
echo mRows(value), ",", mCols(value), ",", value[1, 2];
// 输出：2,3,0

范例03：使用行标和列名创建数据表数组

value := zeros(array("L1", "L2"), array("F1", "F2"));
echo value["L1"]["F1"];
// 输出：0