 YAP 7.1.0
Matrix Library

This package provides a fast implementation of multi-dimensional matrices of integers and floats. More...

## Detailed Description

This package provides a fast implementation of multi-dimensional matrices of integers and floats.

In contrast to dynamic arrays, these matrices are multi-dimensional and compact In contrast to static arrays these arrays are allocated in the stack, and disppear in backtracking Matrices are available by loading the library `library(matrix)` They are multimensional objects of type:

• `terms`: Prolog terms

`ints`: bounded integers, represented as an opaque term The maximum integer depends on hardware, but should be obtained from the natural size of the machine

• `floats`: floating-point numbers, represented as an opaque term

The matrix library also supports a B-Prolog/ECliPSe inspired `foreach`iterator to iterate over elements of a matrix:

• Copy a vector, element by element
foreach(I in 0..N1, X[I] <== Y[I])
• The lower-triangular matrix Z is the difference between the lower-triangular and upper-triangular parts of X
foreach([I in 0..N1, J in I..N1], Z[I,J] <== X[I,J] - X[I,J])
• Add all elements of a matrix by using Sum␇ as an accumulator
foreach([I in 0..N1, J in 0..N1], plus(X[I,J]), 0, Sum)
```Notice that the library does not support all known matrix operations. Please
```

contact the YAP maintainers if you require extra functionality

## ◆ matrix_agg_cols/3

 class matrix_agg_cols/3

matrix_agg_cols(+ Matrix,+Operator,+ Aggregate)

If Matrix is a n-dimensional matrix, unify Aggregate with the one dimensional matrix where each element is obtained by adding all Matrix elements with same first index Currently, only addition is supported

## ◆ matrix_agg_lines/3

 class matrix_agg_lines/3

matrix_agg_lines(+ Matrix,+Operator,+ Aggregate)

s

If Matrix is a n-dimensional matrix, unify Aggregate with the n-1 dimensional matrix where each element is obtained by adding all Matrix elements with same last n-1 index Currently, only addition is supported

## ◆ matrix_arg_to_offset/3

 class matrix_arg_to_offset/3

matrix_arg_to_offset(+ Matrix,+ Position,- Offset)

Given matrix Matrix return what is the numerical Offset of the element at Position

## ◆ matrix_column/3

 class matrix_column/3

matrix_column(+ Matrix,+ Column,- NewMatrix)

Select from Matrix the column matching Column as new matrix NewMatrix Column must have one less dimension than the original matrix

## ◆ matrix_dec/2

 class matrix_dec/2

matrix_dec(+ Matrix,+ Position)

Decrement the element of Matrix at position Position

## ◆ matrix_dec/3

 class matrix_dec/3

matrix_dec(+ Matrix,+ Position,- Element)

Decrement the element of Matrix at position Position and unify with Element

## ◆ matrix_new/4

 class matrix_new/4

matrix_new(+ Type,+ Dims,+ List,- Matrix)

Create a new matrix Matrix of type Type, which may be one of `ints` or `floats`, with dimensions Dims, and initialized from list List

## ◆ matrix_new/3

 class matrix_new/3

matrix_new(+ Type,+ Dims,- Matrix)

Create a new matrix Matrix of type Type, which may be one of `ints` or `floats`, and with a list of dimensions Dims The matrix will be initialized to zeros

?- matrix_new(ints,[2,3],Matrix).
Matrix = {..}
matrix_new(+ Type,+ Dims,- Matrix)

Notice that currently YAP will always write a matrix of numbers as `{..}`

## ◆ matrix_new_set/4

 class matrix_new_set/4

matrix_new_set(? Dims,+ OldMatrix,+ Value,- NewMatrix)

Create a new matrix NewMatrix of type Type, with dimensions Dims The elements of NewMatrix are set to Value

## ◆ matrix_offset_to_arg/3

 class matrix_offset_to_arg/3

matrix_offset_to_arg(+ Matrix,- Offset,+ Position)

Given a position Position _ for matrix _Matrix return the corresponding numerical Offset from the beginning of the matrix

## ◆ matrix_op/4

 class matrix_op/4

matrix_op(+ Matrix1,+ Matrix2,+ Op,- Result)

Result is the result of applying Op to matrix Matrix1 and Matrix2 Currently, only addition (`+`) is supported

## ◆ matrix_op_to_all/4

 class matrix_op_to_all/4

matrix_op_to_all(+ Matrix1,+ Op,+ Operand,- Result)

Result is the result of applying Op to all elements of Matrix1, with Operand as the second argument Currently, only addition (`+`), multiplication (`\*`), and division (`/`) are supported

