Masks

build.gradle

@@ -83,6 +83,7 @@ subprojects {
         compile 'com.google.code.findbugs:jsr305:3.0.2' // @Nullable
 
         testImplementation( 'org.junit.jupiter:junit-jupiter-api:5.4.0' )
+        testImplementation( 'org.junit.jupiter:junit-jupiter-params:5.4.0' )
         testRuntimeOnly( 'org.junit.jupiter:junit-jupiter-engine:5.4.0' )
 
         ['core','generator-annprocess'].each { String a->

main/autocode/src/org/ejml/GenerateJavaCode32.java

@@ -54,6 +54,20 @@ public GenerateJavaCode32() {
         prefix32.add("FUnary");
         prefix64.add("DBinary");
         prefix32.add("FBinary");
+        prefix64.add("DMonoid");
+        prefix32.add("FMonoid");
+        prefix64.add("DSemiRing");
+        prefix32.add("FSemiRing");
+        prefix64.add("DMonoids");
+        prefix32.add("FMonoids");
+        prefix64.add("DSemiRings");
+        prefix32.add("FSemiRings");
+        prefix64.add("PrimitiveDMask");
+        prefix32.add("PrimitiveFMask");
+        prefix64.add("SparseDMask");
+        prefix32.add("SparseFMask");
+        prefix64.add("DMasks");
+        prefix32.add("FMasks");
         prefix64.add("DScalar");
         prefix32.add("FScalar");
         prefix64.add("DMatrix");
@@ -93,6 +107,11 @@ public GenerateJavaCode32() {
         converter.replacePattern("DScalar", "FScalar");
         converter.replacePattern("DUnary", "FUnary");
         converter.replacePattern("DBinary", "FBinary");
+        converter.replacePattern("DMonoid", "FMonoid");
+        converter.replacePattern("DSemiRing", "FSemiRing");
+        converter.replacePattern("SparseDMask", "SparseFMask");
+        converter.replacePattern("PrimitiveDMask", "PrimitiveFMask");
+        converter.replacePattern("DMasks", "FMasks");
         converter.replacePattern("ConvertD", "ConvertF");
         converter.replacePattern("DGrowArray", "FGrowArray");
         converter.replacePattern("DMatrix", "FMatrix");
@@ -133,6 +152,8 @@ public static void main(String[] args ) {
                 "main/ejml-core/test/org/ejml/data",
                 "main/ejml-core/src/org/ejml/ops",
                 "main/ejml-core/test/org/ejml/ops",
+                "main/ejml-core/src/org/ejml/masks",
+                "main/ejml-core/test/org/ejml/masks",
                 "main/ejml-experimental/src/org/ejml/dense/row/decomposition/bidiagonal/"
         };
 

main/ejml-core/src/org/ejml/data/DMatrixRMaj.java

@@ -333,6 +333,13 @@ public void zero() {
         Arrays.fill(data, 0, getNumElements(), 0.0);
     }
 
+    /**
+     * Sets all elements equal to the specified value.
+     */
+    public void fill(double value) {
+        Arrays.fill(data, 0, getNumElements(), value);
+    }
+
     /**
      * Creates and returns a matrix which is idential to this one.
      *

main/ejml-core/src/org/ejml/masks/DMasks.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2009-2020, Peter Abeles. All Rights Reserved.
+ *
+ * This file is part of Efficient Java Matrix Library (EJML).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ejml.masks;
+
+import org.ejml.data.*;
+
+/**
+ * Helper class to get the corresponding mask builder based on a matrix or primitive array
+ */
+public class DMasks {
+    public static PrimitiveDMask.Builder builder(double[] values) {
+        return new PrimitiveDMask.Builder(values);
+    }
+
+    public static PrimitiveDMask.Builder builder(DMatrixD1 matrix) {
+        return new PrimitiveDMask.Builder(matrix.data).withNumCols(matrix.numCols);
+    }
+
+    public static MaskBuilder builder(DMatrixSparseCSC matrix, boolean structural){
+        if (structural) {
+            return new SparseStructuralMask.Builder(matrix);
+        }
+        else {
+            return new SparseDMask.Builder(matrix);
+        }
+    }
+}

main/ejml-core/src/org/ejml/masks/Mask.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright (c) 2009-2020, Peter Abeles. All Rights Reserved.
+ *
+ * This file is part of Efficient Java Matrix Library (EJML).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ejml.masks;
+
+
+import org.ejml.MatrixDimensionException;
+import org.ejml.data.Matrix;
+
+/**
+ * Mask used for specifying which matrix entries should be computed
+ */
+public abstract class Mask {
+    // useful for sparse matrices, as actual negation would be costly and result in dense masks
+    public final boolean negated;
+
+    // whether the result should replace the initial result (otherwise merge them)
+    // same as the "GrB_REPLACE" descriptor
+    public final boolean replace;
+
+    public Mask(boolean negated, boolean replace) {
+        this.negated = negated;
+        this.replace = replace;
+    }
+
+    public abstract boolean isSet(int row, int col);
+
+    public abstract int getNumCols();
+
+    public abstract int getNumRows();
+
+    public void print() {
+        String result = "";
+        for (int row = 0; row < getNumRows(); row++) {
+            for (int col = 0; col < getNumCols(); col++) {
+                result += isSet(row, col) ? "+ " : "- ";
+            }
+            result += System.lineSeparator();
+        }
+
+        System.out.println(result);
+    };
+
+    /**
+     * Checks whether the dimensions of the mask and matrix match
+     * @param matrix the mask is applied to
+     */
+    public void compatible(Matrix matrix) {
+        if (matrix.getNumCols() != getNumCols() || matrix.getNumRows() != getNumRows()) {
+            throw new MatrixDimensionException(String.format(
+                    "Mask of (%d, %d) cannot be applied for matrix (%d, %d)",
+                    getNumRows(), getNumCols(), matrix.getNumCols(), matrix.getNumCols()
+            ));
+        }
+    }
+
+    // TODO: use an Iterator as it should be faster as stepping can be used -> no need to call for each entry?
+    //      Problem .. dense matrices are row-based, whereas existing sparse matrix format is column based
+    //public abstract Iterator<BMatrixSparseCSC.CoordinateBoolValue>
+}

main/ejml-core/src/org/ejml/masks/MaskBuilder.java

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) 2009-2020, Peter Abeles. All Rights Reserved.
+ *
+ * This file is part of Efficient Java Matrix Library (EJML).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ejml.masks;
+
+public abstract class MaskBuilder<MASK extends Mask> {
+    protected boolean negated = false;
+    protected boolean replace = true;
+
+    public MaskBuilder<MASK> withNegated(boolean negated) {
+        this.negated = negated;
+        return this;
+    }
+
+    public MaskBuilder<MASK> withReplace(boolean replace) {
+        this.replace = replace;
+        return this;
+    }
+
+    public abstract MASK build();
+}

main/ejml-core/src/org/ejml/masks/PrimitiveDMask.java

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2009-2020, Peter Abeles. All Rights Reserved.
+ *
+ * This file is part of Efficient Java Matrix Library (EJML).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ejml.masks;
+
+import org.ejml.MatrixDimensionException;
+
+public class PrimitiveDMask extends Mask {
+    // TODO: Check if creating dense boolean mask is worth it (currently converting to boolean on the fly)
+    private final double[] values;
+    // alternatively declare extra separate masks for primitive and dense DMatrix
+    private final int numCols;
+    //
+    private final double zeroElement;
+
+    public PrimitiveDMask(double[] values, int numCols, boolean negated, boolean replace, double zeroElement) {
+        // for dense structures they cannot be used for structural masks
+        super(negated, replace);
+        this.values = values;
+        this.numCols = numCols;
+        this.zeroElement = zeroElement;
+    }
+
+    @Override
+    public boolean isSet(int row, int col) {
+        // XOR as negated flips the mask flag
+        return negated ^ (values[row * numCols + col] != zeroElement);
+    }
+
+    @Override
+    public int getNumCols() {
+        return numCols;
+    }
+
+    @Override
+    public int getNumRows() {
+        return values.length / numCols;
+    }
+
+    public boolean isSet(int index) {
+        return negated ^ (values[index] != zeroElement);
+    }
+
+    public void compatible(double[] vector) {
+        if (vector.length != values.length) {
+            throw new MatrixDimensionException(String.format(
+                    "Mask of length %d cannot be applied to vector of lenght %d",
+                    values.length, vector.length
+            ));
+        }
+    }
+
+    public static class Builder extends MaskBuilder<PrimitiveDMask> {
+        private double[] values;
+        private int numCols = 1;
+        private double zeroElement = 0;
+
+        public Builder(double[] values) {
+            this.values = values;
+        }
+
+        public Builder withNumCols(int numCols) {
+            this.numCols = numCols;
+            return this;
+        }
+
+        public Builder withZeroElement(double zeroElement) {
+            this.zeroElement = zeroElement;
+            return this;
+        }
+
+        @Override
+        public PrimitiveDMask build() {
+            return new PrimitiveDMask(values, numCols, negated, replace, zeroElement);
+        }
+    }
+}
+

main/ejml-core/src/org/ejml/masks/SparseDMask.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2009-2020, Peter Abeles. All Rights Reserved.
+ *
+ * This file is part of Efficient Java Matrix Library (EJML).
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.ejml.masks;
+
+import org.ejml.data.DMatrixSparseCSC;
+
+public class SparseDMask extends Mask {
+    protected final DMatrixSparseCSC matrix;
+    protected final double zeroElement;
+
+    public SparseDMask(DMatrixSparseCSC matrix, boolean negated, boolean replace, double zeroElement) {
+        super(negated, replace);
+        this.matrix = matrix;
+        this.zeroElement = zeroElement;
+    }
+
+    @Override
+    public boolean isSet(int row, int col) {
+        return negated ^ (matrix.unsafe_get(row, col) != zeroElement);
+    }
+
+    @Override
+    public int getNumCols() {
+        return matrix.numCols;
+    }
+
+    @Override
+    public int getNumRows() {
+        return matrix.numRows;
+    }
+
+    public static class Builder extends MaskBuilder<SparseDMask> {
+        private DMatrixSparseCSC matrix;
+        private double zeroElement = 0;
+
+        public Builder(DMatrixSparseCSC matrix) {
+            this.matrix = matrix;
+        }
+
+        public Builder withZeroElement(double zeroElement) {
+            this.zeroElement = zeroElement;
+            return this;
+        }
+
+        @Override
+        public SparseDMask build() {
+            return new SparseDMask(matrix, negated, replace, zeroElement);
+        }
+    }
+}