EXPORT

  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)

parse_from_string

The string may contain any identifiers matching /[a-zA-Z][a-zA-Z0-9_]*/ which will be parsed as variables of the corresponding name.

Please refer to Math::Symbolic::Parser for more information.

CREATING Math::Symbolic TREES

The most convenient way is to use the builtin parser (for example via the "parse_from_string()" 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.

Try to break the formulas you parse into smallish bits. Test the parser performance to see how small they need to be.

I'll give a simple example where this first advice is gospel:

  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;
  }

So what's wrong here? I'm parsing the whole formula every time. How about this?

  use Math::Symbolic qw/parse_from_string/;
  my @formulas;
  my $sin = parse_from_string('sin(x)');
  my $term = parse_from_string('3*y^z');
  my $x = Math::Symbolic::Variable->new('x');
  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;
  }

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!

  use Math::Symbolic qw/parse_from_string/;
  my @formulas;
  my $proto = parse_from_string('sin(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;
  }

Notice how we can combine legibility of a clean formula with removing all parsing work from the loop? The "implement()" method is described in detail in Math::Symbolic::Base.

On a side note: One thing you could do to bring your computer to its knees is to take a function like sin(a*x)*cos(b*x)/e^(2*x), derive that in respect to x a couple of times (like, erm, 50 times?), call "to_string()" on it and parse that string again.

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:

  my $x = Math::Symbolic::Variable->new('x');
  my $formula = $x - sin(3*$x); # $formula will be a M::S tree
  # or:
  my $another = $x - 'sin(3*x)'; # have the string parsed as M::S tree

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.

Use 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.

Finally, you can create objects using the "new()" 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 slightly faster.

Use the constructors to build Math::Symbolic trees if you need speed. Using a prototype object and calling "new()" on that may help with the typing effort and should not result in a slow down.

CRUNCHING NUMBERS WITH Math::Symbolic

The simplest is, of course, to call "value()" on the tree and have that calculate the value of the formula. You might have to supply some input values to the formula via "value()", but you can also call "set_value()" before using "value()". But that's not faster. For each call to "value()", 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.)

Calling value() 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.

You may be able to make the formula simpler using the Math::Symbolic simplification routines (like "simplify()" or some stuff in the Math::Symbolic::Custom::* modules). Simpler formula are quicker to evaluate. In particular, the simplification should fold constants.

If you're going to evaluate a tree many times, try simplifying it first.

But again, your mileage may vary. Test first.

If the overhead of calling "value()" 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:

  my $tree = parse_from_string('3*x+sin(y)^(z+1)');
  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) !!!
  }

Compile your Math::Symbolic trees to Perl subroutines for evaluation in tight loops. The speedup is in the range of a few thousands.

On an interesting side note, the subroutines compiled from Math::Symbolic trees are just as fast as hand-crafted, "performance tuned" subroutines.

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.

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.

For raw execution speed, compile your trees to C code using Math::Symbolic::Custom::CCompiler.

PROOF

In the following tables, value means evaluation using the "value()" method, eval means evaluation of Perl code as a string, sub is a hand-crafted Perl subroutine, compiled is the compiled Perl code, c is the compiled C code. Evaluation of a very simple function yields:

  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%       --

We see that resorting to C is a waste in such simple cases. Compiling to a Perl sub, however is a good idea.

  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%       --

These more involved examples show that using value() can become unpractical even if you're just doing a 2D plot with just a few thousand points. The C routines aren't that much faster, but they scale much better.

Now for something different. Let's see whether I lied about the creation of Math::Symbolic trees. parse indicates that the parser was used to create the object tree. long indicates that the long syntax of the constructor was used. short... well. proto means that the objects were created from prototypes of the same class. For ol_long and ol_parse, I used the overloaded interface in conjunction with constructors or parsing (a la "$x * 'y+z'").

  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%     --

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 short here, because in case of "f(x) = x", you cannot make use of the overloaded interface.

  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%        --

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.) ol_long should, however, be faster than ol_parse. 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.