Choose a canonical branch of the given expression. The square
root, cube root, natural log, etc. functions are multi-valued. The
canonicalize_radical() method will choose one of these values
based on a heuristic.

For example, sqrt(x^2) has two values: x, and
-x. The canonicalize_radical() function will choose
one of them, consistently, based on the behavior of the
expression as x tends to positive infinity. The solution
chosen is the one which exhibits this same behavior. Since
sqrt(x^2) approaches positive infinity as x does, the
solution chosen is x (which also tends to positive
infinity).

Warning

As shown in the examples below, a canonical form is not always
returned, i.e., two mathematically identical expressions might
be converted to different expressions.

Assumptions are not taken into account during the
transformation. This may result in a branch choice
inconsistent with your assumptions.

ALGORITHM:

This uses the Maxima radcan() command. From the Maxima
documentation:

Simplifies an expression, which can contain logs,
exponentials, and radicals, by converting it into a form
which is canonical over a large class of expressions and a
given ordering of variables; that is, all functionally
equivalent forms are mapped into a unique form. For a
somewhat larger class of expressions, radcan produces a
regular form. Two equivalent expressions in this class do
not necessarily have the same appearance, but their
difference can be simplified by radcan to zero.

For some expressions radcan is quite time consuming. This
is the cost of exploring certain relationships among the
components of the expression for simplifications based on
factoring and partial fraction expansions of exponents.

EXAMPLES:

canonicalize_radical() can perform some of the same
manipulations as log_expand():

The simplest example of counter-intuitive behavior is what
happens when we take the square root of a square:

sage: sqrt(x^2).canonicalize_radical()x

If you don’t want this kind of “simplification,” don’t use
canonicalize_radical().

This behavior can also be triggered when the expression under
the radical is not given explicitly as a square:

sage: sqrt(x^2-2*x+1).canonicalize_radical()x - 1

Another place where this can become confusing is with
logarithms of complex numbers. Suppose x is complex with
x==r*e^(I*t) (r real). Then log(x) is
log(r)+I*(t+2*k*pi) for some integer k.

Calling canonicalize_radical() will choose a branch,
eliminating the solutions for all choices of k but
one. Simplified by hand, the expression below is
(1/2)*log(2)+I*pi*k for integer k. However,
canonicalize_radical() will take each log expression, and
choose one particular solution, dropping the other. When the
results are subtracted, we’re left with no imaginary part:

The example below shows two expressions e1 and e2 which are
“simplified” to different expressions, while their difference
is “simplified” to zero; thus canonicalize_radical() does
not return a canonical form:

A new expression, equivalent to the original one, with the
coefficients of s grouped.

Note

The expression is not expanded or factored before the
grouping takes place. For best results, call expand()
on the expression before collect().

EXAMPLES:

In the first term of \(f\), \(x\) has a coefficient of \(4y\). In
the second term, \(x\) has a coefficient of \(z\). Therefore, if
we collect those coefficients, \(x\) will have a coefficient of
\(4y+z\):

If s is not present in the given expression, the
expression should not be modified. The variable \(z\) will not
be present in \(f\) below since \(f\) is a random polynomial of
maximum degree 10 in \(x\) and \(y\):

Expand this symbolic expression. Products of sums and exponentiated
sums are multiplied out, numerators of rational expressions which
are sums are split into their respective terms, and multiplications
are distributed over addition at all levels.

EXAMPLES:

We expand the expression \((x-y)^5\) using both
method and functional notation.

DETAILS: This uses the Maxima simplifier and sets
logexpand option for this simplifier. From the Maxima
documentation: “Logexpand:true causes log(a^b) to become
b*log(a). If it is set to all, log(a*b) will also simplify to
log(a)+log(b). If it is set to super, then log(a/b) will also
simplify to log(a)-log(b) for rational numbers a/b,
a#1. (log(1/b), for integer b, always simplifies.) If it is
set to false, all of these simplifications will be turned
off. “

