xref: /dports/math/reduce/Reduce-svn5758-src/doc/manual/eds.tex

% Extra macros

%\newcommand\implies{\Rightarrow}
\newcommand{\optional}[1]{$\,[$#1$]\,$}
\newenvironment{edssyntax}
   {\begin{list}{}{\tt}\item[]}
   {\end{list}}

%% For MathJax, must be part of a paragraph to avoid extra space:
\ifdefined\VerbMath
\(
\newcommand{\deriv}{\mathrm{d}}
\newcommand{\union}{\cup}
\newcommand{\R}{\mathbf{R}}
\newcommand{\del}{\partial}
\)%
\else
\newcommand{\deriv}{\mathrm{d}}
\newcommand{\union}{\cup}
\def\R{\hbox{\bf R}}
\newcommand{\del}{\partial}
\fi
%
%\begin{abstract}
EDS is a REDUCE package for symbolic analysis of partial differential
equations using the geometrical approach of exterior differential
systems. The package implements much of exterior differential systems
theory, including prolongation and involution analysis, and has been
optimised for large, non-linear problems.
%\end{abstract}

%\newpage
%\tableofcontents

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\newpage
\subsection{Introduction}

Exterior differential systems give a geometrical framework for partial
differential equations and more general differential geometric problems.
The geometrical formulation has several advantages stemming from its
coordinate-independence, including superior treatment of nonlinear and
global problems. There is not sufficient space in this manual for an
introduction to exterior differential systems beyond the scant details
given in section \ref{EDS data structures and concepts}, but there are a
number of up-to-date texts on the subject (eg \cite{Bryant:1991,Spivak:1979}).

EDS provides a number of tools for setting up and manipulating exterior
differential systems and implements many features of the theory. Its main
strengths are the ability to use anholonomic or moving frames and the care
taken with nonlinear problems.

There has long been interest in implementing the theory of exterior
differential systems in a computer algebra system (eg
\cite{Arais:1974,Ganzha:1981,Hartley:91}). The EDS package owes much to these
earlier efforts, and also to related packages for PDE analysis (eg
\cite{Mansfield:1993,reid_1991,Seiler:1995}), as well as to earlier versions of
EDS produced at Lancaster university with R~W~Tucker and
P~A~Tuckey. Finally, EDS uses the exterior calculus package EXCALC of
E~Schr{\"u}fer \ref{package:EXCALC} and the exterior ideals package XIDEAL
\ref{package:XIDEAL}. XIDEAL and EXCALC are loaded automatically with EDS.

This work has been supported by the Graduate College on Scientific
Computing, University of Cologne and GMD St Augustin, funded by the DFG (Deutsche
Forschungsgemeinschaft). I would like to express my thanks to R~W~Tucker,
E~Schr{\"u}fer, P~A~Tuckey, F~W~Hehl and R~B~Gardner for helpful and
encouraging discussions.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{EDS data structures and concepts}
\label{EDS data structures and concepts}

This section presents the various structures used for expressing exterior
systems quantities in EDS. In addition, some the concepts used in EDS to
aid computation are described.

\subsubsection{Coframings}
\label{Coframings}

Within the context of EDS, a {\it coframing} means a real
finite-dimensional differentiable manifold with a given global cobasis.
The information about a coframing required by EDS is kept in a
\meta{coframing} object. The cobasis is the identifying element of an
EDS \meta{coframing}: distinct cobases for the same differentiable
manifold are treated as distinct \meta{coframing} objects in EDS. The
cobasis may be either holonomic or anholonomic, allowing some manifolds
with non-trivial topology (eg.  group manifolds) to be treated.

In addition to the cobasis, an EDS \meta{coframing} can be given {\it
coordinates}, {\it structure equations} and {\it restrictions}. The
coordinates may be an incomplete or overcomplete set. The structure
equations express the exterior derivative of the coordinates and cobasis
elements as needed.  All coordinate differentials must be expressed in
terms of the given cobasis, but not all cobasis differentials need be
known. The restrictions are a set of inequalities (at present using just
$\neq$) describing point sets not in the manifold.

The \meta{coframing} object is, of course, by no means a full
description of a differentiable manifold. For example, there is no
topology and there are no charts. However, the \meta{coframing} object
carries sufficient information about the underlying manifold to allow a
range of exterior systems calculations to be carried out. As such, it is
convenient to accept an abuse of language and think of the
\meta{coframing} object as a manifold.

A \meta{coframing} is constructed or selected using the \f{coframing}
operator.

\paragraph{\it Examples:}
\begin{itemize}
\item $\R^3$ with cobasis $\{\deriv x,\deriv y,\deriv z\}$ and coordinates $\{x,y,z\}$.
\item $\R^2\backslash\{0\}$ with cobasis $\{e^1,e^2\}$, a single
	coordinate $\{r\}$, ``structure equations'' $\{\deriv r = e^1$,
	$\deriv e^1=0$,$\deriv e^2=e^1\wedge e^2/r\}$ and restrictions $\{r\neq0\}$.
\item $\R^2\backslash\{0\}$ with cobasis $\{\deriv x,\deriv y\}$,
	coordinates $\{x,y\}$ and restrictions $\{x^2+y^2\neq0\}$.
\item $S^1$ with cobasis $\{\omega\}$ and structure equations
	$\{\deriv\omega = 0\}$.
\item $S^2$ cannot be encapsulated by an EDS \meta{coframing} since there
        is no global cobasis.
\end{itemize}

\subsection{Exterior differential systems}
\label{Exterior differential systems}

A simple \meta{EDS}, or exterior differential system, is a triple
$(S,\Omega,M)$, where $M$ is a \meta{coframing} (section
\ref{Coframings}), $S$ is a \meta{system} (section \ref{Systems}) on
$M$, and $\Omega$ is an independence condition: either a decomposable
\meta{p-form} or a \meta{system} of 1-forms on $M$ (exterior
differential systems without independence condition are not treated by
EDS).

More generally, an \meta{EDS} is a list of simple \meta{EDS} objects
where the various coframings are all disjoint. This last requirement in
not enforced within EDS unless the \f{edsdisjoint} switch is \f{on}
(section \ref{edsdisjoint}). These more general \meta{EDS} objects are
represented as a list of simple \meta{EDS} objects. All operators which
take an \meta{EDS} argument accept both simple and compound types.

The trivial \meta{EDS}, describing an inconsistent problem with no
solutions, is defined to be (\{1\},\{\},\{\}).

An \meta{EDS} is represented by the \f{eds} operator (section \ref{eds}),
and can additionally be generated using the \f{contact} and \f{pde2eds}
operators (sections \ref{contact}, \ref{pde2eds}).

The solutions of $(S,\Omega,M)$ are integral manifolds, or immersions (cf
section \ref{Maps}) on which $S$ vanishes and the rank of $\Omega$ is
preserved. Solutions at a single point are described by integral elements
(section \ref{Integral elements}).

\subsubsection{Systems}
\label{Systems}

In EDS, the label \meta{system} refers to a list
\begin{edssyntax}
	\{\meta{p-form expr},$\cdots$\}
\end{edssyntax}
of differential forms. This is distinct from an \meta{EDS} (section
\ref{Exterior differential systems}), which has additional structure.
However, many EDS operators will accept either an \meta{EDS} or a
\meta{system} as arguments. In the latter case, any extra information
which is required is taken from the background coframing (section
\ref{Background coframing}).

The \meta{system} of an \meta{EDS} can be obtained with the \f{system}
operator (section \ref{system}).

\subsubsection{Background coframing}
\label{Background coframing}

The information encapsulated in a \f{coframing} operator is usually
inactive. However, when operations are performed on a \meta{coframing} or an
\meta{EDS} object (sections \ref{Coframings}, \ref{Exterior differential
systems}), this information is activated for the duration of those
operations. It is possible to activate the rules and orderings of a
\f{coframing} operator globally, by making it the {\em background
coframing}. All subsequent EXCALC operations will be governed by those
rules. Operations on \meta{EDS} objects are unaffected, since their
coframings are still activated locally. The background coframing can be set
and changed with the \f{set\_coframing} command, and inspected using
\f{coframing}.

\subsubsection{Integral elements}
\label{Integral elements}

An {\it integral element} of an exterior system $(S,\Omega,M)$ is a
subspace $P\subset T_pM$ of the tangent space at some point $p\in M$
such that all forms in $S$ vanish when evaluated on vectors from $P$. In
addition, no non-zero vector in $P$ may annul every form in $\Omega$.

Alternatively, an integral element $P\subset T_pM$ can be represented
by its annihilator $P^\perp\subset T^*_pM$, comprising those 1-forms
at $p$ which annul every vector in $P$. This can also be understood as a
maximal set of 1-forms at $p$ such that $S \simeq 0 \pmod{P^\perp}$ and
the rank of $\Omega$ is preserved modulo $P^\perp$.  This is the
representation used by EDS. Further, the reference to the point $p$ is
omitted, so an \meta{integral element} in EDS is a distribution of
1-forms on $M$, specified as a \meta{system} of 1-forms.

In specifying an integral element for a particular \meta{EDS}, it is
possible to omit the Pfaffian component of the \meta{EDS}, since these
1-forms must be part of any integral element.

\paragraph{\it Examples:}
\begin{itemize}
\item With $M = \R^3 = \{(x,y,z)\}$, $S = \{\deriv x\wedge \deriv z\}$ and
      $\Omega = \{\deriv x,\deriv y\}$, the integral element $P =
       \{\partial_x + \partial_z,\partial_y\}$ is equally determined by its
      annihilator $P^\perp = \{\deriv z - \deriv x\}$.
\item For $S = \{\deriv z - y\deriv x\}$ and $\Omega = \{\deriv x\}$, the integral
      element $P = \{\partial_x + y\partial_z\}$ can be specified
      simply as $\{\deriv y\}$.
\end{itemize}

\subsubsection{Properties}
\label{Properties}

For large problems, it can require a great deal of computation to establish
whether, for example, a system is closed or not. In order to save
recomputing such properties, an \meta{EDS} object carries a list of
\meta{properties} of the form
\begin{edssyntax}
	\{\meta{keyword} = \meta{value},$\cdots$\}
\end{edssyntax}
where \meta{keyword} is one of \f{closed}, \f{quasilinear}, \f{pfaffian} or
\f{involutive}, and \meta{value} is either \f{0} (false) or \f{1}
(true). These properties are suppressed when an \meta{EDS} is printed,
unless the \f{nat} switch is \f{off}. They can be examined using the
\f{properties} operator (section \ref{properties}).

Properties are usually generated automatically by EDS as required, but may
be explicitly checked using the operators in section \ref{Testing exterior
systems}. If a property is not yet present on the list, it is not yet
known, and must be checked explicitly if required.

In addition to the properties just described, an \meta{EDS} object carries
a number of hidden properties which record the results of previous
calculations, such as the closure or information about the prolongation of
the system. These hidden properties speed up many operations which
contain common sub-calculations. The hidden properties are stored using
internal LISP data structures and so are not available for inspection.

Properties can be asserted when an \meta{EDS} is constructed with the
\f{eds} operator (section \ref{eds}). Care is needed since such assertions
are never checked. Properties can be erased using the \f{cleanup} operator
(section \ref{cleanup}).

\subsubsection{Maps}
\label{Maps}

Within EDS, a map $f:M\to N$ is given as a \meta{map} object, a list
\begin{edssyntax}
\{\meta{coordinate} = \meta{expr},$\cdots$,\meta{expr} neq \meta{expr},$\cdots$\}
\end{edssyntax}
of substitutions and restrictions. The substitutions express coordinates on
the target manifold $N$ in terms of those on the source manifold $M$. The
restrictions describe point sets not contained in the source manifold
$M$. The ordering of substitutions and restrictions in the list is
unimportant. It is not necessary that the restrictions and right-hand sides
of the substitutions be written entirely in $M$ coordinates, but it must be
possible by repeated substitution to produce expressions on $M$ (see the
examples below). Any denominators in the substitutions are automatically
added to the list of restrictions. It is not necessary to include trivial
equations for coordinates which are present on both $M$ and $N$. Note that
projections cannot be represented in this fashion (but see the \f{cross}
operator, section \ref{cross}).

Maps are applied using the \f{pullback} and \f{restrict} operators
(sections \ref{pullback}, \ref{restrict}).

\paragraph{\it Examples:}
\begin{itemize}
\item The map $\R^2\backslash\{0\}\to\R^3$, $(x,y)\mapsto (x,y,z=x^2+y^2)$
      is represented $\{z = x^2+y^2,z\neq 0\}$.
\item $\{x=u+v,y=u-v\}$ might represent the coordinate change
      $\R^3\to\R^3$, $(u,v,z)\mapsto(x=u+v,y=u-v,z)$.
\item $\{x=u+v,y=2u-x\}$ is the same map again.
\item $\{x=2v+y,y=2u-x\}$ is unacceptable since $x$ and $y$ cannot be
      eliminated from the right-hand sides by repeated substitution.
\end{itemize}

\subsubsection{Cobasis transformations}
\label{Cobasis transformations}

A cobasis transformation is given in EDS by a \meta{transform}, a list
\begin{edssyntax}
	\{\meta{cobasis element} = \meta{1-form expr},$\cdots$\}
\end{edssyntax}
of substitutions. When applying a transformation to a \meta{p-form} or
\meta{system}, it is necessary to specify the {\it forward}
transformation just as for a \f{sub} substitution. For \meta{EDS} and
\meta{coframing} objects, it is also possible to specify the inverse of
the desired substition: EDS will automatically invert the transformation
as required. For a partial change of cobasis, it is not necessary to
include trivial equalities. Cobasis transformations are applied by the
\f{transform} operator (section \ref{transform}).

\paragraph{\it Examples:}
\begin{itemize}
\item $\{\omega^1 = x\deriv y - y\deriv x, \omega^2 = x\deriv x + y\deriv y\}$ gives a
transformation between Cartesian and polar cobases on
$\R^2\backslash\{0\}$.
\item On $J^1(\R^2,\R)$ with cobasis $\{\deriv u,\deriv p,\deriv q,\deriv r,\deriv s,\deriv t,\deriv
x,\deriv y\}$, the list $\{\theta^1=\deriv u - p\deriv x - q\deriv y, \theta^2=\deriv p -
r\deriv x - s\deriv y, \theta^3=\deriv q - s\deriv x - t\deriv y\}$ specifies a new cobasis in
which the contact system is simply $\{\theta^1,\theta^2,\theta^3\}$.
\end{itemize}

\subsubsection{Tableaux}
\label{Tableaux}

For a quasilinear Pfaffian exterior differential system
$(\{\theta^a\},\{\omega^i\},M)$, the tableau $A=[\pi^a_i]$
is a matrix of 1-forms such that
\[	\deriv \theta^a + \pi^a_i\wedge\omega^i \simeq 0
		\pmod{\{\theta^a,\omega^i\wedge\omega^j\}}
\]
The $\pi^a_i$ are not unique: if $\{\theta^a,\pi^\rho,\omega^i\}$ is a
standard cobasis for the system (section \ref{Standard cobasis}), the EDS
\meta{tableau} is a matrix containing linear combinations of the $\pi^\rho$
only. Zero rows are omitted.

The tableau of an \meta{EDS} is generated by the \f{tableau} operator
(section \ref{tableau}), or can be entered using the \f{mat} operator. The
Cartan characters of a tableau are found using \f{characters} (section
\ref{characters}).

\subsubsection{Normal form}
\label{Normal form}

Parts of the theory of exterior differential systems apply only at points
on the underlying manifold where the system is in some sense
non-singular. To ensure the theory applies, EDS automatically works all
exterior systems $(S,\Omega,M)$ into a {\em normal form} in which

\begin{enumerate}
\item The Pfaffian (degree 1) component of $S$ is in {\em solved} form,
      where each expression has a distinguished term with coefficient 1,
      unique to that expression.
\item The independence condition $\Omega$ is also in solved form.
\item The distinguished terms from the 1-forms in $S$ have been eliminated
      from the rest of $S$ and from $\Omega$.
\item Any 1-forms in $S$ which vanish modulo the independence condition are
      removed from the system and their coefficients are appended as
      0-forms.
\end{enumerate}

Conditions 1 and 2 ensure the 1-forms have constant rank, while 3 is
convenient for many tests and calculations. In bringing the system into
solved form, divisions will be made only by coefficients which are
constants, parameters or functions which are nowhere zero on the
manifold. The test for nowhere-zero functions uses the restrictions
component of the \meta{coframing} structure (cf section \ref{Coframings}) and
is still primitive: facts such as $x^2+1\neq0$ on a real manifold are
overlooked. See also the switch \f{edssloppy} (section \ref{edssloppy}).

This ``normal form'' has, of course, nothing to do with the various normal
forms (eg Goursat) into which some exterior systems may be brought by
cobasis transformations and choices of generators.

\paragraph{\it Examples:}
\begin{itemize}
\item On $M=\{(u,v,w)\in\R^3\mid u\neq v\}$, the Pfaffian system
      \[\{u\deriv u + v\deriv v + \deriv w,\>(u^2 + u - v^2)\deriv u + u\deriv v + \deriv w\}\] has
      the solved form
      \[\{\deriv v + (u + v)\deriv u,\>\deriv w + ( - uv + u - v )\deriv u\}.\]
\item Since the independence condition is defined only modulo the system,
      the system
      \[S=\{\deriv u - \deriv x - u_y\deriv y\},\quad \Omega=\deriv x\wedge\deriv y\] has an
      equivalent normal form
      \[S=\{\deriv x - \deriv u + u_y\deriv y\},\quad \Omega=\deriv u\wedge\deriv y.\]
\end{itemize}

\subsubsection{Standard cobasis}
\label{Standard cobasis}

Given an \meta{EDS} $(S,\Omega,M)$ in normal form (section \ref{Normal
form}), the cobasis of the \meta{coframing} $M$ can be decomposed into three
sets: $\{\theta^a\}$, the distinguished terms from the 1-forms in $S$,
$\{\omega^i\}$, the distinguished terms from the 1-forms in $\Omega$, and
the remainder $\{\pi^\rho\}$. Within EDS, $\{\theta^a,\pi^\rho,\omega^i\}$
is called the {\em standard cobasis}, and all expressions are ordered so
that $\theta^a > \pi^\rho > \omega^i$. The ordering within the three sets
is determined by the REDUCE \meta{kernel} ordering.

\paragraph{\it Examples:}
\begin{itemize}
\item For the system $S=\{\deriv u - \deriv x - u_y\deriv y\}$, $\Omega=\deriv x\wedge\deriv y$,
      the decomposed standard cobasis is $\{\deriv u\}\cup\{\deriv u_y\}\cup\{\deriv
      x,\deriv y\}$.
\item For the contact system
  \[S=\begin{cases}
                \deriv u - u_x\deriv x - u_y\deriv y\\
                \deriv u_x - u_{xx}\deriv x - u_{xy}\deriv y\\
                \deriv u_y - u_{xy}\deriv x - u_{yy}\deriv y
       \end{cases}\]
      the standard cobasis is $\{\deriv u,\deriv u_x,\deriv u_y\}\cup\{\deriv
      u_{xx},\deriv u_{xy},\deriv u_{yy}\}\cup\{\deriv x,\deriv y\}$.

\end{itemize}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Constructing EDS objects}
\label{Constructing EDS objects}

Before analysing an exterior system, it is necessary to enter it into EDS
somehow. Several means are provided for this purpose, and are described in
this section.

\subsubsection{\tt coframing}
\label{coframing}

An EDS \meta{coframing} is constructed using the \f{coframing}
operator. There are several ways in which it can be used.

The simplest syntax
\begin{edssyntax}
	coframing(\{\meta{expr},$\cdots$\})
\end{edssyntax}
examines the argument for 0-form and 1-form variables and deduces a full
\meta{coframing} object capable of supporting the given expressions. This
includes recursively examining the exterior derivatives of the variables
appearing explicitly in the argument, taking into account prevailing
\f{let} rules. In this form, the ordering of the final cobasis elements
follows the prevailing REDUCE ordering. Free indices in indexed expressions
are expanded to a list of explicit indices using \f{index\_expand} (section
\ref{index_expand}).

A more basic syntax is
\begin{edssyntax}
	coframing(\meta{cobasis}\optional{,\meta{coordinates}}
	\optional{,\meta{restrictions}}
	\\\phantom \qquad\qquad\quad
	\optional{,\meta{structure equations}})
\end{edssyntax}
where \meta{cobasis} is a list of \meta{kernel} 1-forms,
\meta{coordinates} is a list of \meta{kernel} 0-forms,
\meta{restrictions} is a list of inequalities (using only $\neq$ at
present), and \meta{structure equations} is a list of rules giving the
exterior derivatives of the coordinates and cobasis elements. All
arguments except the cobasis are optional, and the order of arguments is
unimportant. As in the first syntax, missing parts are deduced. The
ordering of the final cobasis elements follows the ordering specified,
rather than the prevailing REDUCE ordering.

Finally,
\begin{edssyntax}
	coframing(\meta{EDS})
\end{edssyntax}
returns the coframing argument of an \meta{EDS}, and
\begin{edssyntax}
	coframing()
\end{edssyntax}
returns the current background coframing (section \ref{Background
coframing}).

\paragraph{\it Examples:}
\begin{verbatim}
coframing {x,y,z};

   coframing({d x,d y,d z},{x,y,z},{},{})

coframing({e 1,e 2},{r},{r neq 0},
          {d r=>e 1,d e 1=>0,d e 2=>e 1^e 2/r});

                                            1  2
               1  2          1        2    e ^e           1
   coframing({e ,e },{r},{d e => 0,d e => -------,d r => e },
                                             r
             {r neq 0})

coframing({e 2}) where {d r=e 1,d e 1=0,d e 2=e 1^e 2/r};

                                            1  2
               1  2          1        2    e ^e           1
   coframing({e ,e },{r},{d e => 0,d e => -------,d r => e },
                                             r
             {r neq 0})
\end{verbatim}

\subsubsection{\tt eds}
\label{eds}

A simple \meta{EDS} is constructed using the \f{eds} operator.
\begin{edssyntax}
	eds(\meta{system},\meta{indep. condition}\ignorespaces
	\optional{,\meta{coframing}}\optional{,\meta{properties}})
\end{edssyntax}
(cf sections \ref{Systems}, \ref{Coframings}, \ref{Properties}). The
\meta{indep. condition} can be either a decomposable \meta{p-form} or a
\meta{system} of 1-forms. Free indices in indexed expressions are expanded
to a list of explicit indices using \f{index\_expand} (section
\ref{index_expand}).

The \meta{coframing} argument can be omitted, in which case the expressions
from the \meta{system} and \meta{indep. condition} are fed to the
\f{coframing} operator (section \ref{coframing}) to construct a suitable
working space.

The \meta{properties} argument is optional, allowing the given properties
to be asserted. This can save considerable time for large systems, but care
is needed since the assertions are never checked.

The \meta{EDS} is put into normal form (section \ref{Normal form}) before
being returned.

On output, only the \meta{system} and \meta{indep. condition} are
displayed, unless the \f{nat} switch is off, in which case the
\meta{coframing} and \meta{properties} are shown too. This is so that an
\meta{EDS} can be written out to a file and read back in.

The parts of an \meta{EDS} are obtained with the operators \f{system},
\f{cobasis}, \f{independence} and \f{properties} (sections \ref{system},
\ref{cobasis}, \ref{independence} and \ref{properties}).

\paragraph{\it Examples:}
\begin{verbatim}
pform {x,y,z,p,q}=0,{e(i),w(i,j)}=1;

indexrange {i,j,k}={1,2},{a,b,c}={3};

eds({d z - p*d x - q*d y, d p^d q},{d x,d y});

   EDS({d z - p*d x - q*d y,d p^d q},{d x,d y})

OMrules :=
   index_expand {d e(i)=>-w(i,-j)^e(j),w(i,-j)+w(j,-i)=>0}$

eds({e(a)},{e(i)}) where OMrules;

         3    1  2
   EDS({e },{e ,e })

coframing ws;
               3  2    1  2         1        2  2
   coframing({e ,w   ,e ,e },{},{d e  =>  - e ^w   ,
                    1                             1
                  2     1  2
               d e  => e ^w   },{})
                             1
\end{verbatim}

\subsubsection{\tt contact}
\label{contact}

Many PDE problems are formulated as exterior systems using a jet bundle
contact system. To facilitate construction of these systems, the
\f{contact} operator is provided. The syntax is
\begin{edssyntax}
	contact(\meta{order},\meta{source manifold},\meta{target manifold})
\end{edssyntax}
where \meta{order} is a non-negative integer, and the two remaining
arguments are either \meta{coframing} objects or lists of \meta{p-form}
expressions. In the latter case, the expressions are fed to the
\f{coframing} operator (section \ref{coframing}). The contact system for the
bundle $J^r(M,N)$ of $r$-jets of maps $M\to N$ is thus returned by
\f{contact(r,M,N)}. Source and target spaces may have anholonomic
cobases. Indexed names for the jet bundle fibre coordinates are constructed
using the identifiers in the source and target cobases.

\paragraph{\it Examples:}
\begin{verbatim}
pform {x,y,z,u,v}=0,{e i,w a}=1;
indexrange {i}={1,2},{a}=1;
contact(1,{x,y,z},{u,v});

   EDS({d u - u *d x - u *d y - u *d z,
               x        y        z
        d v - v *d x - v *d y - v *d z},{d x,d y,d z})
               x        y        z

OMrules := index_expand{d e(1)=>e(1)^e(2),d e(2)=>0,d w(a)=>0};
contact(2,{e(i)},{w(a)}) where OMrules;

         1    1    1    1    2
   EDS({w  - w   *e  - w   *e ,
                1         2
           1      1      1    1      2
        d w    - w     *e  - w     *e ,
             1      1 1         1 2
           1          1        1     1    1      2    1  2
        d w    + ( - w      + w   )*e  - w     *e },{e ,e })
             2          1 2      1          2 2
\end{verbatim}

\subsubsection{\tt pde2eds}
\label{pde2eds}

A PDE system can be encoded into an \meta{EDS} using \f{pde2eds}. The
syntax is
\begin{edssyntax}
	pde2eds(\meta{pde}\optional{,\meta{dependent},\meta{independent}})
\end{edssyntax}
where \meta{pde} is a list of equations or expressions (implicitly assumed
to vanish) specifying the PDE system using either
the standard REDUCE \f{df} operator, or the EXCALC \f{@} operator. If the
optional variable lists \meta{dependent} and \meta{independent} are not
given, \f{pde2eds} infers them from the expressions in \meta{pde}. The
order of each dependent variable is determined automatically.

The result returned by \f{pde2eds} is an \meta{EDS} based on the contact
system of the relevant mixed-order jet bundle. Any of the \meta{pde}
members which is in solved form is used to pull back this contact
system. Any remaining expressions or unresolved equations are simply
appended as 0-forms: before many of the analysis tools (section
\ref{Analysing exterior systems}) can be applied, it is necessary to
convert this to a system generated in positive degree using the \f{lift}
operator (section \ref{lift}).

The automatic inference of dependent and independent variables is governed
by the following rules. The independent variables are all those with
respect to which derivatives appear. The dependent variables are those
for which explicit derivatives appear, as well as any which have
dependencies (as declared by \f{depend} or \f{fdomain}) or which are 0-forms.
To exclude a variable from the dependent variable list (for example,
because it is regarded as given) or to include extra independent variables,
use the optional arguments to \f{pde2eds}.

One of the awkward points about \f{pde2eds} is that implicit dependence
is changed globally. In order for the \f{df} and \f{@} operators to be used
to express the PDE, the \meta{dependent} variables must depend (via
\f{depend} or \f{fdomain}) on the \meta{independent} variables. On the
other hand, in the \meta{EDS}, these variables are all completely
independent coordinates. The \f{pde2eds} operator thus removes the implicit
dependence so that the \meta{EDS} is correct upon return. This means that
the \meta{pde} will no longer evaluate properly until such time as the
dependence is manually restored, whereupon the \meta{EDS} will no longer be
correct, and so on.

To assist with this difficulty, \f{pde2eds} saves a record of the
dependencies it has removed in the shared variable \f{dependencies}. The
operator \f{mkdepend} can be used to restore the initial state.

See also the operators \f{pde2jet} (section \ref{pde2jet}) and \f{mkdepend}
(section \ref{mkdepend}).

\paragraph{\it Example:}
\begin{verbatim}
depend u,x,y; depend v,x,y;
pde2eds({df(u,y,y)=df(v,x),df(v,y)=y*df(v,x)});

   EDS({d u - u *d x - u *d y,
               x        y

        d u  - u   *d x - u   *d y,
           x    x x        y x

        d u  - u   *d x - v *d y,
           y    y x        x

        d v - v *d x - v *y*d y},d x^d y)
               x        x

dependencies;

   {{u,y,x},{v,y,x}}
\end{verbatim}

\subsubsection{\tt set\_coframing}
\label{set_coframing}

The background coframing (section \ref{Background coframing}) is set with
\f{set\_coframing}. The syntax is
\begin{edssyntax}
   set\_coframing \meta{arg}
\end{edssyntax}
where \meta{arg} is a \meta{coframing} or an \meta{EDS} and the previous
background coframing is returned. All rules, orderings etc pertaining to the
previous background coframing are removed and replaced by those for the new
\meta{coframing}. The special form
\begin{edssyntax}
   set\_coframing()
\end{edssyntax}
clears the background coframing entirely and returns the previous one.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Inspecting EDS objects}
\label{Inspecting EDS objects}

Given an \meta{EDS} or some other EDS structure, it is often desirable to
inspect or extract some part of it. The operators described in this section
do just that. Many of them accept various types of arguments and return the
relevant information in each case.

\subsubsection{\tt cobasis}
\label{cobasis}

\begin{edssyntax}
	cobasis \meta{arg}
\end{edssyntax}
returns the cobasis for \meta{arg}, which may be either a \meta{coframing}
or an \meta{EDS} (sections \ref{Coframings}, \ref{Exterior differential
systems}). The order of the items in the list gives the \meta{kernel}
ordering which applies when the \meta{coframing} in \meta{arg} is active.

\subsubsection{\tt coordinates}
\label{coordinates}

\begin{edssyntax}
	coordinates \meta{arg}
\end{edssyntax}
returns the coordinates for \meta{arg}, which may be either a
\meta{coframing}, an \meta{EDS}, or a list of \meta{expr} (sections
\ref{Coframings}, \ref{Exterior differential systems}). The coordinates in a
list of \meta{expr} are defined to be those 0-form \meta{kernels} with no
implicit dependencies.

\paragraph{\it Examples:}
\begin{verbatim}
coordinates contact(3,{x},{u});

   {x,u,u ,u   ,u     }
         x  x x  x x x

fdomain u=u(x);
coordinates {d u+d y};

   {x,y}
\end{verbatim}

\subsubsection{\tt structure\_equations}
\label{structure_equations}

\begin{edssyntax}
	structure\_equations \meta{arg}
\end{edssyntax}
returns the structure equations (cf section \ref{Coframings}) for
\meta{arg}, which may be either a \meta{coframing}, an \meta{EDS}, or a
\meta{transform} (sections \ref{Coframings}, \ref{Exterior differential
systems}, \ref{Cobasis transformations}). In the case of a
\meta{transform}, it is assumed the exterior derivatives of the right-hand
sides are known, and a list giving the exterior derivatives of the
left-hand sides is returned. This requires inverting the transformation. In
case this has already been done, and was time consuming, an alternative
syntax
\begin{edssyntax}
	structure\_equations(\meta{transform},\meta{inverse transform})
\end{edssyntax}
avoids recomputing the inverse.

\paragraph{\it Example:}
\begin{verbatim}
structure_equations{e 1=d x/x,e 2=x*d y};

       1         2     1  2
   {d e  => 0,d e  => e ^e }
\end{verbatim}

\subsubsection{\tt restrictions}
\label{restrictions}

\begin{edssyntax}
	restrictions \meta{arg}
\end{edssyntax}
returns the restrictions for \meta{arg}, which may be either a
\meta{coframing} or an \meta{EDS} (sections \ref{Coframings}, \ref{Exterior
differential systems}). The result is a list of inequalities.

\subsubsection{\tt system}
\label{system}

\begin{edssyntax}
	system \meta{EDS}
\end{edssyntax}
returns the system component of an \meta{EDS} (sections \ref{Exterior
differential systems}, \ref{Systems}) as a list of \meta{p-form}
expressions. (The PSL-based REDUCE command \f{system} operates as before:
the syntax
\begin{edssyntax}
	system "\meta{command}"
\end{edssyntax}
executes an operating system (eg UNIX) command.)

\subsubsection{\tt independence}
\label{independence}

\begin{edssyntax}
	independence \meta{EDS}
\end{edssyntax}
returns the independence condition of an \meta{EDS} (section \ref{Exterior
differential systems}) as a list of \meta{1-form} expressions.


\subsubsection{\tt properties}
\label{properties}

\begin{edssyntax}
	properties \meta{EDS}
\end{edssyntax}
returns the currently known properties of an \meta{EDS} (sections
\ref{Exterior differential systems}, \ref{Properties}) as a list of
equations of the form {\tt\meta{keyword} = \meta{value}}.

\paragraph{\it Example:}
\begin{verbatim}
properties closure contact(1,{x},{u});

   {closed=1,pfaffian=1,quasilinear=1}
\end{verbatim}


\subsubsection{\tt one\_forms}
\label{one_forms}

\begin{edssyntax}
	one\_forms \meta{arg}
\end{edssyntax}
returns the 1-forms in \meta{arg}, which may be either an \meta{EDS} or a
list of \meta{expr} (sections \ref{Exterior differential systems},
\ref{Systems}).

\paragraph{\it Example:}
\begin{verbatim}
one_forms {5,x*y - u,d u - x*d y,d u^d x- x*d y^d x};

   {d u - d y*x}
\end{verbatim}

\subsubsection{\tt zero\_forms, nought\_forms}
\label{zero_forms}

\begin{edssyntax}
	zero\_forms \meta{arg}
\end{edssyntax}
returns the 0-forms in \meta{arg}, which may be either an \meta{EDS} or a
list of \meta{expr} (sections \ref{Exterior differential systems},
\ref{Systems}). The alternative syntax \f{nought\_forms} does the same thing.

\paragraph{\it Example:}
\begin{verbatim}
zero_forms {5,x*y - u,d u - x*d y,d u^d x- x*d y^d x};

   {5, - u + x*y}
\end{verbatim}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Manipulating EDS objects}
\label{Manipulating EDS objects}

The abililty to change coordinates or cobasis, or to modify the system or
coframing can make the difference between an intractible problem and a
solvable one. The facilities described in this section form the low-level
core of EDS functions.

Most of the operators in this section can be applied to both \meta{EDS} and
\meta{coframing} objects. Where it makes sense (eg \f{pullback},
\f{restrict} and \f{transform}), they can be applied to a \meta{system}, or
list of differential forms as well.

\subsubsection{\tt augment}
\label{augment}

\begin{edssyntax}
	augment(\meta{EDS},\meta{system})
\end{edssyntax}
appends the extra forms in the second argument to the system part of the
first. If the forms in the \meta{system} do not live on the coframing of the
\meta{EDS}, an error results. The original \meta{EDS} is unchanged.

\paragraph{\it Example:}
\begin{verbatim}
% Non-Pfaffian system for a Monge-Ampere equation
S := contact(1,{x,y},{z})$
S := augment(S,{d z(-x)^d z(-y)});

   s := EDS({d z - z *d x - z *d y,
                    x        y

             d z ^d z },{d x,d y})
                x    y
\end{verbatim}

\subsubsection{\tt cross}
\label{cross}

The infix operator \f{cross} gives the direct product of
\meta{coframing} objects. The syntax is
\begin{edssyntax}
	\meta{arg1} cross \meta{arg2} \optional{cross $\cdots$}
\end{edssyntax}
The first argument may be either a \meta{coframing} (section
\ref{Coframings}) or an \meta{EDS} (section \ref{Exterior differential
systems}). The remaining arguments may be either \meta{coframing}
objects or any valid argument to the \f{coframing} operator (section
\ref{coframing}), in which case the corresponding \meta{coframing} is
automatically inferred. The arguments may not contain any common
coordinates or cobasis elements.

If the first argument is an \meta{EDS}, the result is the \meta{EDS}
lifted to the direct product space. In this way, it is possible to
execute a pullback under a projection.

\paragraph{\it Example:}
\begin{verbatim}
coordinates(contact(1,{x,y},{u}) cross {v});

   {x,y,u,u ,u ,v}
           x  y
\end{verbatim}

\subsubsection{\tt pullback}
\label{pullback}

Pullbacks with respect to an EDS \meta{map} (section \ref{Maps}) have the
syntax
\begin{edssyntax}
	pullback(\meta{arg},\meta{map})
\end{edssyntax}
where \meta{arg} can be any one of \meta{EDS}, \meta{coframing},
\meta{system} or \meta{p-form} expression (sections \ref{Exterior
differential systems}, \ref{Coframings}, \ref{Systems}). The result is of
the same type as \meta{arg}.

For an \meta{EDS} or \meta{coframing} with anholonomic cobasis, \f{pullback}
calculates the pullbacks of the cobasis elements and chooses a cobasis for
the source coframing itself. For a \meta{system}, any zeroes in the result
are dropped from the list.

\paragraph{\it Examples:}
\begin{verbatim}
pullback(contact(1,{x,y},{u}),{u(-y) = u*u(-x)});

   EDS({d u - u *d x - u *u*d y},{d x,d y})
               x        x

M := coframing({e 1,e 2},{r},{r neq 0},
               {d r=>e 1,d e 1=>0,d e 2=>e 1^e 2/r})$

pullback(M,{r=1/x});
                                     2
               2              2     e ^d x
   coframing({e ,d x},{x},{d e  => --------},{x neq 0})
                                      x

pullback(ws,{x=0});

   ***** Map image not within target coframing in pullback

pullback({y*d y,d y - d x},{y=x});

   {d x*x}
\end{verbatim}

\subsubsection{\tt restrict}
\label{restrict}

Restrictions with respect to an EDS \meta{map} (section \ref{Maps}) have the
syntax
\begin{edssyntax}
	restrict(\meta{arg},\meta{map})
\end{edssyntax}
where \meta{arg} can be any one of \meta{EDS}, \meta{coframing},
\meta{system} or \meta{p-form} expression (sections \ref{Exterior
differential systems}, \ref{Coframings}, \ref{Systems}). The result is of
the same type as \meta{arg}. The action of \f{restrict} is similar to that
of \f{pullback}, except that only scalar coefficients are affected: 1-form
variables are unchanged.

\paragraph{\it Examples:}
\begin{verbatim}
% Bring a system into normal form by restricting the coframing

S := eds({u*d v - v*d u},{d x});

   s := EDS({v*d u - u*d v},{d x})

restrict(S,{u neq 0});

               v
   EDS({d v - ---*d u},{d x})
               u

% Difference between restrict and pullback

pullback({x*d x - y*d y},{x=y,y=1});

   {}

restrict({x*d x - y*d y},{x=y,y=1});

   {d x - d y}
\end{verbatim}

\subsubsection{\tt transform}
\label{transform}

A change of cobasis is made using the \f{transform} operator
\begin{edssyntax}
	transform(\meta{arg},\meta{transform})
\end{edssyntax}
where \meta{arg} can be any one of \meta{EDS}, \meta{coframing},
\meta{system} or \meta{p-form} expression (sections \ref{Exterior
differential systems}, \ref{Coframings}, \ref{Systems}) and \meta{transform}
is a list of substitutions (cf section \ref{Cobasis transformations}). The
result is of the same type as \meta{arg}.

For an \meta{EDS} or \meta{coframing}, \f{transform} can detect whether the
tranformation is given in the forward or reverse direction and invert
accordingly. Structure equations are updated correctly. If an exact cobasis
element is eliminated, its expression in terms of the new cobasis is added
to the list of structure equations, since the corresponding coordinate may
still be present elsewhere in the structure.

\paragraph{\it Example:}
\begin{verbatim}
S := contact(1,{x},{u});

   s := EDS({d u - u *d x},{d x})
                    x

new := {e(1) = first system S,w(1) = d x};

            1               1
   new := {e =d u - d x*u ,w =d x}
                         x

S := transform(S,new);

              1    1
   s := EDS({e },{w })

structure_equations s;

       1             1
   {d e  =>  - d u ^w ,
                  x
       1
    d w  => 0,

            1       1
    d u => e  + u *w ,
                 x
            1
    d x => w }
\end{verbatim}

\subsubsection{\tt lift}
\label{lift}

Many of the analysis tools (section \ref{Analysing exterior systems})
cannot treat systems containing 0-forms. The \f{lift} operator
\begin{edssyntax}
	lift \meta{EDS}
\end{edssyntax}
solves the 0-forms in the system and uses the solution to pull back to a
smaller manifold. This may generate new 0-form conditions (in the course of
bringing the pulled-back system into normal form), in which case the
process is repeated until the system is generated in positive degree. In
non-linear problems, the solution space of the 0-forms may be a variety, in
which case a compound \meta{EDS} (section \ref{Exterior differential
systems}) will result. If \f{edsverbose} is on (section \ref{edsverbose}),
the solutions are displayed as they are generated.

\paragraph{\it Example:}
\begin{verbatim}
S := augment(contact(2,{x,y},{u}),{u(-y,-y)-u(-x,-x)})$
on edsverbose;
lift S;
   Solving 0-forms
   New equations:
   u   =u
    y y  x x

   EDS({d u - u *d x - u *d y,
               x        y

        d u  - u   *d x - u   *d y,
           x    x x        x y

        d u  - u   *d x - u   *d y},{d x,d y})
           y    x y        x x
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Analysing exterior systems}
\label{Analysing exterior systems}

