umontreal.iro.lecuyer.util.MultivariateFunction Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ssj Show documentation

SSJ is a Java library for stochastic simulation, developed under the direction of Pierre L'Ecuyer, in the Département d'Informatique et de Recherche Opérationnelle (DIRO), at the Université de Montréal. It provides facilities for generating uniform and nonuniform random variates, computing different measures related to probability distributions, performing goodness-of-fit tests, applying quasi-Monte Carlo methods, collecting (elementary) statistics, and programming discrete-event simulations with both events and processes.

The newest version!


/*
 * Class:        MultivariateFunction
 * Description:  Represents a function of multiple variables.
 * Environment:  Java
 * Software:     SSJ 
 * Copyright (C) 2001  Pierre L'Ecuyer and Université de Montréal
 * Organization: DIRO, Université de Montréal
 * @author       
 * @since

 * SSJ is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License (GPL) as published by the
 * Free Software Foundation, either version 3 of the License, or
 * any later version.

 * SSJ is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.

 * A copy of the GNU General Public License is available at
   GPL licence site.
 */

package umontreal.iro.lecuyer.util;


/**
 * Represents a function of multiple variables.
 * This interface specifies a method evaluate that computes
 * a 
 * g(x) function, where 
 * x = (x₀,…, x_d-1)∈R^d.  It also specifies
 * a method evaluateGradient for computing
 * its gradient 
 * ∇g(x).
 * 
 * 
 * The dimension d can be fixed or variable.  When d is fixed, the
 * methods specified by this interface always take the same number of
 * arguments.  This is the case, for example, with a ratio of two
 * variables.
 * When d is variable, the implementation can compute the
 * function for a vector 
 * x of any length.  This can happen for a
 * product or sum of variables.
 * 
 * 
 * The methods of this interface take a variable number of arguments to
 * accomodate the common case of fixed dimension with more convenience;
 * the programmer can call the method without creating an array.
 * For the generic case, however, one can replace the arguments with an
 * array.
 * 
 */
public interface MultivariateFunction {

   /**
    * Returns d, the dimension of the function computed
    *    by this implementation.  If the dimension is not fixed,
    *    this method must return a negative value.
    * 
    * @return the dimension.
    * 
    */
   public int getDimension();


   /**
    * Computes the function 
    * g(x)
    *  for the vector x.  The length of the
    *  given array must correspond to the dimension of
    *  this function.  The method must compute and return the result
    *  of the function without modifying the elements
    *  in x since the array can be reused for
    *  further computation.
    * 
    * @param x a vector 
    * x.
    * 
    *    @return the value of 
    * g(x).
    *    @exception NullPointerException if x is null.
    * 
    *    @exception IllegalArgumentException if x.length
    *     does not correspond to the dimension of this function.
    * 
    * 
    */
   public double evaluate (double... x);


   /**
    * Computes 
    * ∂g(x)/∂x_i,
    *  the derivative of 
    * g(x)
    *  with respect to x_i.    The length of the
    *  given array must correspond to the dimension of
    *  this function.  The method must compute and return the result
    *  of the derivative without modifying the elements
    *  in x since the array can be reused for
    *  further computations, e.g., the gradient 
    * ∇g(x).
    * 
    * @param i the variable to derive with respect to.
    * 
    *    @param x a vector 
    * x.
    * 
    *    @return the value of the partial derivative.
    *    @exception NullPointerException if x is null.
    * 
    *    @exception IllegalArgumentException if x.length
    *     does not correspond to the dimension of this function.
    * 
    *    @exception IndexOutOfBoundsException if i is negative
    *     or greater than or equal to the dimension of this function.
    * 
    * 
    */
   public double evaluateGradient (int i, double... x);
}