Package de.labathome.trustconstr

Class NumDiff

java.lang.Object
de.labathome.trustconstr.NumDiff
public class NumDiff extends Object
Finite-difference Jacobians and gradients (mirrors scipy _numdiff.approx_derivative). Provides:

  • Constructor Details

    • NumDiff

      public NumDiff()

  • Method Details

    • groupColumns

      public static int[] groupColumns(Matrix A)
      Group columns of a 2-D matrix for sparse finite differencing. Two columns are in the same group if in each row at least one of them has zero. A greedy sequential algorithm constructs the groups (Curtis-Powell-Reid, 1974).
      Parameters:
      A - m x n sparsity pattern (non-zero entries mark structural non-zeros of the Jacobian).
      Returns:
      length-n array of group indices in [0, n_groups).

    • groupColumns

      public static int[] groupColumns(Matrix A, int[] order)
      Group columns of a 2-D matrix for sparse FD with a user-supplied permutation that controls greedy-grouping order.
      Parameters:
      A - m x n sparsity pattern
      order - length-n permutation; if null or length ≤ 1, a reproducible random permutation seeded by order[0] (defaulting to 0) is used
      Returns:
      length-n array of group indices

    • adjustSchemeToBounds

      public static AdjustedDifferencingScheme adjustSchemeToBounds(Matrix x0, Matrix h, int numSteps, FiniteDifferenceMethod scheme, Matrix lb, Matrix ub)
      Adjust finite-difference step sizes so that the perturbed point stays within [lb, ub] per dimension, flipping direction or switching forward / backward as needed. Pure per-element logic on length-n vectors.
      Parameters:
      x0 - point at which to estimate the derivative (n x 1)
      h - desired absolute finite-difference steps (n x 1)
      numSteps - number of h steps taken per direction
      scheme - one-sided or two-sided differencing
      lb - per-variable lower bounds (n x 1)
      ub - per-variable upper bounds (n x 1)
      Returns:
      adjusted step sizes plus per-dimension one-sided fall-back flags

    • epsForMethod

      public static double epsForMethod(Class<?> x0Type, Class<?> f0Type, FiniteDifferenceMethod method)
      Calculate the relative EPS step for a given data type and FD method. Progressively smaller steps are used for larger floating-point types. If x0 or f0 is float, the smaller (less precise) machine epsilon is chosen.
      Parameters:
      x0Type - element type of x0 (float or double)
      f0Type - element type of f0 (float or double)
      method - FD scheme: TWO_POINT, THREE_POINT, or COMPLEX_STEP
      Returns:
      relative step size for this combination

    • computeAbsoluteStep

      public static Matrix computeAbsoluteStep(Matrix relStep, Matrix x0, Matrix f0, FiniteDifferenceMethod method)
      Compute the absolute finite-difference step from a relative step.
      Parameters:
      relStep - per-variable relative step (n x 1); pass null to derive a default from epsForMethod
      x0 - point of evaluation (n x 1)
      f0 - function value at x0 (m x 1); used only for value-type dispatch in this port (always treated as double)
      method - FD scheme: TWO_POINT, THREE_POINT, or COMPLEX_STEP
      Returns:
      absolute step (n x 1)

    • approxDerivative

      public static double approxDerivative(DoubleUnaryOperator f, double x0, FiniteDifferenceOptions options)
      Finite-difference gradient of a scalar function of a scalar argument.
      Parameters:
      f - scalar function R -> R
      x0 - evaluation point
      options - FD configuration
      Returns:
      scalar derivative df/dx at x0

    • approxDerivative

      public static double approxDerivative(ToDoubleFunction<Matrix> f, double x0, FiniteDifferenceOptions options)
      Finite-difference gradient of a ToDoubleFunction of a scalar argument.
      Parameters:
      f - scalar function evaluated on a 1 x 1 Matrix
      x0 - evaluation point
      options - FD configuration
      Returns:
      scalar derivative df/dx at x0

    • approxDerivative

      public static double approxDerivative(ToDoubleFunction<Matrix> f, double x0, double f0, FiniteDifferenceOptions options)
      Finite-difference gradient of a scalar function of a scalar argument with a precomputed f0.
      Parameters:
      f - scalar function evaluated on a 1 x 1 Matrix
      x0 - evaluation point
      f0 - precomputed f(x0) (saves one evaluation)
      options - FD configuration
      Returns:
      scalar derivative df/dx at x0

    • approxDerivative

      public static Matrix approxDerivative(ToDoubleFunction<Matrix> f, Matrix x0, double f0, FiniteDifferenceOptions options)
      Finite-difference gradient of a real-valued function of a vector argument.
      Parameters:
      f - function R^n -> R
      x0 - evaluation point (n x 1)
      f0 - precomputed f(x0)
      options - FD configuration
      Returns:
      gradient gradf(x0) (1 x n or n x 1 depending on the underlying call shape)

    • approxDerivative

      public static Matrix approxDerivative(Function<Matrix,Matrix> f, Matrix x0, Matrix f0, FiniteDifferenceOptions options)
      Finite-difference Jacobian of a vector-valued function.
      Parameters:
      f - function R^n -> R^m
      x0 - evaluation point (n x 1)
      f0 - precomputed f(x0) (m x 1); pass null to evaluate inside
      options - FD configuration
      Returns:
      Jacobian J (m x n)

    • approxDerivative

      public static Matrix approxDerivative(BiFunction<Matrix,Object,Matrix> fun, Matrix x0, Matrix f0, FiniteDifferenceOptions options, Object args)
      Finite-difference Jacobian of a vector-valued function with extra args. See the class doc / scipy _numdiff.approx_derivative for the full specification.
      Parameters:
      fun - function (x, args) -> f(x, args)
      x0 - evaluation point (n x 1)
      f0 - precomputed fun(x0, args) (m x 1); pass null to evaluate inside
      options - FD configuration
      args - extra arguments forwarded to fun
      Returns:
      Jacobian J (m x n); a LinearOperator when options.asLinearOperator() is true

    • linearOperatorDifference

      public static LinearOperator linearOperatorDifference(Function<Matrix,Matrix> fun, Matrix x0, Matrix f0, Matrix relStep, FiniteDifferenceMethod method)
      Build a LinearOperator that applies the FD Jacobian J(x0)*p on demand, without materialising the full Jacobian. Used by as_linear_operator=True consumers.
      Parameters:
      fun - vector-valued function being differentiated
      x0 - evaluation point
      f0 - cached fun(x0)
      relStep - relative step size
      method - FD scheme (TWO_POINT, THREE_POINT, COMPLEX_STEP)
      Returns:
      matrix-free FD-Jacobian linear operator

    • approxDerivativeAsLinearOperator

      public static LinearOperator approxDerivativeAsLinearOperator(BiFunction<Matrix,Object,Matrix> fun, Matrix x0, Matrix f0, FiniteDifferenceOptions options, Object args)
      Strict scipy approx_derivative(..., as_linear_operator=True) counterpart: returns a matrix-free LinearOperator that applies the FD Jacobian J(x0) * p on demand. Bounds are not supported in this mode (mirrors scipy).
      Parameters:
      fun - vector-valued function (x, args) -> f(x, args)
      x0 - evaluation point (n x 1)
      f0 - precomputed fun(x0, args) (m x 1); null to evaluate inside
      options - FD configuration (only method and relStep are honored)
      args - extra args forwarded to fun
      Returns:
      matrix-free FD-Jacobian linear operator

    • approxDerivativeWithWorkers

      public static Matrix approxDerivativeWithWorkers(BiFunction<Matrix,Object,Matrix> fun, Matrix x0, Matrix f0, FiniteDifferenceOptions options, Object args, ExecutorService executor)
      Strict scipy approx_derivative(..., workers=...) counterpart: computes a dense FD Jacobian column-by-column with the per-column evaluations dispatched in parallel through executor. Returns the same m x n Jacobian as the serial overload.

      Thread safety: fun must be safe to invoke concurrently (matches scipy's caveat for workers mode).

      Sparse-FD and as_linear_operator modes are not supported by this overload; use the dedicated methods for those.

      Parameters:
      fun - vector-valued function (x, args) -> f(x, args)
      x0 - evaluation point (n x 1)
      f0 - precomputed fun(x0, args) (m x 1); null to evaluate inside
      options - FD configuration
      args - extra args
      executor - pool to dispatch per-column evaluations on; null falls back to the serial path
      Returns:
      dense FD Jacobian (m x n)

    • approxDerivativeFullOutput

      public static ApproxDerivativeResult approxDerivativeFullOutput(BiFunction<Matrix,Object,Matrix> fun, Matrix x0, Matrix f0, FiniteDifferenceOptions options, Object args)
      Strict scipy approx_derivative(..., full_output=True) counterpart: returns the FD Jacobian alongside an info dict carrying metadata about the computation. The info dict has at minimum "nfev" (function-evaluation count) and "method" keys.
      Parameters:
      fun - vector-valued function
      x0 - evaluation point (n x 1)
      f0 - precomputed fun(x0, args) (m x 1); null to evaluate inside
      options - FD configuration
      args - extra args
      Returns:
      Jacobian and info dict bundled in ApproxDerivativeResult