You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@systemml.apache.org by mb...@apache.org on 2018/05/31 22:00:32 UTC
systemml git commit: [MINOR] Fix outdated language documentation
(missing builtins), part 1
Repository: systemml
Updated Branches:
refs/heads/master 4d3216678 -> c9739d788
[MINOR] Fix outdated language documentation (missing builtins), part 1
This patch updates the dml language documentation as follows:
* Fix removeEmpty mark down
* Extended boolean operators for scalars and matrices
* Extended cbind/rbind for nary inputs
* Add missing ifelse builtin function
* Add missing xor builtin function
* Add missing lower.tri/upper.tri builtin functions
Project: http://git-wip-us.apache.org/repos/asf/systemml/repo
Commit: http://git-wip-us.apache.org/repos/asf/systemml/commit/c9739d78
Tree: http://git-wip-us.apache.org/repos/asf/systemml/tree/c9739d78
Diff: http://git-wip-us.apache.org/repos/asf/systemml/diff/c9739d78
Branch: refs/heads/master
Commit: c9739d7881e0a4dec998e36856dee07098432bf2
Parents: 4d32166
Author: Matthias Boehm <mb...@gmail.com>
Authored: Thu May 31 15:00:05 2018 -0700
Committer: Matthias Boehm <mb...@gmail.com>
Committed: Thu May 31 15:00:24 2018 -0700
----------------------------------------------------------------------
docs/dml-language-reference.md | 13 ++++++++-----
1 file changed, 8 insertions(+), 5 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/systemml/blob/c9739d78/docs/dml-language-reference.md
----------------------------------------------------------------------
diff --git a/docs/dml-language-reference.md b/docs/dml-language-reference.md
index d0943d6..b4ed9c8 100644
--- a/docs/dml-language-reference.md
+++ b/docs/dml-language-reference.md
@@ -155,7 +155,7 @@ SystemML follows same associativity and precedence order as R as described in be
| / * | Matrix or Scalar | Matrix or Scalar<sup>1, 2</sup> | Multiplication and Division
| + - | Matrix or Scalar | Matrix or Scalar<sup>1, 2</sup> | Addition (or string concatenation) and Subtraction
| < > == != <= >= | Matrix or Scalar (any value type) | Matrix or Scalar<sup>1, 2</sup> (boolean type) | Relational operators
-| & \| ! | Scalar | Scalar | Boolean operators (Note: operators && and \|\| are not supported)
+| & \| ! | Matrix or Scalar | Matrix or Scalar | Boolean operators (Note: operators && and \|\| are not supported)
| = | - | - | Assignment (Lowest precendence). Note: associativity of assignment "a = b = 3" is not supported
1 If one of the operands is a matrix, output is matrix; otherwise it is scalar.
@@ -638,7 +638,8 @@ The builtin function `sum` operates on a matrix (say A of dimensionality (m x n)
Function | Description | Parameters | Example
-------- | ----------- | ---------- | -------
-cbind() | Column-wise matrix concatenation. Concatenates the second matrix as additional columns to the first matrix | Input: (X <matrix>, Y <matrix>) <br/>Output: <matrix> <br/> X and Y are matrices, where the number of rows in X and the number of rows in Y are the same. | A = matrix(1, rows=2,cols=3) <br/> B = matrix(2, rows=2,cols=3) <br/> C = cbind(A,B) <br/> print("Dimensions of C: " + nrow(C) + " X " + ncol(C)) <br/> Output: <br/> Dimensions of C: 2 X 6
+cbind() | Column-wise matrix concatenation (concatenates the second matrix as additional columns to the first matrix). This operation also supports nary inputs, i.e., more than 2 input matrices. | Input: (X <matrix>, Y <matrix>) <br/>Output: <matrix> <br/> X and Y are matrices, where the number of rows in X and the number of rows in Y are the same. | A = matrix(1, rows=2,cols=3) <br/> B = matrix(2, rows=2,cols=3) <br/> C = cbind(A,B) <br/> print("Dimensions of C: " + nrow(C) + " X " + ncol(C)) <br/> Output: <br/> Dimensions of C: 2 X 6
+lower.tri() | Selects the lower triangular part of a matrix, configurable to include the diagonal and return values or ones. | Input : (target= X <matrix> \[, diag=FALSE\]\[, values=FALSE\]) <br/> Output : <matrix> | A = lower.tri(target=X, diag=TRUE, values=TRUE)
matrix() | Matrix constructor (assigning all the cells to numeric literals). | Input: (<init>, rows=<value>, cols=<value>) <br/> init: numeric literal; <br/> rows/cols: number of rows/cols (expression) <br/> Output: matrix | # 10x10 matrix initialized to 0 <br/> A = matrix (0, rows=10, cols=10)
| Matrix constructor (reshaping an existing matrix). | Input: (<existing matrix>, rows=<value>, cols=<value>, byrow=TRUE) <br/> Output: matrix | A = matrix (0, rows=10, cols=10) <br/> B = matrix (A, rows=100, cols=1)
| Matrix constructor (initializing using string). | Input: (<initialization string>, rows=<value>, cols=<value>) <br/> Output: matrix | A = matrix("4 3 2 5 7 8", rows=3, cols=2) <br/> Creates a matrix: [ [4, 3], [2, 5], [7, 8] ]
@@ -647,13 +648,13 @@ min() <br/> max() | Return the minimum/maximum cell values of two matrices, matr
nrow(), <br/> ncol(), <br/> length() | Return the number of rows, number of columns, or number of cells in matrix or frame respectively. | Input: matrix or frame <br/> Output: scalar | nrow(X) <br/> ncol(F) <br/> length(X)
prod() | Return the product of all cells in matrix | Input: matrix <br/> Output: scalarj | prod(X)
rand() | Generates a random matrix | Input: (rows=<value>, cols=<value>, min=<value>, max=<value>, sparsity=<value>, pdf=<string>, seed=<value>) <br/> rows/cols: Number of rows/cols (expression) <br/> min/max: Min/max value for cells (either constant value, or variable that evaluates to constant value) <br/> sparsity: fraction of non-zero cells (constant value) <br/> pdf: "uniform" (min, max) distribution, or "normal" (0,1) distribution; or "poisson" (lambda=1) distribution. string; default value is "uniform". Note that, for the Poisson distribution, users can provide the mean/lambda parameter as follows: <br/> rand(rows=1000,cols=1000, pdf="poisson", lambda=2.5). <br/> The default value for lambda is 1. <br/> seed: Every invocation of rand() internally generates a random seed with which the cell values are generated. One can optionally provide a seed when repeatability is desired. <br/> Output: matrix | X = rand(rows=10, cols=20, min=0, m
ax=1, pdf="uniform", sparsity=0.2) <br/> The example generates a 10 x 20 matrix, with cell values uniformly chosen at random between 0 and 1, and approximately 20% of cells will have non-zero values.
-rbind() | Row-wise matrix concatenation. Concatenates the second matrix as additional rows to the first matrix | Input: (X <matrix>, Y <matrix>) <br/>Output: <matrix> <br/> X and Y are matrices, where the number of columns in X and the number of columns in Y are the same. | A = matrix(1, rows=2,cols=3) <br/> B = matrix(2, rows=2,cols=3) <br/> C = rbind(A,B) <br/> print("Dimensions of C: " + nrow(C) + " X " + ncol(C)) <br/> Output: <br/> Dimensions of C: 4 X 3
-removeEmpty() | Removes all empty rows or columns from the input matrix target X according to the specified margin. The optional select vector F specifies selected rows or columns; if not provided, the semantics are F=(rowSums(X!=0)>0) and F=(colSums(X!=0)>0) for removeEmpty "rows" and "cols", respectively. The optional empty.return flag indicates if a row or column of zeros should be returned for empty inputs. | Input : (target= X <matrix>, margin="..."[, select=F][, empty.return=TRUE]) <br/> Output : <matrix> <br/> Valid values for margin are "rows" or "cols". | A = removeEmpty(target=X, margin="rows", select=F)
+rbind() | Row-wise matrix concatenation (concatenates the second matrix as additional rows to the first matrix). This operation also supports nary inputs, i.e., more than 2 input matrices. | Input: (X <matrix>, Y <matrix>) <br/>Output: <matrix> <br/> X and Y are matrices, where the number of columns in X and the number of columns in Y are the same. | A = matrix(1, rows=2,cols=3) <br/> B = matrix(2, rows=2,cols=3) <br/> C = rbind(A,B) <br/> print("Dimensions of C: " + nrow(C) + " X " + ncol(C)) <br/> Output: <br/> Dimensions of C: 4 X 3
+removeEmpty() | Removes all empty rows or columns from the input matrix target X according to the specified margin. The optional select vector F specifies selected rows or columns; if not provided, the semantics are F=(rowSums(X!=0)>0) and F=(colSums(X!=0)>0) for removeEmpty "rows" and "cols", respectively. The optional empty.return flag indicates if a row or column of zeros should be returned for empty inputs. | Input : (target= X <matrix>, margin="..."\[, select=F\]\[, empty.return=TRUE\]) <br/> Output : <matrix> <br/> Valid values for margin are "rows" or "cols". | A = removeEmpty(target=X, margin="rows", select=F)
replace() | Creates a copy of input matrix X, where all values that are equal to the scalar pattern s1 are replaced with the scalar replacement s2. | Input : (target= X <matrix>, pattern=<scalar>, replacement=<scalar>) <br/> Output : <matrix> <br/> If s1 is NaN, then all NaN values of X are treated as equal and hence replaced with s2. Positive and negative infinity are treated as different values. | A = replace(target=X, pattern=s1, replacement=s2)
rev() | Reverses the rows in a matrix | Input : (<matrix>) <br/> Output : <matrix> | <span style="white-space: nowrap;">A = matrix("1 2 3 4", rows=2, cols=2)</span> <br/> <span style="white-space: nowrap;">B = matrix("1 2 3 4", rows=4, cols=1)</span> <br/> <span style="white-space: nowrap;">C = matrix("1 2 3 4", rows=1, cols=4)</span> <br/> revA = rev(A) <br/> revB = rev(B) <br/> revC = rev(C) <br/> Matrix revA: [[3, 4], [1, 2]]<br/> Matrix revB: [[4], [3], [2], [1]]<br/> Matrix revC: [[1, 2, 3, 4]]<br/>
seq() | Creates a single column vector with values starting from <from>, to <to>, in increments of <increment> | Input: (<from>, <to>, <increment>) <br/> Output: <matrix> | S = seq (10, 200, 10)
sum() | Sum of all cells in matrix | Input: matrix <br/> Output: scalar | sum(X)
-
+upper.tri() | Selects the upper triangular part of a matrix, configurable to include the diagonal and return values or ones. | Input : (target= X <matrix> \[, diag=FALSE\]\[, values=FALSE\]) <br/> Output : <matrix> | A = upper.tri(target=X, diag=TRUE, values=TRUE)
### Matrix and/or Scalar Comparison Built-In Functions
@@ -664,6 +665,7 @@ Function | Description | Parameters | Example
pmin() <br/> pmax() | "parallel min/max".<br/> Return cell-wise minimum/maximum. If the second input is a scalar then it is compared against all cells in the first input. | Input: (<matrix>, <matrix>), or (<matrix>, <scalar>) <br/> Output: matrix | pmin(X,Y) <br/> pmax(X,y)
rowIndexMax() | Row-wise computation -- for each row, find the max value, and return its column index. | Input: (matrix) <br/> Output: (n x 1) matrix | rowIndexMax(X)
rowIndexMin() | Row-wise computation -- for each row, find the minimum value, and return its column index. | Input: (matrix) <br/> Output: (n x 1) matrix | rowIndexMin(X)
+xor() | Boolean XOR operation with the following cell-wise semantics: (X!=0) XOR (Y!=0). | Input: matrices or scalars <br/> Output: matrix or scalar | xor(X, Y)
ppred() | "parallel predicate".<br/> The relational operator specified in the third argument is cell-wise applied to input matrices. If the second argument is a scalar, then it is used against all cells in the first argument. <br/> **NOTE: ppred() has been replaced by the relational operators, so its use is discouraged.**| Input: (<matrix>, <matrix>, <string with relational operator>), or <br/> (<matrix>, <scalar>, <string with relational operator>) <br/> Output: matrix | ppred(X,Y,"<") <br/> ppred(X,y,"<")
### Casting Built-In Functions
@@ -1544,6 +1546,7 @@ print() | Prints a scalar variable. The print() function allows printf-style for
stop() | Halts the execution of DML program by printing the message that is passed in as the argument. <br/> Note that the use of stop() is not allowed inside a parfor loop. | Input: (<scalar>) | stop("Inputs to DML program are invalid") <br/> stop("Class labels must be either -1 or +1")
assert() | Halts the execution of DML program if the boolean argument doesnot evaluate to TRUE. <br/> Note that the use of assert() is not allowed inside a parfor loop. | Input: (<scalar of type boolean>) | assert(1 != 2)
order() | Sort a column of the matrix X in decreasing/increasing order and return either index (index.return=TRUE) or data (index.return=FALSE). | Input: (target=X, by=column, decreasing, index.return) | order(X, by=1, decreasing=FALSE, index.return=FALSE)
+ifelse() | Conditional selection of inputs or input cells (if the first input is true or non-zero, select the second otherwise the third input). If all inputs are scalars, the output is a scalar; otherwise a matrix of same size as the input matrices. | Input: three inputs, any combinations of matrices and scalars | ifelse(x, Y, Z) <br/> ifelse(X, Y, -1)
## Frames