
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


% Example file for DSMP, ODPOL, SDPOL

Many systems of differential equations may be transformed to equivalent
\index{differential equation}
systems of ordinary differential equations where the equations are
\index{equation!differential}
expressed polynomially in terms of the unknown functions.
\index{polynomial!differential polynomial}
In \Language{}, the domain constructors
\spadtype{OrderlyDifferentialPolynomial}
\index{differential polynomial}
(abbreviated \spadtype{ODPOL}) and
\spadtype{SequentialDifferentialPolynomial} (abbreviation
\spadtype{SDPOL}) implement two domains of ordinary differential
polynomials over any differential ring.
In the simplest case, this differential ring is usually either the ring of
integers, or the field of rational numbers.
However, \Language{} can handle ordinary differential polynomials over a
field of rational functions in a single indeterminate.
\exptypeindex{OrderlyDifferentialPolynomial}
\exptypeindex{SequentialDifferentialPolynomial}

The two domains \spadtype{ODPOL} and \spadtype{SDPOL} are almost
identical, the only difference being the choice of a different ranking,
which is an ordering of the derivatives of the indeterminates.
The first domain uses an orderly ranking, that is, derivatives of higher
order are ranked higher, and derivatives of the same order are ranked
alphabetically.
The second domain uses a sequential ranking, where derivatives are ordered
first alphabetically by the differential indeterminates, and then by
order.
A more general domain constructor,
\spadtype{DifferentialSparseMultivariatePolynomial} (abbreviation
\spadtype{DSMP}) allows both a user-provided list of differential
indeterminates as well as a user-defined ranking.
We shall illustrate \spadtype{ODPOL(FRAC INT)}, which constructs a domain
of ordinary differential polynomials in an arbitrary number of
differential indeterminates with rational numbers as coefficients.
\xtc{
}{
\spadcommand{dpol:= ODPOL(FRAC INT) \bound{dpol}}
}

