Distribution.java

package org.opentrafficsim.core.distributions;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.List;

import org.djutils.exceptions.Throw;

import nl.tudelft.simulation.jstats.distributions.DistUniform;
import nl.tudelft.simulation.jstats.streams.StreamInterface;

/**
 * Generic implementation of a set of objects that have a draw method with corresponding probabilities / frequencies.
 * <p>
 * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands. All rights reserved. <br>
 * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
 * </p>
 * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
 * @param <O> Type of the object returned by the draw method
 */
public class Distribution<O> implements Generator<O>, Serializable
{
    /** */
    private static final long serialVersionUID = 20160301L;

    /** The generators (with their probabilities or frequencies). */
    private final List<FrequencyAndObject<O>> generators = new ArrayList<>();

    /** Sum of all probabilities or frequencies. */
    private double cumulativeTotal;

    /** The uniform random generator used to select a Generator. */
    private final DistUniform random;

    /**
     * Construct a new Distribution.
     * @param generators List&lt;FrequencyAndObject&lt;O&gt;&gt;; the generators and their frequencies (or probabilities)
     * @param stream StreamInterface; source for randomness
     * @throws ProbabilityException when a frequency (or probability) is negative, or when generators is null or stream is null
     */
    public Distribution(final List<FrequencyAndObject<O>> generators, final StreamInterface stream) throws ProbabilityException
    {
        this(stream);
        Throw.when(null == generators, ProbabilityException.class, "generators may not be null");
        // Store a defensive copy of the generator list (the generators are immutable; a list of them is not) and make sure it
        // is a List that supports add, remove, etc.
        this.generators.addAll(generators);
        fixProbabilities();
    }

    /**
     * Construct a new Distribution with no generators.
     * @param stream StreamInterface; source for randomness
     * @throws ProbabilityException when a frequency (or probability) is negative, or when generators is null or stream is null
     */
    public Distribution(final StreamInterface stream) throws ProbabilityException
    {
        Throw.when(null == stream, ProbabilityException.class, "random stream may not be null");
        this.random = new DistUniform(stream, 0, 1);
    }

    /**
     * Compute the cumulative frequencies of the storedGenerators.
     * @throws ProbabilityException on negative frequency
     */
    private void fixProbabilities() throws ProbabilityException
    {
        if (0 == this.generators.size())
        {
            return;
        }
        this.cumulativeTotal = 0;
        for (FrequencyAndObject<O> generator : this.generators)
        {
            double frequency = generator.getFrequency();
            Throw.when(frequency < 0, ProbabilityException.class,
                    "Negative frequency or probability is not allowed (got " + frequency + ")");
            this.cumulativeTotal += frequency;
        }
    }

    /** {@inheritDoc} */
    @Override
    public final O draw() throws ProbabilityException
    {
        Throw.when(0 == this.generators.size(), ProbabilityException.class, "Cannot draw from empty collection");
        Throw.when(0 == this.cumulativeTotal, ProbabilityException.class, "Sum of frequencies or probabilities must be > 0");

        double randomValue = this.random.draw() * this.cumulativeTotal;
        for (FrequencyAndObject<O> fAndO : this.generators)
        {
            double frequency = fAndO.getFrequency();
            if (frequency >= randomValue)
            {
                return fAndO.getObject();
            }
            randomValue -= frequency;
        }
        // If we get here we missed the intended object by a few ULP; return the first object that has non-zero frequency
        FrequencyAndObject<O> useThisOne = this.generators.get(0);
        for (FrequencyAndObject<O> fAndO : this.generators)
        {
            if (fAndO.getFrequency() > 0)
            {
                useThisOne = fAndO;
                break;
            }
        }
        return useThisOne.getObject();
    }

    /**
     * Append a generator to the internally stored list.
     * @param generator FrequencyAndObject&lt;O&gt;; the generator to add
     * @return Distribution&lt;O&gt;; this
     * @throws ProbabilityException when frequency less than zero
     */
    public final Distribution<O> add(final FrequencyAndObject<O> generator) throws ProbabilityException
    {
        return add(this.generators.size(), generator);
    }

