Jule Manual

Appearance

julenum/mat ​

Package for matrices.

Index ​

Variables
fn Empty[T: numeric](): Matrix[T]
fn New[T: numeric](m: int, n: int): Matrix[T]
fn NewFrom[T: numeric](values: [][]T): Matrix[T]
struct Matrix[T: numeric]
    fn Format(*self, wsn: int): string
    fn AppendFormat(*self, mut buf: []byte, wsn: int): []byte
    fn String(*self): string
    fn Data(mut *self): []T
    fn Dims(*self): (m: int, n: int)
    fn Size(*self): int
    fn Zero(*self): bool
    fn Square(*self): bool
    fn Scalar(*self, c: T): bool
    fn Identity(*self): bool
    fn Diagonal(*self): bool
    fn Get(*self, i: int, j: int): T
    fn Set(mut *self, i: int, j: int, value: T)
    fn Equal(*self, &z: *Matrix[T]): bool
    fn Fill(mut *self, &z: *Matrix[T], k: T)
    fn Copy(mut *self, &z: *Matrix[T])
    fn Resize(mut *self, &z: *Matrix[T], m: int, n: int)
    fn Trace(*self): T
    fn Transpose(mut *self, &z: *Matrix[T])
    fn AddScalar(mut *self, &z: *Matrix[T], k: T)
    fn SubScalar(mut *self, &z: *Matrix[T], k: T)
    fn MulScalar(mut *self, &z: *Matrix[T], k: T)
    fn Add(mut *self, &x: *Matrix[T], &y: *Matrix[T])
    fn Sub(mut *self, &x: *Matrix[T], &y: *Matrix[T])
    fn Mul(mut *self, &x: *Matrix[T], &y: *Matrix[T])
    fn MulEx(mut *self, &x: *Matrix[T], &y: *Matrix[T], flags: int)
    fn Det(*self): T
    fn Slogdet(*self): (sign: T, logdet: f64)
    fn Inv(mut *self, &a: *Matrix[T])

Variables ​

jule
const (
	PARALLEL = 1 << iota
	STRASSEN
	STABLE
)

Flags.

Empty ​

jule
fn Empty[T: numeric](): Matrix[T]

Returns new empty (0×0) Matrix for type T.

New ​

jule
fn New[T: numeric](m: int, n: int): Matrix[T]

Returns new (M×N) zero Matrix for type T.

Constraints:

m >= 0
n >= 0

NewFrom ​

jule
#disable boundary
fn NewFrom[T: numeric](values: [][]T): Matrix[T]

Returns new (M×N) Matrix for type T. Uses len(values) for m, len(values[1]) for n. Panics if all rows are not have same amount of values.

Special cases are:

NewFrom(values) = (0×0) Matrix, if len(values) == 0
NewFrom(values) = (0×0) Matrix, if len(values) == 1 && len(values[1]) == 0

Example Use:

mat::NewFrom([
	[1, 2, 4],
	[3, 4, 5],
])

Equals to:
	A = ⎡1 2 4⎤
	    ⎣3 4 5⎦(2×3)

Matrix ​

jule
struct Matrix[T: numeric] {
	// NOTE: contains filtered hidden or unexported fields
}

A matrix for type T. Uses internal mutable slice to store data. Matrix computations may use available capacity of the underlying slice to avoid making new allocation. So shared data needs extra attention. Any mutable operation may be reflected to shared common data. If you need to share same Matrix instance, use smart pointers. If you need to have guaranteed independent copy, use Copy with empty Matrix.

Format ​

jule
fn Format(*self, wsn: int): string

Returns string form of the matrix. wsn represents number of whitespaces between matrix elements. wsn will be considired as zero if wsn < 1. Default wsn value is 1.

AppendFormat ​

jule
fn AppendFormat(*self, mut buf: []byte, wsn: int): []byte

Appends string form of the matrix to buf and returns. wsn represents number of whitespaces between matrix elements. wsn will be considired as zero if wsn < 1. Default wsn value is 1.

String ​

jule
fn String(*self): string

Returns string form of the matrix.

Data ​

jule
unsafe fn Data(mut *self): []T

Returns mutable copy of the internal data. This is an unsafe function, any mutation may cause corruptions.

Dims ​

jule
fn Dims(*self): (m: int, n: int)

Returns dimensions of the Matrix (M×N).

Size ​

jule
fn Size(*self): int

Returns total element count of matrix (M×N).

Zero ​

jule
fn Zero(*self): bool

Reports whether the all values of Matrix are zero.

Special cases are:

Zero() = true, if Dims() == (0, 0)

Square ​

jule
fn Square(*self): bool

Reports whether the Matrix is a square matrix (M == N).

Scalar ​

jule
#disable boundary
fn Scalar(*self, c: T): bool

Reports whether the matrice (M×N) is scalar matrice of c. This function only supports square matrices (M == N && N > 0).

Identity ​

jule
fn Identity(*self): bool

Reports whether the matrice (M×N) is an identity matrice. This function only supports square matrices (M == N && N > 0).

Diagonal ​

jule
fn Diagonal(*self): bool

Reports whether the matrice (M×N) is a diagonal matrice. This function only supports square matrices (M == N && N > 0).

Get ​

jule
fn Get(*self, i: int, j: int): T

Returns value of the specified (i×j) position. Position index starts from zero for column and row.

Implementation will not check for boundaries, invalid position may cause panic. To provide fast computation, it will not check whether the (i×j) is valid (M×N).

Set ​

jule
fn Set(mut *self, i: int, j: int, value: T)

Sets value of the specified (i×j) position. Position index starts from zero for column and row.

