BoxSampler.java

/*
 * 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.rng.sampling.shape;

import org.apache.commons.rng.UniformRandomProvider;
import org.apache.commons.rng.sampling.SharedStateObjectSampler;

/**
 * Generate points uniformly distributed within a n-dimension box (hyperrectangle).
 *
 * <p>Sampling uses:</p>
 *
 * <ul>
 *   <li>{@link UniformRandomProvider#nextDouble()}
 * </ul>
 *
 * @see <a href="https://en.wikipedia.org/wiki/Hyperrectangle">Hyperrectangle (Wikipedia)</a>
 * @since 1.4
 */
public abstract class BoxSampler implements SharedStateObjectSampler<double[]> {
    /** The dimension for 2D sampling. */
    private static final int TWO_D = 2;
    /** The dimension for 3D sampling. */
    private static final int THREE_D = 3;
    /** The source of randomness. */
    private final UniformRandomProvider rng;

    // The following code defines a point within the range ab:
    // p = (1 - u)a + ub, u in [0, 1]
    //
    // This is the same method used in the
    // o.a.c.rng.sampling.distribution.ContinuousUniformSampler but extended to N-dimensions.

    /**
     * Sample uniformly from a box in 2D. This is an non-array based specialisation of
     * {@link BoxSamplerND} for performance.
     */
    private static final class BoxSampler2D extends BoxSampler {
        /** The x component of bound a. */
        private final double ax;
        /** The y component of bound a. */
        private final double ay;
        /** The x component of bound b. */
        private final double bx;
        /** The y component of bound b. */
        private final double by;

        /**
         * @param rng Source of randomness.
         * @param a Bound a.
         * @param b Bound b.
         */
        BoxSampler2D(UniformRandomProvider rng, double[] a, double[] b) {
            super(rng);
            ax = a[0];
            ay = a[1];
            bx = b[0];
            by = b[1];
        }

        /**
         * @param rng Source of randomness.
         * @param source Source to copy.
         */
        BoxSampler2D(UniformRandomProvider rng, BoxSampler2D source) {
            super(rng);
            ax = source.ax;
            ay = source.ay;
            bx = source.bx;
            by = source.by;
        }

        @Override
        public double[] sample() {
            return new double[] {createSample(ax, bx),
                                 createSample(ay, by)};
        }

        @Override
        public BoxSampler withUniformRandomProvider(UniformRandomProvider rng) {
            return new BoxSampler2D(rng, this);
        }
    }

    /**
     * Sample uniformly from a box in 3D. This is an non-array based specialisation of
     * {@link BoxSamplerND} for performance.
     */
    private static final class BoxSampler3D extends BoxSampler {
        /** The x component of bound a. */
        private final double ax;
        /** The y component of bound a. */
        private final double ay;
        /** The z component of bound a. */
        private final double az;
        /** The x component of bound b. */
        private final double bx;
        /** The y component of bound b. */
        private final double by;
        /** The z component of bound b. */
        private final double bz;

        /**
         * @param rng Source of randomness.
         * @param a Bound a.
         * @param b Bound b.
         */
        BoxSampler3D(UniformRandomProvider rng, double[] a, double[] b) {
            super(rng);
            ax = a[0];
            ay = a[1];
            az = a[2];
            bx = b[0];
            by = b[1];
            bz = b[2];
        }

        /**
         * @param rng Source of randomness.
         * @param source Source to copy.
         */
        BoxSampler3D(UniformRandomProvider rng, BoxSampler3D source) {
            super(rng);
            ax = source.ax;
            ay = source.ay;
            az = source.az;
            bx = source.bx;
            by = source.by;
            bz = source.bz;
        }

        @Override
        public double[] sample() {
            return new double[] {createSample(ax, bx),
                                 createSample(ay, by),
                                 createSample(az, bz)};
        }

        @Override
        public BoxSampler withUniformRandomProvider(UniformRandomProvider rng) {
            return new BoxSampler3D(rng, this);
        }
    }

    /**
     * Sample uniformly from a box in ND.
     */
    private static final class BoxSamplerND extends BoxSampler {
        /** Bound a. */
        private final double[] a;
        /** Bound b. */
        private final double[] b;

        /**
         * @param rng Source of randomness.
         * @param a Bound a.
         * @param b Bound b.
         */
        BoxSamplerND(UniformRandomProvider rng, double[] a, double[] b) {
            super(rng);
            // Defensive copy
            this.a = a.clone();
            this.b = b.clone();
        }

        /**
         * @param rng Source of randomness.
         * @param source Source to copy.
         */
        BoxSamplerND(UniformRandomProvider rng, BoxSamplerND source) {
            super(rng);
            // Shared state is immutable
            a = source.a;
            b = source.b;
        }

        @Override
        public double[] sample() {
            final double[] x = new double[a.length];
            for (int i = 0; i < x.length; i++) {
                x[i] = createSample(a[i], b[i]);
            }
            return x;
        }

        @Override
        public BoxSampler withUniformRandomProvider(UniformRandomProvider rng) {
            return new BoxSamplerND(rng, this);
        }
    }

    /**
     * @param rng Source of randomness.
     */
    BoxSampler(UniformRandomProvider rng) {
        this.rng = rng;
    }

    /**
     * @return a random Cartesian coordinate within the box.
     */
    @Override
    public abstract double[] sample();

    /**
     * Creates the sample between bound a and b.
     *
     * @param a Bound a
     * @param b Bound b
     * @return the sample
     */
    double createSample(double a, double b) {
        final double u = rng.nextDouble();
        return (1.0 - u) * a + u * b;
    }

    /** {@inheritDoc} */
    // Redeclare the signature to return a BoxSampler not a SharedStateObjectSampler<double[]>
    @Override
    public abstract BoxSampler withUniformRandomProvider(UniformRandomProvider rng);

    /**
     * Create a box sampler with bounds {@code a} and {@code b}.
     * Sampled points are uniformly distributed within the box defined by the bounds.
     *
     * <p>Sampling is supported in dimensions of 2 or above. Single dimension sampling
     * can be performed using a {@link LineSampler}.
     *
     * <p>Note: There is no requirement that {@code a <= b}. The samples will be uniformly
     * distributed in the range {@code a} to {@code b} for each dimension.
     *
     * @param rng Source of randomness.
     * @param a Bound a.
     * @param b Bound b.
     * @return the sampler
     * @throws IllegalArgumentException If the bounds do not have the same
     * dimension; the dimension is less than 2; or bounds have non-finite coordinates.
     */
    public static BoxSampler of(UniformRandomProvider rng,
                                double[] a,
                                double[] b) {
        final int dimension = a.length;
        if (dimension != b.length) {
            throw new IllegalArgumentException(
                new StringBuilder("Mismatch of box dimensions: ").append(dimension).append(',')
                                                                 .append(b.length).toString());
        }
        // Detect non-finite bounds
        Coordinates.requireFinite(a, "Bound a");
        Coordinates.requireFinite(b, "Bound b");
        // Low dimension specialisations
        if (dimension == TWO_D) {
            return new BoxSampler2D(rng, a, b);
        } else if (dimension == THREE_D) {
            return new BoxSampler3D(rng, a, b);
        } else if (dimension > THREE_D) {
            return new BoxSamplerND(rng, a, b);
        }
        // Less than 2D
        throw new IllegalArgumentException("Unsupported dimension: " + dimension);
    }
}