Api Documantation¶

`random_matrix`	Generate a random square matrix n x n.
`random_orthogonal_matrix`	Generate a random orthogonal matrix n x n.
`random_unitary_matrix`	Generate a random unitary matrix n x n.

sympy_matrices_random.random_matrix(dim, *, spec=None, scalars=None, units=None, triangular=False, rank=None, k=None)¶

Generate a random square matrix n x n.

Such matrix \(\mathbf{S}\) may be of a given rank and may be an upper triangular matrix.

It is constructed as a product of k random elementary matrices with with scalars arguments for defining row-addtion operations and units arguments for row-multiplcation operations.

Eigenvalues may provided as spec argument. In order to specify not only eigenvalues but a random Jordan matrix \(\mathbf{J}\) provide a list of (size, value) pairs to define Jordan blocks.

Then the matrix is constructed as a product \(\mathbf{S^{-1} \cdot J \cdot S}\) of an invertible matrix \(\mathbf{S}\) as the product elementary matrices and a Jordan matrix \(\mathbf{J}\).

If spec is None (default) only \(\mathbf{S}\) will be returned. If k is \(0\) only \(\mathbf{J}\) will be returned.

Parameters¶

dimint: Dimension of the matrix.
speciterable, optional: Set of values for eigenvalues. Can be a list of eigenvalues or tuples of (size, value) for Jordan blocks. Default is None.
scalarsiterable, optional: Values used to build the transformation matrix \(\mathbf{S}\). Defaults to \(\{1, -1\}\).
unitsiterable, optional: Unit values used to build the transformation matrix \(\mathbf{S}\). Defaults to \(\{1, -1\}\).
triangularbool, optional: If True, an upper triangular matrix is returned. Default is False.
rankint, optional: Rank of the matrix. Defaults to full rank.
kint, optional: Number of elementary matrices used to build \(\mathbf{S}\). Defaults to 2 * dim

Returns¶

sympy.Matrix: The generated random matrix.

Examples¶

>>> from sympy_matrices_random import random_matrix

Generate a 3x3 random matrix

>>> random_matrix(3)
Matrix([
[1,  1,  1],
[0,  0, -1],
[0, -1, -1]])

The argument k gives some control of complexity

>>> m = random_matrix(3, k=42)
>>> m
Matrix([
[0, -4,  1],
[1, -8,  3],
[0,  3, -1]])

By default the result has full rank and integer values. And so has the inverse, too.

>>> m.inv()
Matrix([
[ 1, 1,  4],
[-1, 0, -1],
[-3, 0, -4]])

One can specify the rank of the resulting matrix. This is particularly useful for testing algorithms that handle singular matrices.

>>> m = random_matrix(4, rank=2)
>>> m.rank()
2

The spec argument allows to define the eigenvalues of the matrix. As simple list of eigenvalues will define \(\mathbf{J}\) as a diagonal matrix with random values drawn from this list.

To promote larger Jordan blocks repeat the eigenvalue or specify the size of these blocks for each eigenvalue as tuples (size, value).

>>> m = random_matrix(4, spec=(1, 1, 3))
>>> m
Matrix([
[-1,  2,  0, 0],
[-4,  5,  0, 0],
[-1,  1,  2, 1],
[ 3, -3, -1, 0]])

>>> m.eigenvals(multiple=True)
[1, 3, 1, 1]

>>> m.jordan_form(calc_transform=False)
Matrix([
[1, 1, 0, 0],
[0, 1, 0, 0],
[0, 0, 1, 0],
[0, 0, 0, 3]])

If you set k=0, the function skips the transformation matrix \(\mathbf{S}\) and returns the Jordan matrix \(\mathbf{J}\) directly. This is excellent for creating symbolic templates of matrices.

You can use SymPy symbols to create matrices with symbolic entries.

>>> from sympy import symbols
>>> a, b, u, v = symbols('a b u v')

>>> random_matrix(4, spec=[(2, u), (2, v)], k=0)
Matrix([
[u, 1, 0, 0],
[0, u, 0, 0],
[0, 0, v, 1],
[0, 0, 0, v]])

In general matrix entries of \(\mathbf{S}\) are sums and products of scalars and units.

