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 * Create an instance. 036 * 037 * @param gaussian N(0,1) generator. 038 * @param mu Mean of the natural logarithm of the distribution values. 039 * @param sigma Standard deviation of the natural logarithm of the distribution values. 040 * @throws IllegalArgumentException if {@code sigma <= 0}. 041 */ 042 public LogNormalSampler(NormalizedGaussianSampler gaussian, 043 double mu, 044 double sigma) { 045 // Validation before java.lang.Object constructor exits prevents partially initialized object 046 this(mu, InternalUtils.requireStrictlyPositive(sigma, "sigma"), gaussian); 047 } 048 049 /** 050 * @param mu Mean of the natural logarithm of the distribution values. 051 * @param sigma Standard deviation of the natural logarithm of the distribution values. 052 * @param gaussian N(0,1) generator. 053 */ 054 private LogNormalSampler(double mu, 055 double sigma, 056 NormalizedGaussianSampler gaussian) { 057 this.mu = mu; 058 this.sigma = sigma; 059 this.gaussian = gaussian; 060 } 061 062 /** 063 * @param rng Generator of uniformly distributed random numbers. 064 * @param source Source to copy. 065 */ 066 private LogNormalSampler(UniformRandomProvider rng, 067 LogNormalSampler source) { 068 this.mu = source.mu; 069 this.sigma = source.sigma; 070 this.gaussian = InternalUtils.newNormalizedGaussianSampler(source.gaussian, rng); 071 } 072 073 /** {@inheritDoc} */ 074 @Override 075 public double sample() { 076 return Math.exp(mu + sigma * gaussian.sample()); 077 } 078 079 /** {@inheritDoc} */ 080 @Override 081 public String toString() { 082 return "Log-normal deviate [" + gaussian.toString() + "]"; 083 } 084 085 /** 086 * {@inheritDoc} 087 * 088 * <p>Note: This function is available if the underlying {@link NormalizedGaussianSampler} 089 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 090 * Otherwise a run-time exception is thrown.</p> 091 * 092 * @throws UnsupportedOperationException if the underlying sampler is not a 093 * {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler} or 094 * does not return a {@link NormalizedGaussianSampler} when sharing state. 095 * 096 * @since 1.3 097 */ 098 @Override 099 public SharedStateContinuousSampler withUniformRandomProvider(UniformRandomProvider rng) { 100 return new LogNormalSampler(rng, this); 101 } 102 103 /** 104 * Create a new log-normal distribution sampler. 105 * 106 * <p>Note: The shared-state functionality is available if the {@link NormalizedGaussianSampler} 107 * is a {@link org.apache.commons.rng.sampling.SharedStateSampler SharedStateSampler}. 108 * Otherwise a run-time exception will be thrown when the sampler is used to share state.</p> 109 * 110 * @param gaussian N(0,1) generator. 111 * @param mu Mean of the natural logarithm of the distribution values. 112 * @param sigma Standard deviation of the natural logarithm of the distribution values. 113 * @return the sampler 114 * @throws IllegalArgumentException if {@code sigma <= 0}. 115 * @see #withUniformRandomProvider(UniformRandomProvider) 116 * @since 1.3 117 */ 118 public static SharedStateContinuousSampler of(NormalizedGaussianSampler gaussian, 119 double mu, 120 double sigma) { 121 return new LogNormalSampler(gaussian, mu, sigma); 122 } 123}