Print a warning when translating subscripted functions
[maxima.git] / doc / info / to_poly_solve.texi
blob223c104339d7a78651ab808a55703754f060e6fa
1 @menu
2 * Functions and Variables for to_poly_solve::
3 @end menu
5 @node Functions and Variables for to_poly_solve,  , to_poly_solve-pkg, to_poly_solve-pkg
6 @section Functions and Variables for to_poly_solve
8 The packages @code{to_poly} and @code{to_poly_solve} are experimental;
9 the specifications of the functions in these packages might change or
10 the some of the functions in these packages might be merged into other
11 Maxima functions.
13 Barton Willis (Professor of Mathematics, University of Nebraska at
14 Kearney) wrote the @code{to_poly} and @code{to_poly_solve} packages and the
15 English language user documentation for these packages.
17 @deffn {Operator} %and
18 @ifinfo
19 @fnindex Logical conjunction
20 @end ifinfo
22 The operator @code{%and} is a simplifying nonshort-circuited logical
23 conjunction.  Maxima simplifies an @code{%and} expression to either true,
24 false, or a logically equivalent, but simplified, expression.  The
25 operator @code{%and} is associative, commutative, and idempotent.  Thus
26 when @code{%and} returns a noun form, the arguments of @code{%and} form
27 a non-redundant sorted list; for example
29 @example
30 (%i1) a %and (a %and b);
31 (%o1)                       a %and b
32 @end example
34 If one argument to a conjunction is the @i{explicit} the negation of another
35 argument, @code{%and} returns false:
37 @example
38 (%i2) a %and (not a);
39 (%o2)                         false
40 @end example
42 If any member of the conjunction is false, the conjunction simplifies
43 to false even if other members are manifestly non-boolean; for example
45 @example
46 (%i3) 42 %and false;
47 (%o3)                         false
48 @end example
50 Any argument of an @code{%and} expression that is an inequation (that
51 is, an inequality or equation), is simplified using the Fourier
52 elimination package.  The Fourier elimination simplifier has a
53 pre-processor that converts some, but not all, nonlinear inequations
54 into linear inequations; for example the Fourier elimination code
55 simplifies @code{abs(x) + 1 > 0} to true, so
57 @example
58 (%i4) (x < 1) %and (abs(x) + 1 > 0);
59 (%o4)                         x < 1
60 @end example
62 @b{Notes}  
63 @itemize @bullet
64 @item The option variable @code{prederror} does @i{not} alter the
65 simplification @code{%and} expressions.
67 @item To avoid operator precedence errors, compound expressions
68 involving the operators @code{%and, %or}, and @code{not} should be
69 fully parenthesized.
71 @item The Maxima operators @code{and} and @code{or} are both
72 short-circuited.  Thus @code{and} isn't associative or commutative.
74 @end itemize
76 @b{Limitations} The conjunction @code{%and} simplifies inequations
77 @i{locally, not globally}.  This means that conjunctions such as
79 @example
80 (%i5) (x < 1) %and (x > 1);
81 (%o5)                 (x > 1) %and (x < 1)
82 @end example
84 do @i{not} simplify to false.  Also, the Fourier elimination code @i{ignores}
85 the fact database;
87 @example
88 (%i6) assume(x > 5);
89 (%o6)                        [x > 5]
90 (%i7) (x > 1) %and (x > 2);
91 (%o7)                 (x > 1) %and (x > 2)
92 @end example
94 Finally, nonlinear inequations that aren't easily converted into an
95 equivalent linear inequation aren't simplified.
97 There is no support for distributing @code{%and} over @code{%or};
98 neither is there support for distributing a logical negation over
99 @code{%and}.
101 @b{To use} @code{load("to_poly_solve")}
103 @b{Related functions} @code{%or, %if, and, or, not}
105 @b{Status} The operator @code{%and} is experimental; the
106 specifications of this function might change and its functionality
107 might be merged into other Maxima functions.
109 @end deffn
111 @deffn {Operator} %if (@var{bool}, @var{a}, @var{b})
112 @ifinfo
113 @fnindex conditional evaluation
114 @end ifinfo
116 The operator @code{%if} is a simplifying conditional.  The
117 @i{conditional} @var{bool} should be boolean-valued.  When the
118 conditional is true, return the second argument; when the conditional is
119 false, return the third; in all other cases, return a noun form.
121 Maxima inequations (either an inequality or an equality) are @i{not}
122 boolean-valued; for example, Maxima does @i{not} simplify @math{5 < 6}
123 to true, and it does not simplify @math{5 = 6} to false; however, in
124 the context of a conditional to an @code{%if} statement, Maxima
125 @i{automatically} attempts to determine the truth value of an
126 inequation.  Examples:
128 @example
129 (%i1) f : %if(x # 1, 2, 8);
130 (%o1)                 %if(x - 1 # 0, 2, 8)
131 (%i2) [subst(x = -1,f), subst(x=1,f)];
132 (%o2)                        [2, 8]
133 @end example
135 If the conditional involves an inequation, Maxima simplifies it using
136 the Fourier elimination package.
138 @b{Notes} 
140 @itemize @bullet
141 @item If the conditional is manifestly non-boolean, Maxima returns a noun form:
142 @end itemize
144 @example
145 (%i3) %if(42,1,2);
146 (%o3)                     %if(42, 1, 2)
147 @end example
149 @itemize @bullet
150 @item The Maxima operator @code{if} is nary, the operator @code{%if} @i{isn't}
151 nary.
152 @end itemize
154 @b{Limitations} The Fourier elimination code only simplifies nonlinear
155 inequations that are readily convertible to an equivalent linear
156 inequation.
158 @b{To use:} @code{load("to_poly_solve")}
160 @b{Status:} The operator @code{%if} is experimental; its
161 specifications might change and its functionality might be merged into
162 other Maxima functions.
164 @end deffn
165   
166 @deffn {Operator} %or
167 @ifinfo
168 @fnindex Logical disjunction
169 @end ifinfo
171 The operator @code{%or} is a simplifying nonshort-circuited logical
172 disjunction.  Maxima simplifies an @code{%or} expression to either
173 true, false, or a logically equivalent, but simplified,
174 expression.  The operator @code{%or} is associative, commutative, and
175 idempotent.  Thus when @code{%or} returns a noun form, the arguments
176 of @code{%or} form a non-redundant sorted list; for example
178 @example
179 (%i1) a %or (a %or b);
180 (%o1)                        a %or b
181 @end example
183 If one member of the disjunction is the @i{explicit} the negation of another
184 member, @code{%or} returns true:
186 @example
187 (%i2) a %or (not a);
188 (%o2)                         true
189 @end example
191 If any member of the disjunction is true, the disjunction simplifies
192 to true even if other members of the disjunction are manifestly non-boolean;
193 for example
195 @example
196 (%i3) 42 %or true;
197 (%o3)                         true
198 @end example
200 Any argument of an @code{%or} expression that is an inequation (that
201 is, an inequality or equation), is simplified using the Fourier
202 elimination package.  The Fourier elimination code simplifies
203 @code{abs(x) + 1 > 0} to true, so we have
205 @example
206 (%i4) (x < 1) %or (abs(x) + 1 > 0);
207 (%o4)                         true
208 @end example
210 @b{Notes}  
211 @itemize @bullet
212 @item The option variable @code{prederror} does @i{not} alter the 
213 simplification of @code{%or} expressions.
215 @item You should parenthesize compound expressions involving the
216 operators @code{%and, %or}, and @code{not}; the binding powers of these
217 operators might not match your expectations.
219 @item The Maxima operators @code{and} and @code{or} are both short-circuited.
220 Thus @code{or} isn't associative or commutative.
222 @end itemize
224 @b{Limitations} The conjunction @code{%or} simplifies inequations
225 @i{locally, not globally}.  This means that conjunctions such as
227 @c TODO: IN MAXIMA 5.24POST THIS SIMPLIFIES TO TRUE.
229 @example
230 (%i1) (x < 1) %or (x >= 1);
231 (%o1) (x > 1) %or (x >= 1)
232 @end example
234 do @i{not} simplify to true.  Further, the Fourier elimination code ignores
235 the fact database;
237 @example
238 (%i2) assume(x > 5);
239 (%o2)                        [x > 5]
240 (%i3) (x > 1) %and (x > 2);
241 (%o3)                 (x > 1) %and (x > 2)
242 @end example
244 Finally, nonlinear inequations that aren't easily converted into an
245 equivalent linear inequation aren't simplified.
247 The algorithm that looks for terms that cannot both be false is weak;
248 also there is no support for distributing @code{%or} over @code{%and};
249 neither is there support for distributing a logical negation over
250 @code{%or}.
252 @b{To use} @code{load("to_poly_solve")}
254 @b{Related functions} @code{%or, %if, and, or, not}
256 @b{Status} The operator @code{%or} is experimental; the
257 specifications of this function might change and its functionality
258 might be merged into other Maxima functions.
260 @end deffn
262 @anchor{complex_number_p}
263 @deffn {Function} complex_number_p (@var{x})
265 The predicate @code{complex_number_p} returns true if its argument is
266 either @code{a + %i * b}, @code{a}, @code{%i b}, or @code{%i},
267 where @code{a} and @code{b} are either rational or floating point
268 numbers (including big floating point); for all other inputs,
269 @code{complex_number_p} returns false; for example
271 @example
272 (%i1) map('complex_number_p,[2/3, 2 + 1.5 * %i, %i]);
273 (%o1)                  [true, true, true]
274 (%i2) complex_number_p((2+%i)/(5-%i));
275 (%o2)                         false
276 (%i3) complex_number_p(cos(5 - 2 * %i));
277 (%o3)                         false
278 @end example
280 @b{Related functions} @code{isreal_p}
282 @b{To use} @code{load("to_poly_solve")}
284 @b{Status} The operator @code{complex_number_p} is experimental; its
285 specifications might change and its functionality might be merged into
286 other Maxima functions.
288 @end deffn
290 @anchor{compose_functions}
291 @deffn {Function} compose_functions (@var{l})
293 The function call @code{compose_functions(l)} returns a lambda form that is
294 the @i{composition} of the functions in the list @var{l}.  The functions are
295 applied from @i{right} to @i{left}; for example
297 @example
298 (%i1) compose_functions([cos, exp]);
299                                         %g151
300 (%o1)             lambda([%g151], cos(%e     ))
301 (%i2) %(x);
302                                   x
303 (%o2)                       cos(%e )
304 @end example
306 When the function list is empty, return the identity function:
308 @example
309 (%i3) compose_functions([]);
310 (%o3)                lambda([%g152], %g152)
311 (%i4)  %(x);
312 (%o4)                           x
313 @end example
315 @b{Notes} 
316 @itemize @bullet
317 @item When Maxima determines that a list member isn't a symbol or
318 a lambda form, @code{funmake} (@i{not} @code{compose_functions})
319 signals an error:
320 @end itemize
322 @example
323 (%i5) compose_functions([a < b]);
325 funmake: first argument must be a symbol, subscripted symbol,
326 string, or lambda expression; found: a < b
327 #0: compose_functions(l=[a < b])(to_poly_solve.mac line 40)
328  -- an error. To debug this try: debugmode(true);
329 @end example
331 @itemize @bullet
332 @item To avoid name conflicts, the independent variable is determined by the
333 function @code{new_variable}.
335 @example
336 (%i6) compose_functions([%g0]);
337 (%o6)              lambda([%g154], %g0(%g154))
338 (%i7) compose_functions([%g0]);
339 (%o7)              lambda([%g155], %g0(%g155))
340 @end example
342 Although the independent variables are different, Maxima is able to to
343 deduce that these lambda forms are semantically equal:
345 @example
346 (%i8) is(equal(%o6,%o7));
347 (%o8)                         true
348 @end example
349 @end itemize
351 @b{To use} @code{load("to_poly_solve")}
353 @b{Status}  The function @code{compose_functions} is experimental; its
354 specifications might change and its functionality might be merged into
355 other Maxima functions.
356 @end deffn
358 @anchor{dfloat}
359 @deffn {Function} dfloat (@var{x})
361 The function @code{dfloat} is a similar to @code{float}, but the function
362 @code{dfloat} applies @code{rectform} when @code{float} fails to evaluate
363 to an IEEE double floating point number; thus
365 @example
366 (%i1) float(4.5^(1 + %i));
367                                %i + 1
368 (%o1)                       4.5
369 (%i2) dfloat(4.5^(1 + %i));
370 (%o2)        4.48998802962884 %i + .3000124893895671
371 @end example
373 @b{Notes} 
375 @itemize @bullet
376 @item The rectangular form of an expression might be poorly suited for
377 numerical evaluation--for example, the rectangular form might
378 needlessly involve the difference of floating point numbers
379 (subtractive cancellation).
382 @item The identifier @code{float} is both an option variable (default
383 value false) and a function name.
386 @end itemize
388 @b{Related functions} @code{float, bfloat}
390 @b{To use} @code{load("to_poly_solve")}
392 @b{Status} The function @code{dfloat} is experimental; its
393 specifications might change and its functionality might be merged into
394 other Maxima functions.
396 @end deffn
398 @anchor{elim}
399 @deffn {Function} elim (@var{l}, @var{x})
401 The function @code{elim} eliminates the variables in the set or list
402 @code{x} from the equations in the set or list @code{l}.  Each member
403 of @code{x} must be a symbol; the members of @code{l} can either be
404 equations, or expressions that are assumed to equal zero.
406 The function @code{elim} returns a list of two lists; the first is
407 the list of expressions with the variables eliminated; the second
408 is the list of pivots; thus, the second list is a list of
409 expressions that @code{elim} used to eliminate the variables.
411 Here is an example of eliminating between linear equations:
413 @example
414 (%i1) elim(set(x + y + z = 1, x - y  - z = 8, x - z = 1), 
415            set(x,y));
416 (%o1)            [[2 z - 7], [y + 7, z - x + 1]]
417 @end example
419 Eliminating @code{x} and @code{y} yields the single equation @code{2 z - 7 = 0};
420 the equations @code{y + 7 = 0} and @code{z - z + 1 = 1} were used as pivots.
421 Eliminating all three variables from these equations, triangularizes the linear
422 system:
424 @example
425 (%i2) elim(set(x + y + z = 1, x - y  - z = 8, x - z = 1),
426            set(x,y,z));
427 (%o2)           [[], [2 z - 7, y + 7, z - x + 1]]
428 @end example
430 Of course, the equations needn't be linear:
432 @example
433 (%i3) elim(set(x^2 - 2 * y^3 = 1,  x - y = 5), [x,y]);
434                      3    2
435 (%o3)       [[], [2 y  - y  - 10 y - 24, y - x + 5]]
436 @end example
438 The user doesn't control the order the variables are
439 eliminated.  Instead, the algorithm uses a heuristic to @i{attempt} to
440 choose the best pivot and the best elimination order.
442 @b{Notes} 
444 @itemize @bullet
445 @item Unlike the related function @code{eliminate}, the function
446 @code{elim} does @i{not} invoke @code{solve} when the number of equations
447 equals the number of variables.
449 @item The function @code{elim} works by applying resultants; the option
450 variable @code{resultant} determines which algorithm Maxima
451 uses.  Using @code{sqfr}, Maxima factors each resultant and suppresses
452 multiple zeros.
454 @item The @code{elim} will triangularize a nonlinear set of polynomial
455 equations; the solution set of the triangularized set @i{can} be larger
456 than that solution set of the untriangularized set.  Thus, the triangularized
457 equations can have @i{spurious} solutions.
458 @end itemize
460 @b{Related functions} @i{elim_allbut, eliminate_using, eliminate}
462 @b{Option variables} @i{resultant}
464 @b{To use} @code{load("to_poly")}
466 @b{Status} The function @code{elim} is experimental; its
467 specifications might change and its functionality might be merged into
468 other Maxima functions.
470 @end deffn
472 @anchor{elim_allbut}
473 @deffn {Function} elim_allbut (@var{l}, @var{x})
475 This function is similar to @code{elim}, except that it eliminates all the
476 variables in the list of equations @code{l} @i{except} for those variables that
477 in in the list @code{x}
479 @example
480 (%i1) elim_allbut([x+y = 1, x - 5*y = 1],[]);
481 (%o1)                 [[], [y, y + x - 1]]
482 (%i2) elim_allbut([x+y = 1, x - 5*y = 1],[x]);
483 (%o2)                [[x - 1], [y + x - 1]]
484 @end example
486 @b{To use} @code{load("to_poly")}
488 @b{Option variables} @i{resultant}
490 @b{Related functions} @i{elim, eliminate_using, eliminate}
492 @b{Status} The function @code{elim_allbut} is experimental; its
493 specifications might change and its functionality might be merged into
494 other Maxima functions.
496 @end deffn
498 @anchor{eliminate_using}
499 @deffn {Function} eliminate_using (@var{l}, @var{e}, @var{x})
501 Using @code{e} as the pivot, eliminate the symbol @code{x} from the
502 list or set of equations in @code{l}.  The function @code{eliminate_using}
503 returns a set.
505 @example
506 (%i1) eq : [x^2 - y^2 - z^3 , x*y - z^2 - 5, x - y + z];
507                3    2    2     2
508 (%o1)      [- z  - y  + x , - z  + x y - 5, z - y + x]
509 (%i2) eliminate_using(eq,first(eq),z);
510         3              2      2      3    2
511 (%o2) @{y  + (1 - 3 x) y  + 3 x  y - x  - x , 
512                         4    3  3       2  2             4
513                        y  - x  y  + 13 x  y  - 75 x y + x  + 125@}
514 (%i3) eliminate_using(eq,second(eq),z);
515         2            2       4    3  3       2  2             4
516 (%o3) @{y  - 3 x y + x  + 5, y  - x  y  + 13 x  y  - 75 x y + x
517                                                            + 125@}
518 (%i4) eliminate_using(eq, third(eq),z);
519         2            2       3              2      2      3    2
520 (%o4) @{y  - 3 x y + x  + 5, y  + (1 - 3 x) y  + 3 x  y - x  - x @}
521 @end example
523 @b{Option variables} @i{resultant}
525 @b{Related functions} @i{elim, eliminate, elim_allbut}
527 @b{To use} @code{load("to_poly")}
529 @b{Status} The function @code{eliminate_using} is experimental; its
530 specifications might change and its functionality might be merged into
531 other Maxima functions.
533 @end deffn
535 @anchor{fourier_elim}
536 @deffn {Function} fourier_elim ([@var{eq1}, @var{eq2}, @dots{}], [@var{var1}, @var{var}, @dots{}])
538 Fourier elimination is the analog of Gauss elimination for linear inequations
539 (equations or inequalities).  The function call @code{fourier_elim([eq1, eq2,
540 ...], [var1, var2, ...])} does Fourier elimination on a list of linear
541 inequations @code{[eq1, eq2, ...]} with respect to the variables
542 @code{[var1, var2, ...]}; for example
544 @example
545 (%i1) fourier_elim([y-x < 5, x - y < 7, 10 < y],[x,y]);
546 (%o1)            [y - 5 < x, x < y + 7, 10 < y]
547 (%i2) fourier_elim([y-x < 5, x - y < 7, 10 < y],[y,x]);
548 (%o2)        [max(10, x - 7) < y, y < x + 5, 5 < x]
549 @end example
551 Eliminating first with respect to @math{x} and second with respect to
552 @math{y} yields lower and upper bounds for @math{x} that depend on
553 @math{y}, and lower and upper bounds for @math{y} that are numbers.
554 Eliminating in the other order gives @math{x} dependent lower and
555 upper bounds for @math{y}, and numerical lower and upper bounds for
556 @math{x}.
558 When necessary, @code{fourier_elim} returns a @emph{disjunction} of lists of
559 inequations:
561 @example
562 (%i3) fourier_elim([x # 6],[x]);
563 (%o3)                  [x < 6] or [6 < x]
564 @end example
566 When the solution set is empty,  @code{fourier_elim} returns @code{emptyset},
567 and when the solution set is all reals, @code{fourier_elim} returns @code{universalset};
568 for example
570 @example
571 (%i4) fourier_elim([x < 1, x > 1],[x]);
572 (%o4)                       emptyset
573 (%i5) fourier_elim([minf < x, x < inf],[x]);
574 (%o5)                     universalset
575 @end example
577 For nonlinear inequations, @code{fourier_elim} returns a (somewhat) 
578 simplified list of inequations:
580 @example
581 (%i6) fourier_elim([x^3 - 1 > 0],[x]);
582 @group
583                2                             2
584 (%o6) [1 < x, x  + x + 1 > 0] or [x < 1, - (x  + x + 1) > 0]
585 @end group
586 (%i7) fourier_elim([cos(x) < 1/2],[x]);
587 (%o7)                  [1 - 2 cos(x) > 0]
588 @end example
590 Instead of a list of inequations, the first argument to @code{fourier_elim}
591 may be a logical disjunction or conjunction:
593 @example
594 (%i8) fourier_elim((x + y < 5) and (x - y >8),[x,y]);
595                                               3
596 (%o8)            [y + 8 < x, x < 5 - y, y < - -]
597                                               2
598 (%i9) fourier_elim(((x + y < 5) and x < 1) or  (x - y >8),[x,y]);
599 (%o9)          [y + 8 < x] or [x < min(1, 5 - y)]
600 @end example
602 The function @code{fourier_elim} supports the inequation operators 
603 @code{<, <=, >, >=, #}, and @code{=}.
605 The Fourier elimination code has a preprocessor that converts some
606 nonlinear inequations that involve the absolute value, minimum, and
607 maximum functions into linear in equations.  Additionally, the preprocessor
608 handles some expressions that are the product or quotient of linear terms:
610 @example
611 (%i10) fourier_elim([max(x,y) > 6, x # 8, abs(y-1) > 12],[x,y]);
612 (%o10) [6 < x, x < 8, y < - 11] or [8 < x, y < - 11]
613  or [x < 8, 13 < y] or [x = y, 13 < y] or [8 < x, x < y, 13 < y]
614  or [y < x, 13 < y]
615 (%i11) fourier_elim([(x+6)/(x-9) <= 6],[x]);
616 (%o11)           [x = 12] or [12 < x] or [x < 9]
617 (%i12) fourier_elim([x^2 - 1 # 0],[x]);
618 (%o12)      [- 1 < x, x < 1] or [1 < x] or [x < - 1]
619 @end example
621 @b{To use} @code{load("fourier_elim")}
623 @end deffn
625 @anchor{isreal_p}
626 @deffn {Function} isreal_p (@var{e})
628 The predicate @code{isreal_p} returns true when Maxima is able to
629 determine that @code{e} is real-valued on the @i{entire} real line; it
630 returns false when Maxima is able to determine that @code{e} @i{isn't}
631 real-valued on some nonempty subset of the real line; and it returns a
632 noun form for all other cases.
634 @example
635 (%i1) map('isreal_p, [-1, 0, %i, %pi]);
636 (%o1)               [true, true, false, true]
637 @end example
639 Maxima variables are assumed to be real; thus
641 @example
642 (%i2) isreal_p(x);
643 (%o2)                         true
644 @end example
646 The function @code{isreal_p} examines the fact database:
648 @example
649 (%i3) declare(z,complex)$
651 (%i4) isreal_p(z);
652 (%o4)                      isreal_p(z)
653 @end example
655 @b{Limitations}
656 Too often, @code{isreal_p} returns a noun form when it should be able
657 to return false; a simple example: the logarithm function isn't
658 real-valued on the entire real line, so @code{isreal_p(log(x))} should
659 return false; however
661 @example
662 (%i5) isreal_p(log(x));
663 (%o5)                   isreal_p(log(x))
664 @end example
666 @b{To use} @code{load("to_poly_solve")}
668 @b{Related functions} @i{complex_number_p}
670 @b{Status} The function @code{isreal_p} is experimental; its
671 specifications might change and its functionality might be merged into
672 other Maxima functions.
673 @end deffn
676 @anchor{new_variable}
677 @deffn {Function} new_variable (type)
679 Return a unique symbol of the form @code{%[z,n,r,c,g]k}, where
680 @code{k} is an integer.  The allowed values for @math{type} are
681 @i{integer, natural_number, real, complex,} and @i{general}.
682 (By natural number, we mean the @i{nonnegative integers}; thus zero is
683 a natural number.  Some, but not all, definitions of natural number
684 @i{exclude} zero.)
686 When @math{type} isn't one of the allowed values, @math{type} defaults
687 to @math{general}.  For integers, natural numbers, and complex numbers,
688 Maxima automatically appends this information to the fact database.
690 @example
691 (%i1) map('new_variable,
692           ['integer, 'natural_number, 'real, 'complex, 'general]);
693 (%o1)          [%z144, %n145, %r146, %c147, %g148]
694 (%i2) nicedummies(%);
695 (%o2)               [%z0, %n0, %r0, %c0, %g0]
696 (%i3) featurep(%z0, 'integer);
697 (%o3)                         true
698 (%i4) featurep(%n0, 'integer);
699 (%o4)                         true
700 (%i5) is(%n0 >= 0);
701 (%o5)                         true
702 (%i6) featurep(%c0, 'complex);
703 (%o6)                         true
704 @end example
706 @b{Note} Generally, the argument to @code{new_variable} should be quoted.  The quote
707 will protect against errors similar to
709 @example
710 (%i7) integer : 12$
712 (%i8) new_variable(integer);
713 (%o8)                         %g149
714 (%i9) new_variable('integer);
715 (%o9)                         %z150
716 @end example
718 @b{Related functions} @i{nicedummies}
720 @b{To use} @code{load("to_poly_solve")}
722 @b{Status} The function @code{new_variable} is experimental; its
723 specifications might change and its functionality might be merged into
724 other Maxima functions.
726 @end deffn
728 @anchor{nicedummies}
729 @deffn {Function} nicedummies
731 Starting with zero, the function @code{nicedummies} re-indexes the variables 
732 in an expression that were introduced by @code{new_variable};
734 @example
735 (%i1) new_variable('integer) + 52 * new_variable('integer);
736 (%o1)                   52 %z136 + %z135
737 (%i2) new_variable('integer) - new_variable('integer);
738 (%o2)                     %z137 - %z138
739 (%i3) nicedummies(%);
740 (%o3)                       %z0 - %z1
741 @end example
743 @b{Related functions} @i{new_variable}
745 @b{To use} @code{load("to_poly_solve")}
747 @b{Status} The function @code{nicedummies} is experimental; its
748 specifications might change and its functionality might be merged into
749 other Maxima functions.
751 @end deffn
753 @deffn {Function} parg (@var{x})
755 The function @code{parg} is a simplifying version of the complex argument function 
756 @code{carg}; thus
758 @example
759 (%i1) map('parg,[1,1+%i,%i, -1 + %i, -1]);
760                         %pi  %pi  3 %pi
761 (%o1)               [0, ---, ---, -----, %pi]
762                          4    2     4
763 @end example
765 Generally, for a non-constant input, @code{parg} returns a noun form; thus
767 @example
768 (%i2) parg(x + %i * sqrt(x));
769 (%o2)                 parg(x + %i sqrt(x))
770 @end example
772 When @code{sign} can determine that the input is a positive or negative real
773 number, @code{parg} will return a non-noun form for a non-constant input.
774 Here are two examples:
776 @c TODO: THE FIRST RESULT IS A NOUNFORM IN MAXIMA 5.24POST
778 @example
779 (%i3) parg(abs(x));
780 (%o3) 0
781 (%i4) parg(-x^2-1);
782 (%o4)                          %pi
783 @end example
785 @b{Note} The @code{sign} function mostly ignores the variables that are declared
786 to be complex (@code{declare(x,complex)}); for variables that are declared
787 to be complex, the @code{parg} can return incorrect values; for example
789 @c TODO: IN MAXIMA 5.24POST THE RESULT IS A NOUNFORM.
791 @example
792 (%i1) declare(x,complex)$
794 (%i2) parg(x^2 + 1);
795 (%o2) 0
796 @end example
798 @b{Related function} @i{carg, isreal_p}
800 @b{To use} @code{load("to_poly_solve")}
802 @b{Status} The function @code{parg} is experimental; its
803 specifications might change and its functionality might be merged into
804 other Maxima functions.
806 @end deffn
808 @anchor{real_imagpart_to_conjugate}
809 @deffn {Function} real_imagpart_to_conjugate (@var{e})
811 The function @code{real_imagpart_to_conjugate} replaces all occurrences
812 of @code{realpart} and @code{imagpart} to algebraically equivalent expressions
813 involving the @code{conjugate}.
815 @example
816 (%i1) declare(x, complex)$
818 (%i2) real_imagpart_to_conjugate(realpart(x) +  imagpart(x) = 3);
819           conjugate(x) + x   %i (x - conjugate(x))
820 (%o2)     ---------------- - --------------------- = 3
821                  2                     2
822 @end example
824 @b{To use} @code{load("to_poly_solve")}
826 @b{Status} The function @code{real_imagpart_to_conjugate} is experimental; its
827 specifications might change and its functionality might be merged into
828 other Maxima functions.
830 @end deffn
832 @anchor{rectform_log_if_constant}
833 @deffn {Function} rectform_log_if_constant (@var{e})
835 The function @code{rectform_log_if_constant} converts all terms of the form
836 @code{ log(c)} to  @code{rectform(log(c))}, where @code{c} is
837 either a declared constant expression or explicitly declared constant
839 @example
840 (%i1) rectform_log_if_constant(log(1-%i) - log(x - %i));
841                                  log(2)   %i %pi
842 (%o1)            - log(x - %i) + ------ - ------
843                                    2        4
844 (%i2) declare(a,constant, b,constant)$
846 (%i3) rectform_log_if_constant(log(a + %i*b));
847                        2    2
848                   log(b  + a )
849 (%o3)             ------------ + %i atan2(b, a)
850                        2
851 @end example
853 @b{To use} @code{load("to_poly_solve")}
855 @b{Status} The function @code{rectform_log_if_constant} is
856 experimental; the specifications of this function might change might change and its functionality
857 might be merged into other Maxima functions.
859 @end deffn
861 @anchor{simp_inequality}
862 @deffn {Function} simp_inequality (@var{e})
864 The function @code{simp_inequality} applies basic simplifications to inequations,
865 returning either a boolean value (true or false) or the original inequation.
867 The simplification rules used by @code{simp_inequality}
868 include some facts about the ranges of the absolute value, power,
869 and exponential functions along with some elementary algebra facts.
871 For conjunctions or disjunctions of inequations,
872 @code{simp_inequality} is applied to each individual inequation,
873 but no effort is made to simplify the entire logical expression.
875 Effectively, simp_inequality creates a new empty context,
876 so database facts are not used to simplify inequations.
878 @code{load("to_poly_solve")} loads this function.
880 Examples:
882 @example
883 (%i2) simp_inequality(1 # 0);
884 (%o2) true
885 @end example
887 @example
888 (%i3) simp_inequality(1 < 0);
889 (%o3) false
890 @end example
892 @example
893 (%i4) simp_inequality(a=a);
894 (%o4) true
895 @end example
897 @example
898 (%i5) simp_inequality(a # a);
899 (%o5) false
900 @end example
902 @example
903 (%i6) simp_inequality(a + 1 # a);
904 (%o6) true
905 @end example
907 @example
908 (%i7) simp_inequality(a < a+1);
909 (%o7) true
910 @end example
912 @example
913 (%i8) simp_inequality(abs(x) >= 0);
914 (%o8) true
915 @end example
917 @example
918 (%i9) simp_inequality(exp(x)  > 0);
919 (%o9) true
920 @end example
922 @example
923 (%i10) simp_inequality(x^2 >= 0);
924 (%o10) true
925 @end example
927 @example
928 (%i11) simp_inequality(2^x  # 0);
929 (%o11) true
930 @end example
932 @example
933 (%i12) simp_inequality(2^(x+1) > 2^x);
934 (%o12) true
935 @end example
937 The fact database is not consulted.
938 For example:
940 @example
941 (%i13) assume(xx > 0)$
942 (%i14) simp_inequality(xx > 0);
943 (%o14) xx>0
944 @end example
946 And finally, for conjunctions or disjunctions of inequations,
947 each inequation is simplified,
948 but no effort is made to simplify the entire logical expression;
949 for example:
951 @example
952 (%i15) simp_inequality((1 > 0) and (x < 0) and (x > 0));
953 (%o15) x<0 and x>0
954 @end example
956 @end deffn
958 @anchor{standardize_inverse_trig}
959 @deffn {Function} standardize_inverse_trig (@var{e})
961 This function applies the identities @code{cot(x) = atan(1/x),
962 acsc(x) = asin(1/x),} and similarly for @code{asec, acoth, acsch}
963 and @code{asech} to an expression.  See Abramowitz and Stegun, 
964 Eqs. 4.4.6 through 4.4.8 and 4.6.4 through 4.6.6.
966 @b{To use} @code{load("to_poly_solve")}
968 @b{Status} The function @code{standardize_inverse_trig} is experimental; its
969 specifications might change and its functionality might be merged into
970 other Maxima functions.
971 @end deffn
973 @anchor{subst_parallel}
974 @deffn {Function} subst_parallel (@var{l}, @var{e})
976 When @code{l} is a single equation or a list of equations, substitute
977 the right hand side of each equation for the left hand side.  The
978 substitutions are made in parallel; for example
980 @example
981 (%i1) load("to_poly_solve")$
983 (%i2) subst_parallel([x=y,y=x], [x,y]);
984 (%o2)                        [y, x]
985 @end example
987 Compare this to substitutions made serially:
989 @example
990 (%i3) subst([x=y,y=x],[x,y]);
991 (%o3)                        [x, x]
992 @end example
994 The function @code{subst_parallel} is similar to @code{sublis} except that
995 @code{subst_parallel} allows for substitution of nonatoms; for example
997 @example
998 (%i4) subst_parallel([x^2 = a, y = b], x^2 * y);
999 (%o4)                          a b
1000 (%i5) sublis([x^2 = a, y = b], x^2 * y);
1002                                                              2
1003 sublis: left-hand side of equation must be a symbol; found: x
1004  -- an error. To debug this try: debugmode(true);
1005 @end example
1007 The substitutions made by @code{subst_parallel} are literal, not semantic; thus 
1008 @code{subst_parallel} @i{does not} recognize that @math{x * y} is a subexpression 
1009 of @math{x^2 * y}
1011 @example
1012 (%i6) subst_parallel([x * y = a], x^2 * y);
1013                                2
1014 (%o6)                         x  y
1015 @end example
1017 The function @code{subst_parallel} completes all substitutions
1018 @i{before} simplifications.  This allows for substitutions into
1019 conditional expressions where errors might occur if the
1020 simplifications were made earlier:
1022 @example
1023 (%i7) subst_parallel([x = 0], %if(x < 1, 5, log(x)));
1024 (%o7)                           5
1025 (%i8) subst([x = 0], %if(x < 1, 5, log(x)));
1027 log: encountered log(0).
1028  -- an error. To debug this try: debugmode(true);
1029 @end example
1031 @b{Related functions} @i{subst, sublis, ratsubst}
1033 @b{To use} @code{load("to_poly_solve_extra.lisp")}
1035 @b{Status} The function @code{subst_parallel} is experimental; the
1036 specifications of this function might change might change and its
1037 functionality might be merged into other Maxima functions.
1039 @end deffn
1041 @anchor{to_poly}
1042 @deffn {Function} to_poly (@var{e}, @var{l})
1044 The function @code{to_poly} attempts to convert the equation @code{e}
1045 into a polynomial system along with inequality constraints; the
1046 solutions to the polynomial system that satisfy the constraints are
1047 solutions to the equation @code{e}.  Informally, @code{to_poly}
1048 attempts to polynomialize the equation @var{e}; an example might
1049 clarify:
1051 @example
1052 (%i1) load("to_poly_solve")$
1054 (%i2) to_poly(sqrt(x) = 3, [x]);
1055                             2
1056 (%o2) [[%g130 - 3, x = %g130 ], 
1057                       %pi                               %pi
1058                    [- --- < parg(%g130), parg(%g130) <= ---], []]
1059                        2                                 2
1060 @end example
1062 The conditions @code{-%pi/2<parg(%g130),parg(%g130)<=%pi/2} tell us that
1063 @code{%g130} is in the range of the square root function.  When this is
1064 true, the solution set to @code{sqrt(x) = 3} is the same as the
1065 solution set to @code{%g130-3,x=%g130^2}.
1067 To polynomialize trigonometric expressions, it is necessary to
1068 introduce a non algebraic substitution; these non algebraic substitutions
1069 are returned in the third list returned by @code{to_poly}; for example
1071 @example
1072 (%i3) to_poly(cos(x),[x]);
1073                 2                                 %i x
1074 (%o3)    [[%g131  + 1], [2 %g131 # 0], [%g131 = %e    ]]
1075 @end example
1077 Constant terms aren't polynomializied unless the number one is a member of
1078 the variable list; for example
1080 @example
1081 (%i4) to_poly(x = sqrt(5),[x]);
1082 (%o4)                [[x - sqrt(5)], [], []]
1083 (%i5) to_poly(x = sqrt(5),[1,x]);
1084                             2
1085 (%o5) [[x - %g132, 5 = %g132 ], 
1086                       %pi                               %pi
1087                    [- --- < parg(%g132), parg(%g132) <= ---], []]
1088                        2                                 2
1089 @end example
1091 To generate a polynomial with @math{sqrt(5) + sqrt(7)} as
1092 one of its roots, use the commands
1094 @example
1095 (%i6) first(elim_allbut(first(to_poly(x = sqrt(5) + sqrt(7),
1096                                       [1,x])), [x]));
1097                           4       2
1098 (%o6)                   [x  - 24 x  + 4]
1099 @end example
1101 @b{Related functions} @i{to_poly_solve}
1103 @b{To use} @code{load("to_poly")}
1105 @b{Status:} The function @code{to_poly} is experimental; its
1106 specifications might change and its functionality might be merged into
1107 other Maxima functions.
1109 @end deffn
1111 @deffn {Function} to_poly_solve (@var{e}, @var{l}, [options])
1113 The function @code{to_poly_solve} tries to solve the equations @math{e}
1114 for the variables @math{l}.  The equation(s) @math{e} can either be a
1115 single expression or a set or list of expressions; similarly, @math{l}
1116 can either be a single symbol or a list of set of symbols.  When
1117 a member of @math{e} isn't explicitly an equation, for example @math{x^2 -1},
1118 the solver assumes that the expression vanishes.
1120 The basic strategy of @code{to_poly_solve} is to convert the input into a polynomial form and to 
1121 call @code{algsys} on the polynomial system. Internally  @code{to_poly_solve} defaults @code{algexact} 
1122 to true. To change the default for @code{algexact}, append 'algexact=false to the @code{to_poly_solve} 
1123 argument list.
1125 When @code{to_poly_solve} is able to determine the solution set, each
1126 member of the solution set is a list in a @code{%union} object:
1128 @example
1129 (%i1) load("to_poly_solve")$
1131 (%i2) to_poly_solve(x*(x-1) = 0, x);
1132 (%o2)               %union([x = 0], [x = 1])
1133 @end example
1135 When  @code{to_poly_solve} is @i{unable} to determine the solution set, a
1136 @code{%solve} nounform is returned (in this case, a warning is printed)
1138 @example
1139 (%i3) to_poly_solve(x^k + 2* x + 1 = 0, x);
1141 Nonalgebraic argument given to 'to_poly'
1142 unable to solve
1143                           k
1144 (%o3)            %solve([x  + 2 x + 1 = 0], [x])
1145 @end example
1147 Substitution into a @code{%solve} nounform can sometimes result in the solution
1149 @example
1150 (%i4) subst(k = 2, %);
1151 (%o4)                   %union([x = - 1])
1152 @end example
1154 Especially for trigonometric equations, the solver sometimes needs
1155 to introduce an arbitrary integer.  These arbitrary integers have the 
1156 form @code{%zXXX}, where @code{XXX} is an integer; for example
1158 @example
1159 (%i5) to_poly_solve(sin(x) = 0, x);
1160 (%o5)   %union([x = 2 %pi %z33 + %pi], [x = 2 %pi %z35])
1161 @end example
1163 To re-index these variables to zero, use @code{nicedummies}:
1165 @example
1166 (%i6) nicedummies(%);
1167 (%o6)    %union([x = 2 %pi %z0 + %pi], [x = 2 %pi %z1])
1168 @end example
1170 Occasionally, the solver introduces an arbitrary complex number of the
1171 form @code{%cXXX} or an  arbitrary real number of the form @code{%rXXX}.
1172 The function @code{nicedummies} will re-index these identifiers to zero.
1174 The solution set sometimes involves simplifying versions of various
1175 of logical operators including @code{%and}, @code{%or}, or @code{%if}
1176 for conjunction, disjunction, and implication, respectively; for example
1178 @example
1179 (%i7) sol : to_poly_solve(abs(x) = a, x);
1180 (%o7) %union(%if(isnonnegative_p(a), [x = - a], %union()), 
1181                       %if(isnonnegative_p(a), [x = a], %union()))
1182 (%i8) subst(a = 42, sol);
1183 (%o8)             %union([x = - 42], [x = 42])
1184 (%i9) subst(a = -42, sol);
1185 (%o9)                       %union()
1186 @end example
1188 The empty set is represented by @code{%union()}.
1190 The function @code{to_poly_solve} is able to solve some, but not all,
1191 equations involving rational powers, some nonrational powers, absolute
1192 values, trigonometric functions, and minimum and maximum.  Also, some it
1193 can solve some equations that are solvable in in terms of the Lambert W
1194 function; some examples:
1196 @example
1197 (%i1) load("to_poly_solve")$
1199 (%i2) to_poly_solve(set(max(x,y) = 5, x+y = 2), set(x,y));
1200 (%o2)      %union([x = - 3, y = 5], [x = 5, y = - 3])
1201 (%i3) to_poly_solve(abs(1-abs(1-x)) = 10,x);
1202 (%o3)             %union([x = - 10], [x = 12])
1203 (%i4) to_poly_solve(set(sqrt(x) + sqrt(y) = 5, x + y = 10),
1204                     set(x,y));
1205                      3/2               3/2
1206                     5    %i - 10      5    %i + 10
1207 (%o4) %union([x = - ------------, y = ------------], 
1208                          2                 2
1209                                 3/2                 3/2
1210                                5    %i + 10        5    %i - 10
1211                           [x = ------------, y = - ------------])
1212                                     2                   2
1213 (%i5) to_poly_solve(cos(x) * sin(x) = 1/2,x,
1214                     'simpfuncs = ['expand, 'nicedummies]);
1215                                          %pi
1216 (%o5)              %union([x = %pi %z0 + ---])
1217                                           4
1218 (%i6) to_poly_solve(x^(2*a) + x^a + 1,x);
1219                                         2 %i %pi %z81
1220                                         -------------
1221                                   1/a         a
1222                   (sqrt(3) %i - 1)    %e
1223 (%o6) %union([x = -----------------------------------], 
1224                                   1/a
1225                                  2
1226 @group
1227                                                   2 %i %pi %z83
1228                                                   -------------
1229                                             1/a         a
1230                           (- sqrt(3) %i - 1)    %e
1231                      [x = -------------------------------------])
1232                                            1/a
1233                                           2
1234 @end group
1235 (%i7) to_poly_solve(x * exp(x) = a, x);
1236 (%o7)              %union([x = lambert_w(a)])
1237 @end example
1239 For @i{linear} inequalities, @code{to_poly_solve} automatically does Fourier
1240 elimination:
1242 @example
1243 (%i8) to_poly_solve([x + y < 1, x - y >= 8], [x,y]);
1244                                7
1245 (%o8) %union([x = y + 8, y < - -], 
1246                                2
1247                                                               7
1248                                  [y + 8 < x, x < 1 - y, y < - -])
1249                                                               2
1250 @end example
1252 Each optional argument to @code{to_poly_solve} must be an equation;
1253 generally, the order of these options does not matter.
1255 @itemize @bullet
1256 @item @code{simpfuncs = l}, where @code{l} is a list of functions.
1257 Apply the composition of the members of l to each solution.
1259 @example
1260 (%i1) to_poly_solve(x^2=%i,x);
1261                                1/4             1/4
1262 (%o1)       %union([x = - (- 1)   ], [x = (- 1)   ])
1263 (%i2) to_poly_solve(x^2= %i,x, 'simpfuncs = ['rectform]);
1264                       %i         1             %i         1
1265 (%o2) %union([x = - ------- - -------], [x = ------- + -------])
1266                     sqrt(2)   sqrt(2)        sqrt(2)   sqrt(2)
1267 @end example
1269 Sometimes additional simplification can revert a simplification; for example
1271 @example
1272 (%i3) to_poly_solve(x^2=1,x);
1273 (%o3)              %union([x = - 1], [x = 1])
1274 (%i4) to_poly_solve(x^2= 1,x, 'simpfuncs = [polarform]);
1275                                         %i %pi
1276 (%o4)            %union([x = 1], [x = %e      ]
1277 @end example
1279 Maxima doesn't try to check that each member of the function list @code{l} is
1280 purely a simplification; thus
1282 @example
1283 (%i5) to_poly_solve(x^2 = %i,x, 'simpfuncs = [lambda([s],s^2)]);
1284 (%o5)                   %union([x = %i])
1285 @end example
1287 To convert each solution to a double float, use @code{simpfunc = ['dfloat]}:
1289 @example
1290 (%i6) to_poly_solve(x^3 +x + 1 = 0,x, 
1291                     'simpfuncs = ['dfloat]), algexact : true;
1292 (%o6) %union([x = - .6823278038280178], 
1293 [x = .3411639019140089 - 1.161541399997251 %i], 
1294 [x = 1.161541399997251 %i + .3411639019140089])
1295 @end example
1297 @item @code{use_grobner = true} With this option, the function
1298 @code{poly_reduced_grobner} is applied to the equations before
1299 attempting their solution.  Primarily, this option provides a workaround
1300 for weakness in the function @code{algsys}.  Here is an example of
1301 such a workaround:
1303 @example
1304 (%i7) to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y],
1305                     'use_grobner = true);
1306 @group
1307                     sqrt(7) - 1      sqrt(7) + 1
1308 (%o7) %union([x = - -----------, y = -----------], 
1309                          2                2
1310 @end group
1311                                  sqrt(7) + 1        sqrt(7) - 1
1312                             [x = -----------, y = - -----------])
1313                                       2                  2
1314 (%i8) to_poly_solve([x^2+y^2=2^2,(x-1)^2+(y-1)^2=2^2],[x,y]);
1315 (%o8)                       %union()
1316 @end example
1318 @item @code{maxdepth = k}, where @code{k} is a positive integer.  This
1319 function controls the maximum recursion depth for the solver.  The
1320 default value for @code{maxdepth} is five.  When the recursions depth is
1321 exceeded, the solver signals an error:
1323 @example
1324 (%i9) to_poly_solve(cos(x) = x,x, 'maxdepth = 2);
1326 Unable to solve
1327 Unable to solve
1328 (%o9)        %solve([cos(x) = x], [x], maxdepth = 2)
1329 @end example
1331 @item @code{parameters = l}, where @code{l} is a list of symbols.  The solver
1332 attempts to return a solution that is valid for all members of the list
1333 @code{l}; for example:
1335 @example
1336 (%i10) to_poly_solve(a * x = x, x);
1337 (%o10)                   %union([x = 0])
1338 (%i11) to_poly_solve(a * x = x, x, 'parameters = [a]);
1339 (%o11) %union(%if(a - 1 = 0, [x = %c111], %union()), 
1340                                %if(a - 1 # 0, [x = 0], %union()))
1341 @end example
1343 In @code{(%o2)}, the solver introduced a dummy variable; to re-index the
1344 these dummy variables, use the function @code{nicedummies}:
1346 @example
1347 (%i12) nicedummies(%);
1348 (%o12) %union(%if(a - 1 = 0, [x = %c0], %union()), 
1349                                %if(a - 1 # 0, [x = 0], %union()))
1350 @end example
1351 @end itemize
1353 The @code{to_poly_solve} uses data stored in the hashed array
1354 @code{one_to_one_reduce} to solve equations of the form @math{f(a) =
1355 f(b)}.  The assignment @code{one_to_one_reduce['f,'f] : lambda([a,b],
1356 a=b)} tells @code{to_poly_solve} that the solution set of @math{f(a)
1357 = f(b)} equals the solution set of @math{a=b}; for example
1359 @example
1360 (%i13) one_to_one_reduce['f,'f] : lambda([a,b], a=b)$
1362 (%i14) to_poly_solve(f(x^2-1) = f(0),x);
1363 (%o14)             %union([x = - 1], [x = 1])
1364 @end example
1366 More generally, the assignment @code{one_to_one_reduce['f,'g] : lambda([a,b],
1367 w(a, b) = 0} tells @code{to_poly_solve} that the solution set of @math{f(a)
1368 = f(b)} equals the solution set of @math{w(a,b) = 0}; for example
1370 @example
1371 (%i15) one_to_one_reduce['f,'g] : lambda([a,b], a = 1 + b/2)$
1373 (%i16) to_poly_solve(f(x) - g(x),x);
1374 (%o16)                   %union([x = 2])
1375 @end example
1377 Additionally, the function @code{to_poly_solve} uses data stored in the hashed array 
1378 @code{function_inverse} to solve equations of the form @math{f(a) = b}.
1379 The assignment @code{function_inverse['f] : lambda([s], g(s))} 
1380 informs  @code{to_poly_solve} that the solution set to @code{f(x) = b} equals
1381 the solution set to @code{x = g(b)}; two examples:
1383 @example
1384 (%i17) function_inverse['Q] : lambda([s], P(s))$
1386 (%i18) to_poly_solve(Q(x-1) = 2009,x);
1387 (%o18)              %union([x = P(2009) + 1])
1388 (%i19) function_inverse['G] : lambda([s], s+new_variable(integer));
1389 (%o19)       lambda([s], s + new_variable(integer))
1390 (%i20) to_poly_solve(G(x - a) = b,x);
1391 (%o20)             %union([x = b + a + %z125])
1392 @end example
1395 @b{Notes}
1397 @itemize
1398 @item The solve variables needn't be symbols; when @code{fullratsubst} is 
1399 able to appropriately make substitutions, the solve variables can be nonsymbols:
1400 @end itemize
1402 @example
1403 (%i1) to_poly_solve([x^2 + y^2 + x * y = 5, x * y = 8],
1404                     [x^2 + y^2, x * y]);
1405                                   2    2
1406 (%o1)           %union([x y = 8, y  + x  = - 3])
1407 @end example
1409 @itemize
1410 @item For equations that involve complex conjugates, the solver automatically
1411 appends the conjugate equations; for example
1412 @end itemize
1414 @example
1415 (%i1) declare(x,complex)$
1417 (%i2) to_poly_solve(x + (5 + %i) * conjugate(x) = 1, x);
1418                                    %i + 21
1419 (%o2)              %union([x = - -----------])
1420                                  25 %i - 125
1421 (%i3) declare(y,complex)$
1423 (%i4) to_poly_solve(set(conjugate(x) - y = 42 + %i,
1424                         x + conjugate(y) = 0), set(x,y));
1425                            %i - 42        %i + 42
1426 (%o4)        %union([x = - -------, y = - -------])
1427                               2              2
1428 @end example
1430 @itemize
1431 @item For an equation that involves the absolute value function, the
1432 @code{to_poly_solve} consults the fact database to decide if the
1433 argument to the absolute value is complex valued.  When
1435 @example
1436 (%i1) to_poly_solve(abs(x) = 6, x);
1437 (%o1)              %union([x = - 6], [x = 6])
1438 (%i2) declare(z,complex)$
1440 (%i3) to_poly_solve(abs(z) = 6, z);
1441 (%o3) %union(%if((%c11 # 0) %and (%c11 conjugate(%c11) - 36 = 
1442                                        0), [z = %c11], %union()))
1443 @end example
1445 @i{This is the only situation that the solver consults the fact database.  If
1446 a solve variable is declared to be an integer, for example, @code{to_poly_solve}
1447 ignores this declaration}.
1448 @end itemize
1450 @b{Relevant option variables} @i{algexact, resultant, algebraic}
1452 @b{Related functions} @i{to_poly}
1454 @b{To use} @code{load("to_poly_solve")}
1456 @b{Status:} The function @code{to_poly_solve} is experimental; its
1457 specifications might change and its functionality might be merged into
1458 other Maxima functions.
1459 @end deffn
1461 @anchor{%union}
1462 @deffn {Operator} %union (@var{soln_1}, @var{soln_2}, @var{soln_3}, ...)
1463 @deffnx {Operator} %union ()
1465 @code{%union(@var{soln_1}, @var{soln_2}, @var{soln_3}, ...)} represents the union of its arguments,
1466 each of which represents a solution set,
1467 as determined by @code{to_poly_solve}.
1468 @code{%union()} represents the empty set.
1470 In many cases, a solution is a list of equations @code{[@var{x} = ..., @var{y} = ..., @var{z} = ...]}
1471 where @var{x}, @var{y}, and @var{z} are one or more unknowns.
1472 In such cases, @code{to_poly_solve} returns a @code{%union} expression
1473 containing one or more such lists.
1475 The solution set sometimes involves simplifying versions of various
1476 of logical operators including @code{%and}, @code{%or}, or @code{%if}
1477 for conjunction, disjunction, and implication, respectively.
1479 Examples:
1481 @code{%union(...)} represents the union of its arguments,
1482 each of which represents a solution set,
1483 as determined by @code{to_poly_solve}.
1484 In many cases, a solution is a list of equations.
1486 @c ===beg===
1487 @c load ("to_poly_solve") $
1488 @c to_poly_solve ([sqrt(x^2 - y^2), x + y], [x, y]);
1489 @c ===end===
1490 @example
1491 (%i1) load ("to_poly_solve") $
1492 (%i2) to_poly_solve ([sqrt(x^2 - y^2), x + y], [x, y]);
1493 (%o2)    %union([x = 0, y = 0], [x = %c13, y = - %c13])
1494 @end example
1496 @code{%union()} represents the empty set.
1498 @c ===beg===
1499 @c load ("to_poly_solve") $
1500 @c to_poly_solve (abs(x) = -1, x);
1501 @c ===end===
1502 @example
1503 (%i1) load ("to_poly_solve") $
1504 (%i2) to_poly_solve (abs(x) = -1, x);
1505 (%o2)                       %union()
1506 @end example
1508 The solution set sometimes involves simplifying versions of various
1509 of logical operators.
1511 @c ===beg===
1512 @c load ("to_poly_solve") $
1513 @c sol : to_poly_solve (abs(x) = a, x);
1514 @c subst (a = 42, sol);
1515 @c subst (a = -42, sol);
1516 @c ===end===
1517 @example
1518 (%i1) load ("to_poly_solve") $
1519 (%i2) sol : to_poly_solve (abs(x) = a, x);
1520 (%o2) %union(%if(isnonnegative_p(a), [x = - a], %union()), 
1521                       %if(isnonnegative_p(a), [x = a], %union()))
1522 (%i3) subst (a = 42, sol);
1523 (%o3)             %union([x = - 42], [x = 42])
1524 (%i4) subst (a = -42, sol);
1525 (%o4)                       %union()
1526 @end example
1528 @end deffn