Reference Manual: DSL Dmatrix

From DSL

Jump to: navigation, search


This is the basic structure that SMILE uses to store probabilities, utilities, beliefs, etc. It provides several useful functions that facilitate operations with the nodes. It is recommended that this class be perfectly understood before trying to do any programming with SMILE.


Methods

  • DSL_Dmatrix(DSL_intArray &theseDimensions)

Constructs a matrix with the number of dimensions and sizes specified in theseDimensions.

NOTE: theseDimensions is expected to be a list (its NumItems method will be used instead of GetSize).


  • double &Subscript(DSL_intArray &theCoordinates)

Returns the element whose position is given by theCoordinates. theCoordinates must have at least one coordinate for each dimension of the matrix (its size must be equal or bigger than the number of coordinates of the matrix). If theCoordinates are not correct or there are any other error conditions, then this function will return a reference to a double with the value DSL_OUT_OF_RANGE.


  • double &operator[](DSL_intArray &theCoordinates)

Works the same way as Subscript but no checking is performed. Make sure theCoordinates are correct before calling this method.


  • int GetNumberOfDimensions(void)

Surprisingly enough, this function returns the number of dimensions of the matrix. The numbering of the dimensions starts with 0 so in a matrix with 4 dimensions the valid dimension numbers are 0,1,2, and 3.


  • int GetSizeOfDimension(int aDimension)

Returns the size of aDimension. Remember that the numbering of dimensions start from 0.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (aDimension is not a valid dimension of the matrix).


  • int GetSize(void)

Returns the number of elements of the matrix (product of dimensions, so a 3x2x5 matrix will have a size of 30).


  • int Sum(DSL_Dmatrix &aDmatrix, DSL_Dmatrix &withDmatrix)

Fill our contents with the result of adding aDmatrix withDmatrix. The three matrices (aDmatrix, withDmatrix and us) must be compatible for addition (i.e., they must have the same number of dimensions and they must be of the same size.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (the matrices are not compatible).


  • int Multiply(double byThisNumber)

Multiplies every element of the matrix byThisNumber.

Error return values: DSL_OBJECT_NOT_READY


  • int Multiply(DSL_doubleArray &byThisVector)

Multiplies every element with coordinates (a,b,c,...,z=N) by the Nth element of byThisVector. Thus, byThisVector should be at least the same length as the last dimension of the matrix.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (length of byThisVector is incorrect).


  • int CoordinatesToIndex(DSL_intArray &theCoordinates)

Returns the transformation from theCoordinates to a flat index to the data.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (theCoordinates are not valid)


  • int IndexToCoordinates(int theIndex, DSL_intArray &theCoordinates)

Transforms theIndex into theCoordinates. This is the reverse operation of the method CoordinatesToIndex.

Error return values: DSL_OUT_OF_RANGE (theIndex is not valid).


  • int NextCoordinates(DSL_intArray &theCoordinates)

Calculates the next valid set of coordinates from theCoordinates (i.e., increments by 1 theCoordinates starting from the end and taking care of carry).

Error return values: DSL_OUT_OF_RANGE (could not increment or theCoordinates are illegal), DSL_OBJECT_NOT_READY. 

  //Example (for a 5x4x3 Dmatrix):
  NextCoordinates([4,2,1]) = [4,2,2] // no carry
  NextCoordinates([4,2,2]) = [4,3,0] // carry
  NextCoordinates([2,3,2]) = [3,0,0] // carry & carry


  • int PrevCoordinates(DSL_intArray &theCoordinates)

Calculates the previous valid set of coordinates from theCoordinates (i.e., decrements by 1 theCoordinates starting from the end and taking care of carry).

Error return values: DSL_OUT_OF_RANGE (could not increment or theCoordinates are illegal), DSL_OBJECT_NOT_READY. 

  //Example (for a 5x4x3 Dmatrix):
  PrevCoordinates([3,2,1]) = [3,2,0] // no carry
  PrevCoordinates([4,2,0]) = [4,1,2] // carry
  PrevCoordinates([2,0,0]) = [1,3,2] // carry & carry


  • int FillWith(double aNumber)

Fills the matrix with aNumber.


  • int Setup(DSL_intArray &theseDimensions)

Recreates the matrix with theseDimensions as the new parameters. theseDimensions is expected to be a list of dimensions (i.e., the number of dimensions will be set according to the NumItems method of theseDimensions). The previously allocated memory will be freed.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (theseDimensions are not valid).


  • int InsertDimension(int here, int thisSize)

Inserts here a new dimension of thisSize. The actual dimensions will be shifted one position to the right. It is allowed to insert after the last dimension of the matrix, so the new dimension will be just added at the end. The new contents of the matrix will be a duplication of the old contents along the new dimension.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (here is not a valid index).

Example: if we have M1(a,b,c,d) and we call: 

  M1.InsertDimension(2,4);

we get M2(a,b,[new],c,d) with a new dimension of size 4 in which every element of the form M2(a,b,[0..3],c,d) is equal to M1(a,b,c,d).


  • int AddDimension(int thisSize)

Adds a new dimension to the matrix. The new dimension will be the last one. Works exactly the same way as InsertDimension.


  • int AddDimensions(DSL_intArray &theseDimensions)

Adds theseDimensions to the matrix. In practice it just calls AddDimension once for each item in theseDimensions.


  • int RemoveDimension(int thisDimension, int preservingThis)

Shrinks thisDimension while preservingThis value. Preserving means that the new contents of the matrix will be those of the old contents of the matrix where thisDimension takes the value preservingThis. This method is used when evidence is observed, preservingThis being the outcome observed.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension OR preservingThis is not a valid index for thisDimension).

