View source for DMelt:Math/1 Functions



{{sidebar box|[[DMelt:Start|Table of contents]]}}


== Mathematical functions ==
 
[[Function_(mathematics)|Function]] is a relation between inputs values and a set of outputs values such that  each input is related to exactly one output. 

DataMelt can be used to evaluate, plot, simplify functions. There are several approaches to work with parametric or non-parametric  functions using DataMelt Java API:

* User 2D/3D function plotter from DataMelt IDE (see the "Tools" menu)
* Simplify and plot functions using ether Octave or Matlab syntax. Plotting functions in such approach is a bit too simplistic and there is no good integration with Java API and data structures
* Use the full-blown DataMelt Java libraries to create parametric,  non-parametric, special functions as they are provided by Java API.  One can also integrate, differentiate and simplify such functions. In this case one can use the Java language, or any Java scripting languages (such as Jython or BeanShell). There is complete integration with data structures API and functions can be plotted in 2D/3D using several powerful interactive canvases.

In this section we will discuss the third option as it is the most flexible for integration with Java libraries.
We will start with simple analytical functions with one variable ("x") and then will consider more complicated cases with several
variables ("y", "z"). Finally, we will show how to make function of arbitrary complexity with any number of variables

= Functions with one variable=

Functions can be defined using either strings or programically. First we will discuss how to show functions using strings and then we will show other, more flexible  methods.

We will start this tutorial with a simple example of how to create and display a function with one and only one variable ("x").
First, let us create an object representing a function: 

<math>
f(x)=2*exp(-x*x/50)+sin(pi*x)/x
</math>

Such functions are represented by the  <javadoc sc>jhplot.F1D</javadoc> Java class (1D means one-dimensional function).

<jcode lang="python">
from jhplot  import  *
f1 = F1D("2*exp(-x*x/50)+sin(pi*x)/x")
</jcode>
Here the input function is given by <javadoc>java.lang.String</javadoc>. One can evaluate this function at a certain point, say at 10,  as:
<jcode lang="python">
print f1.eval(10)
0.270670566473
</jcode>
By default, all trigonometric functions are implemented using the fast calculations with e-14 accuracy.
Note, you can also use exact calculations using </javadoc>java.lang.Math</javadoc> using additional parameter:

<jcode lang="python">
from jhplot  import  *
HParam.setExactMath()
f1 = F1D("2*exp(-x*x/50)+sin(pi*x)/x")
</jcode>

The method "HParam.setExactMath()" tells that full precision of Java Math package is not required. In this case, calculations of trigonometric
functions is a factor 2-3 slower. Look at the class <javadoc sc>jhplot.HParam</javadoc>.

The code shown below benchmark calculations of F1D function containing trigonometric functions  with and without the fast math enabled.
<jcode lang="python">
dmelt 43369797.py
</jcode>