This section describes higher level operators for extracting information
about exterior systems. Many of them require a \meta{EDS} in normal form
(section \ref{Normal form}) generated in positive degree as input, but some
can also analyse a \meta{system} (section \ref{Systems}) or a single
\meta{p-form}. Only trivial examples are provided in this section, but many
of these operators are used in the longer examples in the test file which
accompanies this package.


\subsubsection{\tt cartan\_system}
\label{cartan_system}

The {\em Cartan system} of a form or system $S$ is the smallest Pfaffian
system $C$ such that $\Lambda(C)$ contains a set $I$ of forms algebraically
equivalent to $S$. The Cartan system is also known as the {\em associated
Pfaff system} or {\em retracting space}. An alternative characterisation is
to note that the annihilator $C^\perp$ comprises all vectors $V$ satisfying
$i_V S \simeq 0 \pmod{S}$.  Note this is a purely algebraic concept: $S$
need not be closed under differentiation. See also \f{cauchy\_system}
(section \ref{cauchy_system}).

The operator
\begin{edssyntax}
	cartan\_system \meta{arg}
\end{edssyntax}
returns the Cartan system of \meta{arg}, which may be an \meta{EDS}, a
\meta{system} or a single \meta{p-form} expression (sections \ref{Exterior
differential systems}, \ref{Systems}). For an \meta{EDS}, the result is a
Pfaffian \meta{EDS} on the same manifold, otherwise it is a
\meta{system}. The argument must be generated in positive degree.

