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 */ 017 018package org.apache.commons.math3.ml.neuralnet.sofm.util; 019 020import org.apache.commons.math3.exception.NotStrictlyPositiveException; 021import org.apache.commons.math3.exception.NumberIsTooLargeException; 022import org.apache.commons.math3.analysis.function.Logistic; 023 024/** 025 * Decay function whose shape is similar to a sigmoid. 026 * <br/> 027 * Class is immutable. 028 * 029 * @since 3.3 030 */ 031public class QuasiSigmoidDecayFunction { 032 /** Sigmoid. */ 033 private final Logistic sigmoid; 034 /** See {@link #value(long)}. */ 035 private final double scale; 036 037 /** 038 * Creates an instance. 039 * The function {@code f} will have the following properties: 040 * <ul> 041 * <li>{@code f(0) = initValue}</li> 042 * <li>{@code numCall} is the inflexion point</li> 043 * <li>{@code slope = f'(numCall)}</li> 044 * </ul> 045 * 046 * @param initValue Initial value, i.e. {@link #value(long) value(0)}. 047 * @param slope Value of the function derivative at {@code numCall}. 048 * @param numCall Inflexion point. 049 * @throws NotStrictlyPositiveException if {@code initValue <= 0}. 050 * @throws NumberIsTooLargeException if {@code slope >= 0}. 051 * @throws NotStrictlyPositiveException if {@code numCall <= 0}. 052 */ 053 public QuasiSigmoidDecayFunction(double initValue, 054 double slope, 055 long numCall) { 056 if (initValue <= 0) { 057 throw new NotStrictlyPositiveException(initValue); 058 } 059 if (slope >= 0) { 060 throw new NumberIsTooLargeException(slope, 0, false); 061 } 062 if (numCall <= 1) { 063 throw new NotStrictlyPositiveException(numCall); 064 } 065 066 final double k = initValue; 067 final double m = numCall; 068 final double b = 4 * slope / initValue; 069 final double q = 1; 070 final double a = 0; 071 final double n = 1; 072 sigmoid = new Logistic(k, m, b, q, a, n); 073 074 final double y0 = sigmoid.value(0); 075 scale = k / y0; 076 } 077 078 /** 079 * Computes the value of the learning factor. 080 * 081 * @param numCall Current step of the training task. 082 * @return the value of the function at {@code numCall}. 083 */ 084 public double value(long numCall) { 085 return scale * sigmoid.value(numCall); 086 } 087}