
==============================================
Computer Algebra with Pure: A Reduce Interface
==============================================

.. default-domain:: pure
.. module:: reduce

Version @version@, |today|

| Albert Graef <aggraef@gmail.com>
| Kurt Pagani <kp@scios.ch>

One of Pure's distinguishing features as a term rewriting programming language
is that it makes the symbolic manipulation of expressions very easy and
convenient. It is thus a natural environment for hosting a full-featured
computer algebra system (CAS). Computer algebra systems are complex pieces of
software featuring advanced algorithms for simplification of algebraic
expressions, symbolic integration, equation solving and much more.
Reimplementing all these algorithms in Pure would be a major undertaking, to
say the least. A much better option is to interface to an existing CAS which
has already proven its worth to the scientific computing community, has been
tested extensively and is known to be both reliable and efficient.

This is also the approach taken by Pure's :mod:`reduce` module which
interfaces to the well-known Reduce_ system. Along with Macsyma/`Maxima`_,
Reduce is one of the oldest computer algebra systems which has been around
since the 1960s and is widely recognized as a state-of-the-art, powerful and
efficient CAS. It is free/open source software distributed under a BSD-style
license_, actively maintained on its SourceForge_ website, and implementations
exist for all major computing platforms. The :mod:`reduce` module makes the
functionality of Reduce available in Pure in a seamless way. It uses an
"embedded" version of Reduce in the form of a shared library which is easy to
build from the Reduce sources; the Installation_ section below describes how
to do this. More background information and a discussion of the interface can
be found in the `Embedding REDUCE`_ thread on the Pure mailing list.

.. _Reduce: http://reduce-algebra.sourceforge.net/
.. _Maxima: http://maxima.sourceforge.net/
.. _SourceForge: http://sourceforge.net/projects/reduce-algebra/
.. _license: http://www.reduce-algebra.com/license.htm
.. _Embedding REDUCE: http://groups.google.com/group/pure-lang/browse_thread/thread/c11e82ca2e9e8cbb

The interface can be found in the reduce.pure module. It has two parts, a
`low-level interface`_ which consists of a handful of C entry points supplied
by the Reduce library, and a `high-level interface`_ which provides everything
that the Pure programmer needs to use Reduce from Pure. Please note that at
present this module is still experimental. But the basic functionality works,
and you're welcome to discuss the new interface on the mailing list and/or
submit bug reports and patches.

Copying
=======

pure-reduce is available under the same 2-clause BSD license_ as Reduce
itself, please see the accompanying COPYING file and the reduce.pure file for
details.

Installation
============

Get the latest source from
https://bitbucket.org/purelang/pure-lang/downloads/pure-reduce-@version@.tar.gz.

You'll need both the Reduce library (named reduce.so, reduce.dylib or
reduce.dll, depending on the system you have) and a Reduce image file
(reduce.img) to make this module work. A Makefile is included with this
package so that you can build these yourself from the Reduce sources. (In
principle, this only needs to be done once for the initial installation of
this module, but you may want to repeat this procedure every once in a while
to get the latest Reduce version.)

The full Reduce system is a big package, so we have packaged a stripped-down
version of the Reduce source which contains all the bits and pieces needed to
compile the Reduce library and image, and has also been patched up so that it
compiles cleanly on recent Linux systems. At the time of this writing, you can
find this package here:

    https://bitbucket.org/purelang/pure-lang/downloads/reduce-algebra-csl-r2204.tar.bz2

(You may want to check the download section on the Pure website for newer
revisions of this package, since we may update the package from time to time
to the latest source from the Reduce svn repository.)

Unpack the reduce-algebra-csl tarball and move the resulting reduce-algebra
directory into the pure-reduce source directory. Run ``make`` and then (if
needed) ``make install`` in the pure-reduce directory (*not* in the
reduce-algebra directory!). You should also run ``make check`` which performs
a few tests in order to verify that the interface works ok (this can be done
without installing the package, but needs the Reduce image and library).

For convenience, the Makefile also has a ``make reduce`` target which builds a
minimal Reduce executable. If you use that option, ``make install`` installs
this executable along with the library and image files, so that you can then
run Reduce directly from the command line by just typing ``reduce``. Please
note that this is a really minimalistic Reduce frontend which is most useful
for testing purposes. (If you want the full Reduce version then you can find
binary Reduce packages for various systems at SourceForge_. But note that
neither the minimalistic nor the full Reduce frontend is required for the
pure-reduce module in any way.)

It is also possible to build the Reduce library and image directly from the
latest source in the Reduce svn repository. You can check out the repository
with the following command:

.. code-block:: console

   svn co svn://svn.code.sf.net/p/reduce-algebra/code/trunk reduce-algebra

This pulls down many hundreds of megabytes, so this may take a while. Once the
checkout is finished, you'll end up with a reduce-algebra directory which you
can drop into the pure-reduce source directory and proceed with the
compilation as described above. Note that if you go that route then you should
be prepared to deal with compilation problems in the Reduce sources. Reduce is
a big and complicated software, so the svn sources are not always in a state
which guarantees smooth compilation on all supported systems. If you run into
problems then please consider using our streamlined reduce-algebra-csl package
instead.