\paragraph{\it Example:}
\begin{verbatim}
cartan_system{d u^d v + d v^d w + d x^d y};

   {d u - d w,d v,d x,d y}
\end{verbatim}

\subsubsection{\tt cauchy\_system}
\label{cauchy_system}

The {\em Cauchy system} $C$ of a form or system $S$ is the Cartan system or
retracting space of its closure under exterior differentiation (section
\ref{cartan_system}). The annihilator $C^\perp$ consists of the Cauchy
vectors for the $S$.

The operator
\begin{edssyntax}
	cauchy\_system \meta{arg}
\end{edssyntax}
returns the Cauchy system of \meta{arg}, which may be an \meta{EDS}, a
\meta{system} or a single \meta{p-form} expression (sections \ref{Exterior
differential systems}, \ref{Systems}). For an \meta{EDS}, the result is a
Pfaffian \meta{EDS} on the same manifold, otherwise it is a
\meta{system}. The argument must be generated in positive degree.

\paragraph{\it Example:}
\begin{verbatim}
cauchy_system{u*d v + v*d w + x*d y};

   {d u,d v,d w,d x,d y}
\end{verbatim}

\subsubsection{\tt characters}
\label{characters}

The Cartan characters $\{s_1,...,s_n\}$ of an \meta{EDS} or \meta{tableau}
(sections \ref{Exterior differential systems}, \ref{Tableaux}) are obtained
with
\begin{edssyntax}
	characters \meta{EDS} \qquad{\em or}\qquad characters \meta{tableau}
