/*
    * 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
    *
    *      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.apache.commons.statistics.distribution;
  
  import java.lang.reflect.Modifier;
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collections;
  import java.util.Properties;
  import java.util.function.Function;
  import java.util.stream.IntStream;
  import java.util.stream.Stream;
  import org.apache.commons.math3.util.MathArrays;
  import org.apache.commons.rng.simple.RandomSource;
  import org.apache.commons.statistics.distribution.DistributionTestData.DiscreteDistributionTestData;
  import org.junit.jupiter.api.Assertions;
  import org.junit.jupiter.api.Assumptions;
  import org.junit.jupiter.api.TestInstance;
  import org.junit.jupiter.api.TestInstance.Lifecycle;
  import org.junit.jupiter.params.ParameterizedTest;
  import org.junit.jupiter.params.provider.Arguments;
  import org.junit.jupiter.params.provider.MethodSource;
  
  /**
   * Abstract base class for {@link DiscreteDistribution} tests.
   *
   * <p>This class uses parameterized tests that are repeated for instances of a
   * distribution. The distribution, test input and expected values are generated
   * dynamically from properties files loaded from resources.
   *
   * <p>The class has a single instance (see {@link Lifecycle#PER_CLASS}) that loads properties
   * files from resources on creation. Resource files are assumed to be in the corresponding package
   * for the class and named sequentially from 1:
   * <pre>
   * test.distname.1.properties
   * test.distname.2.properties
   * </pre>
   * <p>Where {@code distname} is the name of the distribution. The name is dynamically
   * created in {@link #getDistributionName()} and can be overridden by implementing classes.
   * A single parameterization of a distribution is tested using a single properties file.
   *
   * <p>To test a distribution create a sub-class and override the following methods:
   * <ul>
   * <li>{@link #makeDistribution(Object...) makeDistribution(Object...)} - Creates the distribution from the parameters
   * <li>{@link #makeInvalidParameters()} - Generate invalid parameters for the distribution
   * <li>{@link #getParameterNames()} - Return the names of parameter accessors
   * </ul>
   *
   * <p>The distribution is created using
   * {@link #makeDistribution(Object...) makeDistribution(Object...)}. This should
   * create an instance of the distribution using parameters defined in the properties file.
   * The parameters are parsed from String values to the appropriate parameter object. Currently
   * this supports Double and Integer; numbers can be unboxed and used to create the distribution.
   *
   * <p>Illegal arguments for the distribution are tested from parameters provided by
   * {@link #makeInvalidParameters()}. If there are no illegal arguments this method may return
   * null to skip the test. Primitive parameters are boxed to objects so ensure the canonical form
   * is used, e.g. {@code 1.0} not {@code 1} for a {@code double} argument.
   *
   * <p>If the distribution provides parameter accessors then the child test class can return
   * the accessor names using {@link #getParameterNames()}. The distribution method accessors
   * will be detected and invoked using reflection. The accessor must provide the same value
   * as that passed to the {@link #makeDistribution(Object...)} method to create the distribution.
   * This method may return null to skip the test, or null for the name to skip the test for a
   * single parameter accessor.
   *
   * <p>The properties file must contain parameters for the distribution, properties of the
   * distribution (moments and bounds) and points to test the CDF and PMF with the expected values.
   * This information can be used to evaluate the distribution CDF and PMF but also the survival
   * function, consistency of the probability computations and random sampling.
   *
   * <p>Optionally:
   * <ul>
   * <li>Points for the PMF (and log PMF) can be specified. The default will use the CDF points.
   * Note: It is not expected that evaluation of the PMF will require different points to the CDF.
   * <li>Points and expected values for the inverse CDF can be specified. These are used in
   * addition to test the inverse mapping of the CDF values to the CDF test points.
   * <li>Expected values for the log PMF can be specified. The default will use
   * {@link Math#log(double)} on the PMF values.
   * <li>Points and expected values for the survival function can be specified. These are used in
   * addition to test the inverse mapping of the SF values to the SF test points.
   * The default will use the expected CDF values (SF = 1 - CDF).
   * <li>A tolerance for equality assertions. The default is set by {@link #getAbsoluteTolerance()}
   * and {@link #getRelativeTolerance()}.
   * </ul>
  *
  * <p>If the distribution provides higher precision implementations of
  * cumulative probability and/or survival probability as the values approach zero, then test
  * points and expected values can be provided for high-precision computations. If the default
  * absolute tolerance has been set to non-zero, then very small p-values will require the
  * high-precision absolute tolerance is configured for the test to a suitable magnitude (see below).
  *
  * <p>Per-test configuration
  *
  * <p>Each test is identified with a {@link TestName} key in the properties file. This key
  * can be used to set a per-test tolerance, or disable the test:
  * <pre>
  * cdf.hp.relative = 1e-14
  * cdf.hp.absolute = 1e-50
  * sampling.disable
  * </pre>
  *
  * <p>Note: All properties files are read during test initialization. Any errors in a single
  * property file will throw an exception, invalidating the initialization and no tests
  * will be executed.
  *
  * <p>The parameterized tests in this class are inherited. The tests are final and cannot be
  * changed. This ensures each instance of a distribution is tested for all functionality in
  * the {@link DiscreteDistribution} interface. Arguments to the parameterized tests are
  * generated dynamically using methods of the same name. These can be over-ridden in child
  * classes to alter parameters. Throwing a
  * {@link org.opentest4j.TestAbortedException TestAbortedException} in this method will
  * skip the test as the arguments will not be generated.
  *
  * <p>Each parameterized test is effectively static; it uses no instance data.
  * To implement additional test cases with a specific distribution instance and test
  * data, create a test in the child class and call the relevant test case to verify
  * results. Note that it is recommended to use the properties file as this ensures the
  * entire functionality of the distribution is tested for that parameterization.
  *
  * <p>Tests using floating-point equivalence comparisons are asserted using a {@link DoubleTolerance}.
  * This interface computes true or false for the comparison of two {@code double} types.
  * This allows the flexibility to use absolute, relative or ULP thresholds in combinations
  * built using And or Or conditions to compare numbers. The default uses an Or combination
  * of the absolute and relative thresholds. See {@link DoubleTolerances} to construct
  * custom instances for additional tests.
  *
  * <p>Test data should be validated against reference tables or other packages where
  * possible, and the source of the reference data and/or validation should be documented
  * in the properties file or additional test cases as appropriate.
  *
  * <p>The properties file uses {@code key=value} pairs loaded using a
  * {@link java.util.Properties} object. Values will be read as String and then parsed to
  * numeric data, and data arrays. Multi-line values can use a {@code \} character to join lines.
  * Data in the properties file will be converted to numbers using standard parsing
  * functions appropriate to the primitive type, e.g. {@link Double#parseDouble(String)}.
  * Special double values should use NaN, Infinity and -Infinity. As a convenience
  * for creating test data parsing of doubles supports the following notations from
  * other languages ('inf', 'Inf'); parsing of ints supports 'min' and 'max' for the
  * minimum and maximum integer values.
  *
  * <p>The following is a complete properties file for a distribution:
  * <pre>
  * parameters = 0.5 1.0
  * # Computed using XYZ
  * mean = 1.0
  * variance = NaN
  * # optional (default -2147483648, Integer.MIN_VALUE)
  * lower = 0
  * # optional (default 2147483647, Integer.MAX_VALUE)
  * upper = max
  * # optional (default 1e-14 or over-ridden in getRelativeTolerance())
  * tolerance.relative = 1e-9
  * # optional (default 0.0 or over-ridden in getAbsoluteTolerance())
  * tolerance.absolute = 0.0
  * cdf.points = 0, 2
  * cdf.values = 0.0, 0.5
  * # optional (default uses cdf.points)
  * pmf.points = 0, 40000
  * pmf.values = 0.0,\
  *  0.0
  * # optional (default uses log pmf.values)
  * logpmf.values = -1900.123, -Infinity
  * # optional (default uses cdf.points and 1 - cdf.values)
  * sf.points = 400
  * sf.values = 0.0
  * # optional high-precision CDF test
  * cdf.hp.points = 1e-16
  * cdf.hp.values = 1.23e-17
  * # optional high-precision survival function test
  * sf.hp.points = 9
  * sf.hp.values = 2.34e-18
  * # optional inverse CDF test (defaults to ignore)
  * icdf.points = 0.0, 0.5
  * icdf.values = 3, 4
  * # optional inverse CDF test (defaults to ignore)
  * isf.points = 1.0, 0.5
  * isf.values = 3, 4
  * # Optional per-test tolerance and disable
  * cdf.hp.relative = 1e-14
  * cdf.hp.absolute = 1e-50
  * sampling.disable = true
  * </pre>
  *
  * <p>See {@link BinomialDistributionTest} for an example and the resource file {@code test.binomial.1.properties}.
  */
 @TestInstance(Lifecycle.PER_CLASS)
 abstract class BaseDiscreteDistributionTest
     extends BaseDistributionTest<DiscreteDistribution, DiscreteDistributionTestData> {
 
     /** Threshold for the PMF summation test for a range that is too large. */
     private static final int SUM_RANGE_TOO_LARGE = 50;
 
     @Override
     DiscreteDistributionTestData makeDistributionData(Properties properties) {
         return new DiscreteDistributionTestData(properties);
     }
 
     //------------------------ Methods to stream the test data -----------------------------
 
     // The @MethodSource annotation will default to a no arguments method of the same name
     // as the @ParameterizedTest method. These can be overridden by child classes to
     // stream different arguments to the test case.
 
     /**
      * Create a stream of arguments containing the distribution to test, the CDF test
      * points and the test tolerance.
      *
      * @param name Name of the function under test
      * @return the stream
      */
     Stream<Arguments> streamCdfTestPoints(TestName name) {
         return stream(name,
                       DiscreteDistributionTestData::getCdfPoints);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the PMF test points
      * and values, and the test tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testProbability() {
         return stream(TestName.PMF,
                       DiscreteDistributionTestData::getPmfPoints,
                       DiscreteDistributionTestData::getPmfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the log PMF test points
      * and values, and the test tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testLogProbability() {
         return stream(TestName.LOGPMF,
                       DiscreteDistributionTestData::getPmfPoints,
                       DiscreteDistributionTestData::getLogPmfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the CDF test points
      * and values, and the test tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testCumulativeProbability() {
         return stream(TestName.CDF,
                       DiscreteDistributionTestData::getCdfPoints,
                       DiscreteDistributionTestData::getCdfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the survival function
      * test points and values, and the test tolerance.
      *
      * <p>This defaults to using the CDF points. The survival function is tested as 1 - CDF.
      *
      * @return the stream
      */
     Stream<Arguments> testSurvivalProbability() {
         return stream(TestName.SF,
                       DiscreteDistributionTestData::getSfPoints,
                       DiscreteDistributionTestData::getSfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the CDF test points
      * and values, and the test tolerance for high-precision computations.
      *
      * @return the stream
      */
     Stream<Arguments> testCumulativeProbabilityHighPrecision() {
         return stream(TestName.CDF_HP,
                       DiscreteDistributionTestData::getCdfHpPoints,
                       DiscreteDistributionTestData::getCdfHpValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the survival function
      * test points and values, and the test tolerance for high-precision computations.
      *
      * @return the stream
      */
     Stream<Arguments> testSurvivalProbabilityHighPrecision() {
         return stream(TestName.SF_HP,
                       DiscreteDistributionTestData::getSfHpPoints,
                       DiscreteDistributionTestData::getSfHpValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the inverse CDF test points
      * and values. No test tolerance is required as the values are integers and must be exact.
      *
      * @return the stream
      */
     Stream<Arguments> testInverseCumulativeProbability() {
         return stream(TestName.ICDF,
                       DiscreteDistributionTestData::getIcdfPoints,
                       DiscreteDistributionTestData::getIcdfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the inverse CDF test points
      * and values. No test tolerance is required as the values are integers and must be exact.
      *
      * @return the stream
      */
     Stream<Arguments> testInverseSurvivalProbability() {
         return stream(TestName.ISF,
                       DiscreteDistributionTestData::getIsfPoints,
                       DiscreteDistributionTestData::getIsfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test and the CDF test points.
      *
      * @return the stream
      */
     Stream<Arguments> testCumulativeProbabilityInverseMapping() {
         return stream(TestName.CDF_MAPPING,
                       DiscreteDistributionTestData::getCdfPoints);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test and the SF test points.
      *
      * @return the stream
      */
     Stream<Arguments> testSurvivalProbabilityInverseMapping() {
         return stream(TestName.SF_MAPPING,
                       DiscreteDistributionTestData::getSfPoints);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test and
      * high-precision CDF test points.
      *
      * @return the stream
      */
     Stream<Arguments> testCumulativeProbabilityHighPrecisionInverseMapping() {
         return stream(TestName.CDF_HP_MAPPING,
                       DiscreteDistributionTestData::getCdfHpPoints);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test and
      * high-precision SF test points.
      *
      * @return the stream
      */
     Stream<Arguments> testSurvivalProbabilityHighPrecisionInverseMapping() {
         return stream(TestName.SF_HP_MAPPING,
                       DiscreteDistributionTestData::getSfHpPoints);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the test points
      * to evaluate the CDF and survival function, and the test tolerance. CDF + SF must equal 1.
      *
      * @return the stream
      */
     Stream<Arguments> testSurvivalAndCumulativeProbabilityComplement() {
         // This is not disabled based on cdf.disable && sf.disable.
         // Those flags are intended to ignore tests against reference values.
         return streamCdfTestPoints(TestName.COMPLEMENT);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the test points
      * to evaluate the CDF and probability in a range, and the test tolerance.
      * Used to test CDF(x1) - CDF(x0) = probability(x0, x1).
      *
      * @return the stream
      */
     Stream<Arguments> testConsistency() {
         // This is not disabled based on cdf.disable.
         // That flag is intended to ignore tests against reference values.
         return streamCdfTestPoints(TestName.CONSISTENCY);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test and the test tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testOutsideSupport() {
         return stream(TestName.OUTSIDE_SUPPORT);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the PMF test points
      * and values. The sampled PMF should sum to more than 50% of the distribution.
      *
      * @return the stream
      */
     Stream<Arguments> testSamplingPMF() {
         return stream(TestName.SAMPLING_PMF,
                       DiscreteDistributionTestData::getPmfPoints,
                       DiscreteDistributionTestData::getPmfValues);
     }
 
     /**
      * Create a stream of arguments containing the distribution to test. Sampling is tested using
      * the distribution quartiles. The quartiles should be approximately 25% of the distribution
      * PMF. Discrete distributions that have single points that contain much more than 25% of the
      * probability mass will be ignored.
      *
      * @return the stream
      */
     Stream<Arguments> testSampling() {
         return stream(TestName.SAMPLING);
     }
 
     /**
      * Stream the arguments to test the probability sums. The test
      * sums the probability mass function between consecutive test points for the cumulative
      * density function. The default tolerance is based on the test tolerance for evaluation
      * of single points of the CDF.
      * Override this method to change the tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testProbabilitySums() {
         // Assume the test tolerance for single CDF values can be relaxed slightly
         // when summing values.
         final double scale = 10;
         final TestName cdf = TestName.CDF;
         final Function<DiscreteDistributionTestData, DoubleTolerance> tolerance =
             d -> createAbsOrRelTolerance(d.getAbsoluteTolerance(cdf) * scale,
                                          d.getRelativeTolerance(cdf) * scale);
         final TestName name = TestName.PMF_SUM;
         return stream(d -> d.isDisabled(name),
                       DiscreteDistributionTestData::getCdfPoints,
                       DiscreteDistributionTestData::getCdfValues,
                       tolerance, name.toString());
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the support
      * lower and upper bound, and the support connect flag.
      *
      * @return the stream
      */
     Stream<Arguments> testSupport() {
         return streamArguments(TestName.SUPPORT,
             d -> Arguments.of(namedDistribution(d.getParameters()), d.getLower(), d.getUpper()));
     }
 
     /**
      * Create a stream of arguments containing the distribution to test, the mean
      * and variance, and the test tolerance.
      *
      * @return the stream
      */
     Stream<Arguments> testMoments() {
         final TestName name = TestName.MOMENTS;
         return streamArguments(name,
             d -> Arguments.of(namedDistribution(d.getParameters()), d.getMean(), d.getVariance(),
                               createTestTolerance(d, name)));
     }
 
     /**
      * Create a stream of arguments containing the distribution to test.
      *
      * @return the stream
      */
     Stream<Arguments> testMedian() {
         return streamArguments(TestName.MEDIAN,
             d -> Arguments.of(namedDistribution(d.getParameters())));
     }
 
     //------------------------ Tests -----------------------------
 
     // Tests are final. It is expected that the test can be modified by overriding
     // the method used to stream the arguments, for example to use a specific tolerance
     // for a test in preference to the tolerance defined in the properties file.
 
     // Extract the tests from the previous abstract test
 
     /**
      * Test that probability calculations match expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testProbability(DiscreteDistribution dist,
                                int[] points,
                                double[] values,
                                DoubleTolerance tolerance) {
         for (int i = 0; i < points.length; i++) {
             final int x = points[i];
             TestUtils.assertEquals(values[i],
                 dist.probability(x), tolerance,
                 () -> "Incorrect probability mass value returned for " + x);
         }
     }
 
     /**
      * Test that logarithmic probability calculations match expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testLogProbability(DiscreteDistribution dist,
                                   int[] points,
                                   double[] values,
                                   DoubleTolerance tolerance) {
         for (int i = 0; i < points.length; i++) {
             final int x = points[i];
             TestUtils.assertEquals(values[i],
                 dist.logProbability(x), tolerance,
                 () -> "Incorrect log probability mass value returned for " + x);
         }
     }
 
     /**
      * Test that cumulative probability density calculations match expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testCumulativeProbability(DiscreteDistribution dist,
                                          int[] points,
                                          double[] values,
                                          DoubleTolerance tolerance) {
         // verify cumulativeProbability(double)
         for (int i = 0; i < points.length; i++) {
             final int x = points[i];
             TestUtils.assertEquals(values[i],
                 dist.cumulativeProbability(x),
                 tolerance,
                 () -> "Incorrect cumulative probability value returned for " + x);
         }
     }
 
     /**
      * Test that survival probability density calculations match expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testSurvivalProbability(DiscreteDistribution dist,
                                        int[] points,
                                        double[] values,
                                        DoubleTolerance tolerance) {
         for (int i = 0; i < points.length; i++) {
             final double x = points[i];
             TestUtils.assertEquals(
                 values[i],
                 dist.survivalProbability(points[i]),
                 tolerance,
                 () -> "Incorrect survival probability value returned for " + x);
         }
     }
 
     /**
      * Test that cumulative probability is not {@code (1 - survival probability)} by testing values
      * that would result in inaccurate results if simply calculating (1 - sf).
      */
     @ParameterizedTest
     @MethodSource
     final void testCumulativeProbabilityHighPrecision(DiscreteDistribution dist,
                                                       int[] points,
                                                       double[] values,
                                                       DoubleTolerance tolerance) {
         assertHighPrecision(tolerance, values);
         testCumulativeProbability(dist, points, values, tolerance);
     }
 
     /**
      * Test that survival probability is not {@code (1 - cumulative probability)} by testing values
      * that would result in inaccurate results if simply calculating (1 - cdf).
      */
     @ParameterizedTest
     @MethodSource
     final void testSurvivalProbabilityHighPrecision(DiscreteDistribution dist,
                                                     int[] points,
                                                     double[] values,
                                                     DoubleTolerance tolerance) {
         assertHighPrecision(tolerance, values);
         testSurvivalProbability(dist, points, values, tolerance);
     }
 
     /**
      * Test that inverse cumulative probability density calculations match expected values.
      *
      * <p>Note: Any expected values outside the support of the distribution are ignored.
      */
     @ParameterizedTest
     @MethodSource
     final void testInverseCumulativeProbability(DiscreteDistribution dist,
                                                 double[] points,
                                                 int[] values) {
         final int lower = dist.getSupportLowerBound();
         final int upper = dist.getSupportUpperBound();
         for (int i = 0; i < points.length; i++) {
             final int x = values[i];
             if (x < lower || x > upper) {
                 continue;
             }
             final double p = points[i];
             Assertions.assertEquals(
                 x,
                 dist.inverseCumulativeProbability(p),
                 () -> "Incorrect inverse cumulative probability value returned for " + p);
         }
     }
 
     /**
      * Test that inverse survival probability density calculations match expected values.
      *
      * <p>Note: Any expected values outside the support of the distribution are ignored.
      */
     @ParameterizedTest
     @MethodSource
     final void testInverseSurvivalProbability(DiscreteDistribution dist,
                                               double[] points,
                                               int[] values) {
         final int lower = dist.getSupportLowerBound();
         final int upper = dist.getSupportUpperBound();
         for (int i = 0; i < points.length; i++) {
             final int x = values[i];
             if (x < lower || x > upper) {
                 continue;
             }
             final double p = points[i];
             Assertions.assertEquals(
                 x,
                 dist.inverseSurvivalProbability(p),
                 () -> "Incorrect inverse survival probability value returned for " + p);
         }
     }
 
     /**
      * Test that an inverse mapping of the cumulative probability density values matches
      * the original point, {@code x = icdf(cdf(x))}.
      *
      * <p>Note: It is possible for two points to compute the same CDF value. In this
      * case the mapping is not a bijection. Any points computing a CDF=0 or 1 are ignored
      * as this is expected to be inverted to the domain bound.
      *
      * <p>Note: Any points outside the support of the distribution are ignored.
      *
      * <p>This test checks consistency of the inverse with the forward function.
      * The test checks (where applicable):
      * <ul>
      *  <li>{@code icdf( cdf(x) ) = x}
      *  <li>{@code icdf( p > cdf(x) ) >= x+1}
      *  <li>{@code icdf( cdf(x-1) < p < cdf(x) ) = x}
      * </ul>
      *
      * <p>Does not check {@code isf( 1 - cdf(x) ) = x} since the complement {@code q = 1 - p}
      * is inexact. The bound change for the isf to compute x may be different. The isf bound
      * change is verified in a separate test.
      * Thus the {@code icdf <-> cdf} mapping and {@code isf <-> sf} mapping are verified to
      * have correct boundary changes with respect to the forward function and its inverse
      * but the boundaries are allowed to be different. This can be corrected for example
      * with an implementation that has a consistent computation for {@code x > median} and
      * another for {@code x < median} with an inverse computation determined by {@code p > 0.5}.
      */
     @ParameterizedTest
     @MethodSource
     final void testCumulativeProbabilityInverseMapping(DiscreteDistribution dist,
                                                        int[] points) {
         final int lower = dist.getSupportLowerBound();
         final int upper = dist.getSupportUpperBound();
         for (int i = 0; i < points.length; i++) {
             final int x = points[i];
             if (x < lower || x > upper) {
                 continue;
             }
             final double p = dist.cumulativeProbability(x);
             if ((int) p == p) {
                 // Assume mapping not a bijection and ignore
                 continue;
             }
             final double x1 = dist.inverseCumulativeProbability(p);
             Assertions.assertEquals(
                 x,
                 x1,
                 () -> "Incorrect CDF inverse value returned for " + p);
             // The next p value up should return the next value
             final double pp = Math.nextUp(p);
             if (x != upper && pp != 1 && p != dist.cumulativeProbability(x + 1)) {
                 final double x2 = dist.inverseCumulativeProbability(pp);
                 Assertions.assertEquals(
                     x + 1,
                     x2,
                     () -> "Incorrect CDF inverse value returned for " + pp);
             }
 
             // Invert a probability inside the range to the previous CDF value
             if (x != lower) {
                 final double pm1 = dist.cumulativeProbability(x - 1);
                 final double px = (pm1 + p) / 2;
                 if (px > pm1) {
                     final double xx = dist.inverseCumulativeProbability(px);
                     Assertions.assertEquals(
                         x,
                         xx,
                         () -> "Incorrect CDF inverse value returned for " + px);
                 }
             }
         }
     }
 
     /**
      * Test that an inverse mapping of the survival probability density values matches
      * the original point, {@code x = isf(sf(x))}.
      *
      * <p>Note: It is possible for two points to compute the same SF value. In this
      * case the mapping is not a bijection. Any points computing a SF=0 or 1 are ignored
      * as this is expected to be inverted to the domain bound.
      *
      * <p>Note: Any points outside the support of the distribution are ignored.
      *
      * <p>This test checks consistency of the inverse with the forward function.
      * The test checks (where applicable):
      * <ul>
      *  <li>{@code isf( sf(x) ) = x}
      *  <li>{@code isf( p < sf(x) ) >= x+1}
      *  <li>{@code isf( sf(x-1) > p > sf(x) ) = x}
      * </ul>
      *
      * <p>Does not check {@code icdf( 1 - sf(x) ) = x} since the complement {@code q = 1 - p}
      * is inexact. The bound change for the icdf to compute x may be different. The icdf bound
      * change is verified in a separate test.
      * Thus the {@code icdf <-> cdf} mapping and {@code isf <-> sf} mapping are verified to
      * have correct boundary changes with respect to the forward function and its inverse
      * but the boundaries are allowed to be different. This can be corrected for example
      * with an implementation that has a consistent computation for {@code x > median} and
      * another for {@code x < median} with an inverse computation determined by {@code p > 0.5}.
      */
     @ParameterizedTest
     @MethodSource
     final void testSurvivalProbabilityInverseMapping(DiscreteDistribution dist,
                                                      int[] points) {
         final int lower = dist.getSupportLowerBound();
         final int upper = dist.getSupportUpperBound();
         for (int i = 0; i < points.length; i++) {
             final int x = points[i];
             if (x < lower || x > upper) {
                 continue;
             }
             final double p = dist.survivalProbability(x);
             if ((int) p == p) {
                 // Assume mapping not a bijection and ignore
                 continue;
             }
             final double x1 = dist.inverseSurvivalProbability(p);
             Assertions.assertEquals(
                 x,
                 x1,
                 () -> "Incorrect SF inverse value returned for " + p);
 
             // The next p value down should return the next value
             final double pp = Math.nextDown(p);
             if (x != upper && pp != 0 && p != dist.survivalProbability(x + 1)) {
                 final double x2 = dist.inverseSurvivalProbability(pp);
                 Assertions.assertEquals(
                     x + 1,
                     x2,
                     () -> "Incorrect SF inverse value returned for " + pp);
             }
 
             // Invert a probability inside the range to the previous SF value
             if (x != lower) {
                 final double pm1 = dist.survivalProbability(x - 1);
                 final double px = (pm1 + p) / 2;
                 if (px < pm1) {
                     final double xx = dist.inverseSurvivalProbability(px);
                     Assertions.assertEquals(
                         x,
                         xx,
                         () -> "Incorrect SF inverse value returned for " + px);
                 }
             }
         }
     }
 
     /**
      * Test that an inverse mapping of the cumulative probability density values matches
      * the original point, {@code x = icdf(cdf(x))} using the points for the high-precision
      * CDF.
      */
     @ParameterizedTest
     @MethodSource
     final void testCumulativeProbabilityHighPrecisionInverseMapping(
             DiscreteDistribution dist,
             int[] points) {
         testCumulativeProbabilityInverseMapping(dist, points);
     }
 
     /**
      * Test that an inverse mapping of the survival probability density values matches
      * the original point, {@code x = isf(sf(x))} using the points for the high-precision
      * SF.
      */
     @ParameterizedTest
     @MethodSource
     final void testSurvivalProbabilityHighPrecisionInverseMapping(
             DiscreteDistribution dist,
             int[] points) {
         testSurvivalProbabilityInverseMapping(dist, points);
     }
 
     /**
      * Test that cumulative probability density and survival probability calculations
      * sum to approximately 1.0.
      */
     @ParameterizedTest
     @MethodSource
     final void testSurvivalAndCumulativeProbabilityComplement(DiscreteDistribution dist,
                                                               int[] points,
                                                               DoubleTolerance tolerance) {
         for (final int x : points) {
             TestUtils.assertEquals(
                 1.0,
                 dist.survivalProbability(x) + dist.cumulativeProbability(x),
                 tolerance,
                 () -> "survival + cumulative probability were not close to 1.0 for " + x);
         }
     }
 
     /**
      * Test that probability computations are consistent.
      * This checks probability(x, x) = 0; probability(x, x+1) = probability(x+1)
      * and probability(x0, x1) = CDF(x1) - CDF(x0).
      */
     @ParameterizedTest
     @MethodSource
     final void testConsistency(DiscreteDistribution dist,
                                int[] points,
                                DoubleTolerance tolerance) {
         final int upper = dist.getSupportUpperBound();
         for (int i = 0; i < points.length; i++) {
             final int x0 = points[i];
 
             // Check that probability(x, x) == 0
             Assertions.assertEquals(
                 0.0,
                 dist.probability(x0, x0),
                 () -> "Non-zero probability(x, x) for " + x0);
 
             // Check that probability(x, x + 1) == probability(x + 1)
             if (x0 < upper) {
                 Assertions.assertEquals(
                     dist.probability(x0 + 1),
                     dist.probability(x0, x0 + 1),
                     () -> "probability(x + 1) != probability(x, x + 1) for " + x0);
             }
 
             final double cdf0 = dist.cumulativeProbability(x0);
             final double sf0 = cdf0 >= 0.5 ? dist.survivalProbability(x0) : Double.NaN;
             for (int j = 0; j < points.length; j++) {
                 final int x1 = points[j];
                 // Ignore adjacent points.
                 // Use long arithmetic to avoid overflow if x0 is the maximum integer value
                 if (x0 + 1L < x1) {
                     // Check that probability(x0, x1) = CDF(x1) - CDF(x0).
                     // If x0 is above the median it is more accurate to use the
                     // survival probability: probability(x0, x1) = SF(x0) - SF(x1).
                     double expected;
                     if (cdf0 >= 0.5) {
                         expected = sf0 - dist.survivalProbability(x1);
                     } else {
                         expected = dist.cumulativeProbability(x1) - cdf0;
                     }
                     TestUtils.assertEquals(
                         expected,
                         dist.probability(x0, x1),
                         tolerance,
                         () -> "Inconsistent probability for (" + x0 + "," + x1 + ")");
                 } else if (x0 > x1) {
                     Assertions.assertThrows(IllegalArgumentException.class,
                         () -> dist.probability(x0, x1),
                         "probability(int, int) should have thrown an exception that first argument is too large");
                 }
             }
         }
     }
 
     /**
      * Test CDF and inverse CDF values at the edge of the support of the distribution return
      * expected values and the CDF outside the support returns consistent values.
      */
     @ParameterizedTest
     @MethodSource
     final void testOutsideSupport(DiscreteDistribution dist,
                                   DoubleTolerance tolerance) {
         // Test various quantities when the variable is outside the support.
         final int lo = dist.getSupportLowerBound();
         TestUtils.assertEquals(dist.probability(lo), dist.cumulativeProbability(lo), tolerance, () -> "pmf(lower) != cdf(lower) for " + lo);
         Assertions.assertEquals(lo, dist.inverseCumulativeProbability(-0.0), "icdf(-0.0)");
         Assertions.assertEquals(lo, dist.inverseCumulativeProbability(0.0), "icdf(0.0)");
         Assertions.assertEquals(lo, dist.inverseSurvivalProbability(1.0), "isf(1.0)");
 
         if (lo != Integer.MIN_VALUE) {
             final int below = lo - 1;
             Assertions.assertEquals(0.0, dist.probability(below), "pmf(x < lower)");
             Assertions.assertEquals(Double.NEGATIVE_INFINITY, dist.logProbability(below), "logpmf(x < lower)");
             Assertions.assertEquals(0.0, dist.cumulativeProbability(below), "cdf(x < lower)");
             Assertions.assertEquals(1.0, dist.survivalProbability(below), "sf(x < lower)");
         }
 
         final int hi = dist.getSupportUpperBound();
         Assertions.assertTrue(lo <= hi, "lower <= upper");
         Assertions.assertEquals(hi, dist.inverseCumulativeProbability(1.0), "icdf(1.0)");
         Assertions.assertEquals(hi, dist.inverseSurvivalProbability(-0.0), "isf(-0.0)");
         Assertions.assertEquals(hi, dist.inverseSurvivalProbability(0.0), "isf(0.0)");
         if (hi != Integer.MAX_VALUE) {
             // For distributions defined up to integer max value we cannot test that
             // the CDF is 1.0 as they may be truncated.
             Assertions.assertEquals(1.0, dist.cumulativeProbability(hi), "cdf(upper)");
             Assertions.assertEquals(0.0, dist.survivalProbability(hi), "sf(upper)");
             TestUtils.assertEquals(dist.probability(hi), dist.survivalProbability(hi - 1), tolerance, () -> "pmf(upper - 1) != sf(upper - 1) for " + hi);
 
             final int above = hi + 1;
             Assertions.assertEquals(0.0, dist.probability(above), "pmf(x > upper)");
             Assertions.assertEquals(Double.NEGATIVE_INFINITY, dist.logProbability(above), "logpmf(x > upper)");
             Assertions.assertEquals(1.0, dist.cumulativeProbability(above), "cdf(x > upper)");
             Assertions.assertEquals(0.0, dist.survivalProbability(above), "sf(x > upper)");
         }
 
         // Test the logProbability at the support bound. This hits edge case coverage for logProbability.
         assertPmfAndLogPmfAtBound(dist, lo, tolerance, "lower");
         assertPmfAndLogPmfAtBound(dist, hi, tolerance, "upper");
     }
 
     /**
      * Assert the PMF and log PMF are consistent at the named point.
      * This method asserts either:
      * <pre>
      * log(pmf) == logpmf
      * pmf      == exp(logpmf)
      * </pre>
      *
      * @param dist Distribution
      * @param x Point
      * @param tolerance Test tolerance
      * @param name Point name
      */
     private static void assertPmfAndLogPmfAtBound(DiscreteDistribution dist, int x,
                                                   DoubleTolerance tolerance, String name) {
         // It is assumed the log probability may support a value when the plain probability will be zero.
         // Only assert Math.log(dist.probability(x)) == dist.logProbability(x) for normal values.
         final double p = dist.probability(x);
         final double logp = dist.logProbability(x);
         if (p > Double.MIN_NORMAL) {
             TestUtils.assertEquals(Math.log(p), logp, tolerance,
                 () -> String.format("%s: log(pmf(%d)) != logpmf(%d)", name, x, x));
         } else {
             TestUtils.assertEquals(p, Math.exp(logp), tolerance,
                 () -> String.format("%s: pmf(%d) != exp(logpmf(%d))", name, x, x));
         }
     }
 
     /**
      * Test invalid probabilities passed to computations that require a p-value in {@code [0, 1]}
      * or a range where {@code p1 <= p2}.
      */
     @ParameterizedTest
     @MethodSource(value = "streamDistribution")
     final void testInvalidProbabilities(DiscreteDistribution dist) {
         final int lo = dist.getSupportLowerBound();
         final int hi = dist.getSupportUpperBound();
         if (lo < hi) {
             Assertions.assertThrows(DistributionException.class, () -> dist.probability(hi, lo), "x0 > x1");
         }
         Assertions.assertThrows(DistributionException.class, () -> dist.inverseCumulativeProbability(-1), "p < 0.0");
         Assertions.assertThrows(DistributionException.class, () -> dist.inverseCumulativeProbability(2), "p > 1.0");
         Assertions.assertThrows(DistributionException.class, () -> dist.inverseSurvivalProbability(-1), "q < 0.0");
         Assertions.assertThrows(DistributionException.class, () -> dist.inverseSurvivalProbability(2), "q > 1.0");
     }
 
     /**
      * Test sampling from the distribution.
      * This test uses the points that are used to test the distribution PMF.
      * The test is skipped if the sum of the PMF values is less than 0.5.
      */
     @ParameterizedTest
     @MethodSource
     final void testSamplingPMF(DiscreteDistribution dist,
                                int[] points,
                                double[] values) {
         // This test uses the points that are used to test the distribution PMF.
         // The sum of the probability values does not have to be 1 (or very close to 1).
         // Any value generated by the sampler that is not an expected point will
         // be ignored. If the sum of probabilities is above 0.5 then at least half
         // of the samples should be counted and the test will verify these occur with
         // the expected relative frequencies. Note: The expected values are normalised
         // to 1 (i.e. relative frequencies) by the Chi-square test.
         points = points.clone();
         values = values.clone();
         final int length = TestUtils.eliminateZeroMassPoints(points, values);
         final double[] expected = Arrays.copyOf(values, length);
 
         // This test will not be valid if the points do not represent enough of the PMF.
         // Require at least 50%.
         final double sum = Arrays.stream(expected).sum();
         Assumptions.assumeTrue(sum > 0.5,
             () -> "Not enough of the PMF is tested during sampling: " + sum);
 
         // Use fixed seed.
         final DiscreteDistribution.Sampler sampler =
                 dist.createSampler(RandomSource.XO_SHI_RO_256_PP.create(1234567890L));
 
         // Edge case for distributions with all mass in a single point
         if (length == 1) {
             final int point = points[0];
             for (int i = 0; i < 20; i++) {
                 Assertions.assertEquals(point, sampler.sample());
             }
             return;
         }
 
         final int sampleSize = 1000;
         MathArrays.scaleInPlace(sampleSize, expected);
 
         final int[] sample = TestUtils.sample(sampleSize, sampler);
 
         final long[] counts = new long[length];
         for (int i = 0; i < sampleSize; i++) {
             final int x = sample[i];
             for (int j = 0; j < length; j++) {
                 if (x == points[j]) {
                     counts[j]++;
                     break;
                 }
             }
         }
 
         TestUtils.assertChiSquareAccept(points, expected, counts, 0.001);
     }
 
     /**
      * Test sampling from the distribution using quartiles.
      * This test is ignored if the range for the distribution PMF is small
      * and the quartiles do not map to approximately 0.25. When the range of
      * the distribution is small then the {@link #testSamplingPMF(DiscreteDistribution, int[], double[])}
      * method should be used with points that covers at least 50% of the PMF.
      */
     @ParameterizedTest
     @MethodSource
     final void testSampling(DiscreteDistribution dist) {
         final int[] quartiles = TestUtils.getDistributionQuartiles(dist);
         // The distribution quartiles are created using the inverse CDF.
         // This may not be accurate for extreme parameterizations of the distribution.
         // So use the values to compute the expected probability for each interval.
         final double[] expected = {
             dist.cumulativeProbability(quartiles[0]),
             dist.probability(quartiles[0], quartiles[1]),
             dist.probability(quartiles[1], quartiles[2]),
             dist.survivalProbability(quartiles[2]),
         };
         // Ignore this test if the quartiles are different from a quarter.
         // This will exclude distributions where the PMF is heavily concentrated
         // at a single point. In this case it can be realistically
         // sampled using a small number of points.
         final DoubleTolerance tolerance = DoubleTolerances.absolute(0.1);
         for (final double p : expected) {
             Assumptions.assumeTrue(tolerance.test(0.25, p),
                 () -> "Unexpected quartiles: " + Arrays.toString(expected));
         }
 
         final int sampleSize = 1000;
         MathArrays.scaleInPlace(sampleSize, expected);
 
         // Use fixed seed.
         final DiscreteDistribution.Sampler sampler =
             dist.createSampler(RandomSource.XO_SHI_RO_256_PP.create(123456789L));
         final int[] sample = TestUtils.sample(sampleSize, sampler);
 
         final long[] counts = new long[4];
         for (int i = 0; i < sampleSize; i++) {
             TestUtils.updateCounts(sample[i], counts, quartiles);
         }
 
         TestUtils.assertChiSquareAccept(expected, counts, 0.001);
     }
 
     /**
      * Test that probability sums match the distribution.
      * The (filtered, sorted) points array is used to source
      * summation limits. The sum of the probability mass function
      * is compared with the probability over the same interval.
      * Test points outside of the domain of the probability function
      * are discarded and large intervals are ignored.
      *
      * <p>This test is ignored for large ranges.
      */
     @ParameterizedTest
     @MethodSource
     final void testProbabilitySums(DiscreteDistribution dist,
                                    int[] points,
                                    double[] values,
                                    DoubleTolerance tolerance) {
         final ArrayList<Integer> integrationTestPoints = new ArrayList<>();
         for (int i = 0; i < points.length; i++) {
             if (Double.isNaN(values[i]) ||
                 values[i] < 1e-5 ||
                 values[i] > 1 - 1e-5) {
                 continue; // exclude sums outside domain.
             }
             integrationTestPoints.add(points[i]);
         }
         Collections.sort(integrationTestPoints);
 
         for (int i = 1; i < integrationTestPoints.size(); i++) {
             final int x0 = integrationTestPoints.get(i - 1);
             final int x1 = integrationTestPoints.get(i);
             // Ignore large ranges
             if (x1 - x0 > SUM_RANGE_TOO_LARGE) {
                 continue;
             }
             final double sum = IntStream.rangeClosed(x0 + 1, x1).mapToDouble(dist::probability).sum();
             TestUtils.assertEquals(dist.probability(x0, x1), sum, tolerance,
                 () -> "Invalid probability sum: " + (x0 + 1) + " to " + x1);
         }
     }
 
     /**
      * Test the support of the distribution matches the expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testSupport(DiscreteDistribution dist, double lower, double upper) {
         Assertions.assertEquals(lower, dist.getSupportLowerBound(), "lower bound");
         Assertions.assertEquals(upper, dist.getSupportUpperBound(), "upper bound");
     }
 
     /**
      * Test the moments of the distribution matches the expected values.
      */
     @ParameterizedTest
     @MethodSource
     final void testMoments(DiscreteDistribution dist, double mean, double variance, DoubleTolerance tolerance) {
         TestUtils.assertEquals(mean, dist.getMean(), tolerance, "mean");
         TestUtils.assertEquals(variance, dist.getVariance(), tolerance, "variance");
     }
 
     /**
      * Test the median of the distribution is equal to the value returned from the inverse CDF.
      * The median is used internally for computation of the probability of a range
      * using either the CDF or survival function. If overridden by a distribution it should
      * be equivalent to the inverse CDF called with 0.5.
      *
      * <p>The method modifiers are asserted to check the method is not public or protected.
      */
     @ParameterizedTest
     @MethodSource
     final void testMedian(DiscreteDistribution dist) {
         if (dist instanceof AbstractDiscreteDistribution) {
             final AbstractDiscreteDistribution d = (AbstractDiscreteDistribution) dist;
             Assertions.assertEquals(d.inverseCumulativeProbability(0.5), d.getMedian(), "median");
             assertMethodNotModified(dist.getClass(), Modifier.PUBLIC | Modifier.PROTECTED, "getMedian");
         }
     }
 }