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    package org.apache.commons.nabla.core;
018    
019    /** Interface for univariate functions derivatives.
020     * <p>This interface represent a simple function which computes
021     * both the value and the first derivative of a mathematical function.
022     * The derivative is computed with respect to the input variable.</p>
023     * <p>Classes implementing this interface are automatically built by
024     * the {@link UnivariateDifferentiator differentiators} provided by the
025     * Nabla library.</p>
026     * @see UnivariateDifferentiable
027     * @see UnivariateDifferentiator
028     */
029    public interface UnivariateDerivative {
030    
031        /** Get the primitive function associated with this differential.
032         * <p>Each {@link UnivariateDerivative} instance is tightly bound
033         * to an {@link UnivariateDifferentiable} instance. If the state of
034         * the primitive instance changes in any way that affects the
035         * differential computation, this binding allows this change to
036         * be immediately seen by the derivative instance, there is no need
037         * to differentiate the primitive again. The existing instance is aware
038         * of the primitive changes.</p>
039         * <p>In other words in the following code snippet, the three values
040         * f1, f2 and f3 should be equal (at least at machine tolerance level)</p>
041         * <pre>
042         *    UnivariateDerivative derivative = differentiator.differentiate(derivable);
043         *    derivable.someFunctionThatMutatesHeavilyTheInstance();
044         *    double f1 = derivable.f(t);
045         *    double f2 = derivative.getPrimitive().f(t);
046         *    double f3 = detivative.f(DifferentialPair.newVariable(t)).getU0();
047         * </pre>
048         * @return primitive function bound to this derivative
049         */
050        UnivariateDifferentiable getPrimitive();
051    
052        /** Simple mathematical function.
053         * <p>{@link UnivariateDerivative} classes compute both the
054         * value and the first derivative of the function.</p>
055         * @param t function input value
056         * @return function result
057         */
058        DifferentialPair f(DifferentialPair t);
059    
060    }