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
18 package org.apache.commons.math4.neuralnet;
19
20 import java.util.function.DoubleUnaryOperator;
21
22 import org.apache.commons.rng.UniformRandomProvider;
23 import org.apache.commons.rng.sampling.distribution.ContinuousUniformSampler;
24
25 /**
26 * Creates functions that will select the initial values of a neuron's
27 * features.
28 *
29 * @since 3.3
30 */
31 public final class FeatureInitializerFactory {
32 /** Class contains only static methods. */
33 private FeatureInitializerFactory() {}
34
35 /**
36 * Uniform sampling of the given range.
37 *
38 * @param min Lower bound of the range.
39 * @param max Upper bound of the range.
40 * @param rng Random number generator used to draw samples from a
41 * uniform distribution.
42 * @return an initializer such that the features will be initialized with
43 * values within the given range.
44 * @throws IllegalArgumentException if {@code min >= max}.
45 */
46 public static FeatureInitializer uniform(final UniformRandomProvider rng,
47 final double min,
48 final double max) {
49 return randomize(new ContinuousUniformSampler(rng, min, max),
50 function(x -> 0, 0, 0));
51 }
52
53 /**
54 * Creates an initializer from a univariate function {@code f(x)}.
55 * The argument {@code x} is set to {@code init} at the first call
56 * and will be incremented at each call.
57 *
58 * @param f Function.
59 * @param init Initial value.
60 * @param inc Increment
61 * @return the initializer.
62 */
63 public static FeatureInitializer function(final DoubleUnaryOperator f,
64 final double init,
65 final double inc) {
66 return new FeatureInitializer() {
67 /** Argument. */
68 private double arg = init;
69
70 /** {@inheritDoc} */
71 @Override
72 public double value() {
73 final double result = f.applyAsDouble(arg);
74 arg += inc;
75 return result;
76 }
77 };
78 }
79
80 /**
81 * Adds some amount of random data to the given initializer.
82 *
83 * @param random Random variable distribution sampler.
84 * @param orig Original initializer.
85 * @return an initializer whose {@link FeatureInitializer#value() value}
86 * method will return {@code orig.value() + random.sample()}.
87 */
88 public static FeatureInitializer randomize(final ContinuousUniformSampler random,
89 final FeatureInitializer orig) {
90 return new FeatureInitializer() {
91 /** {@inheritDoc} */
92 @Override
93 public double value() {
94 return orig.value() + random.sample();
95 }
96 };
97 }
98 }