View Javadoc
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   * <a href="https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform">
23   * Box-Muller algorithm</a> for sampling from a Gaussian distribution.
24   *
25   * @since 1.0
26   *
27   * @deprecated Since v1.1. Please use {@link BoxMullerNormalizedGaussianSampler}
28   * and {@link GaussianSampler} instead.
29   */
30  @Deprecated
31  public class BoxMullerGaussianSampler
32      extends SamplerBase
33      implements ContinuousSampler {
34      /** Next gaussian. */
35      private double nextGaussian = Double.NaN;
36      /** Mean. */
37      private final double mean;
38      /** standardDeviation. */
39      private final double standardDeviation;
40      /** Underlying source of randomness. */
41      private final UniformRandomProvider rng;
42  
43      /**
44       * @param rng Generator of uniformly distributed random numbers.
45       * @param mean Mean of the Gaussian distribution.
46       * @param standardDeviation Standard deviation of the Gaussian distribution.
47       */
48      public BoxMullerGaussianSampler(UniformRandomProvider rng,
49                                      double mean,
50                                      double standardDeviation) {
51          super(null);
52          this.rng = rng;
53          this.mean = mean;
54          this.standardDeviation = standardDeviation;
55      }
56  
57      /** {@inheritDoc} */
58      @Override
59      public double sample() {
60          final double random;
61          if (Double.isNaN(nextGaussian)) {
62              // Generate a pair of Gaussian numbers.
63  
64              final double x = rng.nextDouble();
65              final double y = rng.nextDouble();
66              final double alpha = 2 * Math.PI * x;
67              final double r = Math.sqrt(-2 * Math.log(y));
68  
69              // Return the first element of the generated pair.
70              random = r * Math.cos(alpha);
71  
72              // Keep second element of the pair for next invocation.
73              nextGaussian = r * Math.sin(alpha);
74          } else {
75              // Use the second element of the pair (generated at the
76              // previous invocation).
77              random = nextGaussian;
78  
79              // Both elements of the pair have been used.
80              nextGaussian = Double.NaN;
81          }
82  
83          return standardDeviation * random + mean;
84      }
85  
86      /** {@inheritDoc} */
87      @Override
88      public String toString() {
89          return "Box-Muller Gaussian deviate [" + rng.toString() + "]";
90      }
91  }