1Math::Symbolic::Base(3)User Contributed Perl DocumentatioMnath::Symbolic::Base(3)
2
6 Math::Symbolic::Base - Base class for symbols in symbolic calculations
7
9 use Math::Symbolic::Base;
10
12 This is a base class for all Math::Symbolic::* terms such as
13 Math::Symbolic::Operator, Math::Symbolic::Variable and
14 Math::Symbolic::Constant objects.
15 EXPORT
17 None by default.
18
20 Method to_string
21 Default method for stringification just returns the object's value.
22 Method value
24 value() evaluates the Math::Symbolic tree to its numeric
25 representation.
26 value() without arguments requires that every variable in the tree
28 contains a defined value attribute. Please note that this refers to
29 every variable object, not just every named variable.
30 value() with one argument sets the object's value (in case of a
32 variable or constant).
33 value() with named arguments (key/value pairs) associates variables in
35 the tree with the value-arguments if the corresponging key matches the
36 variable name. (Can one say this any more complicated?) Since version
37 0.132, an alternative syntax is to pass a single hash reference.
38 Example: $tree->value(x => 1, y => 2, z => 3, t => 0) assigns the value
40 1 to any occurrances of variables of the name "x", aso.
41 If a variable in the tree has no value set (and no argument of value
43 sets it temporarily), the call to value() returns undef.
44 Method signature
46 signature() returns a tree's signature.
47 In the context of Math::Symbolic, signatures are the list of variables
49 any given tree depends on. That means the tree "v*t+x" depends on the
50 variables v, t, and x. Thus, applying signature() on the tree that
51 would be parsed from above example yields the sorted list ('t', 'v',
52 'x').
53 Constants do not depend on any variables and therefore return the empty
55 list. Obviously, operators' dependencies vary.
56 Math::Symbolic::Variable objects, however, may have a slightly more
58 involved signature. By convention, Math::Symbolic variables depend on
59 themselves. That means their signature contains their own name. But
60 they can also depend on various other variables because variables
61 themselves can be viewed as placeholders for more compicated terms. For
62 example in mechanics, the acceleration of a particle depends on its
63 mass and the sum of all forces acting on it. So the variable
64 'acceleration' would have the signature ('acceleration', 'force1',
65 'force2',..., 'mass', 'time').
66 If you're just looking for a list of the names of all variables in the
68 tree, you should use the explicit_signature() method instead.
69 Method explicit_signature
71 explicit_signature() returns a lexicographically sorted list of
72 variable names in the tree.
73 See also: signature().
75 Method set_signature
77 set_signature expects any number of variable identifiers as arguments.
78 It sets a variable's signature to this list of identifiers.
79 Method implement
81 implement() works in-place!
82 Takes key/value pairs as arguments. The keys are to be variable names
84 and the values must be valid Math::Symbolic trees. All occurrances of
85 the variables will be replaced with their implementation.
86 Method replace
88 First argument must be a valid Math::Symbolic tree.
89 replace() modifies the object it is called on in-place in that it
91 replaces it with its first argument. Doing that, it retains the
92 original object reference. This destroys the object it is called on.
93 However, this also means that you can create recursive trees of objects
95 if the new tree is to contain the old tree. So make sure you clone the
96 old tree using the new() method before using it in the replacement tree
97 or you will end up with a program that eats your memory fast.
98 fill_in_vars
100 This method returns a modified copy of the tree it was called on.
101 It walks the tree and replaces all variables whose value attribute is
103 defined (either done at the time of object creation or using
104 set_value()) with the corresponding constant objects. Variables whose
105 value is not defined are unaffected. Take, for example, the following
106 code:
107 $tree = parse_from_string('a*b+a*c');
109 $tree->set_value(a => 4, c => 10); # value of b still not defined.
110 print $tree->fill_in_vars();
111 # prints "(4 * b) + (4 * 10)"
112 Method simplify
114 Minimum method for term simpilification just clones.
115 Method descending_operands
117 When called on an operator, descending_operands tries hard to determine
118 which operands to descend into. (Which usually means all operands.) A
119 list of these is returned.
120 When called on a constant or a variable, it returns the empty list.
122 Of course, some routines may have to descend into different branches of
124 the Math::Symbolic tree, but this routine returns the default operands.
125 The first argument to this method may control its behaviour. If it is
127 any of the following key-words, behaviour is modified accordingly:
128 default -- obvious. Use default heuristics.
130 These are all supersets of 'default':
132 all -- returns ALL operands. Use with caution.
133 all_vars -- returns all operands that may contain vars.
134 Method descend
136 The method takes named arguments (key/value pairs). descend() descends
137 (Who would have guessed?) into the Math::Symbolic tree recursively and
138 for each node, it calls code references with a copy of the current node
139 as argument. The copy may be modified and will be used for construction
140 of the returned tree. The automatic copying behaviour may be turned
141 off.
142 Returns a (modified) copy of the original tree. If in-place
144 modification is turned on, the returned tree will not be a copy.
145 Available parameters are:
147 before
149 A code reference to be used as a callback that will be invoked before
150 descent. Depending on whether or not the "in_place" option is set,
151 the callback will be passed a copy of the current node (default) or
152 the original node itself.
153 The callback may modify the tree node and the modified node will be
155 used to construct descend()'s return value.
156 The return value of this callback describes the way descend() handles
158 the descent into the current node's operands.
159 If it returns the empty list, the (possibly modified) copy of the
161 current that was passed to the callback is used as the return value
162 of descend(), but the recursive descent is continued for all of the
163 current node's operands which may or may not be modified by the
164 callback. The "after" callback will be called on the node after
165 descent into the operands. (This is the normal behavior.)
166 If the callback returns undef, the descent is stopped for the current
168 branch and an exact copy of the current branch's children will be
169 used for descend()'s return value. The "after" callback will be
170 called immediately.
171 If the callback returns a list of integers, these numbers are assumed
173 to be the indexes of the current node's operands that are to be
174 descended into. That means if the callback returns (1), descend will
175 be called for the second operand and only the second. All other
176 children/operands will be cloned. As usual, the "after" callback
177 will be called after descent.
178 Any other return lists will lead to hard-to-debug errors. Tough luck.
180 Returning a hash reference from the callback allows for complete
182 control over the descend() routine. The hash may contain the
183 following elements:
184 operands
186 This is a referenced array that will be put in place of the
187 previous operands. It is the callback's job to make sure the number
188 of operands stays correct. The "operands" entry is evaluated before
189 the "descend_into" entry.
190 descend_into
192 This is a referenced array of integers and references. The integers
193 are assumed to be indices of the array of operands. Returning (1)
194 results in descent into the second operand and only the second.
195 References are assumed to be operands to descend into. descend()
197 will be directly called on them.
198 If the array is empty, descend() will act just as if an empty list
200 had been returned.
201 in_place
203 Boolean indicating whether or not to modify the operands in-place
204 or not. If this is true, descend() will be called with the
205 "in_place => 1" parameter. If false, it will be called with
206 "in_place => 0" instead. Defaults to false. (Cloning)
207 This does not affect the call to the "after" callback but only the
209 descent into operands.
210 skip_after
212 If this option exists and is set to true, the "after" callback will
213 not be invoked. This only applies to the current node, not to its
214 children/operands.
215 The list of options may grow in future versions.
217 after
219 This is a code reference which will be invoked as a callback after
220 the descent into the operands.
221 in_place
223 Controls whether or not to modify the current tree node in-place.
224 Defaults to false - cloning.
225 operand_finder
227 This option controls how the descend routine chooses which operands
228 to recurse into by default. That means it controls which operands
229 descend() recurses into if the 'before' routine returned the empty
230 list or if no 'before' routine was specified.
231 The option may either be a code reference or a string. If it is a
233 code reference, this code reference will be called with the current
234 node as argument. If it is a string, the method with that name will
235 be called on the current node object.
236 By default, descend() calls the 'descending_operands()' method on the
238 current node to determine the operands to descend into.
239 Method term_type
241 Returns the type of the term. This is a stub to be overridden.
242 Method set_value
244 set_value() returns the tree it modifies, but acts in-place on the
245 Math::Symbolic tree it was called on.
246 set_value() requires named arguments (key/value pairs) that associate
248 variable names of variables in the tree with the value-arguments if the
249 corresponging key matches the variable name. (Can one say this any
250 more complicated?) Since version 0.132, an alternative syntax is to
251 pass a single hash reference to the method.
252 Example: $tree->set_value(x => 1, y => 2, z => 3, t => 0) assigns the
254 value 1 to any occurrances of variables of the name "x", aso.
255 As opposed to value(), set_value() assigns to the variables permanently
257 and does not evaluate the tree.
258 When called on constants, set_value() sets their value to its first
260 argument, but only if there is only one argument.
261
263 Please send feedback, bug reports, and support requests to the
264 Math::Symbolic support mailing list: math-symbolic-support at lists dot
265 sourceforge dot net. Please consider letting us know how you use
266 Math::Symbolic. Thank you.
267 If you're interested in helping with the development or extending the
269 module's functionality, please contact the developers' mailing list:
270 math-symbolic-develop at lists dot sourceforge dot net.
271 List of contributors:
273 Steffen Mueller, symbolic-module at steffen-mueller dot net
275 Stray Toaster, mwk at users dot sourceforge dot net
276 Oliver Ebenhoeh
277
279 New versions of this module can be found on http://steffen-mueller.net
280 or CPAN. The module development takes place on Sourceforge at
281 http://sourceforge.net/projects/math-symbolic/
282 Math::Symbolic
284perl v5.34.0 2022-01-21 Math::Symbolic::Base(3)