Merge 1.4.2 branch

pom.xml

@@ -4,7 +4,7 @@
     <groupId>net.sourceforge.streamsupport</groupId>
     <artifactId>jamu</artifactId>
     <packaging>jar</packaging>
-    <version>1.4.1</version>
+    <version>1.4.2-SNAPSHOT</version>
     <name>JAMU</name>
     <description>Java Matrix Utilities built on top of Intel MKL</description>
     <url>https://github.com/stefan-zobel/JAMU/</url>
@@ -46,25 +46,22 @@
         <plugins>
             <plugin>
                 <artifactId>maven-compiler-plugin</artifactId>
-                <version>3.8.1</version>
+                <version>3.12.1</version>
                 <configuration>
-                    <source>1.7</source>
-                    <target>1.7</target>
+                    <source>1.8</source>
+                    <target>1.8</target>
                 </configuration>
             </plugin>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
-                <version>3.2.0</version>
+                <version>3.5.0</version>
                 <executions>
                     <execution>
                         <id>attach-javadocs</id>
                         <goals>
                             <goal>jar</goal>
                         </goals>
-                        <configuration>
-                            <doclint>none</doclint>
-                        </configuration>
                     </execution>
                 </executions>
             </plugin>

src/main/java/net/jamu/matrix/ComplexMatrixD.java

@@ -638,7 +638,7 @@ public interface ComplexMatrixD extends MatrixDimensions, ComplexMatrixDConduct
     ComplexMatrixD expm();
 
     /**
-     * Hadamard product {@code C = A} ∘ {@code B} (also known as
+     * Hadamard product {@code C = A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B

src/main/java/net/jamu/matrix/ComplexMatrixDConduct.java

@@ -339,7 +339,7 @@ public interface ComplexMatrixDConduct {
     ComplexMatrixD inverse();
 
     /**
-     * Hadamard product {@code A} ∘ {@code B} (also known as
+     * Hadamard product {@code A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B

src/main/java/net/jamu/matrix/ComplexMatrixF.java

@@ -638,7 +638,7 @@ public interface ComplexMatrixF extends MatrixDimensions, ComplexMatrixFConduct
     ComplexMatrixF expm();
 
     /**
-     * Hadamard product {@code C = A} ∘ {@code B} (also known as
+     * Hadamard product {@code C = A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B

src/main/java/net/jamu/matrix/ComplexMatrixFConduct.java

@@ -339,7 +339,7 @@ public interface ComplexMatrixFConduct {
     ComplexMatrixF inverse();
 
     /**
-     * Hadamard product {@code A} ∘ {@code B} (also known as
+     * Hadamard product {@code A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B

src/main/java/net/jamu/matrix/DFunction.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2018 Stefan Zobel
+ *
+ * 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 net.jamu.matrix;
+
+/**
+ * Represents a function that accepts one {@code double} argument and produces a
+ * {@code double} result.
+ *
+ * @since 1.4.2
+ */
+@FunctionalInterface
+public interface DFunction {
+    /**
+     * Applies this function to the given argument.
+     *
+     * @param x
+     *            the function argument
+     * @return the function result
+     */
+    double apply(double x);
+}

src/main/java/net/jamu/matrix/FFunction.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2018 Stefan Zobel
+ *
+ * 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 net.jamu.matrix;
+
+/**
+ * Represents a function that accepts one {@code float} argument and produces a
+ * {@code float} result.
+ *
+ * @since 1.4.2
+ */
+@FunctionalInterface
+public interface FFunction {
+    /**
+     * Applies this function to the given argument.
+     *
+     * @param x
+     *            the function argument
+     * @return the function result
+     */
+    float apply(float x);
+}

src/main/java/net/jamu/matrix/Matrices.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019, 2023 Stefan Zobel
+ * Copyright 2019, 2024 Stefan Zobel
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -3499,6 +3499,34 @@ public static ComplexMatrixF sumRows(ComplexMatrixF A) {
         return s;
     }
 
