.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Math::Symbolic 3pm"
.TH Math::Symbolic 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Math::Symbolic \- Symbolic calculations
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Math::Symbolic;
\&  
\&  my $tree = Math::Symbolic\->parse_from_string(\*(Aq1/2 * m * v^2\*(Aq);
\&  # Now do symbolic calculations with $tree.
\&  # ... like deriving it...
\&  
\&  my ($sub) = Math::Symbolic::Compiler\->compile_to_sub($tree);
\&
\&  my $kinetic_energy = $sub\->($mass, $velocity);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Math::Symbolic is intended to offer symbolic calculation capabilities
to the Perl programmer without using external (and commercial) libraries
and/or applications.
.PP
Unless, however, some interested and knowledgable developers turn up to
participate in the development, the library will be severely limited by
my experience in the area. Symbolic calculations are an active field of
research in \s-1CS.\s0
.PP
There are several ways to construct Math::Symbolic trees. There are no
actual Math::Symbolic objects, but rather trees of objects of subclasses of
Math::Symbolic. The most general but unfortunately also the least intuitive
way of constructing trees is to use the constructors of
the Math::Symbolic::Operator, Math::Symbolic::Variable, and
Math::Symbolic::Constant classes to create (nested) objects of the
corresponding types.
.PP
Furthermore, you may use the overloaded interface to apply the standard
Perl operators (and functions, see \*(L"\s-1OVERLOADED OPERATORS\*(R"\s0) to existing
Math::Symbolic trees and standard Perl expressions.
.PP
Possibly the most convenient way of constructing Math::Symbolic trees is
using the builtin parser to generate trees from expressions such as \f(CW\*(C`2 * x^5\*(C'\fR.
You may use the \f(CW\*(C`Math::Symbolic\->parse_from_string()\*(C'\fR class method for this.
.PP
Of course, you may combine the overloaded interface with the parser to
generate trees with Perl code such as \f(CW\*(C`$term * 5 * \*(Aqsin(omega*t+phi)\*(Aq\*(C'\fR which
will create a tree of the existing tree \f(CW$term\fR times 5 times the sine of
the vars omega times t plus phi.
.PP
There are several modules in the distribution that contain subroutines
related to calculus. These are not loaded by Math::Symbolic by default.
Furthermore, there are several extensions to Math::Symbolic available
from \s-1CPAN\s0 as separate distributions. Please refer to \*(L"\s-1SEE ALSO\*(R"\s0
for an incomplete list of these.
.PP
For example, Math::Symbolic::MiscCalculus come with \f(CW\*(C`Math::Symbolic\*(C'\fR and
contains routines to compute Taylor Polynomials and the associated errors.
.PP
Routines related to vector calculus such as grad, div, rot, and Jacobi\- and
Hesse matrices are available through the Math::Symbolic::VectorCalculus
module. This module is also able to compute Taylor Polynomials of
functions of two variables, directional derivatives, total differentials,
and Wronskian Determinants.
.PP
Some basic support for linear algebra can be found in
Math::Symbolic::MiscAlgebra. This includes a routine to compute
the determinant of a matrix of \f(CW\*(C`Math::Symbolic\*(C'\fR trees.
.SS "\s-1EXPORT\s0"
.IX Subsection "EXPORT"
None by default, but you may choose to have the following constants
exported to your namespace using the standard Exporter semantics.
There are two export tags: :all and :constants. :all will export
all constants and the parse_from_string subroutine.
.PP
.Vb 3
\&  Constants for transcendetal numbers:
\&    EULER (2.7182...)
\&    PI    (3.14159...)
\&    
\&  Constants representing operator types: (First letter indicates arity)
\&  (These evaluate to the same numbers that are returned by the type()
\&   method of Math::Symbolic::Operator objects.)
\&    B_SUM
\&    B_DIFFERENCE
\&    B_PRODUCT
\&    B_DIVISION
\&    B_LOG
\&    B_EXP
\&    U_MINUS
\&    U_P_DERIVATIVE (partial derivative)
\&    U_T_DERIVATIVE (total derivative)
\&    U_SINE
\&    U_COSINE
\&    U_TANGENT
\&    U_COTANGENT
\&    U_ARCSINE
\&    U_ARCCOSINE
\&    U_ARCTANGENT
\&    U_ARCCOTANGENT
\&    U_SINE_H
\&    U_COSINE_H
\&    U_AREASINE_H
\&    U_AREACOSINE_H
\&    B_ARCTANGENT_TWO
\&    
\&  Constants representing Math::Symbolic term types:
\&  (These evaluate to the same numbers that are returned by the term_type()
\&   methods.)
\&    T_OPERATOR
\&    T_CONSTANT
\&    T_VARIABLE
\&  
\&  Subroutines:
\&    parse_from_string (returns Math::Symbolic tree)
.Ve
.SH "CLASS DATA"
.IX Header "CLASS DATA"
The package variable \f(CW$Parser\fR will contain a Parse::RecDescent
object that is used to parse strings at runtime.
.SH "SUBROUTINES"
.IX Header "SUBROUTINES"
.SS "parse_from_string"
.IX Subsection "parse_from_string"
This subroutine takes a string as argument and parses it using
a Parse::RecDescent parser taken from the package variable
\&\f(CW$Math::Symbolic::Parser\fR. It generates a Math::Symbolic tree
from the string and returns that tree.
.PP
The string may contain any identifiers matching /[a\-zA\-Z][a\-zA\-Z0\-9_]*/ which
will be parsed as variables of the corresponding name.
.PP
Please refer to Math::Symbolic::Parser for more information.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
This example demonstrates variable and operator creation using
object prototypes as well as partial derivatives and the various
ways of applying derivatives and simplifying terms. Furthermore, it
shows how to use the compiler for simple expressions.
.PP
.Vb 1
\&  use Math::Symbolic qw/:all/;
\&  
\&  my $energy = parse_from_string(<<\*(AqHERE\*(Aq);
\&        kinetic(mass, velocity, time) +
\&        potential(mass, z, time)
\&  HERE
\&  
\&  $energy\->implement(kinetic => \*(Aq(1/2) * mass * velocity(time)^2\*(Aq);
\&  $energy\->implement(potential => \*(Aqmass * g * z(t)\*(Aq);
\&  
\&  $energy\->set_value(g => 9.81); # permanently
\&  
\&  print "Energy is: $energy\en";
\&  
\&  # Is how does the energy change with the height?
\&  my $derived = $energy\->new(\*(Aqpartial_derivative\*(Aq, $energy, \*(Aqz\*(Aq);
\&  $derived = $derived\->apply_derivatives()\->simplify();
\&  
\&  print "Changes with the heigth as: $derived\en";
\&  
\&  # With whatever values you fancy:
\&  print "Putting in some sample values: ",
\&        $energy\->value(mass => 20, velocity => 10, z => 5),
\&        "\en";
\&  
\&  # Too slow?
\&  $energy\->implement(g => \*(Aq9.81\*(Aq); # To get rid of the variable
\&  
\&  my ($sub) = Math::Symbolic::Compiler\->compile($energy);
\&  
\&  print "This was much faster: ",
\&        $sub\->(20, 10, 5),  # vars ordered alphabetically
\&        "\en";
.Ve
.SH "OVERLOADED OPERATORS"
.IX Header "OVERLOADED OPERATORS"
Since version 0.102, several arithmetic operators have been overloaded.
.PP
That means you can do most arithmetic with Math::Symbolic trees just as
if they were plain Perl scalars.
.PP
The following operators are currently overloaded to produce valid
Math::Symbolic trees when applied to an expression involving at least one
Math::Symbolic object:
.PP
.Vb 1
\&  +, \-, *, /, **, sqrt, log, exp, sin, cos
.Ve
.PP
Furthermore, some contexts have been overloaded with particular behaviour:
\&'""' (stringification context) has been overloaded to produce the string
representation of the object. '0+' (numerical context) has been overloaded
to produce the value of the object. 'bool' (boolean context) has been
overloaded to produce the value of the object.
.PP
If one of the operands of an overloaded operator is a Math::Symbolic tree and
the over is undef, the module will throw an error \fIunless the operator
is a + or a \-\fR. If the operator is an addition, the result will be the
original Math::Symbolic tree. If the operator is a subtraction, the result will
be the negative of the Math::Symbolic tree. Reason for this inconsistent
behaviour is that it makes idioms like the following possible:
.PP
.Vb 2
\&  @objects = (... list of Math::Symbolic trees ...);
\&  $sum += $_ foreach @objects;
.Ve
.PP
Without this behaviour, you would have to shift the first object into \f(CW$sum\fR
before using it. This is not a problem in this case, but if you are applying
some complex calculation to each object in the loop body before adding it to
the sum, you'd have to either split the code into two loops or replicate the
code required for the complex calculation when \fBshift()\fRing the first object
into \f(CW$sum\fR.
.PP
\&\fBWarning:\fR The operator to use for exponentiation is the normal Perl
operator for exponentiation \f(CW\*(C`**\*(C'\fR, \s-1NOT\s0 the caret \f(CW\*(C`^\*(C'\fR which denotes
exponentiation in the notation that is recognized by the Math::Symbolic
parsers! The \f(CW\*(C`^\*(C'\fR operator will be interpreted as the normal binary xor.
.SH "EXTENDING THE MODULE"
.IX Header "EXTENDING THE MODULE"
Due to several design decisions, it is probably rather difficult to extend
the Math::Symbolic related modules through subclassing. Instead, we
chose to make the module extendable through delegation.
.PP
That means you can introduce your own methods to extend Math::Symbolic's
functionality. How this works in detail can be read in
Math::Symbolic::Custom.
.PP
Some of the extensions available via \s-1CPAN\s0 right now are listed in the
\&\*(L"\s-1SEE ALSO\*(R"\s0 section.
.SH "PERFORMANCE"
.IX Header "PERFORMANCE"
Math::Symbolic can become quite slow if you use it wrong. To be honest, it can
even be slow if you use it correctly. This section is meant to give you an
idea about what you can do to have Math::Symbolic compute as quickly as
possible. It has some explanation and a couple of 'red flags' to watch out for.
We'll focus on two central points: Creation and evaluation.
.SS "\s-1CREATING\s0 Math::Symbolic \s-1TREES\s0"
.IX Subsection "CREATING Math::Symbolic TREES"
Math::Symbolic provides several means of generating Math::Symbolic trees
(which are just trees of Math::Symbolic::Constant, Math::Symbolic::Variable
and most importantly Math::Symbolic::Operator objects).
.PP
The most convenient way is to use the builtin parser (for example via the 
\&\f(CW\*(C`parse_from_string()\*(C'\fR subroutine). Problem is, this darn thing becomes
really slow for long input strings. This is a known problem for 
Parse::RecDescent parsers and the Math::Symbolic grammar isn't the shortest
either.
.PP
\&\fBTry to break the formulas you parse into smallish bits. Test the parser
performance to see how small they need to be.\fR
.PP
I'll give a simple example where this first advice is gospel:
.PP
.Vb 6
\&  use Math::Symbolic qw/parse_from_string/;
\&  my @formulas;
\&  foreach my $var (qw/x y z foo bar baz/) {
\&      my $formula = parse_from_string("sin(x)*$var+3*y^z\-$var*x");
\&      push @formulas, $formula;
\&  }
.Ve
.PP
So what's wrong here? I'm parsing the whole formula every time. How about this?
.PP
.Vb 10
\&  use Math::Symbolic qw/parse_from_string/;
\&  my @formulas;
\&  my $sin = parse_from_string(\*(Aqsin(x)\*(Aq);
\&  my $term = parse_from_string(\*(Aq3*y^z\*(Aq);
\&  my $x = Math::Symbolic::Variable\->new(\*(Aqx\*(Aq);
\&  foreach my $var (qw/x y z foo bar baz/) {
\&          my $v = $x\->new($var);
\&      my $formula = $sin*$var + $term \- $var*$x;
\&      push @formulas, $formula;
\&  }
.Ve
.PP
I wouldn't call that more legible, but you notice how I moved all the
heavy lifting out of the loop. You'll know and do this for normal code, but it's
maybe not as obvious when dealing with such code. Now, since this is still
slow and \- if anything \- ugly, we'll do something really clever now to get the
best of both worlds!
.PP
.Vb 8
\&  use Math::Symbolic qw/parse_from_string/;
\&  my @formulas;
\&  my $proto = parse_from_string(\*(Aqsin(x)*var+3*y^z\-var*x");
\&  foreach my $var (qw/x y z foo bar baz/) {
\&      my $formula = $proto\->new();
\&      $formula\->implement(var => Math::Symbolic::Variable\->new($var));
\&      push @formulas, $formula;
\&  }
.Ve
.PP
Notice how we can combine legibility of a clean formula with removing all
parsing work from the loop? The \f(CW\*(C`implement()\*(C'\fR method is described in
detail in Math::Symbolic::Base.
.PP
On a side note: One thing you could do to bring your computer to its knees
is to take a
function like \fIsin(a*x)*cos(b*x)/e^(2*x)\fR, derive that in respect to \fIx\fR a
couple of times (like, erm, 50 times?), call \f(CW\*(C`to_string()\*(C'\fR on it and
parse that string again.
.PP
Almost as convenient as the parser is the overloaded interface.
That means, you create a Math::Symbolic object and use it in 
algebraic expressions
as if it was a variable or number. This way, you can even multiply a
Math::Symbolic tree with a string and have the string be parsed as a subtree.
Example:
.PP
.Vb 4
\&  my $x = Math::Symbolic::Variable\->new(\*(Aqx\*(Aq);
\&  my $formula = $x \- sin(3*$x); # $formula will be a M::S tree
\&  # or:
\&  my $another = $x \- \*(Aqsin(3*x)\*(Aq; # have the string parsed as M::S tree
.Ve
.PP
This, however, turns out to be rather slow, too. It is only about two to five
times faster than parsing the formula all the way.
.PP
\&\fBUse the overloaded interface to construct trees from existing Math::Symbolic
objects, but if you need to create new trees quickly, resort to building
them by hand.\fR
.PP
Finally, you can create objects using the \f(CW\*(C`new()\*(C'\fR constructors from
Math::Symbolic::Operator and friends. These can be called in two forms,
a long one that gives you complete control (signature for variables, etc.)
and a short hand. Even if it is just to protect your finger tips from burning,
you should use the short hand whenever possible. It is also \fIslightly\fR faster.
.PP
\&\fBUse the constructors to build Math::Symbolic trees if you need speed.
Using a prototype object and calling \f(CB\*(C`new()\*(C'\fB on that may help with the
typing effort and should not result in a slow down\fR.
.SS "\s-1CRUNCHING NUMBERS WITH\s0 Math::Symbolic"
.IX Subsection "CRUNCHING NUMBERS WITH Math::Symbolic"
As with the generation of Math::Symbolic trees, the evaluation of a formula
can be done in distinct ways.
.PP
The simplest is, of course, to call \f(CW\*(C`value()\*(C'\fR on the tree and have
that calculate the value of the formula. You might have to supply some
input values to the formula via \f(CW\*(C`value()\*(C'\fR, but you can also call
\&\f(CW\*(C`set_value()\*(C'\fR before using \f(CW\*(C`value()\*(C'\fR. But that's not faster.
For each call to \f(CW\*(C`value()\*(C'\fR, the computer walks the complete Math::Symbolic
tree and evaluates the nodes. If it reaches a leaf, the resulting value is
propagated back up the tree. (It's a depth-first search.)
.PP
\&\fBCalling \fBvalue()\fB on a Math::Symbolic tree requires walking the tree for
every evaluation of the formula. Use this if you'll evaluate the formula
only a few times.\fR
.PP
You may be able to make the formula simpler using the Math::Symbolic 
simplification routines (like \f(CW\*(C`simplify()\*(C'\fR or some stuff in the 
Math::Symbolic::Custom::* modules). Simpler formula are quicker to evaluate.
In particular, the simplification should fold constants.
.PP
\&\fBIf you're going to evaluate a tree many times, try simplifying it first.\fR
.PP
But again, your mileage may vary. Test first.
.PP
If the overhead of calling \f(CW\*(C`value()\*(C'\fR is unaccepable, you should use the
Math::Symbolic::Compiler to compile the tree to Perl code. (Which usually
comes in compiled form as an anonymous subroutine.) Example:
.PP
.Vb 7
\&  my $tree = parse_from_string(\*(Aq3*x+sin(y)^(z+1)\*(Aq);
\&  my $sub = $tree\->to_sub(y => 0, x => 1, z => 2);
\&  foreach (1..100) {
\&    # define $x, $y, and $z
\&    my $res = $sub\->($y, $x, $z);
\&    # faster than $tree\->value(x => $x, y => $y, z => $z) !!!
\&  }
.Ve
.PP
\&\fBCompile your Math::Symbolic trees to Perl subroutines for evaluation in
tight loops. The speedup is in the range of a few thousands.\fR
.PP
On an interesting side note, the subroutines compiled from Math::Symbolic
trees are just as fast as hand-crafted, \*(L"performance tuned\*(R" subroutines.
.PP
If you have extremely long formulas, you can choose to even resort to more
extreme measures than generating Perl code. You can have Math::Symbolic
generate C code for you, compile that and link it into your application at run
time. It will then be available to you as a subroutine.
.PP
This is not the most portable thing to do. (You need Inline::C which
in turn needs the C compiler that was used to compile your perl.)
Therefore, you need to install an extra module for this. It's called
Math::Symbolic::Custom::CCompiler. The speed-up for short formulas
is only about factor 2 due to the overhead of calling the Perl subroutine, but
with sufficiently complicated formulas, you should be able to get a boost
up to factor 100 or even 1000.
.PP
\&\fBFor raw execution speed, compile your trees to C code using 
Math::Symbolic::Custom::CCompiler.\fR
.SS "\s-1PROOF\s0"
.IX Subsection "PROOF"
In the last two sections, you were told a lot about the performance of
two important aspects of Math::Symbolic handling. But eventhough benchmarks
are very system dependent and have limited meaning to the general case,
I'll supply some proof for what I claimed. This is
Perl 5.8.6 on linux\-2.6.9, x86_64 (Athlon64 3200+).
.PP
In the following tables, \fIvalue\fR means evaluation using the \f(CW\*(C`value()\*(C'\fR method,
\&\fIeval\fR means evaluation of Perl code as a string, \fIsub\fR is a hand-crafted
Perl subroutine, \fIcompiled\fR is the compiled Perl code, \fIc\fR is the compiled
C code. Evaluation of a very simple function yields:
.PP
.Vb 7
\&  f(x) = x*2
\&                Rate    value     eval      sub compiled        c
\&  value      17322/s       \-\-     \-68%     \-99%     \-99%     \-99%
\&  eval       54652/s     215%       \-\-     \-97%     \-97%     \-97%
\&  sub      1603578/s    9157%    2834%       \-\-      \-1%     \-16%
\&  compiled 1616630/s    9233%    2858%       1%       \-\-     \-15%
\&  c        1907541/s   10912%    3390%      19%      18%       \-\-
.Ve
.PP
We see that resorting to C is a waste in such simple cases. Compiling to
a Perl sub, however is a good idea.
.PP
.Vb 7
\&  f(x,y,z) = x*y*z+sin(x*y*z)\-cos(x*y*z)
\&                Rate    value     eval compiled      sub        c
\&  value       1993/s       \-\-     \-88%    \-100%    \-100%    \-100%
\&  eval       16006/s     703%       \-\-     \-97%     \-97%     \-99%
\&  compiled  544217/s   27202%    3300%       \-\-      \-2%     \-56%
\&  sub       556737/s   27830%    3378%       2%       \-\-     \-55%
\&  c        1232362/s   61724%    7599%     126%     121%       \-\-
\&  
\&  f(x,y,z,a,b) = x^y^tan(a*z)^(y*sin(x^(z*b)))
\&               Rate    value     eval compiled      sub        c
\&  value      2181/s       \-\-     \-84%     \-99%     \-99%    \-100%
\&  eval      13613/s     524%       \-\-     \-97%     \-97%     \-98%
\&  compiled 394945/s   18012%    2801%       \-\-      \-5%     \-48%
\&  sub      414328/s   18901%    2944%       5%       \-\-     \-46%
\&  c        763985/s   34936%    5512%      93%      84%       \-\-
.Ve
.PP
These more involved examples show that using \fI\f(BIvalue()\fI\fR can become unpractical
even if you're just doing a 2D plot with just a few thousand points.
The C routines aren't \fIthat\fR much faster, but they scale much better.
.PP
Now for something different. Let's see whether I lied about the creation of
Math::Symbolic trees. \fIparse\fR indicates that the parser was used to create
the object tree. \fIlong\fR indicates that the long syntax of the constructor
was used. \fIshort\fR... well. \fIproto\fR means that the objects were created from
prototypes of the same class. For \fIol_long\fR and \fIol_parse\fR, I used the
overloaded interface in conjunction with constructors or parsing (a la
\&\f(CW\*(C`$x * \*(Aqy+z\*(Aq\*(C'\fR).
.PP
.Vb 8
\&  f(x) = x
\&               Rate  parse  long   short  ol_long  ol_parse  proto
\&  parse       258/s     \-\-  \-100%  \-100%    \-100%     \-100%  \-100%
\&  long      95813/s 37102%     \-\-   \-33%     \-34%      \-34%   \-35%
\&  short    143359/s 55563%    50%     \-\-      \-2%       \-2%    \-3%
\&  ol_long  146022/s 56596%    52%     2%       \-\-       \-0%    \-1%
\&  ol_parse 146256/s 56687%    53%     2%       0%        \-\-    \-1%
\&  proto    147119/s 57023%    54%     3%       1%        1%     \-\-
.Ve
.PP
Obviously, the parser gets blown to pieces, performance-wise. If you want to
use it, but cannot accept its tranquility, you can resort to
Math::SymbolicX::Inline and have the formulas parsed at compile time. (Which
isn't faster, but means that they are available when the program runs.)
All other methods are about the same speed. Note, that the ol_* tests
are just the same as \fIshort\fR here, because in case of \f(CW\*(C`f(x) = x\*(C'\fR, you cannot
make use of the overloaded interface.
.PP
.Vb 8
\&  f(x,y,a,b) = x*y(a,b)
\&              Rate  parse  ol_parse ol_long   long  proto  short
\&  parse      125/s     \-\-      \-41%    \-41%  \-100%  \-100%  \-100%
\&  ol_parse   213/s    70%        \-\-     \-0%   \-99%   \-99%   \-99%
\&  ol_long    213/s    70%        0%      \-\-   \-99%   \-99%   \-99%
\&  long     26180/s 20769%    12178%  12171%     \-\-    \-6%   \-10%
\&  proto    27836/s 22089%    12955%  12947%     6%     \-\-    \-5%
\&  short    29148/s 23135%    13570%  13562%    11%     5%     \-\-
\&
\&  f(x,a) = sin(x+a)*3\-5*x
\&              Rate    parse ol_long ol_parse     proto     short
\&  parse     41.2/s       \-\-    \-83%     \-84%     \-100%     \-100%
\&  ol_long    250/s     505%      \-\-      \-0%      \-97%      \-98%
\&  ol_parse   250/s     506%      0%       \-\-      \-97%      \-98%
\&  proto     9779/s   23611%   3819%    3810%        \-\-       \-3%
\&  short    10060/s   24291%   3932%    3922%        3%        \-\-
.Ve
.PP
The picture changes when we're dealing with slightly longer functions.
The performance of the overloaded interface isn't that much better than the
parser. (Since it uses the parser to convert non\-Math::Symbolic operands.)
\&\fIol_long\fR should, however, be faster than \fIol_parse\fR. I'll refine the
benchmark somewhen. The three other construction methods are still about
the same speed. I omitted the long version in the last benchmark because
the typing work involved was unnerving.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
New versions of this module can be found on
http://steffen\-mueller.net or \s-1CPAN.\s0 The module development takes place on
Sourceforge at http://sourceforge.net/projects/math\-symbolic/
.PP
The following modules come with this distribution:
.PP
Math::Symbolic::ExportConstants,
Math::Symbolic::AuxFunctions
.PP
Math::Symbolic::Base,
Math::Symbolic::Operator,
Math::Symbolic::Constant,
Math::Symbolic::Variable
.PP
Math::Symbolic::Custom,
Math::Symbolic::Custom::Base,
Math::Symbolic::Custom::DefaultTests,
Math::Symbolic::Custom::DefaultMods
Math::Symbolic::Custom::DefaultDumpers
.PP
Math::Symbolic::Derivative,
Math::Symbolic::MiscCalculus,
Math::Symbolic::VectorCalculus,
Math::Symbolic::MiscAlgebra
.PP
Math::Symbolic::Parser,
Math::Symbolic::Parser::Precompiled,
Math::Symbolic::Compiler
.PP
The following modules are extensions on \s-1CPAN\s0 that do not come with this
distribution in order to keep the distribution size reasonable.
.PP
Math::SymbolicX::Inline \- (Inlined Math::Symbolic functions)
.PP
Math::Symbolic::Custom::CCompiler (Compile Math::Symbolic trees to C
for speed or for use in C code)
.PP
Math::SymbolicX::BigNum (Big number support for the Math::Symbolic parser)
.PP
Math::SymbolicX::Complex (Complex number support for the Math::Symbolic
parser)
.PP
Math::Symbolic::Custom::Contains (Find subtrees in Math::Symbolic
expressions)
.PP
Math::SymbolicX::ParserExtensionFactory (Generate parser extensions for the
Math::Symbolic parser)
.PP
Math::Symbolic::Custom::ErrorPropagation (Calculate Gaussian Error
Propagation)
.PP
Math::SymbolicX::Statistics::Distributions (Statistical Distributions as
Math::Symbolic functions)
.PP
Math::SymbolicX::NoSimplification (Turns off Math::Symbolic simplifications)
.SH "AUTHOR"
.IX Header "AUTHOR"
Please send feedback, bug reports, and support requests to the Math::Symbolic
support mailing list:
math-symbolic-support at lists dot sourceforge dot net. Please
consider letting us know how you use Math::Symbolic. Thank you.
.PP
If you're interested in helping with the development or extending the
module's functionality, please contact the developers' mailing list:
math-symbolic-develop at lists dot sourceforge dot net.
.PP
List of contributors:
.PP
.Vb 3
\&  Steffen MXller, smueller at cpan dot org
\&  Stray Toaster, mwk at users dot sourceforge dot net
\&  Oliver EbenhXh
.Ve
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011,
2013 by Steffen Mueller
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.6.1 or,
at your option, any later version of Perl 5 you may have available.