>>> m = random_matrix(3, scalars=(a, b), units=(u,))
>>> m
Matrix([
[             u, 0,      0],
[a*b*u**3 + a*u, 1, b*u**2],
[        a*u**3, 0,   u**2]])

In contrast, the inverse \(\mathbf{S^{-1}}\) consists of sums and products of scalars and units as well as fractions of units.

>>> m.inv()
Matrix([
[1/u, 0,       0],
[ -a, 1,      -b],
[ -a, 0, u**(-2)]])

sympy_matrices_random.random_orthogonal_matrix(dim, *, spec=None, angles=None, k=None)¶

Generate a random orthogonal matrix n x n.

An orthogonal matrix \(\mathbf{O}\) is a real matrix such that \(\mathbf{O}^{t} = \mathbf{O}^{-1}\). It describes an isometry in n dimensional Euclidian space.

Build as a product of \(2 \times 2\) rotations, known as Givens rotations, with rotation angles values drawn randomly from angles. The number of these rotations is given by k.

If spec is given, it should contain a list of real valued angles to be drawn from. These define the the isometry normal form as a diagonal block matrix \(\mathbf{D}\) with \(2 \times 2\) rotation blocks.

Then the resulting isometry matrix will be the conjugate product \(\mathbf{O}^{-1} \cdot \mathbf{D} \cdot \mathbf{O}\).

If spec is None (default) only \(\mathbf{O}\) will be returned. If k is \(0\) only \(\mathbf{D}\) will be returned.

Parameters¶

dimint: Dimension of the matrix.
speciterable, optional: Set of angles to build the isometry normal form. Default is None.
anglesiterable, optional: Rotation angles to sample from. Defaults to fractions \(\{\pi n/2 \mid n=1 \dots 4 \}\).
kint, optional: Number of rotations to build the matrix. Defaults to 2 * dim.

Returns¶

sympy.Matrix: The generated random orthogonal matrix.

Examples¶

>>> from sympy import expand, pi, sin, symbols
>>> from sympy.abc import phi, psi
>>> from sympy_matrices_random import random_orthogonal_matrix

Generate a 3x3 random orthogonal matrix.

>>> q = random_orthogonal_matrix(3)
>>> q
Matrix([
[             1/2, sqrt(2)/2,              1/2],
[-1/2 + sqrt(2)/4,      -1/2,  sqrt(2)/4 + 1/2],
[ sqrt(2)/4 + 1/2,      -1/2, -1/2 + sqrt(2)/4]])

>>> expand(q.T * q)
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

Controlling the Rotations. To control how many elementary Givens rotations are multiplied to form the random orthogonal matrix, use the k argument. Larger k yields a matrix that is “more random”. The default is 2*dim.

>>> Q = random_orthogonal_matrix(3, k=20)  # more rotations than the default 8
>>> expand(Q)
Matrix([
[sqrt(2)/2,          0, sqrt(2)/2],
[     -1/2,  sqrt(2)/2,       1/2],
[     -1/2, -sqrt(2)/2,       1/2]])

The angles argument serves as the set of angles from which the elementary Givens rotations are sampled.

>>> angles = pi/3, pi*2/3  # 60°, 120°
>>> random_orthogonal_matrix(3, angles=angles, k=1)
Matrix([
[       1/2, 0, sqrt(3)/2],
[         0, 1,         0],
[-sqrt(3)/2, 0,       1/2]])

Even as symbols

>>> random_orthogonal_matrix(3, angles=(phi, psi), k=2)
Matrix([
[ cos(psi), sin(phi)*sin(psi), sin(psi)*cos(phi)],
[        0,          cos(phi),         -sin(phi)],
[-sin(psi), sin(phi)*cos(psi), cos(phi)*cos(psi)]])

The function takes a list of rotation angles as spec argument. It constructs a block-diagonal matrix from random \(2\times2\) rotation blocks (plus an optional \(1\times1\) block for odd dimensions) defining the rotation normal form.

Such specific rotation angles can be floating point values

>>> Q = random_orthogonal_matrix(4, spec=angles, k=0)
>>> expand(Q)
Matrix([
[       1/2, sqrt(3)/2,          0,         0],
[-sqrt(3)/2,       1/2,          0,         0],
[         0,         0,       -1/2, sqrt(3)/2],
[         0,         0, -sqrt(3)/2,      -1/2]])

