The matrix class defined in C++ forms the basis for all ModelSpace mathematics. The class is a templated, safe library designed for use in embedded and simulation operations. It is also swig wrapped for use in Python.

This guide provides the basics on how to interact with the Matrix class. Note that all classes derived from Matrix, including vectors and attitude representations, may be interacted with using Matrix functions, except where explicitly noted.

For a full guide on how to interact with Matrix, check out the Doxygen page. This guide is abbreviated and provided for simplicity. The official/formal documentation is provided by Doxygen. The Doxygen for Matrix is found here:

Matrix Doxygen

The Matrix Class

Description and Naming

The Matrix class is a templated class with three template arguments - T, R, and C. Matrix<T, R, C> produces an RxC matrix of type T. The three arguments are, respectively:

  • T - The type of the Matrix. This should be a floating point type.

  • R - The number of rows of the matrix. This should be an integer input

  • C - The number of columns in the matrix. This should be an integer input.

Because the class is templated, macros are provided to simplify interaction with the Matrix class. These are described in the table below. The Matrix class may be freely defined to any size with at least one row and one column in C. The macros must be used for Matrix declaration in C.

Macros are defined for sizes up to 6x6. Examples provided below (not an exhaustive list). The full type definitions are found in modelspace/clockwerk/src/core/macros.h.

Matrix Template Arguments Macro 
Matrix<double, 3, 3> mat1;
 
Matrix3D mat1;
 
Matrix<float, 3, 1> mat2;
 
Matrix31F mat2;

Creating a Matrix

Description C++ Example Python Example

Default Constructor - Creates a matrix filled with zeros.

 
Matrix<double, 3, 3> mat1;
 
mat1 = Matrix3D

Constructor with Initial Value - Creates a matrix where all elements are the same value.

 
Matrix<double, 3, 3> mat2(5); // All elements are set to 5
 
mat2 = Matrix3D(5) # All elements are set to 5

Constructor with initializer list - Creates a matrix from an initializer list

 
Matrix<double, 3, 3> mat3({{1, 2, 3}, {4, 5, 6}, {7, 8, 9}});
 
mat3 = Matrix3D([[1, 2, 3], [4, 5, 6], [7, 8, 9]])

Constructor with 2D Array - Creates a matrix from a 2D array.

 
double initial[3][3] = {{1, 2, 3}, {4, 5, 6}, {7, 8, 9}};
Matrix<double, 3, 3> mat3(initial);
 
initial = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
mat3 = Matrix3D(initial)

Copy Constructor - Creates a new matrix as a copy of another matrix.

 
Matrix<double, 3, 3> mat4(mat3);
 
mat4 = mat3

Setting and Getting Values

Description C++ Example Python Example

Setting a Value - Set the value at a specific row and column.

 
mat1.set(0, 1, 10); // Sets the value at row 0, column 1 to 10
 
mat1.set(0, 1, 10) # Sets the value at row 0, column 1 to 10

Getting a Value - Get the value at a specific row and column.

 
double value;
mat1.get(0, 1, value); // Retrieves the value at row 0, column 1 into variable 'value'
 
value = 1
mat1.get(0, 1, value) # Retrieves the value at row 0, column 1 into variable 'value'

Bracket access - Directly access the value at a specific row and column (unsafe for embedded operations).

 
double value = mat1[0][1];
 
# No equivalent implemented in Python

Direct Access - Directly access the value at a specific row and column (unsafe for embedded operations).

 
double value = mat1.get(0, 1);
 
value = mat1.get(0, 1);

Matrix Operations

Description C++ Example Python Example

Dumping Matrix Content - Prints the matrix to the console.

 
mat1.dump();
 
mat1.dump()

Getting Matrix as a String - Returns the matrix as a string.

 
std::string matrixStr = mat1.str();
 
matrixStr = mat1.str()

Transposing a Matrix - Transposes the matrix.

 
Matrix<double, 3, 3> transposeMat;
mat1.transpose(transposeMat);
 
