StepFunction.java

  1. /*
  2.  * Licensed to the Apache Software Foundation (ASF) under one or more
  3.  * contributor license agreements.  See the NOTICE file distributed with
  4.  * this work for additional information regarding copyright ownership.
  5.  * The ASF licenses this file to You under the Apache License, Version 2.0
  6.  * (the "License"); you may not use this file except in compliance with
  7.  * the License.  You may obtain a copy of the License at
  8.  *
  9.  *      http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  17. package org.apache.commons.math3.analysis.function;

  18. import java.util.Arrays;
  19. import org.apache.commons.math3.analysis.UnivariateFunction;
  20. import org.apache.commons.math3.exception.DimensionMismatchException;
  21. import org.apache.commons.math3.exception.NonMonotonicSequenceException;
  22. import org.apache.commons.math3.exception.NullArgumentException;
  23. import org.apache.commons.math3.exception.NoDataException;
  24. import org.apache.commons.math3.util.MathArrays;

  25. /**
  26.  * <a href="http://en.wikipedia.org/wiki/Step_function">
  27.  *  Step function</a>.
  28.  *
  29.  * @since 3.0
  30.  */
  31. public class StepFunction implements UnivariateFunction {
  32.     /** Abscissae. */
  33.     private final double[] abscissa;
  34.     /** Ordinates. */
  35.     private final double[] ordinate;

  36.     /**
  37.      * Builds a step function from a list of arguments and the corresponding
  38.      * values. Specifically, returns the function h(x) defined by <pre><code>
  39.      * h(x) = y[0] for all x < x[1]
  40.      *        y[1] for x[1] <= x < x[2]
  41.      *        ...
  42.      *        y[y.length - 1] for x >= x[x.length - 1]
  43.      * </code></pre>
  44.      * The value of {@code x[0]} is ignored, but it must be strictly less than
  45.      * {@code x[1]}.
  46.      *
  47.      * @param x Domain values where the function changes value.
  48.      * @param y Values of the function.
  49.      * @throws NonMonotonicSequenceException
  50.      * if the {@code x} array is not sorted in strictly increasing order.
  51.      * @throws NullArgumentException if {@code x} or {@code y} are {@code null}.
  52.      * @throws NoDataException if {@code x} or {@code y} are zero-length.
  53.      * @throws DimensionMismatchException if {@code x} and {@code y} do not
  54.      * have the same length.
  55.      */
  56.     public StepFunction(double[] x,
  57.                         double[] y)
  58.         throws NullArgumentException, NoDataException,
  59.                DimensionMismatchException, NonMonotonicSequenceException {
  60.         if (x == null ||
  61.             y == null) {
  62.             throw new NullArgumentException();
  63.         }
  64.         if (x.length == 0 ||
  65.             y.length == 0) {
  66.             throw new NoDataException();
  67.         }
  68.         if (y.length != x.length) {
  69.             throw new DimensionMismatchException(y.length, x.length);
  70.         }
  71.         MathArrays.checkOrder(x);

  72.         abscissa = MathArrays.copyOf(x);
  73.         ordinate = MathArrays.copyOf(y);
  74.     }

  75.     /** {@inheritDoc} */
  76.     public double value(double x) {
  77.         int index = Arrays.binarySearch(abscissa, x);
  78.         double fx = 0;

  79.         if (index < -1) {
  80.             // "x" is between "abscissa[-index-2]" and "abscissa[-index-1]".
  81.             fx = ordinate[-index-2];
  82.         } else if (index >= 0) {
  83.             // "x" is exactly "abscissa[index]".
  84.             fx = ordinate[index];
  85.         } else {
  86.             // Otherwise, "x" is smaller than the first value in "abscissa"
  87.             // (hence the returned value should be "ordinate[0]").
  88.             fx = ordinate[0];
  89.         }

  90.         return fx;
  91.     }
  92. }