NAME

Math::Symbolic::Custom::CCompiler - Compile Math::Symbolic trees to C

SYNOPSIS

  use Math::Symbolic qw/:all/;
  use Math::Symbolic::Custom::CCompiler;
  
  my $function = parse_from_string(... some expression ...);
  # ... calculations ... see Math::Symbolic manpage

  my $c_code = $function->to_c();
  # $c_code now contains C code that does the same as the original
  # function.

  my $anon_subroutine = $function->to_compiled_c();
  # Generates and compiles C code. Uses Inline::C to dynamically
  # link the results. Returns an anonymous Perl subroutine that
  # does the same as the original function.
  # But in compiled C. (Ca. 1000x faster than the tree-walking
  # involved with the value() method.)

DESCRIPTION

This module extends the functionality of Math::Symbolic by offering facilities to compile symbolic math trees (formulas) to C code. It also uses Inline::C to compile and link the generated C code at run-time, thus allowing the user to do symbolic calculations in Perl with Math::Symbolic and then use the results in a fast numeric environment.

This software generates code. Code generators are difficult to test, but the first release of the module is now 1.5 years old and I haven't received any bug reports, so I consider it somewhat stable now.

Please read the manpage of Math::Symbolic::Compiler which comes with the Math::Symbolic distribution. Most of the gotchas involved with compiling the functions to Perl subroutines also apply to this module which compiles to C instead.

Alternatively, you can use the module not for faster calculations from your Perl program, but to generate C code for you. I have used it to generate an implementation for (many!) Zernike Polynomials for work in C.

The module adds two methods to all Math::Symbolic objects. These are:

$ms_tree->to_c()

This method returns the C code generated from the function. Please note that the code is extremely difficult to read for humans because variable and function names have been generated to not clash with any reserved words. Feel free to do search/replace on the results of you are bothered.

This code is not intended to be read by humans, but to be understood by C compilers.

The method takes one optional argument: An array reference. The referenced array is to contain some or all of the identifier names that where in the original mathematical formula. You can use the 'signature()' method on a Math::Symbolic object to get at the identifiers (variable names) that were used. The order of the identifier names indicates the order in which the C function parameters are to be mapped to the identifiers. Omitted identifiers are appended to the list in alphabetic order. If no such array reference is passed, the arguments are assumed to be in alphabetic order altogether.

Since this behaviour is equivalent to that of the compilation methods supplied by Math::Symbolic::Compiler, it is suggested that you read the corresponding manual for more detailed instructions.

$ms_tree->to_compiled_c()

This method generates the same code that 'to_c()' generates and compiles it using Inline::C and your local C compiler. The binary is then dynamically linked to your instance of perl through some scary magic in Inline::C. Go there and complain if you don't understand that because I, for sure, don't.

Inline::C also generates an Perl wrapper for the compiled C function. This is then referenced and returned. (The original package sub is deleted to prevent memory leakage.)

AUTHOR

Please send feedback, bug reports, and support requests to one of the contributors or the Math::Symbolic mailing list.

List of contributors:

  Steffen M�ller, symbolic-module at steffen-mueller dot net

COPYRIGHT AND LICENSE

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 or, at your option, any later version of Perl 5 you may have available.