001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.math3.analysis.interpolation;
018
019import org.apache.commons.math3.analysis.UnivariateFunction;
020import org.apache.commons.math3.util.MathUtils;
021import org.apache.commons.math3.util.MathArrays;
022import org.apache.commons.math3.exception.MathIllegalArgumentException;
023import org.apache.commons.math3.exception.NonMonotonicSequenceException;
024import org.apache.commons.math3.exception.NumberIsTooSmallException;
025
026/**
027 * Adapter for classes implementing the {@link UnivariateInterpolator}
028 * interface.
029 * The data to be interpolated is assumed to be periodic. Thus values that are
030 * outside of the range can be passed to the interpolation function: They will
031 * be wrapped into the initial range before being passed to the class that
032 * actually computes the interpolation.
033 *
034 */
035public class UnivariatePeriodicInterpolator
036    implements UnivariateInterpolator {
037    /** Default number of extension points of the samples array. */
038    public static final int DEFAULT_EXTEND = 5;
039    /** Interpolator. */
040    private final UnivariateInterpolator interpolator;
041    /** Period. */
042    private final double period;
043    /** Number of extension points. */
044    private final int extend;
045
046    /**
047     * Builds an interpolator.
048     *
049     * @param interpolator Interpolator.
050     * @param period Period.
051     * @param extend Number of points to be appended at the beginning and
052     * end of the sample arrays in order to avoid interpolation failure at
053     * the (periodic) boundaries of the orginal interval. The value is the
054     * number of sample points which the original {@code interpolator} needs
055     * on each side of the interpolated point.
056     */
057    public UnivariatePeriodicInterpolator(UnivariateInterpolator interpolator,
058                                          double period,
059                                          int extend) {
060        this.interpolator = interpolator;
061        this.period = period;
062        this.extend = extend;
063    }
064
065    /**
066     * Builds an interpolator.
067     * Uses {@link #DEFAULT_EXTEND} as the number of extension points on each side
068     * of the original abscissae range.
069     *
070     * @param interpolator Interpolator.
071     * @param period Period.
072     */
073    public UnivariatePeriodicInterpolator(UnivariateInterpolator interpolator,
074                                          double period) {
075        this(interpolator, period, DEFAULT_EXTEND);
076    }
077
078    /**
079     * {@inheritDoc}
080     *
081     * @throws NumberIsTooSmallException if the number of extension points
082     * is larger than the size of {@code xval}.
083     */
084    public UnivariateFunction interpolate(double[] xval,
085                                          double[] yval)
086        throws NumberIsTooSmallException, NonMonotonicSequenceException {
087        if (xval.length < extend) {
088            throw new NumberIsTooSmallException(xval.length, extend, true);
089        }
090
091        MathArrays.checkOrder(xval);
092        final double offset = xval[0];
093
094        final int len = xval.length + extend * 2;
095        final double[] x = new double[len];
096        final double[] y = new double[len];
097        for (int i = 0; i < xval.length; i++) {
098            final int index = i + extend;
099            x[index] = MathUtils.reduce(xval[i], period, offset);
100            y[index] = yval[i];
101        }
102
103        // Wrap to enable interpolation at the boundaries.
104        for (int i = 0; i < extend; i++) {
105            int index = xval.length - extend + i;
106            x[i] = MathUtils.reduce(xval[index], period, offset) - period;
107            y[i] = yval[index];
108
109            index = len - extend + i;
110            x[index] = MathUtils.reduce(xval[i], period, offset) + period;
111            y[index] = yval[i];
112        }
113
114        MathArrays.sortInPlace(x, y);
115
116        final UnivariateFunction f = interpolator.interpolate(x, y);
117        return new UnivariateFunction() {
118            /** {@inheritDoc} */
119            public double value(final double x) throws MathIllegalArgumentException {
120                return f.value(MathUtils.reduce(x, period, offset));
121            }
122        };
123    }
124}