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 log-normal distribution. 023 * 024 * @since 1.1 025 */ 026public class LogNormalSampler implements SharedStateContinuousSampler { 027 /** Mean of the natural logarithm of the distribution values. */ 028 private final double mu; 029 /** Standard deviation of the natural logarithm of the distribution values. */ 030 private final double sigma; 031 /** Gaussian sampling. */ 032 private final NormalizedGaussianSampler gaussian; 033 034 /** 035 * @param gaussian N(0,1) generator. 036 * @param mu Mean of the natural logarithm of the distribution values. 037 * @param sigma Standard deviation of the natural logarithm of the distribution values. 038 * @throws IllegalArgumentException if {@code sigma <= 0}. 039 */ 040 public LogNormalSampler(NormalizedGaussianSampler gaussian, 041 double mu, 042 double sigma) { 043 if (sigma <= 0) { 044 throw new IllegalArgumentException("sigma is not strictly positive: " + sigma); 045 } 046 this.mu = mu; 047 this.sigma = sigma; 048 this.gaussian = gaussian; 049 } 050 051 /** 052 * @param rng Generator of uniformly distributed random numbers. 053 * @param source Source to copy. 054 */ 055 private LogNormalSampler(UniformRandomProvider rng, 056 LogNormalSampler source) { 057 this.mu = source.mu; 058 this.sigma = source.sigma; 059 this.gaussian = InternalUtils.newNormalizedGaussianSampler(source.gaussian, rng); 060 } 061 062 /** {@inheritDoc} */ 063 @Override 064 public double sample() { 065 return Math.exp(mu + sigma * gaussian.sample()); 066 } 067 068 /** {@inheritDoc} */ 069 @Override 070 public String toString() { 071 return "Log-normal deviate [" + gaussian.toString() + "]"; 072 } 073 074 /** 075 * {@inheritDoc} 076 * 077 * <p>Note: This function is available if the underlying {@link NormalizedGaussianSampler} 078 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 079 * Otherwise a run-time exception is thrown.</p> 080 * 081 * @throws UnsupportedOperationException if the underlying sampler is not a 082 * {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler} or 083 * does not return a {@link NormalizedGaussianSampler} when sharing state. 084 * 085 * @since 1.3 086 */ 087 @Override 088 public SharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) { 089 return new LogNormalSampler(rng, this); 090 } 091 092 /** 093 * Create a new log-normal distribution sampler. 094 * 095 * <p>Note: The shared-state functionality is available if the {@link NormalizedGaussianSampler} 096 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 097 * Otherwise a run-time exception will be thrown when the sampler is used to share state.</p> 098 * 099 * @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}