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
43       None.
44

CLASS DATA

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

AUTHOR

226       Please send feedback, bug reports, and support requests to the
227       Math::Symbolic support mailing list: math-symbolic-support at lists dot
228       sourceforge dot net. Please consider letting us know how you use
229       Math::Symbolic. Thank you.
230
231       If you're interested in helping with the development or extending the
232       module's functionality, please contact the developers' mailing list:
233       math-symbolic-develop at lists dot sourceforge dot net.
234
235       List of contributors:
236
237         Steffen Müller, symbolic-module at steffen-mueller dot net
238         Stray Toaster, mwk at users dot sourceforge dot net
239         Oliver Ebenhöh
240

NAME

SYNOPSIS

DESCRIPTION

CLASS DATA

METHODS

AUTHOR

SEE ALSO