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.rng.sampling.distribution;
018
019import org.apache.commons.rng.UniformRandomProvider;
020
021/**
022 * Sampling from a <a href="https://en.wikipedia.org/wiki/Pareto_distribution">Pareto distribution</a>.
023 *
024 * <p>Sampling uses {@link UniformRandomProvider#nextDouble()}.</p>
025 *
026 * @since 1.0
027 */
028public class InverseTransformParetoSampler
029    extends SamplerBase
030    implements SharedStateContinuousSampler {
031    /** Scale. */
032    private final double scale;
033    /** 1 / Shape. */
034    private final double oneOverShape;
035    /** Underlying source of randomness. */
036    private final UniformRandomProvider rng;
037
038    /**
039     * @param rng Generator of uniformly distributed random numbers.
040     * @param scale Scale of the distribution.
041     * @param shape Shape of the distribution.
042     * @throws IllegalArgumentException if {@code scale <= 0} or {@code shape <= 0}
043     */
044    public InverseTransformParetoSampler(UniformRandomProvider rng,
045                                         double scale,
046                                         double shape) {
047        super(null);
048        if (scale <= 0) {
049            throw new IllegalArgumentException("scale is not strictly positive: " + scale);
050        }
051        if (shape <= 0) {
052            throw new IllegalArgumentException("shape is not strictly positive: " + shape);
053        }
054        this.rng = rng;
055        this.scale = scale;
056        this.oneOverShape = 1 / shape;
057    }
058
059    /**
060     * @param rng Generator of uniformly distributed random numbers.
061     * @param source Source to copy.
062     */
063    private InverseTransformParetoSampler(UniformRandomProvider rng,
064                                          InverseTransformParetoSampler source) {
065        super(null);
066        this.rng = rng;
067        scale = source.scale;
068        oneOverShape = source.oneOverShape;
069    }
070
071    /** {@inheritDoc} */
072    @Override
073    public double sample() {
074        return scale / Math.pow(rng.nextDouble(), oneOverShape);
075    }
076
077    /** {@inheritDoc} */
078    @Override
079    public String toString() {
080        return "[Inverse method for Pareto distribution " + rng.toString() + "]";
081    }
082
083    /**
084     * {@inheritDoc}
085     *
086     * @since 1.3
087     */
088    @Override
089    public SharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) {
090        return new InverseTransformParetoSampler(rng, this);
091    }
092
093    /**
094     * Creates a new Pareto distribution sampler.
095     *
096     * @param rng Generator of uniformly distributed random numbers.
097     * @param scale Scale of the distribution.
098     * @param shape Shape of the distribution.
099     * @return the sampler
100     * @throws IllegalArgumentException if {@code scale <= 0} or {@code shape <= 0}
101     * @since 1.3
102     */
103    public static SharedStateContinuousSampler of(UniformRandomProvider rng,
104                                                  double scale,
105                                                  double shape) {
106        return new InverseTransformParetoSampler(rng, scale, shape);
107    }
108}