To draw the function, one should specify limits during the function initialization (or later using the
methods of the Java object  <javadoc>jhplot.F1D</javadoc>. Then one should build a canvas and use the method "draw" to plot the function.
In the example below,  we define the limits for this function (-2,5) and then we plot it: 

<jcode lang="python">
dmelt 27777667.py
</jcode>

Here we drop the Python invitation ">>>" since we assume that the this code snippet is executed as a file. Insert these lines to the DataMelt editor  and hit the key [F8]. You will see a pop-up window with the output as shown below: 

<jput>
image 27777667
</jput>

To learn about the method of DataMelt or any Jython or Java  objects (like f1 and c1 in the above example): 
* Hit <Ctrl>+<Space> after the dot when using the Jython shell prompt (bottom part of the DataMelt IDE). 
* When using the DataMelt editor, use the key [F4] (after the dot)  which brings up a table with all available Java methods. 
* Use Eclipse or NetBean IDE when developing the code using Java. They have their own help system.
* Read the Java API of these classes.

{{ombox | text=[http://datamelt.org/code/index.php?keyword=F1D F1D code examples] }}

== Information about the syntax ==

Here is a short description about how to define functions. The following table shows the main mathematical  operations:

<jcode lang="python">
 ()     parenthesis           
 +      plus                  
 -      minus                 
 *      times                 
 /      divide                
 ^      raise to a power      
 **     raise to a power     
</jcode>

Functions:
{| class="wikitable sortable" border=1
!  String    !!  Definition             
|-
|  abs         ||   absolute value         
|-
|  log(x)      ||  Natural Logarithm       
|-
|  log10(x)    ||  Logarithm base 10       
|-
|  sqrt(x)     ||  <m>sqrt{x}</m>          
|-
|  exp(x)      ||  Exp                     
|-
|  ceil        ||  nearest upper integer  
|-
|  floor       ||  nearest lower integer   
|-
|  cbrt        ||  cubic root             
|-
|  sin(x)      ||  Sine                    
|-
|  cos(x)      ||  Cosine                  
|-
|  tan(x)      ||  Tangent                 
|-
|  asin(x)     ||  ArcSine                 
|-
|  acos(x)     ||  ArcCosine               
|-
|  atan(x)     ||  ArcTangent              
|-
|  sinh(x)     ||  Hyperbolic Sine         
|-
|  cosh(x)     ||  Hyperbolic Cosine       
|-
|  tanh(x)     ||  Hyperbolic Tangent      
|-
|}

One can also use some predefined constants, such as pi or Pi (the pi value, 3.14..).
It is possible to use [[Scientific notation]] for numbers.
The number is split into a significant / mantissa (y) and exponent (x) of the form 'yEx' which is evaluated as 'y * 10^x'. Let us give the examples:

<jcode lang="python">
from jhplot  import *
 
f1=F1D("1+x+(x^2)-(x^3)")   # correct answer -1
print f1.eval(2)            
f1=F1D("1+x+(x*x)-(x*x*x)") # correct answer -1
print f1.eval(2)            
f1=F1D("1+x+x^2-x^3")       # correct answer -1
print f1.eval(2)
f1=F1D("1+x+x**2-x**3")     # correct answer -1
print f1.eval(2)
</jcode>

== Parameters ==

Functions can have parameters. If you have parameters, you should
avoid "parsing" functions, and apply parsing only after finals substitution.
This example shows how to work with such functions:

<jcode lang="python">
f1=F1D("(3*alpha)/alpha+10+x",0) # 0 means False
f1.simplify()                    # simplify the function
print f1.getName()            
f1.setPar("alpha",100)           # substitute alpha=100
f1.parse()                       # parse it for evaluation, plotting etc.
print f1.getName()
print f1.eval([1,2,3])
</jcode>

Please also consider the method <code>f1.toString()</code> that prints more information about  <javadoc>jhplot.F1D</javadoc>.


== Function initialization ==

Functions can be initialized with and without ranges.

When using this syntax:
<jcode lang="python">
from jhplot import *
f1=F1D("x^2")
</jcode>
function does not have limits used for plotting and evaluation.
For such definition, plot ranges are entirely determined by the
plotting canvases (i.e. by the setRange() methods.

When using this syntax:
<jcode lang="python">
from jhplot import *
f1=F1D("x^2",-10,10) # limit to [-10,10]
</jcode>
The function includes limits for numeric calculation and plotting. This means you can set auto-range for plotting canvases, since the function includes the X-range in the definition, thus it will be shown in the range [-10,10], as in this example.

== Non-parametric functions ==

The most flexible way to draw functions is to use codding with objects and calling third-party Java libraries directly, instead of using strings with function definitions.
This topic will be discussed in Section [[DMelt:Math/3_Non_Parametric_Functions | Non-parametric functions]]

== Symbolic manipulations  ==

Symbolic manipulation with functions will be discussed in more details in Section [[DMelt:Symbolic/1_Introduction | Introduction]]. Still, one should note that symbolic manipulations can also be done with the F1D functions using Java (or Jython) coding without using any other specialized language (as Matlab or Octave). One can simplify and expand F1D functions.
Functions can also be rewritten in terms of elementary functions (log, sqrt, exp). Finally, one can  perform some elementary substitutions before attempting to plot a F1D function. 


<ifauth>
In this example we simplify a few elementary functions:
<jcode lang="python">
dmelt 66535743.py
</jcode>
</ifauth>

It is often useful to rewrite an expression in terms of elementary functions (log, exp, frac, sqrt, implicit roots), using the "elementary()" method, 
before simplifying it.

<ifauth>
<jcode lang="python">
from jhplot  import *
s="cos(x)^2+sin(x)^2"
f1 = F1D(s)
f1.elementary()
print "In ementary functions "+s+" = ",f1.getName()
f1.simplify()
print "Simplified "+s+" = ",f1.getName()
</jcode>
</ifauth>

== Integration and differentiation  ==

Functions can be numerically integrated. The program supports 5 methods
of integration, which vary in evaluation time and accuracy. Below we
will integrate the function "cos(x*x)+sin(1/x)*x^2)"

<ifauth>
<jcode lang="python">
dmelt 45153863.py
</jcode>
</ifauth>

This code integrates the function between 10 and 100 using 5000 integration point
(the large the number is, the more accurate the results are). The code
also performs some benchmarking  which gives you ideas about the accuracy of calculations:

<jcode lang="python">
trapezium  = 4949.64217622  time (ms)= 31.654937
gauss4     = 4949.64028115  time (ms)= 43.84014
gauss8     = 4949.64028111  time (ms)= 65.27855
richardson = 4949.64028393  time (ms)= 56.030938
simpson    = 4949.64014049  time (ms)= 17.634015 
</jcode>

== Displaying  functions  ==

Here is a more detailed example showing how to plot several functions using different colors:

<jcode lang="python">
dmelt 29374959.py
</jcode>


Note that we have imported the Java class <javadoc>java.awt.Color</javadoc>. The output of this script is shown here

<jput>
image 29374959
</jput>

You can also plot objects on different pads as shown in the Section [[DMelt:Plots/1_Canvases | Plotting canvases]].

== Exporting  functions  ==

As any Java object, F1D functions can be saved into files. Read [[DMelt:IO/1_File_Input_and_Output | Input and Output]] for detailed discussion.
In addition, one  can convert a function in [http://www.w3.org/Math/ MathML] or Java formats, or just display it as a table with values after evaluation
of a function.

<jcode lang="python">
>>> from jhplot import F1D
>>> f=F1D("10*sin(x)")
>>> print f.toMathML()  # convert to MathML
>>> print f.toJava()    # convert to Java code
>>> f.toTable()         # show a table with X-Y values (the function should be plotted or evaluated before)
</jcode>

= 2D Functions  =

Functions in 2 dimensions can be build analogously using the 
Java  class <javadoc sc>jhplot.F2D</javadoc>.
The example below shows how to construct and evaluate a function 2D:

<jcode lang="python">
>>> from jhplot  import  *
>>> f1 = F2D("2*exp(-x*y/50)+sin(pi*x)/y")
>>> print f1.eval(10,20)
0.0366312777775
</jcode>
The code prints the answer: 0.270670566473.

Such functions can be displayed as will be shown later. Also, look at the  Sections [[DMelt:Plots/2_Plots_in_2D |2D Plots]] and [[DMelt:Plots/5_Plots_in_3D | 3D Plots]]

= 3D Functions =

Functions in 2 dimensions can be build by analogy  using the 
Java   <javadoc sc>jhplot.F3D</javadoc> class.
The example below shows how to construct and evaluate a function 3D:

<jcode lang="python">
>>> from jhplot  import  *
>>> f1 = F3D("2*exp(-x*y/50)+sin(pi*x)/z")
>>> print f1.eval(10,20,30)
0.0366312777775
</jcode>
The code prints the answer: 0.0366312777775.

= Converting functions to histograms =

Histograms can be created from 1D and 2D functions. In the example above, we created a 2D function and then used it to generate 2D histogram.
Functions can be converted to [[DMelt:DataAnalysis/3_Histograms | Histograms]] with arbitrary number of bins.
This often can be used for show selected regions in different color.

Consider the example in which a function is used to create a histogram with fine
bins. We use this histogram to  highlight a range of our original function.

<jcode lang="python">
dmelt 73771866.py
</jcode>

<jput>
image 73771866
</jput>

Histograms can have arbitrary number of bins, but if the bin number is close to 500 (a typical
evaluation step for functions), the difference between function and a histogram will be almost impossible to see.

= Plotting in 3D =

F2D functions can be shown using 3D canvases.  They can be overlayed and shown on a single plot.
Here is a small example of showing 2 functions in 3D:

<jcode lang="python">
dmelt 33874513.py
</jcode>

The output of this code is:

<jput>
image 32915338
</jput>

One can also overlay several different objects. Let us show an example of how to show functions and histograms in 3D:

<jput>
image 10327869
</jput>


The code used to generate this image is given below.
<ifauth>
<jcode lang="python">
dmelt 10327869.py
</jcode>
</ifauth>


You can plot an arbitrary function in 3D using <javadoc>jhplot.HJavaView</javadoc> by defining function programmatically, and rebuilding vertexes for surface plots.
Here is how you can do it:

<jcode lang="python">
dmelt 141435262.py
</jcode>

The output of this code is:

<jput>
image 141435262
</jput>

You can adjust all visual characteristics of this plot using JavaView GUI.

= Multidimensional functions =

So far we have learned how to build functions in 1D (F1D class), 2D (F2D class) and 3D (F3D class). In addition to these "fixed dimension" classes, there is a 
<javadoc sc>jhplot.FND</javadoc> which can be used to build a function with arbitrary parameters and variables. To build such function is very easy and similar to the above styles, only now one should be more explicit about the names of variables. As example, below we make a function with 4 variables, called xx, yy, bb, kk:

<jcode lang="python">
from jhplot import *
f=FND("xx*sqrt(yy)*bb*+kk",'xx,yy,bb,kk')
ans=f.eval('xx=10,yy=1,bb=0,kk=20')
print ans
</jcode>
Such functions can be evaluated at any variable values and plotted.

== Integration ==

Numeric integration of functions is discussed in section [[DMelt:Numeric/5_Integration| Integration]]. 
Symbolic integrations will be discussed in dedicated sections.

Let us give a small example showing how to integrate <math>cos(x)^3</math> using a trapezium rule. We will integrate this function between 1 and 10 using 10k iterations.

<jcode lang="python">
from jhplot import F1D
f1=F1D('cos(x)^3')
print f1.integral(10000,1,10)
</jcode>

== Differentiation ==

<ifauth>
For differentiation, use the "diff" method. As argument, you must specify variable used for differentiation.
<jcode lang="python">
>>> from jhplot  import *
>>> fn=FND('x^4+x^2+x^4+y+z+h+10+20','x,y,z,h')
>>> fn.diff('x') # differentiate using x
>>> print 'Differentiate=',fn.toString()
Diffirentiate=  4.0*x^3.0+2.0*x+4.0*x^3.0
</jcode>
</ifauth>

== Simplification ==


<ifauth>
F1D functions can be simplified using the method "simplify". The example below simplifies  
<jcode lang="python">
>>> from jhplot  import *
>>> fn=FND('x^4+x^2+x^4+y+z+h+10+20','x,y,z,h')
>>> fn.simplify()
>>> print 'Simplify=',fn.toString()
</jcode>

The output is:
<jcode>
Simplify= 30.0+x^4.0+x^2.0+x^4.0+y+z+h
</jcode>

</ifauth>

== Minimization ==
Please read the section [[DMelt:Numeric/6_Minimization | Minimization]]

=Expression Builder =

Multidimensional functions can also be built using the package jhplot.math.exp4j. 
In the example below we build a function using <javadoc sc>jhplot.math.exp4j.ExpressionBuilder</javadoc>:

<jcode lang="python">
from java.awt import*
from jhplot  import *
from jhplot.math.exp4j import *

e=ExpressionBuilder("3 * sin(x) - 2 / (x - 2)")
e.variables("x")

ff=F1D("Test", e.build() ,10,100)
print ff.eval(10) # check at x=10

c1 = HPlot()
c1.visible(1)
c1.setAutoRange()
c1.draw(ff)
</jcode>

You can build an arbitrary function using Python and plot it, mixing Java and Jython libraries in one code.
You can put an arbitrary complex expressions and "if" statements. In the example below we make a custom function using
a Jython class and build an "ExpressionBuilder" object. then we evaluate this function for array of "X" values and plot it.

<ifauth>
<jcode lang="python">
dmelt 37424672.py
</jcode>
</ifauth>

Now we can show how to create a custom function in 3D. Again, we will use a python code
to do this.

<jput>
image 3591264
</jput>

<ifauth>
<jcode lang="python">
dmelt 3591264.py
</jcode>
</ifauth>

= Fast Math =

The implementation of trigonometric functions is a 3-4 times slower performance compare to C/C++. This is especially true
for atan2(), acos(), asin() functions. By default, DMelt uses fast calculations for all F1D, F2D etc. functions.
The table below shows the performance of FastMath compared to the standard Java implementation [http://blog.element84.com/improving-java-math-perf-with-jafama.html blog].
The times are in mean nanoseconds. 

<html>
<table>
  <thead>
    <tr>
      <th>Function</th>
      <th>Math Mean</th>
      <th>FastMath Mean</th>
      <th>Times Faster</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>acos</td>
      <td>58</td>
      <td>16</td>
      <td>3.6</td>
    </tr>
    <tr>
      <td>asin</td>
      <td>57</td>
      <td>15</td>
      <td>3.8</td>
    </tr>
    <tr>
      <td>atan</td>
      <td>94</td>
      <td>15</td>
      <td>6.2</td>
    </tr>
    <tr>
      <td>atan2</td>
      <td>145</td>
      <td>23</td>
      <td>6.3</td>
    </tr>
    <tr>
      <td>cbrt</td>
      <td>112</td>
      <td>18</td>
      <td>6.2</td>
    </tr>
    <tr>
      <td>ceil</td>
      <td>10</td>
      <td>11</td>
      <td>0.9</td>
    </tr>
    <tr>
      <td>cos</td>
      <td>74</td>
      <td>13</td>
      <td>5.7</td>
    </tr>
    <tr>
      <td>cosh</td>
      <td>141</td>
      <td>28</td>
      <td>5.0</td>
    </tr>
    <tr>
      <td>exp</td>
      <td>73</td>
      <td>16</td>
      <td>4.6</td>
    </tr>
    <tr>
      <td>expm1</td>
      <td>113</td>
      <td>17</td>
      <td>6.6</td>
    </tr>
    <tr>
      <td>floor</td>
      <td>11</td>
      <td>12</td>
      <td>0.9</td>
    </tr>
    <tr>
      <td>hypot</td>
      <td>435</td>
      <td>23</td>
      <td>18.9</td>
    </tr>
    <tr>
      <td>log</td>
      <td>31</td>
      <td>16</td>
      <td>1.9</td>
    </tr>
    <tr>
      <td>log10</td>
      <td>27</td>
      <td>13</td>
      <td>2.1</td>
    </tr>
    <tr>
      <td>log1p</td>
      <td>97</td>
      <td>15</td>
      <td>6.5</td>
    </tr>
    <tr>
      <td>nextAfter</td>
      <td>11</td>
      <td>10</td>
      <td>1.1</td>
    </tr>
    <tr>
      <td>nextUp</td>
      <td>10</td>
      <td>8</td>
      <td>1.3</td>
    </tr>
    <tr>
      <td>pow</td>
      <td>101</td>
      <td>38</td>
      <td>2.7</td>
    </tr>
    <tr>
      <td>round</td>
      <td>11</td>
      <td>10</td>
      <td>1.1</td>
    </tr>
    <tr>
      <td>sin</td>
      <td>72</td>
      <td>16</td>
      <td>4.5</td>
    </tr>
    <tr>
      <td>sinh</td>
      <td>126</td>
      <td>23</td>
      <td>5.5</td>
    </tr>
    <tr>
      <td>sqrt</td>
      <td>7</td>
      <td>15</td>
      <td>0.5</td>
    </tr>
    <tr>
      <td>tan</td>
      <td>52</td>
      <td>14</td>
      <td>3.7</td>
    </tr>
    <tr>
      <td>tanh</td>
      <td>167</td>
      <td>26</td>
      <td>6.4</td>
    </tr>
    <tr>
      <td>toDegrees</td>
      <td>7</td>
      <td>8</td>
      <td>0.9</td>
    </tr>
    <tr>
      <td>toRadians</td>
      <td>7</td>
      <td>7</td>
      <td>1.0</td>
    </tr>
  </tbody>
</table>
</html>

DMelt also include less precise methods for fast evaluation basic functions using <javadoc sc>jhplot.math.MathUtilsd</javadoc>. They are faster than the functions shown in above table, but their accuracy is roughly 1E-05.

=Using special functions =

You can integrate special functions from third-party Java libraries
into your code and show them in 2D and 3D.

= Parametric functions =

Please read the section [[DMelt:Math/2_Parametric_Functions| Parametric functions]].

[[Category:Functions]]
[[Category:Custom functions]]