Implementation will not check for boundaries, invalid position may cause panic. To provide fast computation, it will not check whether the (i×j) is valid (M×N).

Equal ​

jule
#disable boundary
fn Equal(*self, &z: *Matrix[T]): bool

Reports whether self and z matrices are equal.

Fill ​

jule
#disable boundary
fn Fill(mut *self, &z: *Matrix[T], k: T)

Sets self to z, filled with k. If self have enough capacity, Fill will use it to avoid making allocation.

Copy ​

jule
fn Copy(mut *self, &z: *Matrix[T])

Copies z to self.

If self have enough capacity, Copy will use it to avoid making allocation.

Resize ​

jule
fn Resize(mut *self, &z: *Matrix[T], m: int, n: int)

Copies matrice z to self with custom (M×N) size. If new size is larger, it will add padding with zeros. If new size is smaller, it will cut rows and columns.

If self have enough capacity, Resize will use it to avoid making allocation. If M == 0 or N == 0, self will be (0×0). But keeps internal allocation.

Trace ​

jule
#disable boundary
fn Trace(*self): T

Returns trace of matrix. Panics if matrix is not a square matrix.

Special cases are:

Trace() = 0, for (0×0) matrices

Transpose ​

jule
#disable boundary
fn Transpose(mut *self, &z: *Matrix[T])

Sets self to the transpose of the matrix z. If self have enough capacity, Transpose will use it to avoid making allocation. If z is a (0×0) matrix, self will be (0×0). But keeps internal allocation.

AddScalar ​

jule
#disable boundary
fn AddScalar(mut *self, &z: *Matrix[T], k: T)

Sets self to the sum z+k. If self have enough capacity, AddScalar will use it to avoid making allocation. If z is a (0×0) matrix, self will be (0×0). But keeps internal allocation.

SubScalar ​

jule
#disable boundary
fn SubScalar(mut *self, &z: *Matrix[T], k: T)

Sets self to the difference z-k. If self have enough capacity, SubScalar will use it to avoid making allocation. If z is a (0×0) matrix, self will be (0×0). But keeps internal allocation.

MulScalar ​

jule
fn MulScalar(mut *self, &z: *Matrix[T], k: T)

Sets self to the product z*k. If self have enough capacity, MulScalar will use it to avoid making allocation. If z is a (0×0) matrix, self will be (0×0). But keeps internal allocation.

Add ​

jule
fn Add(mut *self, &x: *Matrix[T], &y: *Matrix[T])

Sets self to the sum x+y. If self have enough capacity, Add will use it to avoid making allocation. If matrices are (0×0) matrix, self will be (0×0). But keeps internal allocation.

Sub ​

jule
fn Sub(mut *self, &x: *Matrix[T], &y: *Matrix[T])

Sets self to the difference x-y. If self have enough capacity, Sub will use it to avoid making allocation. If matrices are (0×0) matrix, self will be (0×0). But keeps internal allocation.

Mul ​

jule
fn Mul(mut *self, &x: *Matrix[T], &y: *Matrix[T])

Sets self to the product x*y. If self have enough capacity, Mul will use it to avoid making allocation. Equals to [Matrix.MulEx(x, y, PARALLEL|STRASSEN|STABLE)]

MulEx ​

jule
fn MulEx(mut *self, &x: *Matrix[T], &y: *Matrix[T], flags: int)

Sets self to the product x*y. If self have enough capacity, MulEx will use it to avoid making allocation.

Flags:

PARALLEL: performs parallel computation when it is suitable.
STRASSEN: uses Strassen algorithm when it is suitable.
STABLE: prioritizes numerical stability.

Det ​

jule
fn Det(*self): T

Computes the determinant of the matrix. This function only supports square matrices (M == N && N > 0).

For integer and floating-point types, computations are performed using 64-bit floating-point precision. For complex types, computations use 128-bit complex precision. The result is returned as type T, which may cause rounding errors or loss of precision. To preserve exact results, use an f64 or cmplx128 matrix.

Slogdet ​

jule
#disable boundary
fn Slogdet(*self): (sign: T, logdet: f64)

Computes the sign and natural logarithm of the absolute value of the determinant of the matrix. Returns (sign, logdet). If the matrix is singular, returns (0, -Inf). This function only supports square matrices (M == N && N > 0).

For integer and floating-point types, computations are performed using 64-bit floating-point precision. For complex types, computations use 128-bit complex precision. The result is returned as type T, which may cause rounding errors or loss of precision. To preserve exact results, use an f64 or cmplx128 matrix.

NOTICE (floating-point types)

Let (sign, logdet) = Slogdet()
- Mathematically: Det() = sign * exp(logdet)
- In practice:    Det() ≈ sign * exp(logdet) due to floating-point rounding.

NOTICE (complex types)

Let (sign, logdet) = Slogdet()
- Mathematically: Det() = cmplx(real(sign)*exp(logdet), imag(sign)*exp(logdet))
- In practive:    Det() ≈ cmplx(real(sign)*exp(logdet), imag(sign)*exp(logdet)) due to floating-point rounding.

Inv ​

jule
fn Inv(mut *self, &a: *Matrix[T])

Sets self to A⁻¹, inverse of the matrix a. This function only supports square matrices (M == N && N > 0). If self have enough capacity, Mul will use it to avoid making allocation. It panics if matrix a is singular.

For integer and floating-point types, computations are performed using 64-bit floating-point precision. For complex types, computations use 128-bit complex precision. The result is handled as type T, which may cause rounding errors or loss of precision. To preserve exact results, use an f64 or cmplx128 matrix.