Math::Symbolic::Operator(3pm)

1Math::Symbolic::OperatoUrs(e3r)Contributed Perl DocumentMaattiho:n:Symbolic::Operator(3)
2
3
4

NAME

6       Math::Symbolic::Operator - Operators in symbolic calculations
7

SYNOPSIS

9         use Math::Symbolic::Operator;
10
11         my $sum = Math::Symbolic::Operator->new('+', $term1, $term2);
12
13         # or:
14         my $division =
15           Math::Symbolic::Operator->new(
16             {
17               type     => B_DIVISON,
18               operands => [$term1, $term2],
19             }
20           );
21
22         my $derivative =
23           Math::Symbolic::Operator->new(
24             {
25               type     => U_P_DERIVATIVE,
26               operands => [$term],
27             }
28           );
29

DESCRIPTION

31       This module implements all Math::Symbolic::Operator objects.  These
32       objects are overloaded in stringification-context to call the
33       to_string() method on the object. In numeric and boolean context, they
34       evaluate to their numerical representation.
35
36       For a list of supported operators, please refer to the list found
37       below, in the documentation for the new() constructor.
38
39       Math::Symbolic::Operator inherits from Math::Symbolic::Base.
40
41   EXPORT
42       None.
43

CLASS DATA

45       Math::Symbolic::Operator contains several class data structures.
46       Usually, you should not worry about dealing with any of them because
47       they are mostly an implementation detail, but for the sake of
48       completeness, here's the gist, but feel free to skip this section of
49       the docs:
50
51       One of these is the %Op_Symbols hash that associates operator (and
52       function) symbols with the corresponding constant as exported by
53       Math::Symbolic or Math::Symbolic::ExportConstants. (For example, '+' =>
54       B_SUM which in turn is 0, if I recall correctly. But I didn't tell you
55       that. Because you're supposed to use the supplied (inlined and hence
56       fast) constants so I can change their internal order if I deem it
57       necessary.)
58
59       The array @Op_Types associates operator indices (recall those nifty
60       constants?)  with anonymous hash datastructures that contain some info
61       on the operator such as its arity, the rule used to derive it, its
62       infix string, its prefix string, and information on how to actually
63       apply it to numbers.
64

METHODS

