Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Math::Symbolic::CompilUser)Contributed Perl DocumenMath::Symbolic::Compiler(3)

NAME
       Math::Symbolic::Compiler	- Compile Math::Symbolic trees to Perl code

SYNOPSIS
	 use Math::Symbolic::Compiler;

	 # A tree to compile
	 my $tree = Math::Symbolic->parse_from_string('a^2 + b * c * 2');

	 # The Math::Symbolic::Variable	'a' will be evaluated to $_[1],	etc.
	 my $vars = [qw(b a c)];

	 my ($closure, $code, $trees) =
	   Math::Symbolic::Compiler->compile($tree, $vars);

	 print $closure->(2, 3,	5); # (b, a, c)
	 # prints 29 (=	3^2 + 2	* 5 * 2)

	 # or:
	 ($closure, $trees) =
	   Math::Symbolic::Compiler->compile_to_sub($tree, $vars);

	 ($code, $trees) = Math::Symbolic::Compiler->compile_to_code($tree, $vars);

DESCRIPTION
       This module allows one to compile Math::Symbolic	trees to Perl code
       and/or anonymous	subroutines whose arguments will be positionally
       mapped to the variables of the compiled Math::Symbolic tree.

       The reason you'd	want to	do this	is that	evaluating a Math::Symbolic
       tree to its numeric value is extremely slow. So is compiling, but once
       you've done all necessary symbolic calculations,	you can	take advantage
       of the speed gain of invoking a closure instead of evaluating a tree.

   UNCOMPILED LEFTOVER TREES
       Not all,	however, is well in the	land of	compiled Math::Symbolic	trees.
       There may occasionally be trees that cannot be compiled (such as	a
       derivative) which need to be included into the code as trees. These
       trees will be returned in a referenced array by the compile*() methods.
       The closures will have access to	the required trees as a	special
       variable	'@_TREES inside	the closure's scope, so	you need not worry
       about them in that case.	But if you plan	to use the generated code
       itself, you need	to supply an array named @_TREES that contains the
       trees as	returned by the	compile*() methods in the scope	of the eval()
       you evaluate the	code with.

       Note that you give away all performance benefits	compiling the tree
       might have if the closure contains uncompiled trees. You	can tell there
       are any by checking the length of the referenced	array that contains
       the trees. If it's 0, then there	are no trees left to worry about.

   AVOIDING LEFTOVER TREES
       In most cases, this is pretty simple. Just apply	all derivatives	in the
       tree to make sure that there are	none left in the tree. As of version
       0.130, there is no operator except derivatives that cannot be compiled.
       There may, however, be some operators you cannot	get rid	of this	easily
       some time in the	future.	 If you	have problems getting a	tree to
       compile,	try using the means of simplification provided by
       Math::Symbolic::* to get	a simpler tree for compilation.

   EXPORT
       None by default,	but you	may choose to import the compile(),
       compile_to_sub(), and compile_to_code() subroutines to your namespace
       using the standard Exporter semantics including the ':all' tag.

SUBROUTINES
   ($code, $trees) = compile_to_code($tree, $vars)
       The compile_to_code() class method takes	one mandatory argument which
       is the Math::Symbolic tree to be	compiled. Second argument is optional
       and an array reference to an array of variable mappings.	 See "VARIABLE
       PASSING STYLES" for details on how this works.

       compile_to_code() returns a string and an array reference. The string
       contains	the compiled Perl code that uses the values stored in @_ as
       described in the	section	on positional variable passing.	It also
       accesses	a special variable @_TREES if there were any sub-trees (inside
       the tree	that has been compiled)	that were impossible to	compile. The
       array reference returned	by this	method contains	any of the
       aforementioned trees that failed	to compile.

       If there	are any	such trees that	did not	compile, you may put them into
       the @_TREES variable in scope of	the eval() that	evaluates the compiled
       code in the same	order that they	were returned by this method. If you
       do that,	the code will run and determine	the value of the tree at run-
       time. Needless to say, that is slow.

   ($sub, $trees) = compile_to_sub($tree, $vars)
       The compile_to_sub() class method takes one mandatory argument which is
       the Math::Symbolic tree to be compiled. Second argument is optional and
       an array	reference to an	array of variable mappings.  See "VARIABLE
       PASSING STYLES" for details on how this works.

       compile_to_sub()	returns	a list of two elements,	the first being	the
       compiled	anonymous subroutine. For details on the second	element,
       please refer to the docs	on the compile_to_code() subroutine.

   ($sub, $code, $trees) = compile($tree, $vars)
       The compile() class method takes	one mandatory argument which is	the
       Math::Symbolic tree to be compiled. Second argument is optional and an
       array reference to an array of variable mappings.  See "POSITIONAL
       VARIABLE	PASSING" for details on	how this works.

       compile() returns a list	of three elements, the first being the
       compiled	anonymous subroutine, the second being the compiled code. For
       details on the second and third elements, please	refer to the docs on
       the compile_to_code() subroutine.

   VARIABLE PASSING STYLES
       Currently, the Math::Symbolic compiler only supports compiling to subs
       with positional variable	passing. At some point,	the user should	be
       able to choose between positional- and named variable passing styles.
       The difference is best explained	by an example:

	 # positional:
	 $sub->(4, 5, 1);

	 # named: (NOT IMPLEMENTED!)
	 $sub->(a => 5,	b => 4,	x => 1);

       With positional variable	passing, the subroutine	statically maps	its
       arguments to its	internal variables. The	way the	subroutine does	that
       has been	fixed at compile-time. It is determined	by the second argument
       to the various compile_*	functions found	in this	package. This second
       argument	is expected to be a reference to an array of variable names.
       The order of the	variable names determines which	parameter of the
       compiled	sub will be assigned to	the variable. Example:

	 my ($sub) =
	   Math::Symbolic::Compiler->compile_to_sub($tree, [qw/c a b/]);

	 # First argument will be mapped to c, second to a, and	third to b
	 # All others will be ignored.
	 $sub->(4, 5, 6, 7);

	 # Variable mapping: a = 5, b =	6, c = 4

       One important note remains: if any (or all) variables in	the tree are
       unaccounted for,	they will be lexicographically sorted and appended to
       the variable mapping in that order. That	means if you don't map
       variables yourself, they	will be	sorted lexicographically.

       Thanks to Henrik	Edlund's input,	it's possible to pass a	hash reference
       as second argument to the compile* functions instead of an array
       reference.  The order of	the mapped variables is	then determined	by
       their associated	value, which should be an integer starting with	0.
       Example:

	 Math::Symbolic::Compiler->compile_to_sub($tree, {b => 2, a => 1, c => 0});

       Would result in the order c, a, b.

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.

       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.

       List of contributors:

	 Steffen Mi?1/2ller, symbolic-module at	steffen-mueller	dot net
	 Stray Toaster,	mwk at users dot sourceforge dot net
	 Oliver	Ebenhi?1/2h

SEE ALSO
       New versions of this module can be found	on http://steffen-mueller.net
       or CPAN.	The module development takes place on Sourceforge at
       http://sourceforge.net/projects/math-symbolic/

       Math::Symbolic

perl v5.32.0			  2013-06-17	   Math::Symbolic::Compiler(3)

NAME | SYNOPSIS | DESCRIPTION | SUBROUTINES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Math::Symbolic::Compiler&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help