Example: given a Dmatrix with five dimensions M1(a,b,c,d,e), calling: 

  M1.RemoveDimension(3,2); // remove d preserving d=2

will shrink the matrix into four dimensions (a,b,c,e) in which every element (a,b,c,e) after the shrinking is equal to the element (a,b,c,2,e) before the shrinking.


  • int RemoveDimension(int thisDimension, DSL_doubleArray &usingTheseValues)

Removes thisDimension and the new contents of the matrix are calculated in this way: New(a=a1,b=b1,...,z=z1) is equal to the sum of every element with coordinates Old(a=a1,b=b1,..., thisDimension = N ,...,z=z1) multiplied by the Nth value of thisValues. This method is used when marginalizing a parent, usingThisValues being the prior beliefs of the parent (i.e., when we want the sum over B of P(A|B) * P(B)). usingTheseValues is expected to be an array whose size must be equal to the size of thisDimension.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension OR usingTheseValues does not have the correct size).

Example: given a matrix with four dimensions M1(3x2x5x2), calling: 

  M1.RemoveDimension(1, (2.3,4.7) ); // remove dimension 1

will shrink the matrix into three dimensions M2(3x5x2) and the element M2(0,3,1), for instance, will be calculated as M1(0,0,3,1) * 2.3 + M1(0,1,3,1) * 4.7


  • int RemoveDimension(int thisDimension)

The same as calling RemoveDimension(thisDimension,0). This method is used when removing an arc.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension).


  • int IncreaseDimensionSize(int thisDimension)

Increases by one the size of thisDimension while preserving the old contents of the matrix and setting the new ones to 0.0.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension).


  • int DecreaseDimensionSize(int thisDimension)

Decreases by one the size of thisDimension while preserving the contents of the rest of the matrix.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension).


  • int ResizeDimension(int thisDimension, int thisSize)

Changes the size of thisDimension to thisSize. The contents of the matrix are not preserved.

Error return values: DSL_OBJECT_NOT_READY, DSL_OUT_OF_RANGE (thisDimension is not a valid dimension OR thisSize is not bigger than 0).


  • int RemoveDimension(int thisDimension, int preservingThis, DSL_Dmatrix &intoThisMatrix)

The same as RemoveDimension(thisDimension,preservingThis) but the results are stored intoThisMatrix.


  • int RemoveDimensions(DSL_intArray &theseDimensions, DSL_Dmatrix &intoThisMatrix)

Remove one or more dimensions. theseDimensions will contain one number for each of the dimensions of the matrix. For any given dimension, if the number is negative we will preserve that dimension. If the number is positive, we will remove that dimension preserving the value indicated by the number.


  • int RemoveDimension(int thisDimension, DSL_doubleArray &usingTheseValues, DSL_Dmatrix &intoThisMatrix)

The same as RemoveDimension(thisDimension,usingTheseValues) but storing the results intoThisMatrix.


  • int RemoveDimension(int thisDimension, DSL_Dmatrix &usingTheseValues, DSL_intArray &dimensionMapping)

