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 Lévy distribution. 023 * 024 * @see <a href="https://en.wikipedia.org/wiki/L%C3%A9vy_distribution">Lévy distribution</a> 025 * @since 1.4 026 */ 027public final class LevySampler implements SharedStateContinuousSampler { 028 /** Gaussian sampler. */ 029 private final NormalizedGaussianSampler gaussian; 030 /** Location. */ 031 private final double location; 032 /** Scale. */ 033 private final double scale; 034 /** RNG (used for the toString() method). */ 035 private final UniformRandomProvider rng; 036 037 /** 038 * @param rng Generator of uniformly distributed random numbers. 039 * @param location Location of the Lévy distribution. 040 * @param scale Scale of the Lévy distribution. 041 */ 042 private LevySampler(UniformRandomProvider rng, 043 double location, 044 double scale) { 045 this.gaussian = ZigguratSampler.NormalizedGaussian.of(rng); 046 this.location = location; 047 this.scale = scale; 048 this.rng = rng; 049 } 050 051 /** 052 * @param rng Generator of uniformly distributed random numbers. 053 * @param source Source to copy. 054 */ 055 private LevySampler(UniformRandomProvider rng, 056 LevySampler source) { 057 this.gaussian = ZigguratSampler.NormalizedGaussian.of(rng); 058 this.location = source.location; 059 this.scale = source.scale; 060 this.rng = rng; 061 } 062 063 /** {@inheritDoc} */ 064 @Override 065 public double sample() { 066 final double n = gaussian.sample(); 067 return scale / (n * n) + location; 068 } 069 070 /** {@inheritDoc} */ 071 @Override 072 public String toString() { 073 return "Lévy deviate [" + rng.toString() + "]"; 074 } 075 076 /** {@inheritDoc} */ 077 @Override 078 public LevySampler withUniformRandomProvider(UniformRandomProvider rng) { 079 return new LevySampler(rng, this); 080 } 081 082 /** 083 * Create a new Lévy distribution sampler. 084 * 085 * @param rng Generator of uniformly distributed random numbers. 086 * @param location Location of the Lévy distribution. 087 * @param scale Scale of the Lévy distribution. 088 * @return the sampler 089 * @throws IllegalArgumentException if {@code scale <= 0} 090 */ 091 public static LevySampler of(UniformRandomProvider rng, 092 double location, 093 double scale) { 094 if (scale <= 0) { 095 throw new IllegalArgumentException("scale is not strictly positive: " + scale); 096 } 097 return new LevySampler(rng, location, scale); 098 } 099}