NAME

Math::SymbolicX::Complex - Complex number support for the Math::Symbolic parser

SYNOPSIS

  use Math::Symbolic qw/parse_from_string/;
  use Math::SymbolicX::Complex;
  
  my $formula = parse_from_string('3 * complex(3,2)^2 + polar(1, pi/2)');
  print $formula->value();
  # prints '14.9999999997949+37i'
  # (blame the inaccuracy on the floating point representation of "pi")

DESCRIPTION

This module adds complex number support to Math::Symbolic. It does so by extending the parser of the Math::Symbolic module (that is, the one stored in $Math::Symbolic::Parser) with certain special functions that create complex constants. (Math::Symbolic::Variable objects have been able to contain complex number objects since the very beginning.)

MOTIVATION

All constants in strings that are parsed by Math::Symbolic::Parser are converted to Math::Symbolic::Constant objects holding the value associated to the constant in an ordinary Perl Scalar by default. Unfortunately, that means you are limited to real floating point numbers.

On the other hand, there's the formidable Math::Complex module that gives complex number support to Perl. Since the Math::Symbolic::Scalar objects can hold any object, you can build your trees by hand using Math::Complex objects instead of Perl Scalars for the value of the constants. But since the Math::Symbolic::Parser is by far the most convenient interface to Math::Symbolic, there had to be a reasonably simple way of introducing Math::Complex support to the parser. So here goes.

USAGE

In order to complex number constants in Math::Symbolic trees from the parser, you just load this extension module and wrap any of the functions listed hereafter around any constants that are complex in nature.

The aforementioned functions are "complex()" and "polar()". "complex(RE, IM)" takes a real portion and an imaginary portion of the complex number as arguments. That means, it uses the "Math::Complex-"make(RE, IM)> method to create the Math::Complex objects. Similarily, "polar()" uses the "Math::Complex-"emake(R, ARG)> syntax provided by Math::Complex. (Polar notation is r*e^(i*arg). It is equivalent to the "x+i*y" notation because it also covers the whole complex plane.)

There are some usability extensions to the simple "complex(RE, IM)" and "polar(R, ARG)" notations: You can use the basic operators ('+', '-', '*', '/', and '**') and the symbolic constant 'pi' in the expressions for RE, IM, R, and ARG. That means "polar(1, pi/2)" should be translated to "polar(1, 1.5707963267949)" internally.

Note, however, that the floating point representation of pi used in this module is far from exact. So, instead of yielding "0+i" as a result, the above example will be "-3.49148336110938e-015+i". Of course, "-3.49148336110938e-015" is as close to a real zero as you'll get, but testing for equality with the "==" operator will break.

AUTHOR

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

You may contact the author at symbolic-module at steffen-mueller dot net

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.