+    /**
+     * Returns a {@code 1 x A.numColumns()} matrix that contains the average of
+     * the row sums of matrix {@code A}.
+     * 
+     * @param A
+     *            the matrix whose average of the row sums should be computed
+     * @return a new matrix of dimension {@code 1 x A.numColumns()} that
+     *         contains the average of the row sums of matrix {@code A}
+     * @since 1.4.2
+     */
+    public static MatrixD rowsAverage(MatrixD A) {
+        return sumRows(A).scaleInplace(A.numRows());
+    }
+
+    /**
+     * Returns a {@code 1 x A.numColumns()} matrix that contains the average of
+     * the row sums of matrix {@code A}.
+     * 
+     * @param A
+     *            the matrix whose average of the row sums should be computed
+     * @return a new matrix of dimension {@code 1 x A.numColumns()} that
+     *         contains the average of the row sums of matrix {@code A}
+     * @since 1.4.2
+     */
+    public static MatrixF rowsAverage(MatrixF A) {
+        return sumRows(A).scaleInplace(A.numRows());
+    }
+
     /**
      * Returns a {@code A.numRows() x 1} matrix that contains the column sums of
      * matrix {@code A}.
@@ -3617,6 +3645,34 @@ public static ComplexMatrixF sumColumns(ComplexMatrixF A) {
         return s;
     }
 
+    /**
+     * Returns a {@code A.numRows() x 1} matrix that contains the average of the
+     * column sums of matrix {@code A}.
+     * 
+     * @param A
+     *            the matrix whose average of column sums should be computed
+     * @return a new matrix of dimension {@code A.numRows() x 1} that contains
+     *         the average of the column sums of matrix {@code A}
+     * @since 1.4.2
+     */
+    public static MatrixD colsAverage(MatrixD A) {
+        return sumColumns(A).scaleInplace(A.numColumns());
+    }
+
+    /**
+     * Returns a {@code A.numRows() x 1} matrix that contains the average of the
+     * column sums of matrix {@code A}.
+     * 
+     * @param A
+     *            the matrix whose average of column sums should be computed
+     * @return a new matrix of dimension {@code A.numRows() x 1} that contains
+     *         the average of the column sums of matrix {@code A}
+     * @since 1.4.2
+     */
+    public static MatrixF colsAverage(MatrixF A) {
+        return sumColumns(A).scaleInplace(A.numColumns());
+    }
+
     private static boolean checkApproxEqualArgs(MatrixDimensions A, MatrixDimensions B, double relTol, double absTol) {
         if (relTol < 0.0 || Double.isNaN(relTol) || Double.isInfinite(relTol)) {
             throw new IllegalArgumentException("illegal relTol : " + relTol);

src/main/java/net/jamu/matrix/MatrixD.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019, 2023 Stefan Zobel
+ * Copyright 2019, 2024 Stefan Zobel
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -604,7 +604,7 @@ public interface MatrixD extends MatrixDimensions, MatrixDConduct {
     MatrixD expm();
 
     /**
-     * Hadamard product {@code C = A} ∘ {@code B} (also known as
+     * Hadamard product {@code C = A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B
@@ -683,6 +683,17 @@ public interface MatrixD extends MatrixDimensions, MatrixDConduct {
      */
     MatrixD clampInplace(double min, double max);
 
+    /**
+     * {@code A = f(A)} where the scalar function {@code f} is applied to each
+     * element of {@code A}.
+     * 
+     * @param f
+     *            the scalar function to apply to each element of this matrix
+     * @return this matrix (mutated)
+     * @since 1.4.2
+     */
+    MatrixD mapInplace(DFunction f);
+
     /**
      * Set all elements <code>|x<sub>ij</sub>| &le; k * 2<sup>-53</sup></code>
      * ({@code k} times the machine epsilon for doubles) to {@code 0.0} where

src/main/java/net/jamu/matrix/MatrixDBase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019, 2023 Stefan Zobel
+ * Copyright 2019, 2024 Stefan Zobel
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -657,6 +657,18 @@ public MatrixD clampInplace(double min, double max) {
         return this;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public MatrixD mapInplace(DFunction f) {
+        double[] _a = a;
+        for (int i = 0; i < _a.length; ++i) {
+            _a[i] = f.apply(_a[i]);
+        }
+        return this;
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -1027,6 +1039,14 @@ public MatrixD abs() {
         return m;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public MatrixD map(DFunction f) {
+        return copy().mapInplace(f);
+    }
+
     /**
      * {@inheritDoc}
      */

src/main/java/net/jamu/matrix/MatrixDConduct.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2020, 2023 Stefan Zobel
+ * Copyright 2020, 2024 Stefan Zobel
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -330,7 +330,7 @@ public interface MatrixDConduct {
     MatrixD inverse();
 
     /**
-     * Hadamard product {@code A} ∘ {@code B} (also known as
+     * Hadamard product {@code A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B
@@ -341,7 +341,7 @@ public interface MatrixDConduct {
     MatrixD hadamard(MatrixD B);
 
     /**
-     * <code>A</code> &SmallCircle; <code>B<sup>T</sup></code> Hadamard
+     * <code>A</code> \u2218 <code>B<sup>T</sup></code> Hadamard
      * multiplication (also known as element-wise product) between this matrix
      * ({@code A}) and the transpose of {@code B} (<code>B<sup>T</sup></code>).
      * 
@@ -353,7 +353,7 @@ public interface MatrixDConduct {
     MatrixD hadamardTransposed(MatrixD B);
 
     /**
-     * <code>A<sup>T</sup></code> &SmallCircle; <code>B</code> Hadamard
+     * <code>A<sup>T</sup></code> \u2218 <code>B</code> Hadamard
      * multiplication (also known as element-wise product) between this matrix
      * ({@code A}) transposed (<code>A<sup>T</sup></code>) and {@code B}.
      * 
@@ -364,6 +364,18 @@ public interface MatrixDConduct {
      */
     MatrixD transposedHadamard(MatrixD B);
 
+    /**
+     * Returns {@code f(A)} where the scalar function {@code f} is applied to
+     * each element on a copy of {@code A}.
+     * 
+     * @param f
+     *            the scalar function to apply to each element on a copy of this
+     *            matrix
+     * @return a copy of this matrix where f has been applied to each element
+     * @since 1.4.2
+     */
+    MatrixD map(DFunction f);
+
     /**
      * Reshapes this matrix into a new matrix of dimension {@code rows x cols}
      * where the elements in this matrix are read in Fortran-style column-major

src/main/java/net/jamu/matrix/MatrixF.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019, 2023 Stefan Zobel
+ * Copyright 2019, 2024 Stefan Zobel
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -604,7 +604,7 @@ public interface MatrixF extends MatrixDimensions, MatrixFConduct {
     MatrixF expm();
 
     /**
-     * Hadamard product {@code C = A} ∘ {@code B} (also known as
+     * Hadamard product {@code C = A} \u2218 {@code B} (also known as
      * element-wise product) of this matrix (A) and B.
      * 
      * @param B
@@ -683,6 +683,17 @@ public interface MatrixF extends MatrixDimensions, MatrixFConduct {
      */
     MatrixF clampInplace(float min, float max);
 
+    /**
+     * {@code A = f(A)} where the scalar function {@code f} is applied to each
+     * element of {@code A}.
+     * 
+     * @param f
+     *            the scalar function to apply to each element of this matrix
+     * @return this matrix (mutated)
+     * @since 1.4.2
+     */
+    MatrixF mapInplace(FFunction f);
+
     /**
      * Set all elements <code>|x<sub>ij</sub>| &le; k * 2<sup>-24</sup></code>
      * ({@code k} times the machine epsilon for floats) to {@code 0.0f} where