transposeMat = Matrix3D()
mat1.transpose(transposeMat)

Finding Maximum Value - Finds the maximum value and its position.

 
double maxVal;
std::pair<unsigned int, unsigned int> index;
mat1.max(maxVal, index); // maxVal holds the maximum value, index holds its position
 
# Not implemented for Python

Finding Minimum Value - Finds the minimum value and its position.

 
double minVal;
std::pair<unsigned double, unsigned double> index;
mat1.min(minVal, index); // minVal holds the minimum value, index holds its position
 
# Not implemented for Python

Determinant of a Matrix - Calculates the determinant of the matrix.

 
double detVal;
mat1.det(detVal);
 
detVal = 0.0
mat1.det(detVal)

Inverse of a Matrix - Calculates the inverse of the matrix.

 
Matrix<double, 3, 3> inverseMat;
int error = mat1.inverse(inverseMat);
 
inverseMat = Matrix3D()
error = mat1.inverse(inverseMat)

Trace of a Matrix - Calculates the trace of the matrix (sum of diagonal elements).

 
double traceVal;
mat1.trace(traceVal);
 
traceVal = 0.0
mat1.trace(traceVal)

Additional Operations

Description C++ Example Python Example

Setting All Elements to Zero - Sets all elements of the matrix to zero.

 
mat1.setToZeros();
 
mat1.setToZeros()

Matrix Math Functions

Description and Naming

The matrix math functions operate on the Matrix class. They have two flavors: functions which return a pass by reference and an error code if the operation is invalid, which are typically used for embedded/safe operations, and functions which are overloaded and more intuitive operators which return directly without an error code. The matrix functions follow a consistent naming convention:

  • Capital letters represent matrices.

  • Lowercase letters represent scalars.

  • Vectors are treated as 1-dimensional matrices.

  • Pass-by-reference return values are all named result.

  • The letter used in the function indicates the order of operations (e.g., A/a comes first, then B/b).

For a complete guide on interacting with the matrix math functions, refer to the Doxygen documentation: Matrix Math Functions Doxygen

Adding Matrices

Description C++ Example Python Example

Adding a Scalar to a Matrix - Adds a scalar to a matrix and returns the result.

 
double scalar = 2.0;
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = add(scalar, A, result);
 
# Python equivalent not yet available

Element-wise Addition - Adds two matrices element-wise and returns the result.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = eAdd(A, B, result);
 
# Python equivalent not yet available

Matrix Addition - Overloaded operator for adding two matrices.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result = A + B;
 
# Python equivalent not yet available

Scalar Addition - Overloaded operator for adding a scalar to a matrix.

 
double scalar = 2.0;
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result = scalar + A;
 
# Python equivalent not yet available

Subtracting Matrices

Description C++ Example Python Example

Element-wise Subtraction - Subtracts one matrix from another element-wise and returns the result.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = eSubtract(A, B, result);
 
# Python equivalent not yet available

Matrix Subtraction - Overloaded operator for subtracting one matrix from another.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result = A - B;
 
# Python equivalent not yet available

Multiplying Matrices

Description C++ Example Python Example

Multiplying Two Matrices - Multiplies two matrices and returns the result.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = multiply(A, B, result);
 
# Python equivalent not yet available

Multiplying a Scalar by a Matrix - Multiplies a scalar by a matrix and returns the result.

 
double scalar = 2.0;
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = multiply(scalar, A, result);
 
# Python equivalent not yet available

Element-wise Multiplication - Multiplies two matrices element-wise and returns the result.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result;
int error = eMultiply(A, B, result);
 
# Python equivalent not yet available

Matrix Multiplication - Overloaded operator for multiplying two matrices.

 
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> B({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result = A * B;
 
# Python equivalent not yet available

Scalar Multiplication - Overloaded operator for multiplying a matrix by a scalar.

 
double scalar = 2.0;
Matrix<double, 2, 2> A({{1.0, 2.0}, {3.0, 4.0}});
Matrix<double, 2, 2> result = scalar * A;
 
# Python equivalent not yet available