Merge pull request #5 from stefan-zobel/1.4.4-SNAPSHOT

Merge branch 1.4.4-Snapshot

README.md

@@ -30,7 +30,7 @@ Matrices in *JAMU* are internally backed by 1-dimensional Java arrays in column-
 <dependency>
     <groupId>net.sourceforge.streamsupport</groupId>
     <artifactId>jamu</artifactId>
-    <version>1.4.3</version>
+    <version>1.4.4-SNAPSHOT</version>
 </dependency>
 ```
 

pom.xml

@@ -4,7 +4,7 @@
     <groupId>net.sourceforge.streamsupport</groupId>
     <artifactId>jamu</artifactId>
     <packaging>jar</packaging>
-    <version>1.4.3</version>
+    <version>1.4.4</version>
     <name>JAMU</name>
     <description>Java Matrix Utilities built on top of Intel MKL</description>
     <url>https://github.com/stefan-zobel/JAMU/</url>

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

@@ -179,8 +179,7 @@ static void checkSameRows(Dimensions A, Dimensions B) {
 
     static void checkSameCols(Dimensions A, Dimensions B) {
         if (A.numColumns() != B.numColumns()) {
-            throw new IndexOutOfBoundsException(
-                    "A.numColumns() != B.numColumns() (" + A.numColumns() + " != " + B.numColumns() + ")");
+            throw getSameColsException(A, B);
         }
     }
 
@@ -318,6 +317,11 @@ static void throwInconsistentRowLengths(int cols, int rowIdx, int rowLength) {
                 + " has length " + rowLength + ")");
     }
 
+    static IndexOutOfBoundsException getSameColsException(Dimensions A, Dimensions B) {
+        return new IndexOutOfBoundsException(
+                "A.numColumns() != B.numColumns() (" + A.numColumns() + " != " + B.numColumns() + ")");
+    }
+
     private Checks() {
         throw new AssertionError();
     }

src/main/java/net/jamu/matrix/ComplexMatrixD.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.
@@ -385,6 +385,22 @@ public interface ComplexMatrixD extends MatrixDimensions, ComplexMatrixDConduct
      */
     ComplexMatrixD setInplace(ComplexMatrixD other);
 
+    /**
+     * Overwrite the content of the column indexed by {@code colIdx} with the
+     * content of the column vector {@code colVector} where {@code colVector}
+     * must have dimension {@code this.numRows() x 1}.
+     * 
+     * @param colIdx
+     *            index of the column that will be overwritten by the content of
+     *            {@code colVector}
+     * @param colVector
+     *            a column vector that has the same number of rows as this
+     *            matrix
+     * @return this matrix (mutated)
+     * @since 1.4.4
+     */
+    ComplexMatrixD setColumnInplace(int colIdx, ComplexMatrixD colVector);
+
     /**
      * Let {@code this} be a m-by-n matrix and let {@code B} be a j-by-k matrix.
      * Set the entries on and above the main diagonal in {@code this} matrix

src/main/java/net/jamu/matrix/ComplexMatrixDBase.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.
@@ -435,6 +435,16 @@ public ComplexMatrixD submatrix(int r0, int c0, int r1, int c1, ComplexMatrixD B
         return B;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public ComplexMatrixD setColumnInplace(int colIdx, ComplexMatrixD colVector) {
+        checkIndex(0, colIdx);
+        Checks.checkCommensurateColVector(this, colVector);
+        return setSubmatrixInplace(0, colIdx, colVector, 0, 0, colVector.endRow(), 0);
+    }
+
     /**
      * {@inheritDoc}
      */

src/main/java/net/jamu/matrix/ComplexMatrixF.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.
@@ -385,6 +385,22 @@ public interface ComplexMatrixF extends MatrixDimensions, ComplexMatrixFConduct
      */
     ComplexMatrixF setInplace(ComplexMatrixF other);
 
+    /**
+     * Overwrite the content of the column indexed by {@code colIdx} with the
+     * content of the column vector {@code colVector} where {@code colVector}
+     * must have dimension {@code this.numRows() x 1}.
+     * 
+     * @param colIdx
+     *            index of the column that will be overwritten by the content of
+     *            {@code colVector}
+     * @param colVector
+     *            a column vector that has the same number of rows as this
+     *            matrix
+     * @return this matrix (mutated)
+     * @since 1.4.4
+     */
+    ComplexMatrixF setColumnInplace(int colIdx, ComplexMatrixF colVector);
+
     /**
      * Let {@code this} be a m-by-n matrix and let {@code B} be a j-by-k matrix.
      * Set the entries on and above the main diagonal in {@code this} matrix

src/main/java/net/jamu/matrix/ComplexMatrixFBase.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.
@@ -435,6 +435,16 @@ public ComplexMatrixF submatrix(int r0, int c0, int r1, int c1, ComplexMatrixF B
         return B;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public ComplexMatrixF setColumnInplace(int colIdx, ComplexMatrixF colVector) {
+        checkIndex(0, colIdx);
+        Checks.checkCommensurateColVector(this, colVector);
+        return setSubmatrixInplace(0, colIdx, colVector, 0, 0, colVector.endRow(), 0);
+    }
+
     /**
      * {@inheritDoc}
      */

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

@@ -408,6 +408,68 @@ public static ComplexMatrixF identityComplexF(int n) {
         return m;
     }
 
+    /**
+     * Create a {@code (1, 1)} MatrixD matrix holding the given {@code scalar}.
+     * 
+     * @param scalar
+     *            the scalar value in the created {@code 1 x 1} matrix
+     * @return a scalar MatrixD matrix of dimension {@code (1, 1)} with the
+     *         given {@code scalar} value
+     * @since 1.4.4
+     */
+    public static MatrixD scalarD(double scalar) {
+        return new SimpleMatrixD(1, 1, new double[] { scalar });
+    }
+
+    /**
+     * Create a {@code (1, 1)} MatrixF matrix holding the given {@code scalar}.
+     * 
+     * @param scalar
+     *            the scalar value in the created {@code 1 x 1} matrix
+     * @return a scalar MatrixF matrix of dimension {@code (1, 1)} with the
+     *         given {@code scalar} value
+     * @since 1.4.4
+     */
+    public static MatrixF scalarF(float scalar) {
+        return new SimpleMatrixF(1, 1, new float[] { scalar });
+    }
+
+    /**
+     * Create a {@code (1, 1)} ComplexMatrixD matrix holding the given complex
+     * scalar {@code (reVal, imVal)}.
+     * 
+     * @param reVal
+     *            real part of the complex scalar in the created {@code 1 x 1}
+     *            matrix
+     * @param imVal
+     *            imaginary part of the complex scalar in the created
+     *            {@code 1 x 1} matrix
+     * @return a scalar ComplexMatrixD matrix of dimension {@code (1, 1)} with
+     *         the given complex scalar {@code (reVal, imVal)} value
+     * @since 1.4.4
+     */
+    public static ComplexMatrixD scalarComplexD(double reVal, double imVal) {
+        return new SimpleComplexMatrixD(1, 1, new double[] { reVal, imVal });
+    }
+
+    /**
+     * Create a {@code (1, 1)} ComplexMatrixF matrix holding the given complex
+     * scalar {@code (reVal, imVal)}.
+     * 
+     * @param reVal
+     *            real part of the complex scalar in the created {@code 1 x 1}
+     *            matrix
+     * @param imVal
+     *            imaginary part of the complex scalar in the created
+     *            {@code 1 x 1} matrix
+     * @return a scalar ComplexMatrixF matrix of dimension {@code (1, 1)} with
+     *         the given complex scalar {@code (reVal, imVal)} value
+     * @since 1.4.4
+     */
+    public static ComplexMatrixF scalarComplexF(float reVal, float imVal) {
+        return new SimpleComplexMatrixF(1, 1, new float[] { reVal, imVal });
+    }
+
     /**
      * Create a quadratic diagonal matrix whose main diagonal contains the
      * entries provided in the {@code diagonal} array.

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

@@ -339,6 +339,22 @@ public interface MatrixD extends MatrixDimensions, MatrixDConduct {
      */
     MatrixD setInplace(MatrixD other);
 
+    /**
+     * Overwrite the content of the column indexed by {@code colIdx} with the
+     * content of the column vector {@code colVector} where {@code colVector}
+     * must have dimension {@code this.numRows() x 1}.
+     * 
+     * @param colIdx
+     *            index of the column that will be overwritten by the content of
+     *            {@code colVector}
+     * @param colVector
+     *            a column vector that has the same number of rows as this
+     *            matrix
+     * @return this matrix (mutated)
+     * @since 1.4.4
+     */
+    MatrixD setColumnInplace(int colIdx, MatrixD colVector);
+
     /**
      * Let {@code this} be a m-by-n matrix and let {@code B} be a j-by-k matrix.
      * Set the entries on and above the main diagonal in {@code this} matrix
@@ -694,6 +710,26 @@ public interface MatrixD extends MatrixDimensions, MatrixDConduct {
      */
     MatrixD mapInplace(DFunction f);
 
+    /**
+     * If {@code B} is a column vector with the same number of rows as this
+     * matrix a "stretched" version of {@code B} with a compatible number of
+     * columns (where the "additional" columns are simple copies of the original
+     * {@code B} column vector) gets added to this matrix inplace. If
+     * {@code B}'s dimension is the same as the dimension of this matrix this
+     * operation behaves exactly like {@link #addInplace(MatrixD)}. Any other
+     * dimension of {@code B} is treated as a mismatch and results in an
+     * IndexOutOfBoundsException.
+     * 
+     * @param B
+     *            a column vector with dimension {@code (this.numRows() x 1)}
+     * @return this matrix (mutated)
+     * @throws IndexOutOfBoundsException
+     *             if the dimension of {@code B} doesn't match in the sense
+     *             described above
+     * @since 1.4.4
+     */
+    MatrixD addBroadcastedVectorInplace(MatrixD B);
+
     /**
      * 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

@@ -172,6 +172,31 @@ public MatrixD add(double alpha, MatrixD B, MatrixD C) {
         return C;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public MatrixD addBroadcastedVectorInplace(MatrixD B) {
+        Checks.checkSameRows(this, B);
+        if (this.numColumns() == B.numColumns()) {
+            return addInplace(B);
+        }
+        if (B.numColumns() == 1) {
+            double[] _a = a;
+            double[] _b = B.getArrayUnsafe();
+            int cols_ = cols;
+            int rows_ = rows;
+            for (int col = 0; col < cols_; ++col) {
+                for (int row = 0; row < rows_; ++row) {
+                    _a[idx(row, col)] += _b[row];
+                }
+            }
+            return this;
+        }
+        // incompatible dimensions
+        throw Checks.getSameColsException(this, B);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -394,6 +419,16 @@ public MatrixD submatrix(int r0, int c0, int r1, int c1, MatrixD B, int rb, int
         return B;
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public MatrixD setColumnInplace(int colIdx, MatrixD colVector) {
+        checkIndex(0, colIdx);
+        Checks.checkCommensurateColVector(this, colVector);
+        return setSubmatrixInplace(0, colIdx, colVector, 0, 0, colVector.endRow(), 0);
+    }
+
     /**
      * {@inheritDoc}
      */
@@ -1047,6 +1082,14 @@ public MatrixD map(DFunction f) {
         return copy().mapInplace(f);
     }
 
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public MatrixD plusBroadcastedVector(MatrixD B) {
+        return copy().addBroadcastedVectorInplace(B);
+    }
+
     /**
      * {@inheritDoc}
      */

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

@@ -376,6 +376,27 @@ public interface MatrixDConduct {
      */
     MatrixD map(DFunction f);
 
+    /**
+     * If {@code B} is a column vector with the same number of rows as this
+     * matrix a "stretched" version of {@code B} with a compatible number of
+     * columns (where the "additional" columns are simple copies of the original
+     * {@code B} column vector) gets added to a copy of this matrix. If
+     * {@code B}'s dimension is the same as the dimension of this matrix this
+     * operation behaves exactly like {@link #plus(MatrixD)}. Any other
+     * dimension of {@code B} is treated as a mismatch and results in an
+     * IndexOutOfBoundsException.
+     * 
+     * @param B
+     *            a column vector with dimension {@code (this.numRows() x 1)}
+     * @return a copy of this matrix where the column vector {@code B} has been
+     *         added as described above
+     * @throws IndexOutOfBoundsException
+     *             if the dimension of {@code B} doesn't match in the sense
+     *             described above
+     * @since 1.4.4
+     */
+    MatrixD plusBroadcastedVector(MatrixD B);
+
     /**
      * 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