Most of these log expansions only make sense over the
reals. So, we should set the Maxima domain variable to
‘real’ before we call out to Maxima. When we return, however, we
should set the domain back to what it was, rather than
assuming that it was ‘complex’. See trac ticket #12780:

Expand this symbolic expression. Products of sums and exponentiated
sums are multiplied out, numerators of rational expressions which
are sums are split into their respective terms, and multiplications
are distributed over addition at all levels.

EXAMPLES:

We expand the expression \((x-y)^5\) using both
method and functional notation.

Expand trigonometric and hyperbolic functions of sums of angles
and of multiple angles occurring in self. For best results, self
should already be expanded.

INPUT:

full - (default: False) To enhance user control
of simplification, this function expands only one level at a time
by default, expanding sums of angles or multiple angles. To obtain
full expansion into sines and cosines immediately, set the optional
parameter full to True.

Factor the expression, containing any number of variables or functions, into
factors irreducible over the integers.

INPUT:

self - a symbolic expression

dontfactor - list (default: []), a list of
variables with respect to which factoring is not to occur.
Factoring also will not take place with respect to any variables
which are less important (using the variable ordering assumed for
CRE form) than those on the ‘dontfactor’ list.

If you are factoring a polynomial with rational coefficients (and
dontfactor is empty) the factorization is done using Singular
instead of Maxima, so the following is very fast instead of
dreadfully slow:

Numerically find a root of self on the closed interval [a,b] (or
[b,a]) if possible, where self is a function in the one variable.
Note: this function only works in fixed (machine) precision, it is not
possible to get arbitrary precision approximations with it.

INPUT:

a,b - endpoints of the interval

var - optional variable

xtol,rtol - the routine converges when a root
is known to lie within xtol of the value return. Should be >= 0. The
routine modifies this to take into account the relative precision
of doubles.

maxiter - integer; if convergence is not
achieved in maxiter iterations, an error is raised. Must be >= 0.

Return this expression as element of the algebraic fraction
field over the base ring given.

EXAMPLES:

sage: fr=(1/x).fraction(ZZ);fr1/xsage: parent(fr)Fraction Field of Univariate Polynomial Ring in x over Integer Ringsage: parent(((pi+sqrt(2)/x).fraction(SR)))Fraction Field of Univariate Polynomial Ring in x over Symbolic Ringsage: parent(((pi+sqrt(2))/x).fraction(SR))Fraction Field of Univariate Polynomial Ring in x over Symbolic Ringsage: y=var('y')sage: fr=((3*x^5-5*y^5)^7/(x*y)).fraction(GF(7));fr(3*x^35 + 2*y^35)/(x*y)sage: parent(fr)Fraction Field of Multivariate Polynomial Ring in x, y over Finite Field of size 7

Return the gcd of self and b, which must be integers or polynomials over
the rational numbers.

TODO: I tried the massive gcd from
http://trac.sagemath.org/sage_trac/ticket/694 on Ginac dies
after about 10 seconds. Singular easily does that GCD now.
Since Ginac only handles poly gcd over QQ, we should change
ginac itself to use Singular.

This function returns a vector whose components are the derivatives
of the original function with respect to the arguments of the
original function. Alternatively, you can specify the variables as
a list.

The following fails because “2*(x+y)” automatically gets converted to
“2*x+2*y” of which “x+y” is not a subexpression:

sage: (x*sin(2*(x+y)+2*a)).has(x+y)False

Although x^1==x and x^0==1, neither “x” nor “1” are actually of the
form “x^something”:

sage: (x+1).has(x^w0)False

Here is another possible pitfall, where the first expression
matches because the term “-x” has the form “(-1)*x” in GiNaC. To check
whether a polynomial contains a linear term you should use the
coeff() function instead.

algorithm – (default: 'maxima') the algorithm to use for
for simplification. Implemented are 'maxima', which uses Maxima’s
hgfred function, and 'sage', which uses an algorithm
implemented in the hypergeometric module