\end{edssyntax}
The zeroth character $s_0$ is not returned, it is simply the number of
1-forms in the \meta{EDS} (cf \f{one\_forms}, section \ref{one_forms}). The
definition used for the last character: $s_n = (d - n) - (s_0 + s_1 + ... +
s_{n-1})$, where $d$ is the manifold dimension, allows Cartan's test to be
used even when Cauchy characteristics are present.

For a nonlinear \meta{EDS}, the Cartan characters can vary from stratum to
stratum of the Grassmann bundle variety of ordinary integral elements (cf
\f{grassmann\_variety} in section \ref{grassmann_variety}). Nonetheless,
they are constant on each stratum, so it suffices to calculate them at one
point (ie at one integral element). This is done using the syntax
\begin{edssyntax}
	characters(\meta{EDS},\meta{integral element})
\end{edssyntax}
where \meta{integral element} is a list of 1-forms (cf section
\ref{Integral elements}).

The Cartan characters are calculated from the reduced characters for a
fixed flag of integral elements based on the 1-forms in the independence
condition of an \meta{EDS}. This can lead to incorrect results if the flag
is somehow singular, so two switches are provided to overcome this (section
\ref{ranpos}). First, \f{genpos} looks at a generic flag by using a general
linear transformation to put the system in {\em general position}. This
guarantees correct results, but can be too slow for practical
purposes. Secondly, \f{ranpos} performs a linear transformation using a
sparse matrix of random integers. In most cases, this is much faster than
using general position, and a few repetitions give some confidence in the
results.

\paragraph{\it Example:}
\begin{verbatim}
S := pullback(contact(2,{x,y},{u}),{u(-x,-y)=0});

   s := EDS({d u - u *d x - u *d y,
                    x        y

             d u  - u   *d x,
                x    x x

             d u  - u   *d y},{d x,d y})
                y    y y

