1 files changed, 183 insertions, 0 deletions
diff --git a/src/main/java/org/apache/commons/math3/analysis/function/HarmonicOscillator.java b/src/main/java/org/apache/commons/math3/analysis/function/HarmonicOscillator.java
new file mode 100644
index 0000000..0fbad9c
--- /dev/null
+++ b/src/main/java/org/apache/commons/math3/analysis/function/HarmonicOscillator.java
@@ -0,0 +1,183 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You 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 org.apache.commons.math3.analysis.function;
+
+import org.apache.commons.math3.analysis.DifferentiableUnivariateFunction;
+import org.apache.commons.math3.analysis.FunctionUtils;
+import org.apache.commons.math3.analysis.ParametricUnivariateFunction;
+import org.apache.commons.math3.analysis.UnivariateFunction;
+import org.apache.commons.math3.analysis.differentiation.DerivativeStructure;
+import org.apache.commons.math3.analysis.differentiation.UnivariateDifferentiableFunction;
+import org.apache.commons.math3.exception.DimensionMismatchException;
+import org.apache.commons.math3.exception.NullArgumentException;
+import org.apache.commons.math3.util.FastMath;
+
+/**
+ * <a href="http://en.wikipedia.org/wiki/Harmonic_oscillator">
+ *  simple harmonic oscillator</a> function.
+ *
+ * @since 3.0
+ */
+public class HarmonicOscillator implements UnivariateDifferentiableFunction, DifferentiableUnivariateFunction {
+    /** Amplitude. */
+    private final double amplitude;
+    /** Angular frequency. */
+    private final double omega;
+    /** Phase. */
+    private final double phase;
+
+    /**
+     * Harmonic oscillator function.
+     *
+     * @param amplitude Amplitude.
+     * @param omega Angular frequency.
+     * @param phase Phase.
+     */
+    public HarmonicOscillator(double amplitude,
+                              double omega,
+                              double phase) {
+        this.amplitude = amplitude;
+        this.omega = omega;
+        this.phase = phase;
+    }
+
+    /** {@inheritDoc} */
+    public double value(double x) {
+        return value(omega * x + phase, amplitude);
+    }
+
+    /** {@inheritDoc}
+     * @deprecated as of 3.1, replaced by {@link #value(DerivativeStructure)}
+     */
+    @Deprecated
+    public UnivariateFunction derivative() {
+        return FunctionUtils.toDifferentiableUnivariateFunction(this).derivative();
+    }
+
+    /**
+     * Parametric function where the input array contains the parameters of
+     * the harmonic oscillator function, ordered as follows:
+     * <ul>
+     *  <li>Amplitude</li>
+     *  <li>Angular frequency</li>
+     *  <li>Phase</li>
+     * </ul>
+     */
+    public static class Parametric implements ParametricUnivariateFunction {
+        /**
+         * Computes the value of the harmonic oscillator at {@code x}.
+         *
+         * @param x Value for which the function must be computed.
+         * @param param Values of norm, mean and standard deviation.
+         * @return the value of the function.
+         * @throws NullArgumentException if {@code param} is {@code null}.
+         * @throws DimensionMismatchException if the size of {@code param} is
+         * not 3.
+         */
+        public double value(double x, double ... param)
+            throws NullArgumentException,
+                   DimensionMismatchException {
+            validateParameters(param);
+            return HarmonicOscillator.value(x * param[1] + param[2], param[0]);
+        }
+
+        /**
+         * Computes the value of the gradient at {@code x}.
+         * The components of the gradient vector are the partial
+         * derivatives of the function with respect to each of the
+         * <em>parameters</em> (amplitude, angular frequency and phase).
+         *
+         * @param x Value at which the gradient must be computed.
+         * @param param Values of amplitude, angular frequency and phase.
+         * @return the gradient vector at {@code x}.
+         * @throws NullArgumentException if {@code param} is {@code null}.
+         * @throws DimensionMismatchException if the size of {@code param} is
+         * not 3.
+         */
+        public double[] gradient(double x, double ... param)
+            throws NullArgumentException,
+                   DimensionMismatchException {
+            validateParameters(param);
+
+            final double amplitude = param[0];
+            final double omega = param[1];
+            final double phase = param[2];
+
+            final double xTimesOmegaPlusPhase = omega * x + phase;
+            final double a = HarmonicOscillator.value(xTimesOmegaPlusPhase, 1);
+            final double p = -amplitude * FastMath.sin(xTimesOmegaPlusPhase);
+            final double w = p * x;
+
+            return new double[] { a, w, p };
+        }
+
+        /**
+         * Validates parameters to ensure they are appropriate for the evaluation of
+         * the {@link #value(double,double[])} and {@link #gradient(double,double[])}
+         * methods.
+         *
+         * @param param Values of norm, mean and standard deviation.
+         * @throws NullArgumentException if {@code param} is {@code null}.
+         * @throws DimensionMismatchException if the size of {@code param} is
+         * not 3.
+         */
+        private void validateParameters(double[] param)
+            throws NullArgumentException,
+                   DimensionMismatchException {
+            if (param == null) {
+                throw new NullArgumentException();
+            }
+            if (param.length != 3) {
+                throw new DimensionMismatchException(param.length, 3);
+            }
+        }
+    }
+
+    /**
+     * @param xTimesOmegaPlusPhase {@code omega * x + phase}.
+     * @param amplitude Amplitude.
+     * @return the value of the harmonic oscillator function at {@code x}.
+     */
+    private static double value(double xTimesOmegaPlusPhase,
+                                double amplitude) {
+        return amplitude * FastMath.cos(xTimesOmegaPlusPhase);
+    }
+
+    /** {@inheritDoc}
+     * @since 3.1
+     */
+    public DerivativeStructure value(final DerivativeStructure t)
+        throws DimensionMismatchException {
+        final double x = t.getValue();
+        double[] f = new double[t.getOrder() + 1];
+
+        final double alpha = omega * x + phase;
+        f[0] = amplitude * FastMath.cos(alpha);
+        if (f.length > 1) {
+            f[1] = -amplitude * omega * FastMath.sin(alpha);
+            final double mo2 = - omega * omega;
+            for (int i = 2; i < f.length; ++i) {
+                f[i] = mo2 * f[i - 2];
+            }
+        }
+
+        return t.compose(f);
+
+    }
+
+}