This function is intended to provide an interface to query the internal
representation of the expression. In this sense, the word constant
does not reflect the mathematical properties of the expression.
Expressions which have no variables may return False.

Return the lcm of self and b, which must be integers or
polynomials over the rational numbers. This is computed from
the gcd of self and b implicitly from the relation
self * b = gcd(self, b) * lcm(self, b).

Note

In agreement with the convention in use for integers, if
self * b == 0, then gcd(self, b) == max(self, b) and
lcm(self, b) == 0.

DETAILS: This uses the Maxima simplifier and sets
logexpand option for this simplifier. From the Maxima
documentation: “Logexpand:true causes log(a^b) to become
b*log(a). If it is set to all, log(a*b) will also simplify to
log(a)+log(b). If it is set to super, then log(a/b) will also
simplify to log(a)-log(b) for rational numbers a/b,
a#1. (log(1/b), for integer b, always simplifies.) If it is
set to false, all of these simplifications will be turned
off. “

Most of these log expansions only make sense over the
reals. So, we should set the Maxima domain variable to
‘real’ before we call out to Maxima. When we return, however, we
should set the domain back to what it was, rather than
assuming that it was ‘complex’. See trac ticket #12780:

Return the complex norm of this symbolic expression, i.e.,
the expression times its complex conjugate. If \(c = a + bi\) is a
complex number, then the norm of \(c\) is defined as the product of
\(c\) and its complex conjugate

The norm of a complex number is different from its absolute value.
The absolute value of a complex number is defined to be the square
root of its norm. A typical use of the complex norm is in the
integral domain \(\ZZ[i]\) of Gaussian integers, where the norm of
each Gaussian integer \(c = a + bi\) is defined as its complex norm.

Using the ring parameter, you can also create polynomials
rings over the symbolic ring where only certain variables are
considered generators of the polynomial ring and the others
are considered “constants”:

Expand this symbolic expression. Products of sums and exponentiated
sums are multiplied out, numerators of rational expressions which
are sums are split into their respective terms, and multiplications
are distributed over addition at all levels.

EXAMPLES:

We expand the expression \((x-y)^5\) using both
method and functional notation.

‘simple’ (simplify rational functions into quotient of two
polynomials),

‘full’ (apply repeatedly, if necessary)

‘noexpand’ (convert to commmon denominator and add)

map - (default: False) if True, the result is an
expression whose leading operator is the same as that of the
expression self but whose subparts are the results of
applying simplification rules to the corresponding subparts
of the expressions.

With map=True each term in a sum is simplified separately
and thus the resuls are shorter for functions which are
combination of rational and nonrational funtions. In the
following example, we use this option if we want not to
combine logarithm and the rational function into one
fraction:

It is possible to solve a greater variety of equations
using solve() and the keyword to_poly_solve,
but only at the price of possibly encountering
approximate solutions. See documentation for f.solve
for more details.

Following the GiNaC tutorial, we use John Machin’s amazing
formula \(\pi = 16 \tan^{-1}(1/5) - 4 \tan^{-1}(1/239)\) to compute
digits of \(\pi\). We expand the arc tangent around 0 and insert
the fractions 1/5 and 1/239.

algorithm – (default: 'maxima') the algorithm to use for
for simplification. Implemented are 'maxima', which uses Maxima’s
hgfred function, and 'sage', which uses an algorithm
implemented in the hypergeometric module

‘simple’ (simplify rational functions into quotient of two
polynomials),

‘full’ (apply repeatedly, if necessary)

‘noexpand’ (convert to commmon denominator and add)

map - (default: False) if True, the result is an
expression whose leading operator is the same as that of the
expression self but whose subparts are the results of
applying simplification rules to the corresponding subparts
of the expressions.