    /**
     * Insert a generator at the specified position in the internally stored list.
     * @param index int; position to store the generator
     * @param generator FrequencyAndObject&lt;O&gt;; the generator to add
     * @return Distribution&lt;O&gt;; this
     * @throws ProbabilityException when frequency less than zero
     */
    public final Distribution<O> add(final int index, final FrequencyAndObject<O> generator) throws ProbabilityException
    {
        Throw.when(generator.getFrequency() < 0, ProbabilityException.class,
                "frequency (or probability) must be >= 0 (got " + generator.getFrequency() + ")");
        this.generators.add(index, generator);
        fixProbabilities();
        return this;
    }

    /**
     * Remove the generator at the specified position from the internally stored list.
     * @param index int; the position
     * @return this
     * @throws IndexOutOfBoundsException when index is &lt; 0 or &gt;= size
     * @throws ProbabilityException if the sum of the remaining probabilities or frequencies adds up to 0
     */
    public final Distribution<O> remove(final int index) throws IndexOutOfBoundsException, ProbabilityException
    {
        this.generators.remove(index);
        fixProbabilities();
        return this;
    }

    /**
     * Replace the generator at the specified position.
     * @param index int; the position of the generator that must be replaced
     * @param generator FrequencyAndObject&lt;O&gt;; the new generator and the frequency (or probability)
     * @return this
     * @throws ProbabilityException when the frequency (or probability) &lt; 0, or when index is &lt; 0 or &gt;= size
     */
    public final Distribution<O> set(final int index, final FrequencyAndObject<O> generator) throws ProbabilityException
    {
        Throw.when(generator.getFrequency() < 0, ProbabilityException.class,
                "frequency (or probability) must be >= 0 (got " + generator.getFrequency() + ")");
        try
        {
            this.generators.set(index, generator);
        }
        catch (IndexOutOfBoundsException ie)
        {
            throw new ProbabilityException("Index out of bounds for set operation, index=" + index);
        }
        fixProbabilities();
        return this;
    }

    /**
     * Alter the frequency (or probability) of one of the stored generators.
     * @param index int; index of the stored generator
     * @param frequency double; new frequency (or probability)
     * @return this
     * @throws ProbabilityException when the frequency (or probability) &lt; 0, or when index is &lt; 0 or &gt;= size
     */
    public final Distribution<O> modifyFrequency(final int index, final double frequency) throws ProbabilityException
    {
        Throw.when(index < 0 || index >= this.size(), ProbabilityException.class, "Index %s out of range (0..%d)", index,
                this.size() - 1);
        return set(index, new FrequencyAndObject<O>(frequency, this.generators.get(index).getObject()));
    }

    /**
     * Empty the internally stored list.
     * @return this
     */
    public final Distribution<O> clear()
    {
        this.generators.clear();
        return this;
    }

    /**
     * Retrieve one of the internally stored generators.
     * @param index int; the index of the FrequencyAndObject to retrieve
     * @return FrequencyAndObject&lt;O&gt;; the generator stored at position <cite>index</cite>
     * @throws ProbabilityException when index &lt; 0 or &gt;= size()
     */
    public final FrequencyAndObject<O> get(final int index) throws ProbabilityException
    {
        try
        {
            return this.generators.get(index);
        }
        catch (IndexOutOfBoundsException ie)
        {
            throw new ProbabilityException("Index out of bounds for set operation, index=" + index);
        }
    }

    /**
     * Report the number of generators.
     * @return int; the number of generators
     */
    public final int size()
    {
        return this.generators.size();
    }

    /** {@inheritDoc} */
    @Override
    public final int hashCode()
    {
        final int prime = 31;
        int result = 1;
        long temp;
        temp = Double.doubleToLongBits(this.cumulativeTotal);
        result = prime * result + (int) (temp ^ (temp >>> 32));
        result = prime * result + ((this.generators == null) ? 0 : this.generators.hashCode());
        result = prime * result + ((this.random == null) ? 0 : this.random.hashCode());
        return result;
    }

