AxisChecker.java

/*
 * Licensed to the Hipparchus project under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The Hipparchus project 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
 *
 *      https://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.hipparchus.analysis.interpolation;

import org.hipparchus.exception.LocalizedCoreFormats;
import org.hipparchus.exception.MathIllegalArgumentException;
import org.hipparchus.util.FastMath;

import java.util.function.ToDoubleFunction;

/**
 * Checker for sampled data along a regular grid.
 * <p>
 * This class is intended to check one axis of n-dimensional grid data.
 * </p>
 * <p>
 * A typical use case is loading data from a file with entries of the form:
 * </p>
 * <pre>
 *   x₁ y₁ valueA₁₁ valueB₁₁
 *   x₁ y₂ valueA₁₂ valueB₁₂
 *   ⋮
 *   x₁ yₙ valueA₁ₙ valueB₁ₙ
 *   x₂ y₁ valueA₂₁ valueB₂₁
 *   x₂ y₂ valueA₂₂ valueB₂₂
 *   ⋮
 *   x₂ yₙ valueA₂ₙ valueB₂ₙ
 *   x₃ yₙ valueA₃ₙ valueB₃ₙ
 *   ⋮
 *   xₘ yₙ valueAₘₙ valueBₘₙ
 * </pre>
 * <p>
 * In this case, the grid is two-dimensional, with the x-axis having m steps
 *  ranging from x₁ to xₘ and the y-axis having n steps ranging from y₁ to yₙ.
 * </p>
 * <p>
 * In this case, users could store the entries in some custom container
 * class {@code Entry} with getters {@code getX()}, {@code getY()}, {@code getValueA()}, and
 * {@code getValueB()}. Then the checks for both x and y axes could be built as follows:
 * </p>
 * <pre>{@code
 *   List<Entry>    data     = readData();
 *   RegularIndexer xIndexer = new AxisChecker<>(Entry::getX(), toleranceX).checkGridData(data);
 *   RegularIndexer yIndexer = new AxisChecker<>(Entry::getY(), toleranceY).checkGridData(data);
 * }</pre>
 * @param <T> grid data type
 * @since 4.1
 */
public class AxisChecker<T> {

    /** Coordinate extractor. */
    private final ToDoubleFunction<T> extractor;

    /** Tolerance below which extracted coordinates are considered equal. */
    private final double tolerance;

    /** Simple constructor.
     * @param extractor coordinate extractor
     * @param tolerance tolerance below which extracted coordinates are considered equal
     */
    public AxisChecker(final ToDoubleFunction<T> extractor, final double tolerance) {
        this.extractor = extractor;
        this.tolerance = tolerance;
    }

    /** Check grid data for regularity (i.e., regular sampling, no missing points,
     * same number of points at all coordinates…).
     * <p>
     * The check for one axis performs two passes over the full grid data.
     * </p>
     * @param gridData grid data to check
     * @return regular sampling for the axis configured at construction
     */
    public RegularIndexer checkGridData(final Iterable<T> gridData) {

        // first pass, extract statistics
        double currentMin = Double.POSITIVE_INFINITY;
        double currentMax = Double.NEGATIVE_INFINITY;
        int    minCount   = 0;
        int    size       = 0;
        for (final T t : gridData) {
            final double coordinate = extractor.applyAsDouble(t);
            if (Double.isNaN(coordinate)) {
                throw new MathIllegalArgumentException(LocalizedCoreFormats.NAN_ELEMENT_AT_INDEX, size);
            }
            ++size;
            if (coordinate < currentMin - tolerance) {
                // this is a new minimum, we reset counter
                currentMin = coordinate;
                minCount   = 1;
            } else if (coordinate - currentMin < tolerance) {
                // we found again an already known minimum, update the count
                ++minCount;
            }
            currentMax = FastMath.max(currentMax, coordinate);
        }

        // store global indexing data
        final RegularIndexer regularIndexer = new RegularIndexer(currentMin, currentMax, size / minCount);

        // second pass, check grid data is regular
        final int[] count = new int[regularIndexer.getN()];
        for (final T t : gridData) {
            final double coordinate = extractor.applyAsDouble(t);
            final int    index      = regularIndexer.index(coordinate);
            final double expected   = regularIndexer.coordinate(index);
            if (FastMath.abs(coordinate - expected) > tolerance) {
                throw new MathIllegalArgumentException(LocalizedCoreFormats.MISALIGNED_GRID_POINT,
                                                       index, expected, coordinate - expected);
            }
            count[index]++;
        }
        for (int i = 0; i < regularIndexer.getN(); i++) {
            if (count[i] != minCount) {
                throw new MathIllegalArgumentException(LocalizedCoreFormats.IRREGULAR_GRID, minCount, i, count[i]);
            }
        }

        return regularIndexer;

    }

}