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