characters S;

   {1,1}

on ranpos; characters S;

   {2,0}
\end{verbatim}

\subsubsection{\tt closure}
\label{closure}

\begin{edssyntax}
	closure \meta{EDS}
\end{edssyntax}
returns the closure of the \meta{EDS} under exterior differentiation.

Owing to conflicts with the requirements of a normal form (section
\ref{Normal form}), \f{closure} cannot guarantee that the resulting system
is closed if the \meta{EDS} contains 0-forms.

\subsubsection{\tt derived\_system}
\label{derived_system}

\begin{edssyntax}
	derived\_system \meta{arg}
\end{edssyntax}
returns the first derived system of \meta{arg}, which must be a Pfaffian
\meta{EDS} or \meta{system}. Repeated use gives the derived flag leading to
the maximal integrable subsystem.

\paragraph{\it Example:}
\begin{verbatim}
pform {p,r,x,y,z}=0; korder z;
derived_system eds({d z - q*d y,d p - e**z*d y,
                    d r - e**z*p*d y,d x},{d y});

               z            z
   EDS({d p - e *d y,d r - e *p*d y,d x},{d y})

derived_system ws;

               1
   EDS({d p - ---*d r,d x},{d y})
               p

derived_system ws;

               1
   EDS({d p - ---*d r,d x},{d y})
               p
\end{verbatim}

\subsubsection{\tt dim\_grassmann\_variety}
\label{dim_grassmann_variety}

\begin{edssyntax}
	dim\_grassmann\_variety \meta{EDS}
\end{edssyntax}
returns the dimension of the Grassmann bundle variety of ordinary integral
elements for an \meta{EDS} (cf \f{grassmann\_variety}, section
\ref{grassmann_variety}). This number is useful, for example, in Cartan's
test. For a nonlinear \meta{EDS}, this can vary from stratum to stratum of
the variety, so
\begin{edssyntax}
	dim\_grassmann\_variety(\meta{EDS},\meta{integral element})
\end{edssyntax}
returns the dimension of the stratum containing the \meta{integral element}
(cf section \ref{Integral elements}).

\subsubsection{\tt dim}
\label{dim}

\begin{edssyntax}
	dim \meta{arg}
\end{edssyntax}
returns the dimension of the manifold underlying \meta{arg},
which can be either an \meta{EDS} or a \meta{coframing} (sections \ref{Exterior
differential systems}, \ref{Coframings}).

\subsubsection{\tt involution}
\label{involution}

\begin{edssyntax}
	involution \meta{EDS}
\end{edssyntax}
repeatedly prolongs an \meta{EDS} until it reaches involution or
inconsistency (cf \f{prolong}, section \ref{prolong}). The system must be
in normal form (section \ref{Normal form}) and generated in positive
degree. For nonlinear problems, all branches of the prolongation tree are
followed. The result is an \meta{EDS} (usually a compound one for
nonlinear problems, see section \ref{Exterior differential systems})
giving the involutive prolongation. In case some variety couldn't be
resolved during the process, the relevant branch is truncated at that point
and represented by a system with 0-forms, as with \f{grassmann\_variety}
(section \ref{grassmann_variety}). The result of \f{involution} might then
{\em not} be in involution.

If the \f{edsverbose} switch is on (section \ref{edsverbose}), a trace of
the prolongations is produced. See the Janet problem in the test file for
an example.

\subsubsection{\tt linearise, linearize}
\label{linearise}

A nonlinear exterior system can be linearised at some point on the
manifold with respect to any integral element, yielding a constant
coefficient exterior system with the same Cartan characters. In EDS,
reference to the point is omitted, so the result is an exterior system
linearised with respect to a distribution of integral elements. The syntax
is
\begin{edssyntax}
	linearise(\meta{EDS},\meta{integral element})
\end{edssyntax}
but \f{linearize} will work just as well. See the isometric embeddings
example in the test file.

For a quasilinear \meta{EDS} (cf section \ref{quasilinear}),
\begin{edssyntax}
	linearise \meta{EDS}
\end{edssyntax}
returns an equivalent exterior system containing only linear generators.

\paragraph{\it Example:}
\begin{verbatim}
f := d u^d x + d v^d y$
S := eds({f,d v^f},{d x,d y});

   s := EDS({d u^d x + d v^d y,d u^d v^d x},{d x,d y})

linearise S;

   EDS({d u^d x + d v^d y},{d x,d y})
\end{verbatim}

\subsubsection{\tt integral\_element}
\label{integral_element}

\begin{edssyntax}
	integral\_element \meta{EDS}
\end{edssyntax}
returns a random \meta{integral element} of the \meta{EDS} (section
\ref{Integral elements}). The system must be in normal form (section
\ref{Normal form}) and generated in positive degree. This integral element
is found using the method described by Wahlquist \cite{Wahlquist:1993}
(essentially the Cartan-K{\"a}hler construction filling in the free variables
from each polar system with random integer values). This method can fail on
non-involutive systems, or \meta{EDS} objects whose independence conditions
indicate a singular flag of integral elements (cf the discussion about
Cartan characters, section \ref{characters}).

See the isometric embedding problem in the test file for an example.

\subsubsection{\tt prolong}
\label{prolong}

\begin{edssyntax}
	prolong \meta{EDS}
\end{edssyntax}
calculates the prolongation of the \meta{EDS} to the Grassmann bundle
variety of integral elements. The system must be in normal form (section
\ref{Normal form}) and generated in positive degree. The variety is
decomposed using essentially the REDUCE \f{solve} operator. If no solutions
can be found, the variety is empty, and the prolongation is the
inconsistent \meta{EDS} (section \ref{Exterior differential
systems}). Otherwise, the result is a list of variety components, which
fall into three classes:
\begin{enumerate}
\item a submanifold of the Grassmann bundle which surjects onto the base
      manifold. The result in this case is the pullback of the Grassmann
      bundle contact \meta{EDS} to this submanifold.
\item a submanifold of the Grassmann bundle which does not surject onto the
      base manifold (ie cannot be presented by solving for Grassmann
      bundle fibre coordinates). The result in this case is the pullback of
      the original \meta{EDS} to the projection onto the base manifold. If
      0-forms arise in bringing the pullback to normal form, these are
      solved recursively and the system pulled back again until the result
      is generated in positive degree (cf \f{lift}, section \ref{lift}).
\item a component of the variety which \f{solve} was not able to resolve
      explicitly. The result in this case is the Grassmann bundle contact
      \meta{EDS} augmented with the 0-forms which \f{solve} couldn't
      treat. This can be extracted from the result of \f{prolong} and
      manipulated further ``by hand'',
\end{enumerate}
The result returned by \f{prolong} will, in general, be a compound
\meta{EDS} (section \ref{Exterior differential systems}). If the switch
\f{edsverbose} (section \ref{edsverbose}) is on, a trace of the
prolongation is printed.

The \meta{map}s which are generated in a \f{prolong} call are available
subsequently in the global variable \f{pullback\_maps}. This facility is
still very primitive and unstructured. It should be extended to the
\f{involution} operator as well...

\paragraph{\it Example:}
\begin{verbatim}
pde := {u(-y,-y)=u(-x,-x)**2/2,u(-x,-y)=u(-x,-x)};

                       2
                 (u   )
                   x x
   pde := {u   =---------,u   =u   }
            y y     2      x y  x x

S := pullback(contact(2,{x,y},{u}),pde)$
on edsverbose;
prolong S;
   Reduction using new equations:
   u   =1
    x x
   Prolongation using new equations:
   u     =0
    x x x
   u     =0
    x x y

   {EDS({d u - u *d x - u *d y,
                x        y

         d u  - d x - d y,
            x
                       1
         d u  - d x - ---*d y},{d x,d y}),
            y          2

    EDS({d u - u *d x - u *d y,
                x        y

         d u  - u   *d x - u   *d y,
            x    x x        x x
                                  2
                            (u   )
                              x x
         d u  - u   *d x - ---------*d y,
            y    x x           2

         d u   },{d x,d y})}
            x x
\end{verbatim}

\subsubsection{\tt tableau}
\label{tableau}

\begin{edssyntax}
	tableau \meta{EDS}
\end{edssyntax}
returns the \meta{tableau} (section \ref{Tableaux}) of a quasilinear
Pfaffian \meta{EDS}, which must be in normal form and generated in positive
degree.

\paragraph{\it Example:}
\begin{verbatim}
tableau contact(2,{x,y},{u});

   [d u     d u   ]
   [   x x     x y]
   [              ]
   [d u     d u   ]
   [   x y     y y]
\end{verbatim}

\subsubsection{\tt torsion}
\label{torsion}

For a semilinear Pfaffian exterior differential system, the torsion
corresponds to first-order integrability conditions for the
system. Specifically,
\begin{edssyntax}
	torsion \meta{EDS}
\end{edssyntax}
returns a list of 0-forms describing the projection of the Grassmann bundle
variety of integral elements onto the base manifold. If the switch
\f{edssloppy} (section \ref{edssloppy}) is on, quasilinear systems are
treated as semilinear. A semilinear system is involutive if both the
torsion is empty, and Cartan's test for the reduced characters is
satisfied.

\paragraph{\it Example:}
\begin{verbatim}
S := pullback(contact(2,{x,y},{u}),
              {u(-y,-y)=u(-x),u(-x,-y)=u});

   s := EDS({d u - u *d x - u *d y,
                    x        y

             d u  - u   *d x - u*d y,
                x    x x

             d u  - u*d x - u *d y},{d x,d y})
                y            x
torsion s;

   {u    - u }
     x x    y
\end{verbatim}

\subsubsection{\tt grassmann\_variety}
\label{grassmann_variety}

Given an exterior system $(S,\Omega,M)$ with independence condition of
rank $n$, the Grassmann bundle of $n$-planes over $M$ contains a
submanifold characterised by those $n$-planes compatible with the
independence condition. All integral elements must lie in this
submanifold. The operator
\begin{edssyntax}
	grassmann\_variety \meta{EDS}
\end{edssyntax}
returns the contact system for this part of the Grassmann bundle augmented
by the 0-forms specifying the variety of integral elements of $S$. In cases
where \f{prolong} (section \ref{prolong}) is unable to decompose the
variety automatically, \f{grassmann\_variety} can be used in combination
with \f{zero\_forms} (section \ref{zero_forms}) to calculate the variety
conditions. Any solutions found ``by hand'' can be incorporated using
\f{pullback} (section \ref{pullback}).

\paragraph{\it Example:}
Using the system from the example in section \ref{prolong}:
\begin{verbatim}
zero_forms grassmann_variety S;

   { - u     *u    + u     ,
        x x x  x x    x x y

     - u      + u     }
        x x x    x x y

solve ws;

   Unknowns: {u     ,u     ,u   }
               x x x  x x y  x x

   {{u     =0,u     =0},
      x x y    x x x

    {u   =1,u     =u     }}
      x x    x x x  x x y
\end{verbatim}
The second solution contains an integrability condition.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Testing exterior systems}
\label{Testing exterior systems}

The operators in this section allow various properties of an \meta{EDS} to
be checked. These checks are done automatically when required on entry to
the routines in sections \ref{Manipulating EDS objects} and \ref{Analysing
exterior systems}, but sometimes it is useful to know explicitly. The
result is either a \f{1} (true) or a \f{0} (false), so the operators can be
used in boolean expressions within \f{if} statements etc.  Since checking
these properties can be very time-consuming, the result of the first test
is stored on the \meta{properties} record of an \meta{EDS} to avoid
re-checking. This memory can be cleared using the \f{cleanup} operator.

\subsubsection{\tt closed}
\label{closed}

\begin{edssyntax}
	closed \meta{arg}