66   Constructor new
67       Expects a hash reference as first argument. That hash's contents will
68       be treated as key-value pairs of object attributes.  Important
69       attributes are 'type' => OPERATORTYPE (use constants as exported by
70       Math::Symbolic::ExportConstants!) and 'operands=>[op1,op2,...]'.  Where
71       the operands themselves may either be valid Math::Symbolic::* objects
72       or strings that will be parsed as such.
73
74       Special case: if no hash reference was found, first argument is assumed
75       to be the operator's symbol and the operator is assumed to be binary.
76       The following 2 arguments will be treated as operands. This special
77       case will ignore attempts to clone objects but if the operands are no
78       valid Math::Symbolic::* objects, they will be sent through a
79       Math::Symbolic::Parser to construct Math::Symbolic trees.
80
81       Returns a Math::Symbolic::Operator.
82
83       Supported operator symbols: (number of operands and their function in
84       parens)
85
86         +                  => sum (2)
87         -                  => difference (2)
88         *                  => product (2)
89         /                  => division (2)
90         log                => logarithm (2: base, function)
91         ^                  => exponentiation (2: base, exponent)
92         neg                => unary minus (1)
93         partial_derivative => partial derivative (2: function, var)
94         total_derivative   => total derivative (2: function, var)
95         sin                => sine (1)
96         cos                => cosine (1)
97         tan                => tangent (1)
98         cot                => cotangent (1)
99         asin               => arc sine (1)
100         acos               => arc cosine (1)
101         atan               => arc tangent (1)
102         atan2              => arc tangent of y/x (2: y, x)
103         acot               => arc cotangent (1)
104         sinh               => hyperbolic sine (1)
105         cosh               => hyperbolic cosine (1)
106         asinh              => hyperbolic area sine (1)
107         acosh              => hyperbolic area cosine (1)
108
109   Method arity
110       Returns the operator's arity as an integer.
111
112   Method type
113       Optional integer argument that sets the operator's type.  Returns the
114       operator's type as an integer.
115
116   Method to_string
117       Returns a string representation of the operator and its operands.
118       Optional argument: 'prefix' or 'infix'. Defaults to 'infix'.
119
120   Method term_type
121       Returns the type of the term. ( T_OPERATOR )
122
123   Method simplify
124       Term simpilification.  First argument: Boolean indicating that the tree
125       does not need to be cloned, but can be restructured instead.  While
126       this is faster, you might not be able to use the old tree any more.
127
128       Example:
129
130         my $othertree = $tree->simplify();
131         # can use $othertree and $tree now.
132
133         my $yetanothertree = $tree->simplify(1);
134         # must not use $tree any more because its internal
135         # representation might have been destroyed.
136
137       If you want to optimize a routine and you're sure that you won't need
138       the unsimplified tree any more, go ahead and use the first parameter.
139       In all other cases, you should go the safe route.
140
141   Methods op1 and op2
142       Returns first/second operand of the operator if it exists or undef.
143
144   Method apply
145       Applies the operation to its operands' value() and returns the result
146       as a constant (-object).
147
148       Without arguments, all variables in the tree are required to have a
149       value.  If any don't, the call to apply() returns undef.
150
151       To (temorarily, for this single method call) assign values to variables
152       in the tree, you may provide key/value pairs of variable names and
153       values. Instead of passing a list of key/value pairs, you may also pass
154       a single hash reference containing the variable mappings.
155
156       You usually want to call the value() instead of this.
157
158   Method value
159       value() evaluates the Math::Symbolic tree to its numeric
160       representation.
161
162       value() without arguments requires that every variable in the tree
163       contains a defined value attribute. Please note that this refers to
164       every variable object, not just every named variable.
165
166       value() with one argument sets the object's value if you're dealing
167       with Variables or Constants. In case of operators, a call with one
168       argument will assume that the argument is a hash reference. (see next
169       paragraph)
170
171       value() with named arguments (key/value pairs) associates variables in
172       the tree with the value-arguments if the corresponging key matches the
173       variable name.  (Can one say this any more complicated?) Since version
174       0.132, an equivalent and valid syntax is to pass a single hash
175       reference instead of a list.
176
177       Example: $tree->value(x => 1, y => 2, z => 3, t => 0) assigns the value
178       1 to any occurrances of variables of the name "x", aso.
179
180       If a variable in the tree has no value set (and no argument of value
181       sets it temporarily), the call to value() returns undef.
182
183   Method signature
184       signature() returns a tree's signature.
185
186       In the context of Math::Symbolic, signatures are the list of variables
187       any given tree depends on. That means the tree "v*t+x" depends on the
188       variables v, t, and x. Thus, applying signature() on the tree that
189       would be parsed from above example yields the sorted list ('t', 'v',
190       'x').
191
192       Constants do not depend on any variables and therefore return the empty
193       list.  Obviously, operators' dependencies vary.
194
195       Math::Symbolic::Variable objects, however, may have a slightly more
196       involved signature. By convention, Math::Symbolic variables depend on
197       themselves. That means their signature contains their own name. But
198       they can also depend on various other variables because variables
199       themselves can be viewed as placeholders for more compicated terms. For
200       example in mechanics, the acceleration of a particle depends on its
201       mass and the sum of all forces acting on it. So the variable
202       'acceleration' would have the signature ('acceleration', 'force1',
203       'force2',..., 'mass', 'time').
204
205       If you're just looking for a list of the names of all variables in the
206       tree, you should use the explicit_signature() method instead.
207
208   Method explicit_signature
209       explicit_signature() returns a lexicographically sorted list of
210       variable names in the tree.
211
212       See also: signature().
213

AUTHOR

215       Please send feedback, bug reports, and support requests to the
216       Math::Symbolic support mailing list: math-symbolic-support at lists dot
217       sourceforge dot net. Please consider letting us know how you use
218       Math::Symbolic. Thank you.
219
220       If you're interested in helping with the development or extending the
221       module's functionality, please contact the developers' mailing list:
222       math-symbolic-develop at lists dot sourceforge dot net.
223
224       List of contributors:
225
226         Steffen Müller, symbolic-module at steffen-mueller dot net
227         Stray Toaster, mwk at users dot sourceforge dot net
228         Oliver Ebenhöh
229

NAME

SYNOPSIS

DESCRIPTION

CLASS DATA

METHODS

AUTHOR

SEE ALSO