Package org.djunits.util

Class ArrayMath

java.lang.Object
org.djunits.util.ArrayMath
public final class ArrayMath extends Object
Utility methods for element-wise arithmetic on primitive double[] arrays.

This class provides common operations such as addition, scaling (multiplying by a scalar), and the fused AXPY operation (out = a + alpha * b). Each operation is available in two forms:

Design & Performance Notes

  • Methods operate on primitive arrays to avoid boxing and reduce allocation overhead.
  • Simple indexed for-loops are used on purpose; modern JVMs can hoist bounds checks, unroll loops, and sometimes auto-vectorize tight loops on hot paths.
  • Procedural variants (...Into) allow output reuse to reduce GC pressure.
  • No special-casing for short arrays; on modern CPUs/JITs, well-structured loops scale efficiently.

Preconditions

  • All array parameters must be non-null.
  • Arrays participating in an operation must have identical lengths.

This class is not instantiable. Copyright (c) 2025-2026 Delft University of Technology, Jaffalaan 5, 2628 BX Delft, the Netherlands. All rights reserved. See for project information https://djunits.org. The DJUNITS project is distributed under a three-clause BSD-style license.

Author:
Alexander Verbraeck

  • Method Summary

    Modifier and Type
    Method
    Description
    static double[]
    abs(double[] a)
    Returns a new array with absolute values for each entry abs(a).
    static double[]
    add(double[] a, double c)
    Returns a new array equal to the element-wise sum with a constant a + c.
    static double[]
    add(double[] a, double[] b)
    Returns a new array equal to the element-wise sum a + b.
    static void
    addInto(double[] a, double[] b, double[] out)
    Computes the element-wise sum a + b and writes the result into out.
    static double[]
    axpy(double[] a, double[] b, double alpha)
    Returns a new array equal to the fused AXPY operation a + alpha * b.
    static void
    axpyInto(double[] a, double[] b, double alpha, double[] out)
    Computes the fused AXPY operation out = a + alpha * b and writes the result into out.
    static double[]
    divide(double[] a, double[] b)
    Returns a new array equal to the element-wise division a / b.
    static double[]
    multiply(double[] a, double[] b)
    Returns a new array equal to the element-wise multiplication a * b.
    static double[]
    reciprocal(double[] a)
    Returns a new array equal to the element-wise reciprocal 1 / a.
    static double[]
    scaleBy(double[] a, double alpha)
    Returns a new array equal to the element-wise scaled vector alpha * a.
    static void
    scaleInto(double[] a, double alpha, double[] out)
    Computes the element-wise scaling alpha * a and writes the result into out.
    static double[]
    subtract(double[] a, double[] b)
    Returns a new array equal to the element-wise difference a - b.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • add

      public static double[] add(double[] a, double[] b)
      Returns a new array equal to the element-wise sum a + b.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      Returns:
      a newly allocated array where out[i] = a[i] + b[i] for all indices
      Throws:
      NullPointerException - if a or b is null
      IllegalArgumentException - if a.length != b.length

    • add

      public static double[] add(double[] a, double c)
      Returns a new array equal to the element-wise sum with a constant a + c.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the left-hand array; must be non-null
      c - a constant to add to each element
      Returns:
      a newly allocated array where out[i] = a[i] + c for all indices
      Throws:
      NullPointerException - if a is null

    • subtract

      public static double[] subtract(double[] a, double[] b)
      Returns a new array equal to the element-wise difference a - b.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      Returns:
      a newly allocated array where out[i] = a[i] - b[i] for all indices
      Throws:
      NullPointerException - if a or b is null
      IllegalArgumentException - if a.length != b.length

    • scaleBy

      public static double[] scaleBy(double[] a, double alpha)
      Returns a new array equal to the element-wise scaled vector alpha * a.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations.

      Parameters:
      a - the input array; must be non-null
      alpha - the scalar multiplier
      Returns:
      a newly allocated array where out[i] = alpha * a[i] for all indices
      Throws:
      NullPointerException - if a is null

    • abs

      public static double[] abs(double[] a)
      Returns a new array with absolute values for each entry abs(a).

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations.

      Parameters:
      a - the input array; must be non-null
      Returns:
      a newly allocated array where out[i] = Math.abs(a[i]) for all indices
      Throws:
      NullPointerException - if a is null

    • axpy

      public static double[] axpy(double[] a, double[] b, double alpha)
      Returns a new array equal to the fused AXPY operation a + alpha * b.

      This performs a single pass over the data to improve cache locality compared to separate scale and add steps.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations.

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      alpha - the scalar multiplier for b
      Returns:
      a newly allocated array where out[i] = a[i] + alpha * b[i]
      Throws:
      NullPointerException - if a or b is null
      IllegalArgumentException - if a.length != b.length

    • multiply

      public static double[] multiply(double[] a, double[] b)
      Returns a new array equal to the element-wise multiplication a * b.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      Returns:
      a newly allocated array where out[i] = a[i] * b[i] for all indices
      Throws:
      NullPointerException - if a or b is null
      IllegalArgumentException - if a.length != b.length

    • divide

      public static double[] divide(double[] a, double[] b)
      Returns a new array equal to the element-wise division a / b.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      Returns:
      a newly allocated array where out[i] = a[i] / b[i] for all indices
      Throws:
      NullPointerException - if a or b is null
      IllegalArgumentException - if a.length != b.length

    • reciprocal

      public static double[] reciprocal(double[] a)
      Returns a new array equal to the element-wise reciprocal 1 / a.

      Implementation Note: Uses a simple indexed for-loop to enable JIT optimizations (bounds-check elimination, loop unrolling, potential auto-vectorization).

      Parameters:
      a - the array; must be non-null
      Returns:
      a newly allocated array where out[i] = 1 / a[i] for all indices
      Throws:
      NullPointerException - if a is null

    • addInto

      public static void addInto(double[] a, double[] b, double[] out)
      Computes the element-wise sum a + b and writes the result into out.

      Implementation Note: Reusing out avoids allocation and reduces GC pressure in hot paths.

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      out - the destination array; must be non-null and the same length as a
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if lengths differ among a, b, and out

    • scaleInto

      public static void scaleInto(double[] a, double alpha, double[] out)
      Computes the element-wise scaling alpha * a and writes the result into out.

      Implementation Note: Reusing out avoids allocation and reduces GC pressure in hot paths.

      Parameters:
      a - the input array; must be non-null
      alpha - the scalar multiplier
      out - the destination array; must be non-null and the same length as a
      Throws:
      NullPointerException - if a or out is null
      IllegalArgumentException - if out.length != a.length

    • axpyInto

      public static void axpyInto(double[] a, double[] b, double alpha, double[] out)
      Computes the fused AXPY operation out = a + alpha * b and writes the result into out.

      Implementation Note: Performs a single pass over the arrays to maximize cache locality.

      Parameters:
      a - the left-hand array; must be non-null
      b - the right-hand array; must be non-null and the same length as a
      alpha - the scalar multiplier for b
      out - the destination array; must be non-null and the same length as a
      Throws:
      NullPointerException - if any argument is null
      IllegalArgumentException - if lengths differ among a, b, and out