\end{edssyntax}
checks whether \meta{arg}, which may be an \meta{EDS}, a \meta{system} or a
single \meta{p-form} is closed under exterior differentiation.

\paragraph{\it Examples:}
\begin{verbatim}
closed(x*d x);

   1

closed {d u - p*d x,d p - p/y*d x};

   0
\end{verbatim}

\subsubsection{\tt involutive}
\label{involutive}

\begin{edssyntax}
	involutive \meta{EDS}
\end{edssyntax}
checks whether \meta{EDS} is involutive, using Cartan's test. See the test
file for examples.

\subsubsection{\tt pfaffian}
\label{pfaffian}

\begin{edssyntax}
	pfaffian \meta{EDS}
\end{edssyntax}
checks whether \meta{EDS} is a Pfaffian system: generated by a set of
1-forms and their exterior derivatives. The \meta{EDS} must be in normal
form (section \ref{Normal form}) for this to succeed. Systems with 0-forms
are non-Pfaffian by definition in EDS.

\paragraph{\it Examples:}
\begin{verbatim}
pfaffian eds({d u - p*d x - q*d y,d p^d x+d q^d y},{d x,d y});

   1

pfaffian eds({d u - p*d x - q*d y,d p^d q},{d x,d y});

   0
\end{verbatim}

\subsubsection{\tt quasilinear}
\label{quasilinear}

An exterior system $(S,\Omega,M)$ is said to be {\em quasilinear} if, when
written in the standard cobasis $\{\theta^a,\pi^\rho,\omega^i\}$ (section
\ref{Standard cobasis}), its {\em closure} can be generated by a set of
forms which are of combined total degree 1 in $\{\theta^a,\pi^\rho\}$. The
operation
\begin{edssyntax}
	quasilinear \meta{EDS}
\end{edssyntax}
checks whether the {\em closure} of \meta{EDS} is a quasilinear system. The
\meta{EDS} must be in normal form (section \ref{Normal form}) for this to
succeed. Systems with 0-forms are not quasilinear by definition in EDS.

\paragraph{\it Examples:}
\begin{verbatim}
% A system where pi(rho)={d p,d q}, and which looks non-linear

S := eds({d u - p*d x - q*d y,d p^d q^d y},{d x,d y})$

quasilinear S;

   1

linearise closure S;

   EDS({d u - p*d x - q*d y,
         - d p^d x - d q^d y},{d x,d y})

% One which is really non-linear

quasilinear eds({d u - p*d x - q*d y,d p^d q},{d x,d y});

   0
\end{verbatim}

\subsubsection{\tt semilinear}
\label{semilinear}

Let $(S,\Omega,M)$ be such that, written in the standard cobasis
$\{\theta^a,\pi^\rho,\omega^i\}$ (section \ref{Standard cobasis}), its
closure is explicitly quasilinear. If the coefficients of $\{\pi^\rho\}$
depend only on the independent variables, then the system is said to be
{\em semilinear}.  The operation
\begin{edssyntax}
	semilinear \meta{EDS}
\end{edssyntax}
checks whether {\em closure} of \meta{EDS} is a semilinear system. The
\meta{EDS} must be in normal form (section \ref{Normal form}) for this to
succeed. Systems with 0-forms are not semilinear by definition in EDS.

For semilinear systems, the expressions determining the Grassmann bundle
variety of integral elements will be linear in the Grassmann bundle fibre
coordinates, with coefficients which depend only upon the independent
variables. This allows alternative, faster algorithms to be used in
analysis.

If the switch \f{edssloppy} is on (section \ref{edssloppy}), all
quasilinear systems are treated as if they are semilinear.

\paragraph{\it Examples:}
\begin{verbatim}
% A semilinear system: @(u,y) = y*@(u,x)
S := eds({d u - p*d x - p*y*d y},{d x,d y})$
semilinear S;

   1
% A quasilinear system: @(u,y) = u*@(u,x)
S := eds({d u - p*d x - p*u*d y},{d x,d y})$
quasilinear S;

   1
semilinear S;

   0
on edssloppy;
semilinear S;

   1
\end{verbatim}

\subsubsection{\tt frobenius}
\label{frobenius}

\begin{edssyntax}
	frobenius \meta{arg}
\end{edssyntax}
checks whether \meta{arg}, which may be an \meta{EDS} or a \meta{system},
is a completely integrable Pfaffian system.

\paragraph{\it Examples:}
\begin{verbatim}
if frobenius eds({d u -p*(d x+d y)},d x^d y) then yes else no;

   no

if frobenius eds({d u -u*(d x+d y)},d x^d y) then yes else no;

   yes
\end{verbatim}

\subsubsection{\tt equiv}
\label{equiv}

\begin{edssyntax}
	\meta{EDS1} equiv \meta{EDS2}
\end{edssyntax}
checks whether \meta{EDS1} and \meta{EDS2} are algebraically equivalent as
exterior systems (ie generate the same algebraic ideal).

\paragraph{\it Examples:}
\begin{verbatim}
S1 := contact(2,{x,y},{u})$
S2 := augment(S1,foreach f in system S1 join {d f,d x^d f})$
if S1 equiv S2 then yes else no;

   no

if closure S1 equiv S2 then yes else no;

   yes
\end{verbatim}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Switches}
\label{Switches}

EDS provides several switches to govern the display of information and
speed or reliability of the results.

\subsubsection{\tt edsverbose}
\label{edsverbose}

If \f{edsverbose} is \f{on}, a number of operators (eg \f{prolong},
\f{involution}) will display additional information as the calculation
progresses. For large problems, this can produce too much output to be
useful, so \f{edsverbose} is \f{off} by default. This allows only warning
(\f{***}) and error (\f{*****}) messages to be printed.

\subsection{\tt edsdebug}
\label{edsdebug}

If \f{edsdebug} is \f{on}, EDS produces copious quantities of information,
in addition to that produced with \f{edsverbose} on. This information is
for debugging purposes, and may not make much sense without knowledge of
the inner workings of EDS. \f{edsdebug} is \f{off} by default.

\subsection{\tt edssloppy}
\label{edssloppy}

Normally, EDS will not divide by any expressions it does not know to be
nowhere zero. If an \meta{EDS} can be brought into normal form only by
restricting away from the zeroes of some coefficients, then these
restrictions should be made using the \f{restrict} operator (section
\ref{restrict}). However, if \f{edssloppy} is \f{on}, then EDS will, as a
last resort, divide by whatever is necessary to bring an \meta{EDS} into
normal form, invert a transformation, and so on. The relevant restrictions
will be made automatically, so no inconsistency should arise. In addition,
with \f{edssloppy} \f{on}, all quasilinear systems are treated as if they
were semilinear (cf section \ref{semilinear}). \f{edssloppy} is \f{off} by
default.


\subsection{\tt edsdisjoint}
\label{edsdisjoint}

When decomposing a variety into (something like) smooth components, EDS
normally pays no attention to whether the components are disjoint. Turning
\f{on} the switch \f{edsdisjoint} forces EDS to ensure the decomposition is
a disjoint union (cf \f{disjoin}, section \ref{disjoin}). For large
problems this can lead to a proliferation of singular pieces. If some of
these turn out to be uninteresting, EDS cannot re-join the remaining pieces
into a smaller decomposition. \f{edsdisjoint} is \f{off} by default.

\subsection{\tt ranpos, genpos}
\label{ranpos}

When calculating Cartan characters (eg to check involution), EDS uses the
independence condition of an \meta{EDS} {\em as presented} to define a flag
of integral elements. Depending on the cobasis and ordering, this flag may
be singular, leading to incorrect Cartan characters. To overcome this
problem, the switches \f{ranpos} and \f{genpos} provide a means to select
other flags. With \f{ranpos} \f{on}, a flag defined by taking a random
linear transformation of the 1-forms in the independence condition will be
used. The results may still be incorrect, but the likelihood is much lower.
With \f{genpos} on, a generic (upper triangular) transformation is
used. this guarantees the correct Cartan characters, but reduces
performance too much to be useful for large problems. Both switches are
\f{off} by default, and switching one \f{on} automatically switches the other
\f{off}. See section \ref{characters} for an example.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Auxiliary functions}
\label{Auxiliary functions}

This section describes various operators designed to ease working with
exterior forms and exterior systems in REDUCE.

\subsubsection{\tt invert}
\label{invert}

\begin{edssyntax}
	invert \meta{transform}
\end{edssyntax}
returns a \meta{transform} which is inverse to the given one (section
\ref{transform}). If the \meta{transform} given is only partial, the
1-form \meta{kernel}s to eliminate are chosen based on the prevailing
kernel ordering. If a background coframing (section \ref{Background
coframing}) is active, and \f{edssloppy} (section \ref{edssloppy}) is
\f{off}, \f{invert} will divide by nowhere-zero expressions only.

\paragraph{\it Examples:}
\begin{verbatim}
set_coframing coframing{u,v,w,x,y,z}$
invert {d u = 3*d x - d y + 5*d z, d v = d x + 2*d z};

   {d x=d v - 2*d z,d y= - d u + 3*d v - d z}

% A y coefficient forces a different choice of inverse

invert {d u = 3*d x - y*d y + 5*d z, d v = d x + 2*d z};

   {d x=2*d u - 5*d v + 2*d y*y,d z= - d u + 3*d v - d y*y}
\end{verbatim}


% \subsubsection{\tt exact}
% \label{exact}

% \begin{edssyntax}
% 	exact \meta{expr}
% \end{edssyntax}
% is a boolean operator which tests if the given expression is an exact
% \meta{kernel} (ie $\deriv x$ for some variable $x$). More general exact
% expressions are not recognised

% \paragraph{\it Examples:}
% \begin{verbatim}
% if exact d x then yes;

%    yes

% if exact d(x+y) then yes else no;

%    no
% \end{verbatim}

\subsubsection{\tt linear\_divisors}
\label{linear_divisors}

\begin{edssyntax}
	linear\_divisors \meta{pform}
\end{edssyntax}
returns a basis for the space of linear divisors (1-form factors) of a
\meta{p-form}.

\paragraph{\it Example:}
\begin{verbatim}
f := d p^d q^d u - d p^d q^d x*x + d p^d q^d z*y
     - d u^d v^d x*x + d u^d v^d z*y + d u^d x^d y
     + d x^d y^d z*y$
linear_divisors f;

   {d u - d x*x + d z*y}
\end{verbatim}

\subsubsection{\tt exfactors}
\label{exfactors}
\begin{edssyntax}
	exfactors \meta{pform}
\end{edssyntax}
returns a list of factors for a \meta{p-form}, consisting of the linear
divisors plus one more factor. The list is ordered such that the original
expression is a product of the factors in this order.

\paragraph{\it Example:}
\begin{verbatim}
f := d p^d q^d u - d p^d q^d x*x + d p^d q^d z*y
     - d u^d v^d x*x + d u^d v^d z*y + d u^d x^d y
     + d x^d y^d z*y$
exfactors f;

   {d p^d q - d v^d x*x + d v^d z*y + d x^d y,
    d u - d x*x + d z*y}

f - (part(ws,0) := ^);

   0
\end{verbatim}

\subsubsection{\tt index\_expand}
\label{index_expand}

EXCALC caters for indexed variables in which various index names have been
assigned a specific set of values. Any expression with {\em paired} indices
is expanded automatically to an explicit sum over the index set (provided
the EXCALC command \f{nosum} has not been applied). The EDS operator
\f{index\_expand} is designed to expand an expression with {\em free}
indices to an explicit list over the index set, taking some limited account
of the possible index symmetries.

The syntax is
\begin{edssyntax}
	index\_expand \meta{arg}
\end{edssyntax}
where \meta{arg} can be an expression, a rule or equation or a boolean
expression, or an arbitrarily nested list of these items. The result is a
flattened list.