\xtc{
A differential indeterminate \spad{w} may be viewed as an infinite
sequence of algebraic indeterminates, which are the derivatives of
\spad{w}.
To facilitate referencing these, \Language{} provides the operation
\spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial} to convert an
element of type \spadtype{Symbol} to a map from the natural numbers to the
differential polynomial ring.
}{
\spadcommand{w := makeVariable('w)\$dpol \free{dpol}\bound{w}}
}
\xtc{
}{
\spadcommand{z := makeVariable('z)\$dpol \free{dpol}\bound{z}}
}
\xtc{
The fifth derivative of \spad{w} can be obtained by applying the map
\spad{w} to the number \spad{5.}
Note that the order of differentiation is given as a subscript (except
when the order is 0).
}{
\spadcommand{w.5 \free{w}}
}
\xtc{
}{
\spadcommand{w 0 \free{w}}
}
\xtc{
The first five derivatives of \spad{z} can be generated by a list.
}{
\spadcommand{[z.i for i in 1..5] \free{z}}
}
\xtc{
The usual arithmetic can be used to form a differential polynomial from
the derivatives.
}{
\spadcommand{f:= w.4 - w.1 * w.1 * z.3 \free{w}\free{z}\bound{f}}
}
\xtc{
}{
\spadcommand{g:=(z.1)^3 * (z.2)^2 - w.2 \free{z}\free{w}\bound{g}}
}
\xtc{
The operation \spadfunFrom{D}{OrderlyDifferentialPolynomial}
computes the derivative of any differential polynomial.
}{
\spadcommand{D(f) \free{f}}
}
\xtc{
The same operation can compute higher derivatives, like the
fourth derivative.
}{
\spadcommand{D(f,4) \free{f}}
}
\xtc{
The operation \spadfunFrom{makeVariable}{OrderlyDifferentialPolynomial}
creates a map to facilitate referencing the derivatives of \spad{f},
similar to the map \spad{w}.
}{
\spadcommand{df:=makeVariable(f)\$dpol \free{f}\bound{df}}
}
\xtc{
The fourth derivative of f may be referenced easily.
}{
\spadcommand{df.4 \free{df}}
}
\xtc{
The operation \spadfunFrom{order}{OrderlyDifferentialPolynomial}
returns the order of a differential polynomial, or the order
in a specified differential indeterminate.
}{
\spadcommand{order(g)  \free{g}}
}
\xtc{
}{
\spadcommand{order(g, 'w)  \free{g}}
}
\xtc{
The operation
\spadfunFrom{differentialVariables}{OrderlyDifferentialPolynomial} returns
a list of differential indeterminates occurring in a differential
polynomial.
}{
\spadcommand{differentialVariables(g)  \free{g}}
}
\xtc{
The operation \spadfunFrom{degree}{OrderlyDifferentialPolynomial} returns
the degree, or the degree in the differential indeterminate specified.
}{
\spadcommand{degree(g) \free{g}}
}
\xtc{
}{
\spadcommand{degree(g, 'w)  \free{g}}
}
\xtc{
The operation \spadfunFrom{weights}{OrderlyDifferentialPolynomial} returns
a list of weights of differential monomials appearing in differential
polynomial, or a list of weights in a specified differential
indeterminate.
}{
\spadcommand{weights(g)  \free{g}}
}
\xtc{
}{
\spadcommand{weights(g,'w) \free{g}}
}
\xtc{
The operation \spadfunFrom{weight}{OrderlyDifferentialPolynomial} returns
the maximum weight of all differential monomials appearing in the
differential polynomial.
}{
\spadcommand{weight(g)  \free{g}}
}
\xtc{
A differential polynomial is {\em isobaric} if the weights of all
differential monomials appearing in it are equal.
}{
\spadcommand{isobaric?(g) \free{g}}
}
\xtc{
To substitute {\em differentially}, use
\spadfunFrom{eval}{OrderlyDifferentialPolynomial}.
Note that we must coerce \spad{'w} to \spadtype{Symbol}, since in
\spadtype{ODPOL}, differential indeterminates belong to the domain
\spadtype{Symbol}.
Compare this result to the next, which substitutes {\em algebraically} (no
substitution is done since \spad{w.0} does not appear in \spad{g}).
}{
\spadcommand{eval(g,['w::Symbol],[f]) \free{f}\free{g}}
}
\xtc{
}{
\spadcommand{eval(g,variables(w.0),[f]) \free{f}\free{g}}
}
\xtc{
Since \spadtype{OrderlyDifferentialPolynomial} belongs to
\spadtype{PolynomialCategory}, all the operations defined in the latter
category, or in packages for the latter category, are available.
}{
\spadcommand{monomials(g) \free{g}}
}
\xtc{
}{
\spadcommand{variables(g) \free{g}}
}
\xtc{
}{
\spadcommand{gcd(f,g) \free{f}\free{g}}
}
\xtc{
}{
\spadcommand{groebner([f,g]) \free{f}\free{g}}
}
\xtc{
The next three operations are essential for elimination procedures in
differential polynomial rings.
The operation \spadfunFrom{leader}{OrderlyDifferentialPolynomial} returns
the leader of a differential polynomial, which is the highest ranked
derivative of the differential indeterminates that occurs.
}{
\spadcommand{lg:=leader(g)  \free{g}\bound{lg}}
}
\xtc{
The operation \spadfunFrom{separant}{OrderlyDifferentialPolynomial} returns
the separant of a differential polynomial, which is the partial derivative
with respect to the leader.
}{
\spadcommand{sg:=separant(g)  \free{g}\bound{sg}}
}
\xtc{
The operation \spadfunFrom{initial}{OrderlyDifferentialPolynomial} returns
the initial, which is the leading coefficient when the given differential
polynomial is expressed as a polynomial in the leader.
}{
\spadcommand{ig:=initial(g)  \free{g}\bound{ig}}
}
\xtc{
Using these three operations, it is possible to reduce \spad{f} modulo the
differential ideal generated by \spad{g}.
The general scheme is to first reduce the order, then reduce the degree in
the leader.
First, eliminate \spad{z.3} using the derivative of \spad{g}.
}{
\spadcommand{g1 := D g \free{g}\bound{g1}}
}
\xtc{
Find its leader.
}{
\spadcommand{lg1:= leader g1 \free{g1}\bound{lg1}}
}
\xtc{
Differentiate \spad{f} partially with respect to this leader.
}{
\spadcommand{pdf:=D(f, lg1) \free{f}\free{lg1}\bound{pdf}}
}
\xtc{
Compute the partial remainder of \spad{f} with respect to \spad{g}.
}{
\spadcommand{prf:=sg * f- pdf * g1 \free{f}\free{sg}\free{pdf}\free{g1}\bound{prf}}
}
\xtc{
Note that high powers of \spad{lg} still appear in \spad{prf}.
Compute the leading coefficient of \spad{prf}
as a polynomial in the leader of \spad{g}.
}{
\spadcommand{lcf:=leadingCoefficient univariate(prf, lg) \free{prf}\free{lg}\bound{lcf}}
}
\xtc{
Finally, continue eliminating the high powers of \spad{lg} appearing in
\spad{prf} to obtain the (pseudo) remainder of \spad{f} modulo \spad{g}
and its derivatives.
}{
\spadcommand{ig * prf - lcf * g * lg \free{ig}\free{prf}\free{lcf}\free{g}\free{lg}}
}
\showBlurb{OrderlyDifferentialPolyomial}
\showBlurb{SequentialDifferentialPolynomial}
