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 /** Mean of the natural logarithm of the distribution values. */ 28 private final double mu; 29 /** Standard deviation of the natural logarithm of the distribution values. */ 30 private final double sigma; 31 /** Gaussian sampling. */ 32 private final NormalizedGaussianSampler gaussian; 33 34 /** 35 * @param gaussian N(0,1) generator. 36 * @param mu Mean of the natural logarithm of the distribution values. 37 * @param sigma Standard deviation of the natural logarithm of the distribution values. 38 * @throws IllegalArgumentException if {@code sigma <= 0}. 39 */ 40 public LogNormalSampler(NormalizedGaussianSampler gaussian, 41 double mu, 42 double sigma) { 43 if (sigma <= 0) { 44 throw new IllegalArgumentException("sigma is not strictly positive: " + sigma); 45 } 46 this.mu = mu; 47 this.sigma = sigma; 48 this.gaussian = gaussian; 49 } 50 51 /** 52 * @param rng Generator of uniformly distributed random numbers. 53 * @param source Source to copy. 54 */ 55 private LogNormalSampler(UniformRandomProvider rng, 56 LogNormalSampler source) { 57 this.mu = source.mu; 58 this.sigma = source.sigma; 59 this.gaussian = InternalUtils.newNormalizedGaussianSampler(source.gaussian, rng); 60 } 61 62 /** {@inheritDoc} */ 63 @Override 64 public double sample() { 65 return Math.exp(mu + sigma * gaussian.sample()); 66 } 67 68 /** {@inheritDoc} */ 69 @Override 70 public String toString() { 71 return "Log-normal deviate [" + gaussian.toString() + "]"; 72 } 73 74 /** 75 * {@inheritDoc} 76 * 77 * <p>Note: This function is available if the underlying {@link NormalizedGaussianSampler} 78 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 79 * Otherwise a run-time exception is thrown.</p> 80 * 81 * @throws UnsupportedOperationException if the underlying sampler is not a 82 * {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler} or 83 * does not return a {@link NormalizedGaussianSampler} when sharing state. 84 * 85 * @since 1.3 86 */ 87 @Override 88 public SharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) { 89 return new LogNormalSampler(rng, this); 90 } 91 92 /** 93 * Create a new log-normal distribution sampler. 94 * 95 * <p>Note: The shared-state functionality is available if the {@link NormalizedGaussianSampler} 96 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 97 * Otherwise a run-time exception will be thrown when the sampler is used to share state.</p> 98 * 99 * @param gaussian N(0,1) generator. 100 * @param mu Mean of the natural logarithm of the distribution values. 101 * @param sigma Standard deviation of the natural logarithm of the distribution values. 102 * @return the sampler 103 * @throws IllegalArgumentException if {@code sigma <= 0}. 104 * @see #withUniformRandomProvider(UniformRandomProvider) 105 * @since 1.3 106 */ 107 public static SharedStateContinuousSampler of(NormalizedGaussianSampler gaussian, 108 double mu, 109 double sigma) { 110 return new LogNormalSampler(gaussian, mu, sigma); 111 } 112 }