\paragraph{\it Examples:}
\begin{verbatim}
indexrange {i,j,k}={1,2,3},{a,b}={x,y};
pform {e(i),o(a,b)}=1;
index_expand(e(i)^e(j));

     1  2  1  3  2  3
   {e ^e ,e ^e ,e ^e }

index_expand{o(-a,-b)+o(-b,-a) => 0};

   {2*o    => 0,o    + o    => 0, 2*o    => 0}
       x x       x y    y x          y y
\end{verbatim}


\subsubsection{\tt pde2jet}
\label{pde2jet}

A PDE system can be encoded into EDS jet variable notation using
\f{pde2jet}. The syntax is as for \f{pde2eds}:
\begin{edssyntax}
	pde2jet(\meta{pde}\optional{,\meta{dependent},\meta{independent}})
\end{edssyntax}
where \meta{pde} is a list of equations or expressions (implicitly assumed
to vanish) specifying the PDE system using either the standard REDUCE
\f{df} operator, or the EXCALC \f{@} operator. If the optional variable
lists \meta{dependent} and \meta{independent} are not given, \f{pde2jet}
infers them from the expressions in \meta{pde}, using the same rules as
\f{pde2eds} (section \ref{pde2eds}).

The result of \f{pde2jet} is the input \meta{pde}, with all derivatives
of dependent variables replaced by indexed 0-form variables from the
appropriate jet bundle. Unlike \f{pde2eds}, \f{pde2jet} does not disturb
the variable dependencies.

\paragraph{\it Example:}
\begin{verbatim}
depend u,x,y; depend v,x,y;
pde2jet({df(u,y,y)=df(v,x),df(v,y)=y*df(v,x)});

   {u   =v ,
     y y  x

    v =v *y}
     y  x
\end{verbatim}


\subsubsection{\tt mkdepend}
\label{mkdepend}

The \f{mkdepend} operator is intended for restoring the dependencies
destroyed by a call to \f{pde2eds} (section \ref{pde2eds}). The syntax is
\begin{edssyntax}
	mkdepend \{\meta{list of variables},$\cdots$\}
\end{edssyntax}
where the first variable in each list is declared to depend on the
remaining ones.


\subsubsection{\tt disjoin}
\label{disjoin}

The \f{disjoin} operator takes a list of \meta{maps} (section \ref{Maps})
describing a decomposition of a variety, and returns an equivalent list of
\meta{maps} such that the components are all disjoint. The background
coframing (section \ref{Background coframing}) should be set appropriately
before calling \f{disjoin}. The syntax is
\begin{edssyntax}
	disjoin \{\meta{map},$\cdots$\}
\end{edssyntax}

\paragraph{\it Example:}
\begin{verbatim}
set_coframing coframing {x,y};
disjoin {{x=0},{y=0}};

   {{y=0,x neq 0},{x=0,y neq 0},{y=0,x=0}}
\end{verbatim}

\subsubsection{\tt cleanup}
\label{cleanup}

To avoid lengthy recomputations, EDS stores various properties (section
\ref{Properties}) and also many intermediate results in a hidden list
attached to each \meta{EDS}. When EDS detects a change in circumstances
which could make the information innacurate, it is discarded and
recomputed. Unfortunately, this mechanism is not perfect, and occasionally
misses something which renders the results incorrect. In such a case, it is
possible to discard all the properties and hidden information using the
\f{cleanup} operator. The call
\begin{edssyntax}
	cleanup \meta{arg}
\end{edssyntax}
returns a copy of \meta{arg}, which may be a \meta{coframing} or an
\meta{EDS} which has been stripped of this auxilliary information. Note
that the original input (with possible innacuracies) is left undisturbed by
this operation: the result of \f{cleanup} must be used.

\paragraph{\it Example:}
\begin{verbatim}
% An erroneous property assertion
S := eds({d u - p*d x},{d x,d y},{closed = 1})$
closure S;

   EDS({d u - p*d x},{d x,d y});

S := cleanup S$
properties S;

   {}

closure S;

   EDS({d u - p*d x, - d p^d x},{d x,d y});
\end{verbatim}

\subsubsection{\tt reorder}
\label{reorder}

All operations with a \meta{coframing} or \meta{EDS} temporarily override
the prevailing kernel order with their own. Thus the ordering of the
cobasis elements in a \meta{coframing} operator remains fixed, even when a
REDUCE \f{korder} statement is issued. To enforce conformity to the
prevailing kernel order, the \f{reorder} operator is available. The call
\begin{edssyntax}
	reorder \meta{arg}
\end{edssyntax}
returns a copy of \meta{arg}, which may be a \meta{coframing} or an
\meta{EDS} which has been reordered. Note that the original input is left
undisturbed by this operation: the result of \f{reorder} must be used.

\paragraph{\it Example:}
\begin{verbatim}
M := coframing {x,y,z};

   m := coframing({d x,d y,d z},{x,y,z},{},{})

korder z,y,x;
reorder m;

   coframing({d z,d y,d x},{z,y,x},{},{})
\end{verbatim}



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{Experimental facilities}
\label{Experimental facilities}

This section describes various operators in EDS which either not
algorithmically well-founded, or whose implementation is very unstable, or
which have known bugs.


\subsubsection{\tt poincare}
\label{poincare}