or symbols

>>> random_orthogonal_matrix(4, spec=(phi, psi), k=0)
Matrix([
[ cos(psi), sin(psi),         0,        0],
[-sin(psi), cos(psi),         0,        0],
[        0,        0,  cos(psi), sin(psi)],
[        0,        0, -sin(psi), cos(psi)]])

By default the orthogonal matrix is a rotation, i.e. has determinant 1. To turn it into a refelction with determinant -1:

>>> Q = random_orthogonal_matrix(3)
>>> Q[0, :] = -Q[0, :]  # flip a row to change sign
>>> Q.det()
-1

These examples show how to generate orthogonal matrices suited for numerical experiments, symbolic derivations, or test‑suite generation.

sympy_matrices_random.random_unitary_matrix(dim, *, spec=None, units=None, k=None)¶

Generate a random unitary matrix n x n.

A unitary matrix \(\mathbf{U}\) is complex matrix such that \(\mathbf{U}^H = \mathbf{U}^{-1}.\) It describes an isometry in n-dimensional unitary (complex) vectorspace.

If spec is given, it defines the set of random entries of an isometry normal form as a diagonal matrix \(\mathbf{D}\) with a diagonal of roots of unity.

Then the resulting isometry matrix will be the conjugate product \(\mathbf{U}^{-1} \cdot \mathbf{D} \cdot \mathbf{U}\).

If spec is None (default) only \(\mathbf{U}\) will be returned. If k is \(0\) only \(\mathbf{D}\) will be returned.

Note, spec (the set of eigenvalues) and units must consist of complex roots of unity only, i.e. complex numbers \(z\) with \(|z| = z * \bar{z} = 1\).

Parameters¶

dimint: Dimension of the matrix.
speciterable, optional: Set of eigenvalues. Must consist of complex roots of unity. Default is None.
unitsiterable, optional: Complex roots of unity used to build the matrix. Defaults to \(\{1, i, -1, -i \}\).
kint, optional: Number of rotations to build the matrix. Defaults to 2 * dim.

Returns¶

sympy.Matrix: The generated random unitary matrix.

Examples¶

>>> from sympy import I, pi, exp, expand, simplify, symbols
>>> from sympy_matrices_random import random_unitary_matrix

Generate 3×3 unitary matrix (default settings)

>>> u = random_unitary_matrix(3)
>>> u
Matrix([
[ 0,  0, -I],
[-1,  0,  0],
[ 0, -I,  0]])

>>> expand(u.H * u)
Matrix([
[1, 0, 0],
[0, 1, 0],
[0, 0, 1]])

Control of Rotations. The k argument controls how many elementary complex rotation cells are multiplied to form the random matrix. The default is 2*dim.

>>> u = random_unitary_matrix(5, k=30)  # a denser random unitary matrix

The units argument defines the set of complex numbers (roots of unity) from which the elementary rotation cells are drawn.

>>> roots_of_unity = I, exp(I * pi / 4), -I, exp(-I * pi / 4)

>>> random_unitary_matrix(3, units=roots_of_unity, k=1)
Matrix([
[sqrt(2)*exp(-I*pi/4)/2, 0, -sqrt(2)*exp(-I*pi/4)/2],
[                     0, 1,                       0],
[ sqrt(2)*exp(I*pi/4)/2, 0,   sqrt(2)*exp(I*pi/4)/2]])

Specific eigenvalues may provided as spec argument

>>> x = symbols('x', real=True)
>>> spec = exp(I * x), exp(I * pi / 4)
>>> U = random_unitary_matrix(3, spec=spec, units=spec, k=1)

Without given spec the function returns a matrix with determinat 1 by default

>>> random_unitary_matrix(6).det()
1

Random determinats can be obtained by providing spec

>>> spec = exp(I * x), exp(I * pi / 4)
>>> random_unitary_matrix(6, spec=spec).det()
I*exp(4*I*x)

Api Documantation¶

Parameters¶

Returns¶

See Also¶

Examples¶

Parameters¶

Returns¶

See Also¶

Examples¶

Parameters¶

Returns¶

See Also¶

Examples¶