+#include <ginac/ginac.h>
+using namespace std;
+using namespace GiNaC;
+
+int main()
+@{
+ symbol v("v"), c("c");
+
+ ex gamma = 1/sqrt(1 - pow(v/c,2));
+ ex mass_nonrel = gamma.series(v==0, 10);
+
+ cout << "the relativistic mass increase with v is " << endl
+ << mass_nonrel << endl;
+
+ cout << "the inverse square of this series is " << endl
+ << pow(mass_nonrel,-2).series(v==0, 10) << endl;
+@}
+@end example
+
+Only calling the series method makes the last output simplify to
+@math{1-v^2/c^2+O(v^10)}, without that call we would just have a long
+series raised to the power @math{-2}.
+
+@cindex Machin's formula
+As another instructive application, let us calculate the numerical
+value of Archimedes' constant
+@tex
+$\pi$
+@end tex
+(for which there already exists the built-in constant @code{Pi})
+using John Machin's amazing formula
+@tex
+$\pi=16$~atan~$\!\left(1 \over 5 \right)-4$~atan~$\!\left(1 \over 239 \right)$.
+@end tex
+@ifnottex
+@math{Pi==16*atan(1/5)-4*atan(1/239)}.
+@end ifnottex
+This equation (and similar ones) were used for over 200 years for
+computing digits of pi (see @cite{Pi Unleashed}). We may expand the
+arcus tangent around @code{0} and insert the fractions @code{1/5} and
+@code{1/239}. However, as we have seen, a series in GiNaC carries an
+order term with it and the question arises what the system is supposed
+to do when the fractions are plugged into that order term. The solution
+is to use the function @code{series_to_poly()} to simply strip the order
+term off:
+
+@example
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+ex machin_pi(int degr)
+@{
+ symbol x;
+ ex pi_expansion = series_to_poly(atan(x).series(x,degr));
+ ex pi_approx = 16*pi_expansion.subs(x==numeric(1,5))
+ -4*pi_expansion.subs(x==numeric(1,239));
+ return pi_approx;
+@}
+
+int main()
+@{
+ using std::cout; // just for fun, another way of...
+ using std::endl; // ...dealing with this namespace std.
+ ex pi_frac;
+ for (int i=2; i<12; i+=2) @{
+ pi_frac = machin_pi(i);
+ cout << i << ":\t" << pi_frac << endl
+ << "\t" << pi_frac.evalf() << endl;
+ @}
+ return 0;
+@}
+@end example
+
+Note how we just called @code{.series(x,degr)} instead of
+@code{.series(x==0,degr)}. This is a simple shortcut for @code{ex}'s
+method @code{series()}: if the first argument is a symbol the expression
+is expanded in that symbol around point @code{0}. When you run this
+program, it will type out:
+
+@example
+2: 3804/1195
+ 3.1832635983263598326
+4: 5359397032/1706489875
+ 3.1405970293260603143
+6: 38279241713339684/12184551018734375
+ 3.141621029325034425
+8: 76528487109180192540976/24359780855939418203125
+ 3.141591772182177295
+10: 327853873402258685803048818236/104359128170408663038552734375
+ 3.1415926824043995174
+@end example
+
+
+@node Symmetrization, Built-in Functions, Series Expansion, Methods and Functions
+@c node-name, next, previous, up
+@section Symmetrization
+@cindex @code{symmetrize()}
+@cindex @code{antisymmetrize()}
+@cindex @code{symmetrize_cyclic()}
+
+The three methods
+
+@example
+ex ex::symmetrize(const lst & l);
+ex ex::antisymmetrize(const lst & l);
+ex ex::symmetrize_cyclic(const lst & l);
+@end example
+
+symmetrize an expression by returning the sum over all symmetric,
+antisymmetric or cyclic permutations of the specified list of objects,
+weighted by the number of permutations.
+
+The three additional methods
+
+@example
+ex ex::symmetrize();
+ex ex::antisymmetrize();
+ex ex::symmetrize_cyclic();
+@end example
+
+symmetrize or antisymmetrize an expression over its free indices.
+
+Symmetrization is most useful with indexed expressions but can be used with
+almost any kind of object (anything that is @code{subs()}able):
+
+@example
+@{
+ idx i(symbol("i"), 3), j(symbol("j"), 3), k(symbol("k"), 3);
+ symbol A("A"), B("B"), a("a"), b("b"), c("c");
+
+ cout << indexed(A, i, j).symmetrize() << endl;
+ // -> 1/2*A.j.i+1/2*A.i.j
+ cout << indexed(A, i, j, k).antisymmetrize(lst(i, j)) << endl;
+ // -> -1/2*A.j.i.k+1/2*A.i.j.k
+ cout << lst(a, b, c).symmetrize_cyclic(lst(a, b, c)) << endl;
+ // -> 1/3*@{a,b,c@}+1/3*@{b,c,a@}+1/3*@{c,a,b@}
+@}
+@end example
+
+
+@node Built-in Functions, Solving Linear Systems of Equations, Symmetrization, Methods and Functions
+@c node-name, next, previous, up
+@section Predefined mathematical functions
+
+GiNaC contains the following predefined mathematical functions:
+
+@cartouche
+@multitable @columnfractions .30 .70
+@item @strong{Name} @tab @strong{Function}
+@item @code{abs(x)}
+@tab absolute value
+@cindex @code{abs()}
+@item @code{csgn(x)}
+@tab complex sign
+@cindex @code{csgn()}
+@item @code{sqrt(x)}
+@tab square root (not a GiNaC function, rather an alias for @code{pow(x, numeric(1, 2))})
+@cindex @code{sqrt()}
+@item @code{sin(x)}
+@tab sine
+@cindex @code{sin()}
+@item @code{cos(x)}
+@tab cosine
+@cindex @code{cos()}
+@item @code{tan(x)}
+@tab tangent
+@cindex @code{tan()}
+@item @code{asin(x)}
+@tab inverse sine
+@cindex @code{asin()}
+@item @code{acos(x)}
+@tab inverse cosine
+@cindex @code{acos()}
+@item @code{atan(x)}
+@tab inverse tangent
+@cindex @code{atan()}
+@item @code{atan2(y, x)}
+@tab inverse tangent with two arguments
+@item @code{sinh(x)}
+@tab hyperbolic sine
+@cindex @code{sinh()}
+@item @code{cosh(x)}
+@tab hyperbolic cosine
+@cindex @code{cosh()}
+@item @code{tanh(x)}
+@tab hyperbolic tangent
+@cindex @code{tanh()}
+@item @code{asinh(x)}
+@tab inverse hyperbolic sine
+@cindex @code{asinh()}
+@item @code{acosh(x)}
+@tab inverse hyperbolic cosine
+@cindex @code{acosh()}
+@item @code{atanh(x)}
+@tab inverse hyperbolic tangent
+@cindex @code{atanh()}
+@item @code{exp(x)}
+@tab exponential function
+@cindex @code{exp()}
+@item @code{log(x)}
+@tab natural logarithm
+@cindex @code{log()}
+@item @code{Li2(x)}
+@tab Dilogarithm
+@cindex @code{Li2()}
+@item @code{zeta(x)}
+@tab Riemann's zeta function
+@cindex @code{zeta()}
+@item @code{zeta(n, x)}
+@tab derivatives of Riemann's zeta function
+@item @code{tgamma(x)}
+@tab Gamma function
+@cindex @code{tgamma()}
+@cindex Gamma function
+@item @code{lgamma(x)}
+@tab logarithm of Gamma function
+@cindex @code{lgamma()}
+@item @code{beta(x, y)}
+@tab Beta function (@code{tgamma(x)*tgamma(y)/tgamma(x+y)})
+@cindex @code{beta()}
+@item @code{psi(x)}
+@tab psi (digamma) function
+@cindex @code{psi()}
+@item @code{psi(n, x)}
+@tab derivatives of psi function (polygamma functions)
+@item @code{factorial(n)}
+@tab factorial function
+@cindex @code{factorial()}
+@item @code{binomial(n, m)}
+@tab binomial coefficients
+@cindex @code{binomial()}
+@item @code{Order(x)}
+@tab order term function in truncated power series
+@cindex @code{Order()}
+@item @code{Li(n, x)}
+@tab polylogarithm
+@cindex @code{Li()}
+@item @code{S(n, p, x)}
+@tab Nielsen's generalized polylogarithm
+@cindex @code{S()}
+@item @code{H(m_lst, x)}
+@tab harmonic polylogarithm
+@cindex @code{H()}
+@item @code{Li(m_lst, x_lst)}
+@tab multiple polylogarithm
+@cindex @code{Li()}
+@item @code{mZeta(m_lst)}
+@tab multiple zeta value
+@cindex @code{mZeta()}
+@end multitable
+@end cartouche
+
+@cindex branch cut
+For functions that have a branch cut in the complex plane GiNaC follows
+the conventions for C++ as defined in the ANSI standard as far as
+possible. In particular: the natural logarithm (@code{log}) and the
+square root (@code{sqrt}) both have their branch cuts running along the
+negative real axis where the points on the axis itself belong to the
+upper part (i.e. continuous with quadrant II). The inverse
+trigonometric and hyperbolic functions are not defined for complex
+arguments by the C++ standard, however. In GiNaC we follow the
+conventions used by CLN, which in turn follow the carefully designed
+definitions in the Common Lisp standard. It should be noted that this
+convention is identical to the one used by the C99 standard and by most
+serious CAS. It is to be expected that future revisions of the C++
+standard incorporate these functions in the complex domain in a manner
+compatible with C99.
+
+
+@node Solving Linear Systems of Equations, Input/Output, Built-in Functions, Methods and Functions
+@c node-name, next, previous, up
+@section Solving Linear Systems of Equations
+@cindex @code{lsolve()}
+
+The function @code{lsolve()} provides a convenient wrapper around some
+matrix operations that comes in handy when a system of linear equations
+needs to be solved:
+
+@example
+ex lsolve(const ex &eqns, const ex &symbols, unsigned options=solve_algo::automatic);
+@end example
+
+Here, @code{eqns} is a @code{lst} of equalities (i.e. class
+@code{relational}) while @code{symbols} is a @code{lst} of
+indeterminates. (@xref{The Class Hierarchy}, for an exposition of class
+@code{lst}).
+
+It returns the @code{lst} of solutions as an expression. As an example,
+let us solve the two equations @code{a*x+b*y==3} and @code{x-y==b}:
+
+@example
+@{
+ symbol a("a"), b("b"), x("x"), y("y");
+ lst eqns, vars;
+ eqns = a*x+b*y==3, x-y==b;
+ vars = x, y;
+ cout << lsolve(eqns, vars) << endl;
+ // -> @{x==(3+b^2)/(b+a),y==(3-b*a)/(b+a)@}
+@end example
+
+When the linear equations @code{eqns} are underdetermined, the solution
+will contain one or more tautological entries like @code{x==x},
+depending on the rank of the system. When they are overdetermined, the
+solution will be an empty @code{lst}. Note the third optional parameter
+to @code{lsolve()}: it accepts the same parameters as
+@code{matrix::solve()}. This is because @code{lsolve} is just a wrapper
+around that method.
+
+
+@node Input/Output, Extending GiNaC, Solving Linear Systems of Equations, Methods and Functions
+@c node-name, next, previous, up
+@section Input and output of expressions
+@cindex I/O
+
+@subsection Expression output
+@cindex printing
+@cindex output of expressions
+
+Expressions can simply be written to any stream:
+
+@example
+@{
+ symbol x("x");
+ ex e = 4.5*I+pow(x,2)*3/2;
+ cout << e << endl; // prints '4.5*I+3/2*x^2'
+ // ...
+@end example
+
+The default output format is identical to the @command{ginsh} input syntax and
+to that used by most computer algebra systems, but not directly pastable
+into a GiNaC C++ program (note that in the above example, @code{pow(x,2)}
+is printed as @samp{x^2}).
+
+It is possible to print expressions in a number of different formats with
+a set of stream manipulators;
+
+@example
+std::ostream & dflt(std::ostream & os);
+std::ostream & latex(std::ostream & os);
+std::ostream & tree(std::ostream & os);
+std::ostream & csrc(std::ostream & os);
+std::ostream & csrc_float(std::ostream & os);
+std::ostream & csrc_double(std::ostream & os);
+std::ostream & csrc_cl_N(std::ostream & os);
+std::ostream & index_dimensions(std::ostream & os);
+std::ostream & no_index_dimensions(std::ostream & os);
+@end example
+
+The @code{tree}, @code{latex} and @code{csrc} formats are also available in
+@command{ginsh} via the @code{print()}, @code{print_latex()} and
+@code{print_csrc()} functions, respectively.
+
+@cindex @code{dflt}
+All manipulators affect the stream state permanently. To reset the output
+format to the default, use the @code{dflt} manipulator:
+
+@example
+ // ...
+ cout << latex; // all output to cout will be in LaTeX format from now on
+ cout << e << endl; // prints '4.5 i+\frac@{3@}@{2@} x^@{2@}'
+ cout << sin(x/2) << endl; // prints '\sin(\frac@{1@}@{2@} x)'
+ cout << dflt; // revert to default output format
+ cout << e << endl; // prints '4.5*I+3/2*x^2'
+ // ...
+@end example
+
+If you don't want to affect the format of the stream you're working with,
+you can output to a temporary @code{ostringstream} like this:
+
+@example
+ // ...
+ ostringstream s;
+ s << latex << e; // format of cout remains unchanged
+ cout << s.str() << endl; // prints '4.5 i+\frac@{3@}@{2@} x^@{2@}'
+ // ...
+@end example
+
+@cindex @code{csrc}
+@cindex @code{csrc_float}
+@cindex @code{csrc_double}
+@cindex @code{csrc_cl_N}
+The @code{csrc} (an alias for @code{csrc_double}), @code{csrc_float},
+@code{csrc_double} and @code{csrc_cl_N} manipulators set the output to a
+format that can be directly used in a C or C++ program. The three possible
+formats select the data types used for numbers (@code{csrc_cl_N} uses the
+classes provided by the CLN library):
+
+@example
+ // ...
+ cout << "f = " << csrc_float << e << ";\n";
+ cout << "d = " << csrc_double << e << ";\n";
+ cout << "n = " << csrc_cl_N << e << ";\n";
+ // ...
+@end example
+
+The above example will produce (note the @code{x^2} being converted to
+@code{x*x}):
+
+@example
+f = (3.0/2.0)*(x*x)+std::complex<float>(0.0,4.5000000e+00);
+d = (3.0/2.0)*(x*x)+std::complex<double>(0.0,4.5000000000000000e+00);
+n = cln::cl_RA("3/2")*(x*x)+cln::complex(cln::cl_I("0"),cln::cl_F("4.5_17"));
+@end example
+
+@cindex @code{tree}
+The @code{tree} manipulator allows dumping the internal structure of an
+expression for debugging purposes:
+
+@example
+ // ...
+ cout << tree << e;
+@}
+@end example
+
+produces
+
+@example
+add, hash=0x0, flags=0x3, nops=2
+ power, hash=0x0, flags=0x3, nops=2
+ x (symbol), serial=0, hash=0xc8d5bcdd, flags=0xf
+ 2 (numeric), hash=0x6526b0fa, flags=0xf
+ 3/2 (numeric), hash=0xf9828fbd, flags=0xf
+ -----
+ overall_coeff
+ 4.5L0i (numeric), hash=0xa40a97e0, flags=0xf
+ =====
+@end example
+
+@cindex @code{latex}
+The @code{latex} output format is for LaTeX parsing in mathematical mode.
+It is rather similar to the default format but provides some braces needed
+by LaTeX for delimiting boxes and also converts some common objects to
+conventional LaTeX names. It is possible to give symbols a special name for
+LaTeX output by supplying it as a second argument to the @code{symbol}
+constructor.
+
+For example, the code snippet
+
+@example
+@{
+ symbol x("x", "\\circ");
+ ex e = lgamma(x).series(x==0,3);
+ cout << latex << e << endl;
+@}
+@end example
+
+will print
+
+@example
+ @{(-\ln(\circ))@}+@{(-\gamma_E)@} \circ+@{(\frac@{1@}@{12@} \pi^@{2@})@} \circ^@{2@}+\mathcal@{O@}(\circ^@{3@})
+@end example
+
+@cindex @code{index_dimensions}
+@cindex @code{no_index_dimensions}
+Index dimensions are normally hidden in the output. To make them visible, use
+the @code{index_dimensions} manipulator. The dimensions will be written in
+square brackets behind each index value in the default and LaTeX output
+formats:
+
+@example
+@{
+ symbol x("x"), y("y");
+ varidx mu(symbol("mu"), 4), nu(symbol("nu"), 4);
+ ex e = indexed(x, mu) * indexed(y, nu);
+
+ cout << e << endl;
+ // prints 'x~mu*y~nu'
+ cout << index_dimensions << e << endl;
+ // prints 'x~mu[4]*y~nu[4]'
+ cout << no_index_dimensions << e << endl;
+ // prints 'x~mu*y~nu'
+@}
+@end example
+
+
+@cindex Tree traversal
+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_a<function>(e))
+ cout << ex_to<function>(e).get_name();
+ else
+ cout << e.bp->class_name();
+ cout << "(";
+ size_t n = e.nops();
+ if (n)
+ for (size_t i=0; i<n; i++) @{
+ my_print(e.op(i));
+ if (i != n-1)
+ cout << ",";
+ @}
+ else
+ cout << e;
+ cout << ")";
+@}
+
+int main()
+@{
+ 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
+@cindex input of expressions
+
+GiNaC provides no way to directly read an expression from a stream because
+you will usually want the user to be able to enter something like @samp{2*x+sin(y)}
+and have the @samp{x} and @samp{y} correspond to the symbols @code{x} and
+@code{y} you defined in your program and there is no way to specify the
+desired symbols to the @code{>>} stream input operator.
+
+Instead, GiNaC lets you construct an expression from a string, specifying the
+list of symbols to be used:
+
+@example
+@{
+ symbol x("x"), y("y");
+ ex e("2*x+sin(y)", lst(x, y));
+@}
+@end example
+
+The input syntax is the same as that used by @command{ginsh} and the stream
+output operator @code{<<}. The symbols in the string are matched by name to
+the symbols in the list and if GiNaC encounters a symbol not specified in
+the list it will throw an exception.
+
+With this constructor, it's also easy to implement interactive GiNaC programs:
+
+@example
+#include <iostream>
+#include <string>
+#include <stdexcept>
+#include <ginac/ginac.h>
+using namespace std;
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x");
+ string s;
+
+ cout << "Enter an expression containing 'x': ";
+ getline(cin, s);
+
+ try @{
+ ex e(s, lst(x));
+ cout << "The derivative of " << e << " with respect to x is ";
+ cout << e.diff(x) << ".\n";
+ @} catch (exception &p) @{
+ cerr << p.what() << endl;
+ @}
+@}
+@end example
+
+
+@subsection Archiving
+@cindex @code{archive} (class)
+@cindex archiving
+
+GiNaC allows creating @dfn{archives} of expressions which can be stored
+to or retrieved from files. To create an archive, you declare an object
+of class @code{archive} and archive expressions in it, giving each
+expression a unique name:
+
+@example
+#include <fstream>
+using namespace std;
+#include <ginac/ginac.h>
+using namespace GiNaC;
+
+int main()
+@{
+ symbol x("x"), y("y"), z("z");
+
+ ex foo = sin(x + 2*y) + 3*z + 41;
+ ex bar = foo + 1;
+
+ archive a;
+ a.archive_ex(foo, "foo");
+ a.archive_ex(bar, "the second one");
+ // ...
+@end example
+
+The archive can then be written to a file:
+
+@example
+ // ...
+ ofstream out("foobar.gar");
+ out << a;
+ out.close();
+ // ...
+@end example
+
+The file @file{foobar.gar} contains all information that is needed to
+reconstruct the expressions @code{foo} and @code{bar}.
+
+@cindex @command{viewgar}
+The tool @command{viewgar} that comes with GiNaC can be used to view
+the contents of GiNaC archive files:
+
+@example
+$ viewgar foobar.gar
+foo = 41+sin(x+2*y)+3*z
+the second one = 42+sin(x+2*y)+3*z
+@end example