The \f{poincare} operator implements the homotopy integral found in the
proof of Poincar{\'e}'s lemma. The expansion point is the origin of the
coordinates found in the input. The syntax is
\begin{edssyntax}
	poincare \meta{p-form}
\end{edssyntax}
If \f{f} is a $p$-form, then \f{poincare f} is a $(p-1)$-form, and
\f{f - poincare d f} is an exact $p$-form.

\paragraph{\it Examples:}
\begin{verbatim}
poincare(3*d x^d y^d z);

   d x^d y*z - d x^d z*y + d y^d z*x

d ws;

   3*d x^d y^d z

2*x*d y - poincare d(2*x*d y);

   d x*y + d y*x
\end{verbatim}


\subsubsection{\tt invariants}
\label{invariants}

The \f{invariants} operator implements the algorithm implicit in the
inductive proof of the Frobenius theorem. The syntax is
\begin{edssyntax}
	invariants(\meta{system}\optional{,\meta{list of coordinate}})
\end{edssyntax}
where \meta{system} is a set of 1-forms satisfying the Frobenius condition.
The optional second argument specifies the order in which the coordinates
are projected away to get a trivially integrable system.  The CRACK and
ODESOLVE packages are used to solve the ODE systems which arise, so the
limitations of these packages constrain the scope of this operator as well.

\paragraph{\it Examples:}
\begin{verbatim}
invariants {d x*y + d y*x*z + d z*log(y)*x*y};

        z
   { - y *x}

invariants {d y*z**2 - d y*z + d z*y,d x*(1 - z) + d z*x};

       x     y*(z - 1)
   {-------,-----------}
     z - 1       z
\end{verbatim}


\subsubsection{\tt symbol\_relations}
\label{symbol_relations}

The \f{symbol\_relations} operator finds the linear relations between the
entries of the tableau matrix for a quasilinear system. The syntax is
\begin{syntax}
  \f{symbol\_relations}(\meta{EDS},\,\meta{identifier})
\end{syntax}
where \meta{EDS} is a quasilinear Pfaffian system and \meta{identifier} is
used to create a 2-indexed 1-form which will label the tableau entries.

\paragraph{\it Example:}
\begin{verbatim}
S := pde2eds {df(u,y,y) = df(u,x,x)};

   s := EDS({d u - u *d x - u *d y,
                    x        y

             d u  - u   *d x - u   *d y,
                x    x x        x y

             d u  - u   *d x - u   *d y},d x^d y)
                y    x y        x x

symbol_relations(S,pi);

      1       2
   {pi    - pi   ,
        x       y
      1       2
    pi    - pi   }
        y       x
\end{verbatim}

\subsubsection{\tt symbol\_matrix}
\label{symbol_matrix}

The \f{symbol\_matrix} operator returns the symbol matrix for a quasilinear
system in terms of a given variable. The syntax is
\begin{syntax}
  \f{symbol\_matrix}(\meta{EDS},\,\meta{identifier})
\end{syntax}
where \meta{EDS} is a quasilinear Pfaffian system and \meta{identifier} is
used to create an indexed 0-form which will parameterise the matrix.

\paragraph{\it Example:}
\begin{verbatim}
% With the same system as for symbol_relations:

symbol_matrix(S,xi);

   [xi    - xi ]
   [  x       y]
   [           ]
   [xi    - xi ]
   [  y       x]
\end{verbatim}

\subsubsection{\tt characteristic\_variety}
\label{characteristic_variety}

The \f{characteristic\_variety} operator returns the equations specifying
the characteristic variety for a quasilinear
system in terms of a given variable. The syntax is
\begin{syntax}
  \f{characteristic\_variety}(\meta{EDS},\,\meta{identifier})
\end{syntax}
where \meta{EDS} is a quasilinear Pfaffian system and \meta{identifier} is
used to create an indexed 0-form variable. The result is a list of two
lists: the first being the variety equations and the second the variables
involved.

\paragraph{\it Example:}
\begin{verbatim}
% With the same system as for symbol_relations:

characteristic_variety(S,xi);

          2        2
   {{(xi )  - (xi ) },
        x        y
    {xi ,xi }}
       x   y
\end{verbatim}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% \subsection{Examples}
% \label{Examples}

% This section contains some longer examples showing complete calculations
% using the facilities of EDS.

% \subsubsection{Twisting type-N solutions to Einstein's equations}
% \label{Twisting type-N solutions to Einstein's equations}

% \subsubsection{Isometric immersions}
% \label{Isometric immersions}

% \subsubsection{Riemannian submersions}
% \label{Riemannian submersions}

% \subsubsection{The ``Janet'' problem}
% \label{The ``Janet'' problem}\label{janet}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%\newpage
%\appendix
\subsection{Command tables}\label{tables}


\def\literal#1{\hbox{\texttt{#1}}}


% Command Table environment

\newsavebox{\commandtablecaption}
\newenvironment{commandtable}[2]
   {%\savebox\commandtablecaption{#1} % save caption for the end
    \def\mkcaption{\caption{#1}\label{#2}}
    \def\header##1{\rule[-.7\baselineskip]{0pt}{2\baselineskip}\textbf{##1}}
    \table[htbp]\small\tabular{|p{.4\hsize}|p{.5\hsize}|}\hline}
   {\endtabular%\caption{\usebox\commandtablecaption}
    \mkcaption\endtable}
\def\nl{\par}             % for use within columns

% Text

The tables in this appendix summarise the commands available in EDS.
More detailed descriptions of the syntax and function of each command
are to be found in the earlier sections. In each case, examples of
the command are given, whereby the argument variables have the following
types (see section \ref{EDS data structures and concepts}):

\bigskip
\begin{tabular}{ll}
$E$, $E'$   &\meta{EDS}\\
$S$         &\meta{system}\\
$M$, $N$    &\meta{coframing}, or a \meta{system} specifying a \meta{coframing}\\
$r$         &\meta{integer}\\
$\Omega$    &\meta{p-form}\\
$f$         &\meta{map}\\
$rsx$       &\meta{list of inequalities}\\
$cob$       &\meta{list of 1-form variables}\\
$crd$, $dep$, $ind$
            &\meta{list of 0-form variables}\\
$drv$       &\meta{list of rules for exterior derivatives}\\
$pde$       &\meta{list of expressions or equations}\\
$X$         &\meta{transform}\\
$T$         &\meta{tableau}\\
$P$         &\meta{integral element}\\
\end{tabular}

\begin{commandtable}{Commands for constructing EDS objects}{constructors}
\header{Command}
    &\header{Function}\\\hline
\literal{coframing($cob$,$crd$,$rsx$,$drv$)}
    &constructs a \meta{coframing} with the given cobasis $cob$, coordinates $crd$,
     restrictions $rsx$ and structure equations $drv$: $crd$, $rsx$ and $drv$
     are optional\\\hline
\literal{coframing($S$)}
    &constructs a \meta{coframing} capable of supporting the given
     \meta{system}\\\hline
\literal{eds($S$,$\Omega$,$M$)}
    &constructs a simple \meta{EDS} object with given system and independence
     condition: if $M$ is not supplied, it is deduced from the rest\\\hline
\literal{contact($r$,$M$,$N$)}
    &constructs the \meta{EDS} for the contact system of the jet bundle
     $J^r(M,N)$\\\hline
\literal{pde2eds($pde$,$dep$,$ind$)}
    &converts a PDE system to an EDS: dependent and independent
    variables are deduced if they are not specified (variable dependencies
    are removed)\\\hline
\literal{set\_coframing($M$)}\nl
\literal{set\_coframing($E$)}
    &sets background coframing and returns previous one\\\hline
\literal{set\_coframing()}
    &clears background coframing and returns previous one\\\hline
\end{commandtable}


\begin{commandtable}{Commands for inspecting EDS objects}{selectors}
\header{Command}
    &\header{Function}\\\hline
\literal{coframing($E$)}
    &extracts the underlying \meta{coframing}\\\hline
\literal{coframing()}
    &returns the current background coframing\\\hline
\literal{cobasis($M$)}\nl \literal{cobasis($E$)}
    &extracts the underlying cobasis\\\hline
\literal{coordinates($M$)}\nl \literal{coordinates($E$)}
    &extracts the coordinates\\\hline
\literal{structure\_equations($M$)}\nl \literal{structure\_equations($E$)}
    &extracts the rules for exterior derivatives for cobasis and
     coordinates\\\hline
\literal{restrictions($M$)}\nl \literal{restrictions($E$)}
    &extracts the inequalities describing the restrictions
     in the \meta{coframing}\\\hline
\literal{system($E$)}
    &extracts the \meta{system} part of $E$\\\hline
\literal{independence($E$)}
    &extracts the independence condition from $E$ as a Pfaffian
     \meta{system}\\\hline
\literal{properties($E$)}
    &returns the currently known properties of the \meta{EDS} $E$ as a list of
     equations \meta{keyword}$ = $\meta{value}\\\hline
\literal{one\_forms($E$)}\nl \literal{one\_forms($S$)}
    &selects the 1-forms from a system\\\hline
\literal{zero\_forms($E$)}\nl \literal{zero\_forms($S$)}
    &selects the 0-forms from a system\\\hline
\end{commandtable}


\begin{commandtable}{Commands for manipulating EDS objects}{manipulators}
\header{Command}
    &\header{Function}\\\hline
\literal{augment($E$,$S$)}
    &appends the extra forms in $S$ to the system in $E$\\\hline
\literal{$M$ cross $N$}\nl \literal{$E$ cross $N$}
    &forms the direct product of two coframings: an \meta{EDS} $E$ is lifted
     to the extended space\\\hline
\literal{pullback($E$,$f$)}\nl \literal{pullback($S$,$f$)}\nl \literal{pullback($\Omega$,$f$)}
    &pulls back the first argument using the \meta{map} $f$\\\hline
\literal{pullback($M$,$f$)}
    &returns a \meta{coframing} $N$ suitable as the source for $f:N\to M$\\\hline
\literal{restrict($E$,$f$)}\nl \literal{restrict($S$,$f$)}\nl \literal{restrict($\Omega$,$f$)}
    &restricts the first argument to the points specified by the
     \meta{map} $f$\\\hline
\literal{restrict($M$,$f$)}
    &adds the restrictions in $f$ to $M$\\\hline
\literal{transform($M$,$X$)}\nl \literal{transform($E$,$X$)}\nl
\literal{transform($S$,$X$)}\nl \literal{transform($\Omega$,$X$)}
    &applies the change of cobasis $X$ to the first argument: for a \meta{coframing}
     $M$ or an \meta{EDS} $E$, $X$ may be specified in either the forward or
     reverse direction\\\hline
\literal{lift($E$)}
    &eliminates any 0-forms in $E$ by solving and pulling back\\\hline
\end{commandtable}


\begin{commandtable}{Commands for analysing exterior systems}{analysers}
\header{Command}
    &\header{Function}\\\hline
\literal{cartan\_system($E$)}\nl \literal{cartan\_system($S$)}\nl \literal{cartan\_system($\Omega$)}
    &calculates the Cartan system (associated Pfaff system, retracting
     space): no differentiations are performed\\\hline
\literal{cauchy\_system($E$)}\nl \literal{cauchy\_system($S$)}\nl \literal{cauchy\_system($\Omega$)}
    &calculates the Cauchy system: the Cartan system of the closure under
     exterior differentiation\\\hline
\literal{characters($E$)} \nl \literal{characters($T$)}
    &calculates the (reduced) Cartan characters $\{s_1,...,s_n\}$
     ($E$ quasilinear)\\\hline
\literal{characters($E$,$P$)}
    &Cartan characters for a non-linear $E$ at integral element $P$\\\hline
\literal{closure($E$)}
    &calculates the closure of $E$ under exterior
    differentiation\\\hline
\literal{derived\_system($E$)}\nl \literal{derived\_system($S$)}
    &calculates the first derived system of the Pfaffian system $E$ or
    $S$\\\hline
\literal{dim\_grassmann\_variety($E$)}\nl \literal{dim\_grassmann\_variety($E$,$P$)}
    &dimension of the Grassman bundle variety of integral elements: for
    non-linear $E$, the base element $P$ must be given\\\hline
\literal{dim($M$)}\nl \literal{dim($E$)}
    &returns the manifold dimension\\\hline
\literal{involution($E$)}
    &repeatedly prolongs $E$ to involution (or inconsistency)\\\hline
\literal{linearise($E$,$P$)}
    &linearise the (non-linear) EDS $E$ with respect to the integral element
     $P$\\\hline
\literal{integral\_element($E$)}
    &find a random \meta{integral element} of $E$\\\hline
\literal{prolong($E$)}
    &prolongs $E$, and projects back down to a subvariety of the
     original manifold if integrability conditions arise\\\hline
\literal{tableau($E$)}
    &calculates the \meta{tableau} of the quasilinear Pfaffian \meta{EDS}
     $E$\\\hline
\literal{torsion($E$)}
    &returns a \meta{system} of 0-forms specifying the integrability
     conditions for the semilinear or quasilinear Pfaffian \meta{EDS}
     $E$\\\hline
\literal{grassmann\_variety($E$)}
    &returns the contact \meta{EDS} for the Grassmann bundle of $n$-planes
     over the manifold of $E$, augmented by the 0-forms specifying the
     variety of integral elements of $E$\\\hline
\end{commandtable}


\begin{commandtable}{Commands for testing exterior systems}{testers}
\header{Command}
    &\header{Function}\\\hline
\literal{closed($E$)}\nl \literal{closed($S$)}\nl \literal{closed($\Omega$)}
    &checks for closure under exterior differ\-entiation\\\hline
\literal{involutive($E$)}
    &applies Cartan's test for involution\\\hline
\literal{pfaffian($E$)}
    &checks if $E$ is generated by 1-forms and their exterior
     derivatives\\\hline
\literal{quasilinear($E$)}
    &tests if the {\it closure} of $E$ can be generated by forms at
     most linear in the complement of the independence condition\\\hline
\literal{semilinear($E$)}
    &tests if the {\it closure} of $E$ is quasilinear and, in addition, the
    coefficients of the linear terms contain only independent variables or
    constants\\\hline
\literal{$E$ equiv $E'$}
    &checks whether $E$ and $E'$ are algebraically equivalent\\\hline
\end{commandtable}


\begin{commandtable}{Switches (all \literal{off} by default)}{edsswitches}
\header{Switch}
    &\header{Function}\\\hline
\literal{edsverbose}
    &if \literal{on}, displays additional information as calculations
    progress\\\hline
\literal{edsdebug}
    &if \literal{on}, produces copious quantities of internal information,
    in addition to that produced by \literal{edsverbose}\\\hline
\literal{edssloppy}
    &if \literal{on}, allows EDS to divide by expressions not known to be non-zero
    and treats quasilinear systems as semilinear\\\hline
\literal{edsdisjoint}
    &if \literal{on}, forces varieties to be decomposed into disjoint
    components\\\hline
\literal{ranpos}\nl \literal{genpos}
    &if \literal{on}, uses a random or generic flag of integral elements when
    calculating Cartan characters: otherwise the independence condition as
    presented guides the choice of flag\\\hline
\end{commandtable}


\begin{commandtable}{Auxilliary functions}{auxilliaries}
\header{Command}
    &\header{Function}\\\hline
\nl \literal{coordinates($S$)}
    &scans the expressions in $S$ for coordinates\\\hline
\literal{invert($X$)}
    &returns the inverse \meta{transform} $X^{-1}$\\\hline
\literal{structure\_equations($X$)} \nl
\literal{structure\_equations($X$,$X^{-1}$)}
    &returns exterior derivatives of $\mathop{\hbox{lhs}}(X)$\\\hline
\literal{linear\_divisors($\Omega$)}
    &calculates a basis for the space of 1-form factors of
     $\Omega$\\\hline
\literal{exfactors($\Omega$)}
    &as for \literal{linear\_divisors}, but with the additional (non-linear) factor\\\hline
\literal{index\_expand($any$)}
    &returns a list of copies of its argument, with free EXCALC indices
     replaced by successive values from the relevant index range\\\hline
\literal{pde2jet($pde$,$dep$,$ind$)}
    &converts a PDE system into jet bundle notation, replacing derivatives by
     jet bundle coordinates (variable dependencies are not affected)\\\hline
\literal{mkdepend($list$)}
    &restores variable dependencies destroyed by \literal{pde2eds}\\\hline
\literal{disjoin($\{f,g,...\}$)}
    &decomposes the variety specified by the given \meta{map} variables into
     a disjoint union\\\hline
\literal{cleanup($E$)}\nl \literal{cleanup($M$)}
    &returns a fresh copy of $E$ or $M$ with all properties and stored
     results removed\\\hline
\literal{reorder($E$)}\nl \literal{reorder($M$)}
    &returns a fresh copy of $E$ or $M$, conforming to the prevailing
    REDUCE kernel order\\\hline
\end{commandtable}


\begin{commandtable}{Experimental functions (unstable)}{experiments}
\header{Command}
    &\header{Function}\\\hline
\literal{poincare($\Omega$)}
    &calculates the homotopy integral from the proof of Poincar{\'e}'s lemma:
    if $\Omega$ is exact, then the result is a form whose exterior derivative
    gives back $\Omega$\\\hline
\literal{invariants($E$,$crd$)}\nl \literal{invariants($S$,$crd$)}
    &calculates the invariants (first integrals) of a completely
    integrable Pfaffian system using the inductive proof of the Frobenius
    theorem: the optional second argument specifies the
    order in which the coordinates are to be projected away\\\hline
\literal{symbol\_relations($E$,$\pi$)}
    &returns relations between the entries of the tableau
    matrix, represented by 2-indexed \meta{1-form} variables $\pi^a{}_i$\\\hline
\literal{symbol\_matrix($E$,$\xi$)}
    &returns the symbol matrix for a quasilinear \meta{EDS} $E$ as a function
    of \meta{0-form} variables $\xi_i$\\\hline
\literal{characteristic\_variety($E$,$\xi$)}
    &returns equations describing the characteristic variety of
    $E$ in terms of \meta{0-form} variables $\xi_i$\\\hline
\end{commandtable}

%\catcode`\"=12\relax
%\catcode`\<=12\relax

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\clearpage