    /** {@inheritDoc} */
    @Override
    @SuppressWarnings("checkstyle:needbraces")
    public final boolean equals(final Object obj)
    {
        if (this == obj)
            return true;
        if (obj == null)
            return false;
        if (getClass() != obj.getClass())
            return false;
        Distribution<?> other = (Distribution<?>) obj;
        if (Double.doubleToLongBits(this.cumulativeTotal) != Double.doubleToLongBits(other.cumulativeTotal))
            return false;
        if (this.generators == null)
        {
            if (other.generators != null)
                return false;
        }
        else if (!this.generators.equals(other.generators))
            return false;
        if (this.random == null)
        {
            if (other.random != null)
                return false;
        }
        else if (!this.random.equals(other.random))
            return false;
        return true;
    }

    /** {@inheritDoc} */
    @Override
    public final String toString()
    {
        StringBuilder result = new StringBuilder();
        result.append("Distribution [");
        String separator = "";
        for (FrequencyAndObject<O> fAndO : this.generators)
        {
            result.append(separator + fAndO.getFrequency() + "->" + fAndO.getObject());
            separator = ", ";
        }
        result.append(']');
        return result.toString();
    }

    /**
     * Immutable storage for a frequency (or probability) plus a Generator.
     * <p>
     * Copyright (c) 2013-2024 Delft University of Technology, PO Box 5, 2600 AA, Delft, the Netherlands.<br>
     * All rights reserved. <br>
     * BSD-style license. See <a href="https://opentrafficsim.org/docs/license.html">OpenTrafficSim License</a>.
     * </p>
     * @author <a href="https://github.com/averbraeck">Alexander Verbraeck</a>
     * @author <a href="https://tudelft.nl/staff/p.knoppers-1">Peter Knoppers</a>
     * @param <O> Type of the object returned by the draw method
     */
    public static class FrequencyAndObject<O> implements Serializable
    {
        /** */
        private static final long serialVersionUID = 20160301L;

        /** Frequency (or probability) of an object. */
        private final double frequency;

        /** The object. */
        private final O object;

        /**
         * Construct a new FrequencyAndObject instance.
         * @param frequency double; the (<b>not cumulative</b>) frequency (or probability) of the <cite>generatingObject</cite>
         * @param object O; an object
         */
        public FrequencyAndObject(final double frequency, final O object)
        {
            this.frequency = frequency;
            this.object = object;
        }

        /**
         * Retrieve the frequency (or probability) of this FrequencyAndObject.
         * @return double; the frequency (or probability) of this FrequencyAndObject
         */
        public final double getFrequency()
        {
            return this.frequency;
        }

        /**
         * Call the draw method of the generatingObject and return its result.
         * @return O; the result of a call to the draw method of the generatingObject
         */
        public final O getObject()
        {
            return this.object;
        }

        /** {@inheritDoc} */
        @Override
        public final int hashCode()
        {
            final int prime = 31;
            int result = 1;
            long temp;
            temp = Double.doubleToLongBits(this.frequency);
            result = prime * result + (int) (temp ^ (temp >>> 32));
            result = prime * result + ((this.object == null) ? 0 : this.object.hashCode());
            return result;
        }

        /** {@inheritDoc} */
        @Override
        @SuppressWarnings("checkstyle:needbraces")
        public final boolean equals(final Object obj)
        {
            if (this == obj)
                return true;
            if (obj == null)
                return false;
            if (getClass() != obj.getClass())
                return false;
            FrequencyAndObject<?> other = (FrequencyAndObject<?>) obj;
            if (Double.doubleToLongBits(this.frequency) != Double.doubleToLongBits(other.frequency))
                return false;
            if (this.object == null)
            {
                if (other.object != null)
                    return false;
            }
            else if (!this.object.equals(other.object))
                return false;
            return true;
        }

        /** {@inheritDoc} */
        @Override
        public final String toString()
        {
            return "FrequencyAndObject [frequency=" + this.frequency + ", object=" + this.object + "]";
        }

    }

}