Removes thisDimension usingTheseValues. Each dimension of usingThisValues must correspond to one of our dimensions. dimensionMapping contains the position of each of the dimensions of usingTheseValues in ourselves, i.e., dimension number 0 of usingTheseValues corresponds to my dimensionMapping[0]th dimension.

Example: if dimensionMapping contains [2,3,1], that means that dimension 0 of usingTheseValues corresponds to my dimension 2, dimension 1 corresponds to my dimension 3 and dimension 2 corresponds to my dimension 1. Of course, all this "pairs" must have the same size in both matrices or the thing will go really wrong.


  • int Normalize(void)

Multiplies all elements of the matrix by a constant value such that the elements with coordinates (a,b,c,d,...,z=z0..zn) all sum to 1 (one) over z.


  • int Normalize(DSL_intArray &theseCoordinates)

The same as Normalize, but it only normalizes the "column" specified by theseCoordinates (elements with coordinates (a = a0,b = b0,...,z=z0..zn)). The last element of theseCoordinates will be ignored and the elements of the matrix will be normalized along the last dimension.


  • int Complement(DSL_intArray &theseCoordinates)

Recalculates the content of the element at thisCoordinates so the sum of all the elements with coordinates (a,b,c,d,...,z=0..n) is 1 (one).

WARNING : this can result in negative numbers inside the matrix


  • int ShiftDataUpwards(int thisDimension, int fromThisValue)

Shifts the contents of the matrix upward (i.e., from lower value of the coordinate to higher value).

Example: suppose that we have a matrix M1(a,b,c) with dimension sizes a=2, b=4 and c=3. If we call: 

  M1.ShiftDataUpwards(1,1); // shift b starting from b=1

the resulting matrix (M2) will contain the following values: 

  M2(a,0,c) = M1(a,0,c)
  M2(a,1,c) = 0 (empty new value)
  M2(a,2,c) = M1(a,1,c)
  M2(a,3,c) = M1(a,2,c)

Note that we lose the value M1(a,3,c) because we are shifting upwards.


  • int ShiftDataDownwards(int thisDimension, int fromThisValue)

Shifts the contents of the matrix downward (i.e., from higher value of the coordinate to lower value).

Example: suppose that we have a matrix M1(a,b,c) with dimension sizes a=2, b=4 and c=3. If we call: 

  M1.ShiftDataDownwards(1,1); // shift b starting from b=1

the resulting matrix (M2) will contain the following values: 

  M2(a,0,c) = M1(a,0,c)
  M2(a,1,c) = M1(a,2,c)
  M2(a,2,c) = M1(a,3,c)
  M2(a,3,c) = 0 (empty new value)

Note that we lose the value M1(a,1,c) because we are shifting downwards.


  • int Ok(DSL_intArray &theCoordinates)

Returns DSL_TRUE if theCoordinates are valid for the matrix. Returns DSL_FALSE otherwise. For theCoordinates to be valid, the size (GetSize) of theCoordinates is expected to be at least as big as the number of dimensions of the matrix.


  • int CheckElements(double aValue, DSL_intArray &theseCoordinates)

Returns DSL_TRUE if a set of elements of the matrix are equal to aValue. The set of elements includes all the elements of the whole matrix except when indicated otherwise in theseCoordinates by a positive number. A positive number in the position [n] of theseCoordinates means that the set of elements checked are only those that have the [n]th coordinate equal to the value of that positive number.

Example: if theseCoordinates contains (-1,2,-1,1), the only elements that will be checked are those with coordinates (a,2,c,1) and the function will return DSL_TRUE if all of them are equal to aValue


  • int ChangeOrderOfDimensions(DSL_intArray &newOrder)

Allows user changing order of dimensions within DSL_Dmatrix. The newOrder contains permutation vector, where i-th element with value x indicates, that after permutation, the i-th position will be occupied by element which was before on x-th position. Returns DSL_TRUE if operation was successful.


  • int ChangeOrderWithinDimension(int thisDim, DSL_intArray &newOrder)

Allows user changing order elements within single thisDim dimension in DSL_Dmatrix. The newOrder contains permutation vector, where i-th element with value x indicates, that after permutation, the i-th position will be occupied by element which was before on x-th position. Returns DSL_TRUE if operation was successful.

Retrieved from "http://genie.sis.pitt.edu/wiki/Reference_Manual:_DSL_Dmatrix"
Personal tools