With map=True each term in a sum is simplified separately
and thus the resuls are shorter for functions which are
combination of rational and nonrational funtions. In the
following example, we use this option if we want not to
combine logarithm and the rational function into one
fraction:

Attempt to simplify this expression by expressing it in the
form \(a + bi\) where both \(a\) and \(b\) are real. This
transformation is generally not a simplification, so we use
the given complexity_measure to discard
non-simplifications.

INPUT:

self – the expression to simplify.

complexity_measure – (default:
sage.symbolic.complexity_measures.string_length) a
function taking a symbolic expression as an argument and
returning a measure of that expressions complexity. If
None is supplied, the simplification will be performed
regardless of the result.

OUTPUT:

If the transformation produces a simpler expression (according
to complexity_measure) then that simpler expression is
returned. Otherwise, the original expression is returned.

ALGORITHM:

We first call rectform() on the given
expression. Then, the supplied complexity measure is used to
determine whether or not the result is simpler than the
original expression.

This should not be expanded with Euler’s formula since the
resulting expression is longer when considered as a string,
and the default complexity_measure uses string length to
determine which expression is simpler:

expand - (default:True) if True, expands trigonometric
and hyperbolic functions of sums of angles and of multiple
angles occurring in self first. For best results,
self should be expanded. See also expand_trig() to
get more controls on this expansion.

Analytically solve the equation self==0 or a univariate
inequality for the variable \(x\).

Warning

This is not a numerical solver - use find_root to solve
for self == 0 numerically on an interval.

INPUT:

x - variable(s) to solve for

multiplicities - bool (default: False); if True,
return corresponding multiplicities. This keyword is
incompatible with to_poly_solve=True and does not make
any sense when solving an inequality.

solution_dict - bool (default: False); if True or non-zero,
return a list of dictionaries containing solutions. Not used
when solving an inequality.

explicit_solutions - bool (default: False); require that
all roots be explicit rather than implicit. Not used
when solving an inequality.

to_poly_solve - bool (default: False) or string; use
Maxima’s to_poly_solver package to search for more possible
solutions, but possibly encounter approximate solutions.
This keyword is incompatible with multiplicities=True
and is not used when solving an inequality. Setting to_poly_solve
to 'force' omits Maxima’s solve command (useful when
some solutions of trigonometric equations are lost).

Given a dictionary of key:value pairs, substitute all occurrences
of key for value in self. The substitutions can also be given
as a number of symbolic equalities key == value; see the
examples.

Warning

This is a formal pattern substitution, which may or may not
have any mathematical meaning. The exact rules used at
present in Sage are determined by Maxima’s subst
command. Sometimes patterns are not replaced even though
one would think they should be - see examples below.

Given a dictionary of key:value pairs, substitute all occurrences
of key for value in self. The substitutions can also be given
as a number of symbolic equalities key == value; see the
examples.

Warning

This is a formal pattern substitution, which may or may not
have any mathematical meaning. The exact rules used at
present in Sage are determined by Maxima’s subst
command. Sometimes patterns are not replaced even though
one would think they should be - see examples below.

Sage can currently only understand a subset of the output of Maxima, Maple and
Mathematica, so even if the chosen backend can perform the summation the
result might not be convertable into a usable Sage expression.

Expand this symbolic expression in a truncated Taylor or
Laurent series in the variable \(v\) around the point \(a\),
containing terms through \((x - a)^n\). Functions in more
variables is also supported.

Expand trigonometric and hyperbolic functions of sums of angles
and of multiple angles occurring in self. For best results, self
should already be expanded.

INPUT:

full - (default: False) To enhance user control
of simplification, this function expands only one level at a time
by default, expanding sums of angles or multiple angles. To obtain
full expansion into sines and cosines immediately, set the optional
parameter full to True.

expand - (default:True) if True, expands trigonometric
and hyperbolic functions of sums of angles and of multiple
angles occurring in self first. For best results,
self should be expanded. See also expand_trig() to
get more controls on this expansion.