1 /* 2 * Licensed to the Apache Software Foundation (ASF) under one or more 3 * contributor license agreements. See the NOTICE file distributed with 4 * this work for additional information regarding copyright ownership. 5 * The ASF licenses this file to You under the Apache License, Version 2.0 6 * (the "License"); you may not use this file except in compliance with 7 * the License. You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 package org.apache.commons.rng.sampling.distribution; 18 19 import org.apache.commons.rng.UniformRandomProvider; 20 21 /** 22 * Sampling from a log-normal distribution. 23 * 24 * @since 1.1 25 */ 26 public class LogNormalSampler implements SharedStateContinuousSampler { 27 /** Scale. */ 28 private final double scale; 29 /** Shape. */ 30 private final double shape; 31 /** Gaussian sampling. */ 32 private final NormalizedGaussianSampler gaussian; 33 34 /** 35 * @param gaussian N(0,1) generator. 36 * @param scale Scale of the log-normal distribution. 37 * @param shape Shape of the log-normal distribution. 38 * @throws IllegalArgumentException if {@code scale < 0} or {@code shape <= 0}. 39 */ 40 public LogNormalSampler(NormalizedGaussianSampler gaussian, 41 double scale, 42 double shape) { 43 if (scale < 0) { 44 throw new IllegalArgumentException("scale is not positive: " + scale); 45 } 46 if (shape <= 0) { 47 throw new IllegalArgumentException("shape is not strictly positive: " + shape); 48 } 49 this.scale = scale; 50 this.shape = shape; 51 this.gaussian = gaussian; 52 } 53 54 /** 55 * @param rng Generator of uniformly distributed random numbers. 56 * @param source Source to copy. 57 */ 58 private LogNormalSampler(UniformRandomProvider rng, 59 LogNormalSampler source) { 60 this.scale = source.scale; 61 this.shape = source.shape; 62 this.gaussian = InternalUtils.newNormalizedGaussianSampler(source.gaussian, rng); 63 } 64 65 /** {@inheritDoc} */ 66 @Override 67 public double sample() { 68 return Math.exp(scale + shape * gaussian.sample()); 69 } 70 71 /** {@inheritDoc} */ 72 @Override 73 public String toString() { 74 return "Log-normal deviate [" + gaussian.toString() + "]"; 75 } 76 77 /** 78 * {@inheritDoc} 79 * 80 * <p>Note: This function is available if the underlying {@link NormalizedGaussianSampler} 81 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 82 * Otherwise a run-time exception is thrown.</p> 83 * 84 * @throws UnsupportedOperationException if the underlying sampler is not a 85 * {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler} or 86 * does not return a {@link NormalizedGaussianSampler} when sharing state. 87 * 88 * @since 1.3 89 */ 90 @Override 91 public SharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) { 92 return new LogNormalSampler(rng, this); 93 } 94 95 /** 96 * Create a new log-normal distribution sampler. 97 * 98 * <p>Note: The shared-state functionality is available if the {@link NormalizedGaussianSampler} 99 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 100 * Otherwise a run-time exception will be thrown when the sampler is used to share state.</p> 101 * 102 * @param gaussian N(0,1) generator. 103 * @param scale Scale of the log-normal distribution. 104 * @param shape Shape of the log-normal distribution. 105 * @return the sampler 106 * @throws IllegalArgumentException if {@code scale < 0} or {@code shape <= 0}. 107 * @see #withUniformRandomProvider(UniformRandomProvider) 108 * @since 1.3 109 */ 110 public static SharedStateContinuousSampler of(NormalizedGaussianSampler gaussian, 111 double scale, 112 double shape) { 113 return new LogNormalSampler(gaussian, scale, shape); 114 } 115 }