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 foreachiterator 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

---

Class Documentation

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 = {..}

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_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[1000] of int
  2. Atom <== matrix[333] of 0 %% The opaque family of routines allocates on stack:
  1. Var <== [[1000],[1001],[1002]]
  1. Var <== matrix[1000] 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