Although symbols can be assigned expressions for internal reasons, you
should not do it (and we are not going to tell you how it is done). If
you want to replace a symbol with something else in an expression, you
-can use the expression's @code{.subs()} method (@xref{Substituting Symbols},
+can use the expression's @code{.subs()} method (@xref{Substituting Expressions},
for more information).
@itemize @bullet
+@cindex contravariant
+@cindex covariant
+@cindex variance
@item Index objects are of class @code{idx} or a subclass. Every index has
a @dfn{value} and a @dfn{dimension} (which is the dimension of the space
the index lives in) which can both be arbitrary expressions but are usually
Sometimes you will want to substitute one symbolic index with another
symbolic or numeric index, for example when calculating one specific element
of a tensor expression. This is done with the @code{.subs()} method, as it
-is done for symbols (see @ref{Substituting Symbols}).
+is done for symbols (see @ref{Substituting Expressions}).
You have two possibilities here. You can either substitute the whole index
by another index or expression:
@end example
@cindex @code{get_free_indices()}
+@cindex Dummy index
@subsection Dummy indices
GiNaC treats certain symbolic index pairs as @dfn{dummy indices} meaning
@menu
* Information About Expressions::
-* Substituting Symbols::
+* Substituting Expressions::
* Polynomial Arithmetic:: Working with polynomials.
* Rational Expressions:: Working with rational functions.
* Symbolic Differentiation::
@end menu
-@node Information About Expressions, Substituting Symbols, Methods and Functions, Methods and Functions
+@node Information About Expressions, Substituting Expressions, Methods and Functions, Methods and Functions
@c node-name, next, previous, up
@section Getting information about expressions
expressions will give very surprising results.
-@node Substituting Symbols, Polynomial Arithmetic, Information About Expressions, Methods and Functions
+@node Substituting Expressions, Polynomial Arithmetic, Information About Expressions, Methods and Functions
@c node-name, next, previous, up
-@section Substituting symbols
+@section Substituting expressions
@cindex @code{subs()}
-Symbols can be replaced with expressions via the @code{.subs()} method:
+Algebraic objects inside expressions can be replaced with arbitrary
+expressions via the @code{.subs()} method:
@example
ex ex::subs(const ex & e);
@end example
In the first form, @code{subs()} accepts a relational of the form
-@samp{symbol == expression} or a @code{lst} of such relationals. E.g.
+@samp{object == expression} or a @code{lst} of such relationals:
@example
@{
symbol x("x"), y("y");
+
ex e1 = 2*x^2-4*x+3;
cout << "e1(7) = " << e1.subs(x == 7) << endl;
+ // -> 73
+
ex e2 = x*y + x;
cout << "e2(-2, 4) = " << e2.subs(lst(x == -2, y == 4)) << endl;
+ // -> -10
@}
@end example
-will print @samp{73} and @samp{-10}, respectively.
+@code{subs()} performs syntactic substitution of any complete algebraic
+object; it does not try to match sub-expressions as is demonstrated by the
+following example:
+
+@example
+@{
+ symbol x("x"), y("y"), z("z");
+
+ ex e1 = pow(x+y, 2);
+ cout << e1.subs(x+y == 4) << endl;
+ // -> 16
+
+ ex e2 = sin(x)*cos(x);
+ cout << e2.subs(sin(x) == cos(x)) << endl;
+ // -> cos(x)^2
+
+ ex e3 = x+y+z;
+ cout << e3.subs(x+y == 4) << endl;
+ // -> x+y+z
+ // (and not 4+z as one might expect)
+@}
+@end example
If you specify multiple substitutions, they are performed in parallel, so e.g.
@code{subs(lst(x == y, y == x))} exchanges @samp{x} and @samp{y}.
-The second form of @code{subs()} takes two lists, one for the symbols and
-one for the expressions to be substituted (both lists must contain the same
-number of elements). Using this form, you would write @code{subs(lst(x, y), lst(y, x))}
-to exchange @samp{x} and @samp{y}.
+The second form of @code{subs()} takes two lists, one for the objects to be
+replaced and one for the expressions to be substituted (both lists must
+contain the same number of elements). Using this form, you would write
+@code{subs(lst(x, y), lst(y, x))} to exchange @samp{x} and @samp{y}.
-@node Polynomial Arithmetic, Rational Expressions, Substituting Symbols, Methods and Functions
+@node Polynomial Arithmetic, Rational Expressions, Substituting Expressions, Methods and Functions
@c node-name, next, previous, up
@section Polynomial arithmetic
@code{collect()} accomplishes this task:
@example
-ex ex::collect(const symbol & s);
+ex ex::collect(const ex & s);
@end example
Note that the original polynomial needs to be in expanded form in order
methods
@example
-int ex::degree(const symbol & s);
-int ex::ldegree(const symbol & s);
+int ex::degree(const ex & s);
+int ex::ldegree(const ex & s);
@end example
which also work reliably on non-expanded input polynomials (they even work
a coefficient with a certain power from an expanded polynomial you use
@example
-ex ex::coeff(const symbol & s, int n);
+ex ex::coeff(const ex & s, int n);
@end example
You can also obtain the leading and trailing coefficients with the methods
@example
-ex ex::lcoeff(const symbol & s);
-ex ex::tcoeff(const symbol & s);
+ex ex::lcoeff(const ex & s);
+ex ex::tcoeff(const ex & s);
@end example
which are equivalent to @code{coeff(s, degree(s))} and @code{coeff(s, ldegree(s))},
or even from run to run since the internal canonical ordering is not
within the user's sphere of influence.
+@code{degree()}, @code{ldegree()}, @code{coeff()}, @code{lcoeff()},
+@code{tcoeff()} and @code{collect()} can also be used to a certain degree
+with non-polynomial expressions as they not only work with symbols but with
+constants, functions and indexed objects as well:
+
+@example
+@{
+ symbol a("a"), b("b"), c("c");
+ idx i(symbol("i"), 3);
+
+ ex e = pow(sin(x) - cos(x), 4);
+ cout << e.degree(cos(x)) << endl;
+ // -> 4
+ cout << e.expand().coeff(sin(x), 3) << endl;
+ // -> -4*cos(x)
+
+ e = indexed(a+b, i) * indexed(b+c, i);
+ e = e.expand(expand_options::expand_indexed);
+ cout << e.collect(indexed(b, i)) << endl;
+ // -> a.i*c.i+(a.i+c.i)*b.i+b.i^2
+@}
+@end example
+
@subsection Polynomial division
@cindex polynomial division
@end example
+@subsection Square-free decomposition
+@cindex square-free decomposition
+@cindex factorization
+@cindex @code{sqrfree()}
+
+GiNaC still lacks proper factorization support. Some form of
+factorization is, however, easily implemented by noting that factors
+appearing in a polynomial with power two or more also appear in the
+derivative and hence can easily be found by computing the GCD of the
+original polynomial and its derivatives. Any system has an interface
+for this so called square-free factorization. So we provide one, too:
+@example
+ex sqrfree(const ex & a, const lst & l = lst());
+@end example
+Here is an example that by the way illustrates how the result may depend
+on the order of differentiation:
+@example
+ ...
+ symbol x("x"), y("y");
+ ex BiVarPol = expand(pow(x-2*y*x,3) * pow(x+y,2) * (x-y));
+
+ cout << sqrfree(BiVarPol, lst(x,y)) << endl;
+ // -> (y+x)^2*(-1+6*y+8*y^3-12*y^2)*(y-x)*x^3
+
+ cout << sqrfree(BiVarPol, lst(y,x)) << endl;
+ // -> (1-2*y)^3*(y+x)^2*(-y+x)*x^3
+
+ cout << sqrfree(BiVarPol) << endl;
+ // -> depending on luck, any of the above
+ ...
+@end example
+
+
@node Rational Expressions, Symbolic Differentiation, Polynomial Arithmetic, Methods and Functions
@c node-name, next, previous, up
@section Rational expressions
@{
symbol x("x");
ex e = 4.5+pow(x,2)*3/2;
- cout << e << endl; // prints '4.5+3/2*x^2'
+ cout << e << endl; // prints '(4.5)+3/2*x^2'
// ...
@end example
into a GiNaC C++ program (note that in the above example, @code{pow(x,2)}
is printed as @samp{x^2}).
-To print an expression in a way that can be directly used in a C or C++
-program, you use the method
+It is possible to print expressions in a number of different formats with
+the method
@example
-void ex::printcsrc(ostream & os, unsigned type, const char *name);
+void ex::print(const print_context & c, unsigned level = 0);
@end example
-This outputs a line in the form of a variable definition @code{<type> <name> = <expression>}.
-The possible types are defined in @file{ginac/flags.h} (@code{csrc_types})
-and mostly affect the way in which floating point numbers are written:
+The type of @code{print_context} object passed in determines the format
+of the output. The possible types are defined in @file{ginac/print.h}.
+All constructors of @code{print_context} and derived classes take an
+@code{ostream &} as their first argument.
+
+To print an expression in a way that can be directly used in a C or C++
+program, you pass a @code{print_csrc} object like this:
@example
// ...
- e.printcsrc(cout, csrc_types::ctype_float, "f");
- e.printcsrc(cout, csrc_types::ctype_double, "d");
- e.printcsrc(cout, csrc_types::ctype_cl_N, "n");
+ cout << "float f = ";
+ e.print(print_csrc_float(cout));
+ cout << ";\n";
+
+ cout << "double d = ";
+ e.print(print_csrc_double(cout));
+ cout << ";\n";
+
+ cout << "cl_N n = ";
+ e.print(print_csrc_cl_N(cout));
+ cout << ";\n";
// ...
@end example
+The three possible types mostly affect the way in which floating point
+numbers are written.
+
The above example will produce (note the @code{x^2} being converted to @code{x*x}):
@example
float f = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00;
double d = (3.000000e+00/2.000000e+00)*(x*x)+4.500000e+00;
-cl_N n = (cl_F("3.0")/cl_F("2.0"))*(x*x)+cl_F("4.5");
+cl_N n = (cln::cl_F("3.0")/cln::cl_F("2.0"))*(x*x)+cln::cl_F("4.5");
@end example
-Finally, there are the two methods @code{printraw()} and @code{printtree()} intended for GiNaC
-developers, that provide a dump of the internal structure of an expression for
-debugging purposes:
+The @code{print_context} type @code{print_tree} provdes a dump of the
+internal structure of an expression for debugging purposes:
@example
// ...
- e.printraw(cout); cout << endl << endl;
- e.printtree(cout);
+ e.print(print_tree(cout));
@}
@end example
produces
@example
-ex(+((power(ex(symbol(name=x,serial=1,hash=150875740,flags=11)),ex(numeric(2)),hash=2,flags=3),numeric(3/2)),,hash=0,flags=3))
-
-type=Q25GiNaC3add, hash=0 (0x0), flags=3, nops=2
- power: hash=2 (0x2), flags=3
- x (symbol): serial=1, hash=150875740 (0x8fe2e5c), flags=11
- 2 (numeric): hash=2147483714 (0x80000042), flags=11
- 3/2 (numeric): hash=2147483745 (0x80000061), flags=11
+add, hash=0x0, flags=0x3, nops=2
+ power, hash=0x9, flags=0x3, nops=2
+ x (symbol), serial=3, hash=0x44a113a6, flags=0xf
+ 2 (numeric), hash=0x80000042, flags=0xf
+ 3/2 (numeric), hash=0x80000061, flags=0xf
-----
overall_coeff
- 4.5L0 (numeric): hash=2147483723 (0x8000004b), flags=11
+ 4.5L0 (numeric), hash=0x8000004b, flags=0xf
=====
@end example
-The @code{printtree()} method is also available in @command{ginsh} as the
-@code{print()} function.
+This kind of output is also available in @command{ginsh} as the @code{print()}
+function.
+
+If you need any fancy special output format, e.g. for interfacing GiNaC
+with other algebra systems or for producing code for different
+programming languages, you can always traverse the expression tree yourself:
+
+@example
+static void my_print(const ex & e)
+@{
+ if (is_ex_of_type(e, function))
+ cout << ex_to_function(e).get_name();
+ else
+ cout << e.bp->class_name();
+ cout << "(";
+ unsigned n = e.nops();
+ if (n)
+ for (unsigned i=0; i<n; i++) @{
+ my_print(e.op(i));
+ if (i != n-1)
+ cout << ",";
+ @}
+ else
+ cout << e;
+ cout << ")";
+@}
+
+int main(void)
+@{
+ my_print(pow(3, x) - 2 * sin(y / Pi)); cout << endl;
+ return 0;
+@}
+@end example
+
+This will produce
+
+@example
+add(power(numeric(3),symbol(x)),mul(sin(mul(power(constant(Pi),numeric(-1)),
+symbol(y))),numeric(-2)))
+@end example
+
+If you need an output format that makes it possible to accurately
+reconstruct an expression by feeding the output to a suitable parser or
+object factory, you should consider storing the expression in an
+@code{archive} object and reading the object properties from there.
+See the section on archiving for more information.
@subsection Expression input
different symbol than the @code{x} which was defined at the beginning of
the program, altough both would appear as @samp{x} when printed.
+You can also use the information stored in an @code{archive} object to
+output expressions in a format suitable for exact reconstruction. The
+@code{archive} and @code{archive_node} classes have a couple of member
+functions that let you access the stored properties:
+
+@example
+static void my_print2(const archive_node & n)
+@{
+ string class_name;
+ n.find_string("class", class_name);
+ cout << class_name << "(";
+
+ archive_node::propinfovector p;
+ n.get_properties(p);
+
+ unsigned num = p.size();
+ for (unsigned i=0; i<num; i++) @{
+ const string &name = p[i].name;
+ if (name == "class")
+ continue;
+ cout << name << "=";
+
+ unsigned count = p[i].count;
+ if (count > 1)
+ cout << "@{";
+
+ for (unsigned j=0; j<count; j++) @{
+ switch (p[i].type) @{
+ case archive_node::PTYPE_BOOL: @{
+ bool x;
+ n.find_bool(name, x);
+ cout << (x ? "true" : "false");
+ break;
+ @}
+ case archive_node::PTYPE_UNSIGNED: @{
+ unsigned x;
+ n.find_unsigned(name, x);
+ cout << x;
+ break;
+ @}
+ case archive_node::PTYPE_STRING: @{
+ string x;
+ n.find_string(name, x);
+ cout << '\"' << x << '\"';
+ break;
+ @}
+ case archive_node::PTYPE_NODE: @{
+ const archive_node &x = n.find_ex_node(name, j);
+ my_print2(x);
+ break;
+ @}
+ @}
+
+ if (j != count-1)
+ cout << ",";
+ @}
+
+ if (count > 1)
+ cout << "@}";
+
+ if (i != num-1)
+ cout << ",";
+ @}
+
+ cout << ")";
+@}
+
+int main(void)
+@{
+ ex e = pow(2, x) - y;
+ archive ar(e, "e");
+ my_print2(ar.get_top_node(0)); cout << endl;
+ return 0;
+@}
+@end example
+
+This will produce:
+
+@example
+add(rest=@{power(basis=numeric(number="2"),exponent=symbol(name="x")),
+symbol(name="y")@},coeff=@{numeric(number="1"),numeric(number="-1")@},
+overall_coeff=numeric(number="0"))
+@end example
+
+Be warned, however, that the set of properties and their meaning for each
+class may change between GiNaC versions.
@node Extending GiNaC, What does not belong into GiNaC, Input/Output, Top
@{
...
public:
- void print(ostream &os, unsigned upper_precedence) const;
+ void print(const print_context &c, unsigned level = 0) const;
...
@};
-void mystring::print(ostream &os, unsigned upper_precedence) const
+void mystring::print(const print_context &c, unsigned level) const
@{
- os << '\"' << str << '\"';
+ // print_context::s is a reference to an ostream
+ c.s << '\"' << str << '\"';
@}
@end example
-The @code{upper_precedence} argument is only required for container classes
-to correctly parenthesize the output. Let's try again to print the expression:
+The @code{level} argument is only required for container classes to
+correctly parenthesize the output. Let's try again to print the expression:
@example
cout << e << endl;
git://www.ginac.de / ginac.git / blobdiff