functionsTutorial.html

<html> <head>
  <script src="Histo.js"></script>
  <script src="Func.js"></script>
  <script src="Vector.js"></script>
  <script src="Matrix.js"></script>
  <script src="distributions.js"></script>
  <script src="Plot.js"></script>
  </head> <body>

  <script type="text/JavaScript">

  /*-----Intro to Clairvoyant Func class-----------------------------
  One of the core objects in Clairvoyant is the Func class of objects.
  Funcs allow the user to declare math functions so that all of 
  Clairvoyant's methods for doing interesting things to them can
  handle them.  

  -----------------------------------------------------------------*/

  //-----The Constructor---------------------------------------------
  //Func(<name>,<function>,<parameters>)
  //  <name>		A string name for the function.
  //  <function>	a JavaScript function instance
  //  <parameters>	(optional) A number or an array initializing any parameters.


  //Declare a new JavaScript function as per the usual:
  //NOTE the function must accept exactly the arguments <coordinates>, <parameters>.
  var pbla = function (x, par) {
      return x*x
  }

  //declare the Func object:
  var parabola = new Func(pbla)

  //parabola has been declared with the name 'parabola', and the 
  //functional form x*x - a 1D parabola with no parameters.
  //We could also declare things like:

  var poly2D = function (x, par) {
      return x[0]*x[0]*Math.pow(x[1], 3);
  }

  var quadCube = new Func(poly2D);

  //which is a quadratic times a cubic, perhaps more readable as the
  //familiar z = x^2*y^3.  If we want parameters, we can do:

  var quadratic = function (x, par) {
      return Math.pow(x - par[0], 2) + par[1];
  }

  var quad = new Func(quadratic);

  //which is the same parabola as above, but with its center shifted
  //left by par[0] and up by par[1].  As declared, quad's par[0] will
  //be initialized as 0, and all the rest will be undefined.  You can
  //them via things like:

  quad.params[0] = 4;
  quad.params[1] = -3;

  //Or, if you have an Array() of parameters when you declare the Func,
  //you can pass it in as the third argument to the constructor to the same
  //effect:

  var parameters = new Array();
  parameters[0] = 4;
  parameters[1] = -3;
  quad = new Func(quadratic, parameters);

  //-----------------------------------------------------------------

  //-----draw Method---------------------------------------------
  //draw(<canvas>, <xmin>, <xmax>, <ymin>, <ymax>, <title>, <xtitle>, <ytitle>, <plotstyle>)
  //  <canvas>	   the HTML5 canvas to draw this Func in
  //  <xmin>	   minimum x value to draw from
  //  <xmax>  	   maximum x value to draw to
  //  <ymin>	   minimum y value to draw from
  //  <ymax>	   maximum y value to draw to
  //  <title>	   plot title
  //  <xtitle>	   x axis label
  //  <ytitle>     y axis label
  //  <plotstyle>  (optional) PlotStyle() object to style this plot with
  //Return type: 0 on success

  //draws this Func in the window specified.  Note that if <ymin> === <ymax>,
  //draw() will try to automatically seek an appropriate y-window.

  document.write('/////////////////// .draw examples //////////////////////////////////</br>');
  </script>

  <canvas id="canvas1" width="600" height="450"></canvas>  

  <script type="text/JavaScript">

  var style = new PlotStyle();
  style.color = "red";
  style.titleFont = "24px sans-serif";
  style.lineWidth = 4;

  parabola.draw('canvas1', -12,12, 0,100,'A Lovely Parabola', 'x', 'y=x*x', style);

  //-----Evaluate Method---------------------------------------------
  //evaluate(<inputs>)
  // <inputs>	A number (for 1D functions) or an n-element array (for n-dimensional functions
  //            specifying the point in space the function is to be evaluated at.
  //Return type: float

  //You can pass a single variable function a single value:

  document.write('</br>/////////////////// .evaluate examples //////////////////////////////////</br>');
  document.write('</br>x^2 evaluated at x = 2 returns: ');
  document.write(parabola.evaluate(2));  

  //or, you can pass an Array() of values to a higher-dimensional function:

  var point = new Array();
  point[0] = 3;
  point[1] = 5;
  document.write('</br>x^2y^3 evaluated at x = 3 and y = 5 returns: ');
  document.write(quadCube.evaluate(point));


  //-----getParameters Method----------------------------------------
  //getParameters(<array>)
  //  <array>	An empty Array() object into which this.params will be copied.
  //Return type: 0 on successfull exit

  //Given a function, getParameters(<array>) will load that function's
  //parameters into <array>, thusly:

  document.write('</br></br>/////////////////// .getParameters examples //////////////////////////////////</br>');
  var whatParams = new Array();
  quad.getParameters(whatParams);
  document.write('</br>Func quad had the parameters quad.param[0] = '+whatParams[0]+', quad.param[1] = '+whatParams[1]);

  //-----setParameters Method----------------------------------------
  //setParameters(<array>)
  //  <array>  An Array() of parameters to be loaded into this.params.
  //Return type: 0 on successfull exit 

  //All the parameters of a given function can be reset at once, with
  //a new array as follows:

  document.write('</br></br>/////////////////// .setParameters examples //////////////////////////////////</br>');
  var newParams = new Array();
  newParams[0] = -3;
  newParams[1] = 2;
  quad.setParameters(newParams);
  quad.getParameters(whatParams);
  document.write('</br>Func quad has the new parameters quad.param[0] = '+whatParams[0]+', quad.param[1] = '+whatParams[1]);
  
  //-----getExtremum Method------------------------------------------
  //getExtremum(<min>,<max>,<tol>)
  //  <min>	the lower bound on x[0] defining the search region.
  //  <max>	the upper bound on x[0] defining the search region.
  //  <tol>	(optional) the tolerance to which the extremum will be found; default 0.000001
  //Return type: Array, first elements = extremum location in x[0], second element indicates minima (0) or maxima (1).

  //Clairvoyant uses Brent's Algorithm (http://en.wikipedia.org/wiki/Brent's_method)
  //on the derivative of func objects as evaluated by Richardson's Extrapolation
  //(http://en.wikipedia.org/wiki/Richardson_extrapolation) as a fast extremum finder 
  //for 1D functions.  In order for this toconverge, you must start with a guess good 
  //enough to bracket a single zero.  Upon convergence, an array is returned with the 
  //x[0] coordinate of the extremum in the first entry; the second entry indicates
  //whether it is a minima (0) or maxima (1), as per the following:

  document.write('</br></br>/////////////////// .getExtremum examples //////////////////////////////////</br>');
  document.write('</br>If I guess the bottom of the parabola defined by quad is somewhere between -10 and 10, Clairvoyant finds it at x[0] = ');
  document.write((quad.getExtremum(-10,10))[0]); 

  if((quad.getExtremum(-10,10))[1]==0){
    document.write(', and this is a minima.')
  }    
  if((quad.getExtremum(-10,10))[1]==1){
    document.write(', and this is a maxima.')
  }
  
  //By default, getExtremum finds the extremum to within a tolerance
  //of 1 part in a million; you can override this by including your
  //desired tolerance as a third argument in getExtremum().


  //-----randPull Method----------------------------------------------
  //randPull(<min>,<max>)
  //  <min>       the lower bound on x[0] defining the range of random pulls.
  //  <max>       the upper bound on x[0] defining the range of random pulls.
  //Return type: float
  
  //Clairvoyant can generate random pulls from a 1D Func object by treating
  //it as a probability density function over some range.  In order for this
  //to make sense, the func had better be nonnegative and finite throughout
  //the range requested!  Support for higher dimensional Funcs coming soon...

  document.write('</br></br>/////////////////// .randPull examples //////////////////////////////////</br>');
  document.write('</br>Ten random pulls from Func parabola on x[0] within -1..1:</br>');
  for(var i=0; i<10; i++){
    document.write(parabola.randPull(-1,1)+'</br>');
  }
  document.write('Notice that more of them are near the edges of the range than the center, as we would expect from this distribution.');

  //-----brentSoln Method----------------------------------------------
  //brentSoln(<min>,<max>,<tol>)
  //  <min>       the lower bound on x[0] defining the search region.
  //  <max>       the upper bound on x[0] defining the search region.
  //  <tol>       (optional) the tolerance to which the extremum will be found; default 0.000001
  //Return type: float

  //Clairvoyant uses Brent's Algorithm (http://en.wikipedia.org/wiki/Brent's_method)
  //to find the zero of a 1D Func between a user-defined minimum and maximum  value for
  //x[0]:

  document.write('</br></br>/////////////////// .brentSoln examples //////////////////////////////////</br>');

  var cube = function (x, par) {
      return (x-1)*(x-2)*(x-3);
  }

  var cubic = new Func(cube);
  document.write('</br>The cubic (x-1)*(x-2)*(x-3) has a zero between x=1.5 and x=2.7 at x = ');
  document.write(cubic.brentSoln(1.5,2.7));

  //Bad things happen if there is not exactly 1 zero in the search range!  
  //Examples to come, try it yourself for now.  Zeroes are found to a 
  //default tolerance of 0.000001, but this can be overridden with by an 
  //optional third argument to brentSoln()

  //-----biSoln Method-------------------------------------------------
  //biSoln(<min>,<max>,<tol>)
  //  <min>       the lower bound on x[0] defining the search region.
  //  <max>       the upper bound on x[0] defining the search region.
  //  <tol>       (optional) the tolerance to which the extremum will be found; default 0.000001
  //Return type: float

  //When Brent's Algorithm runs into problems (usually because the user didn't
  //bracket a unique zero), a slow but robust grid search and bisection is 
  //performed to find a function zero.  This is VERY slow, and should only be
  //called as a last-ditch attempt to find a zero.

  document.write('</br></br>/////////////////// .biSoln examples //////////////////////////////////</br>');

  document.write('</br>The cubic (x-1)*(x-2)*(x-3) has a zero between x=2.1 and x=10.6 at x = ');
  document.write(cubic.biSoln(2.1,10.6));

  //Default tolerance is 1 part in a million; override with third argument
  //to biSoln().

  //-----derivative Method----------------------------------------------
  //derivative(<x>,<dim>,<tol>,<roundoff>)
  //  <x>		number or array describing the point at which to evaluate the derivative
  //  <dim>    		(optional)take the derivative with respect to x[<dim>].  default <dim>=0
  //  <tol>		(optional)tolerance to which the derivative is calculated.  default 0.000001
  //  <roundoff>	(optional)round off the answer to tolerance? 0=no, 1=yes, default 1 
  //Return type: float
 
  //Clairvoyant uses Richardson's Extrapolation 
  //(http://en.wikipedia.org/wiki/Richardson_extrapolation) to approximate
  //the derivative of a function in any dimension at a given point. derivative()
  //accepts 4 arguments:
  //  <x> is the point at which the derivative will be evaluated; it can be a 
  //    number for a 1D function, or an Array() for higher dimensionality.
  //  <dim> is the dimension the derivative will be taken in; <dim>=n corresponds
  //    to taking the derivative WRT x[n]
  //  <tol> is the tolerance to which the derivative is estimated; default is 0.000001
  //  <roundoff> is a flag that decides whether to round the result off to the nearest
  //    multiple of the tolerance.  Default is yes (<roundoff>=1), may set to 0 (no),
  //    useful for avoiding compounding roundoff errors when other functions call this.

  document.write('</br></br>/////////////////// .derivative examples //////////////////////////////////</br>');
  document.write('</br>The derivative of x^2*y^3 WRT x at x=3,y=5 is: ');
  document.write(quadCube.derivative(point,0));

 
  //-----gradient Method------------------------------------------------
  //gradient(<x>)
  //  <x> 	number or array locating the point at which to evaluate the gradient.
  //Return type: Array(), element n = the derivative evaluated WRT x[n]

  //evaluates the derivative of the Func along every dimension at the specified 
  //point, and returns the reuslts in an array:

  document.write('</br></br>/////////////////// .gradient examples //////////////////////////////////</br>');
  document.write('</br>The gradient of x^2*y^3 at x=3,y=5 is: '+quadCube.gradient(point)[0]+' in x and '+quadCube.gradient(point)[1]+' in y.');
  document.write('</br>Beware of roundoff error!  Bugfix coming soon.')


  //-----minimize Method------------------------------------------------
  //minimize(<start>, <tolerance>)
  //  <start> 		Array() containing the starting position for the minimum funder
  //  <tolerance>	(optional) tolerance on minimum, default 0.000001.

  //seeks the nearest minimum by walking down the gradient of the function starting from <start>, until subsequent
  //steps are within <tolerance> of each other.

  document.write('</br></br>/////////////////// .minimize examples //////////////////////////////////</br>');

  var bowl = function (x, par) {
      var r = Math.sqrt(Math.pow(x[0]-2,2) + Math.pow(x[1]-3,2) + Math.pow(x[2]-5,2) + Math.pow(x[3]+1,2) + Math.pow(x[4]+3,2));

      return r
  }

  var minimizeMe = new Func(bowl);

  document.write('minimize() finds the minimum of y = (x[0] - 2)^2 + (x[1] - 3)^2 + (x[2] - 5)^2 + (x[3] + 1)^2 + (x[4] + 3)^2 at: ');
  document.write(minimizeMe.minimize([1,2.7,7,-3,1]))


  </script>

</body> </html>