## ◆ matrix_op_to_cols/4

 class matrix_op_to_cols/4

matrix_op_to_cols(+ Matrix1,+ Cols,+ Op,- Result)

Result is the result of applying Op to all elements of Matrix1, with the corresponding element in Cols as the second argument Currently, only addition (`+`) is supported Notice that Cols will have n-1 dimensions

## ◆ matrix_op_to_lines/4

 class matrix_op_to_lines/4

matrix_op_to_lines(+ Matrix1,+ Lines,+ Op,- Result)

Result is the result of applying Op to all elements of Matrix1, with the corresponding element in Lines as the second argument Currently, only division (`/`) is supported

## ◆ matrix_select/4

 class matrix_select/4

matrix_select(+ Matrix,+ Dimension,+ Index,- New)

Select from Matrix the elements who have Index at Dimension

## ◆ matrix_shuffle/3

 class matrix_shuffle/3

matrix_shuffle(+ Matrix,+ NewOrder,- Shuffle)

Shuffle the dimensions of matrix Matrix according to NewOrder The list NewOrder must have all the dimensions of Matrix, starting from 0

## ◆ matrix_transpose/2

 class matrix_transpose/2

matrix_transpose(+ Matrix,- Transpose)

Transpose matrix Matrix to Transpose Equivalent to:

matrix_transpose(Matrix,Transpose) :-
matrix_shuffle(Matrix,[1,0],Transpose).
matrix_shuffle(+ Matrix,+ NewOrder,- Shuffle)
matrix_transpose(+ Matrix,- Transpose)

## ◆ matrix_type/2

 class matrix_type/2

matrix_type(+ Matrix,- Type)

?_LHS_ <== ?_RHS_

LHS ==> RHS

Unify NElems with the type of the elements in Matrix

%% Matrix operation %% 1 Initialization:

• One can use use old array routines (check static_array/3 ) for offline arrays/ %%

1. `Atom <== [1000,1001,1002]`
1. `Atom <== matrix of int`
2. `Atom <== matrix of 0` %% The opaque family of routines allocates on stack:
1. `Var <== [,,]`
1. `Var <== matrix of term`
2. `Var <== matrix[333,2] of 3.1415` %% YAP also supports foreign matrices, as

properties: semideterministic

General matrix assignment operation It evaluates the right-hand side according to the left-hand side and to the matrix:

• if LHS is part of an integer or floating-point matrix, perform non-backtrackable assignment
• other unify left-hand side and right-hand size

Matrix elements can be accessed through the `matrix_get/2 ` predicate or through an `R`-inspired access notation (that uses the ciao style extension to `[]`) Examples include:

• Access the second row, third column of matrix `X` Indices start from `0`,
_E_ _X_[2,3]

Access all the second row, the output is a list ofe elements

_L_ _X_ _X_[2,_]
• Access all the second, thrd and fourth rows, the output is a list of elements
_L_ _X_ _X_[2..4,_]
• Access all the fifth, sixth and eight rows, the output is a list of elements
_L_ _X_ _X_[2..4+3,_]

The right-hand side supports the following operators:

• `[]/2`

written as M[ Offset]: obtain an element or list of elements of matrix M at offset Offset

• <tt>../2

I J generates a list with all integers from I to J, included

• <tt>+/2

add two numbers, add two matrices element-by-element, or add a number to all elements of a matrix or list

• <tt>-/2

subtract two numbers, subtract two matrices or lists element-by-element, or subtract a number from all elements of a matrix or list

• `* /2`

multiply two numbers, multiply two matrices or lists element-by-element, or multiply a number from all elements of a matrix or list

• `log/1 `

natural logarithm of a number, matrix or list

• `exp/1 `

natural exponentiation of a number, matrix or list

• X <== array[ Dim1,..., Dimn] of Objects The of/2 operator can be used to create a new array of Objects The objects supported are:
• `Unbound Variable` create an array of free variables
• `ints` create an array of integers
• `floats` create an array of floating-point numbers
• `_I_: _J_` create an array with integers from I to J
• `[..]` create an array from the values in a list

The dimensions can be given as an integer, and the matrix will be indexed `C`-style from `0..( _Max_-1)`, or can be given as an interval `_Base_ _Limit_` In the latter case, matrices of integers and of floating-point numbers should have the same Base on every dimension

## ◆ matrix_get/3

 class matrix_get/3

matrix_get(+ Matrix,+ Position,- Elem)

Unify Elem with the element of Matrix at position Position, or with a list of elements i if Pod is a range