==============================================================================
README. Generated from README.in by configure.
==============================================================================
General information
===================
Name : mupad-combinat
Version : 1.3.3 (development)
Summary : MuPAD-Combinat -- Algebraic Combinatorics package for MuPAD
License : LGPL
Vendor: : Nicolas M. Thiéry <nthiery@users.sourceforge.net>
URL : http://mupad-combinat.sourceforge.net/
Requires : MuPAD
Description :
MuPAD-Combinat is an open-source algebraic combinatorics package for\
the Computer Algebra System MuPAD. Main features:\
* classical combinatorial classes such as permutations tableaux or trees;\
* classical combinatorial algebras such as symmetric functions;\
* tools for building user defined combinatorial classes and algebras.
Requirements
============
The computer algebra system MuPAD, version 2.0.0 or above. This system
is available in binary form for many operating systems:
http://www.mupad.com/download
Using the lastest version of MuPAD Pro (currently 4.0.*) is recommended:
- some features are more efficient there
- older versions of MuPAD require the package to apply compatibility
fixes to the MuPAD library; those might break accidently some other
parts of MuPAD; in case of doubt, please try to upgrade.
Free licences for MuPAD used to be available for personnal use and (up
to a point) research. This is no more the case, except for a 30 days
trial licence, and hopefuly temporarily. For details, see:
http://fuchssteiner.info/
Licences for all versions of MuPAD are available for the
MuPAD-Combinat developers. The licence keys can be fetched from the
sourceforge shell server:
scp shell.sf.net:/home/groups/m/mu/mupad-combinat/private/keys .
Most of the library is written in pure MuPAD, and should work on all
operating systems supported by MuPAD. The installation procedure
however is quite UNIX oriented; it has currently been successfully
tested on various flavors of Linux, on Open-BSD (note that there is no
official port of MuPAD for this system), as well as on Mac OS X, and
Windows + cygwin.
Here are the precise requirements outside of the library itself:
For the C++ dynamic modules:
- gcc >= 2.95 (Linux, MacOs X), Visual C++ (Windows)
gcc 4.0 may temporarilly cause some trouble
On MacOs X (Darwin): Xcode Tools >= 2.1 Open Source
(select at least gcc, java, Developer Tool Software, and Software Developments Kit)
For the xml documentation:
- java (GCJ runtime environment does not work yet; sorry but we have
to rely on Sun's JRE for the moment)
- perl
- ruby >= 1.8.4
For the html documentation:
- MuPAD >= 4.0.0
For the ascii documentation:
- ruby >= ???
For the optional compilation of the posters, papers, ...:
- a fairly recent distribution of latex, such as tetex-1.*;
- pdflatex
- tex4ht
For the installation procedure:
- gnu make
Hopefuly in the future any version of make will work.
Note: there are systems where GNU make is installed by default
under a different name, like 'gmake'. Just use this name instead of
'make' in all the 'make' commands below.
For interaction with linbox (work in progress):
- get givaro from ... ./configure; make; make install
- yum install atlas atlas-devel atlas-sse atlas-sse2 atlas-sse-devel
- get linbox >= 1.1.0
./configure --with-blas=/usr/lib/atlas --with-givaro --enable-optimization --enable-doc
make; make install
g++ -O0 linbox-rank.C -o linbox-rank -I../ -L/usr/local/lib -llinbox -lgmp -lgivaro -lgmpxx
For the C generation feature of the library combinat::decomposableObjects:
- gmp >= 4.0.0
Download and Installation
=========================
mupad-combinat is distributed on the web page (see above) in the following form:
- zip file with precompiled documentation and dynamic modules
for all platforms (Linux, Windows, Mac OS X) and for recent
versions of MuPAD Pro. To install, you just need to unpack
the zip file in the system-wide MuPAD package directory
(<MuPAD-Root>/packages), or in your own package directory
typically ~/.mupadpro40/packages/.
Also available from: http://www.mupad.de/download/contributions.php
- precompiled RPM and debian packages (GNU/linux i386)
- experimental binary installer for Windows
- source code
- anonymous access to the latest development version via SVN
The installation from source code follows the usual UNIX scheme
configure / make / make install. See the file 'INSTALL' for generic
instructions and 'QuickInstall' for a brief summary. This works as is
for Mac OS X. For Windows there are some extra prerequisites (cygwin,
Visual C++, ...); see CompilationOnWindows/Notes.
In any cases, we strongly recommend that you join the users mailing list:
http://lists.sourceforge.net/mailman/listinfo/mupad-combinat-users
License
=======
mupad-combinat is open source software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License, a
copy of which is provided in the file 'COPYING.LIB'.
If you use this software for your research, please cite it as you
would cite any journal or book, using the following reference:
@article {Hivert_Thiery.MuPAD-Combinat.2004,
AUTHOR = {Hivert, Florent and Thi{\'e}ry, Nicolas M.},
TITLE = {Mu{PAD}-{C}ombinat, an open-source package for research in
algebraic combinatorics},
JOURNAL = {S\'em. Lothar. Combin.},
FJOURNAL = {S\'eminaire Lotharingien de Combinatoire},
VOLUME = {51},
YEAR = {2004},
PAGES = {Art. B51z, 70 pp. (electronic)},
MRCLASS = {05-00 (05-04)},
MRNUMBER = {MR2080390 (2005c:05001)},
note = {\texttt{http://mupad-combinat.sf.net/}},
URL = {http://mupad-combinat.sf.net/},
}
We would also appreciate if you could let us know about it (either by
e-mail, or better via the Wiki
http://mupad-combinat.sourceforge.net/Wiki/UserTestimonials). This
will help us find support for further development of this package. And
this makes us feel useful :-)
External programs included in the distribution:
===============================================
mupad-combinat contains optional interfaces with external C/C++
programs. For the user convenience we have included the sources of
most of those programs in our distribution. We would like to thank
their original copyright holder for allowing us to do so. We however
do not own those software copyright, and they may bear other licences
than the LGPL.
If you plan to redistribute mupad-combinat, you may safely strip away those
sources from the distribution. Otherwise, please make sure those
licences are compatible with the distribution mean, and/or contact
their respective copyright holder for permission.
Symmetrica:
- Copyright Axel Kohnert & all
- License: public domain
- URL: http://www.mathe2.uni-bayreuth.de/axel/symneu_engl.html
- Source directory: src/Symmetrica
- Configure option: --(en/dis)able-symmetrica
Littlewood-Richardson Calculator:
- Copyright (C) 1999 Anders S. Buch (abuch@math.mit.edu)
- License: GPL
- URL: http://www-math.mit.edu/~abuch/lrcalc/
- Source directory: src/lrcalc
- Configure option: --(en/dis)able-lrcalc
Nauty 2.2 (final):
- Copyright Brendan McKay, bdm@cs.anu.edu.au
- License: see src/nauty/nauty.h
- URL: http://cs.anu.edu.au/~bdm/nauty
- Source directory: src/nauty
Those are the pristine sources of Nauty 2.2 with a little
compatibility patch applied (see src/nauty-module/nauty.patch)
- Configure option: --(en/dis)able-nauty
MuPAD Documentation tools and LaTeX style files:
- Copyright 2002 SciFace Software GmbH
- License: LaTeX Project Public License
- URL: ftp://ftp.mupad.de/MuPAD/distrib/doc-utils
- Source directories: src/TOOLS, src/STYLES, src/XSL
Bug reports & mailing lists
===========================
The web page (see General Information above) provides access to
mailing-lists as well as to a bug tracking system. Please use them
for bug reports, suggestions, flames and other comments. Any
contribution will be warmly welcomed. If you don't have web access,
feel free to contact directly the authors (see the file 'AUTHORS').
Please include the following information in any bug report:
- Some information about your system:
- What operating system and version,
- For Linux, what version of the C library,
- The version of the compiler (if you know),
- Anything else you think is relevant;
- A description of the bug itself;
- If you can reproduce the bug, the exact steps to reproduce it;
- Anything else which you think is helpful.
Getting the latest version from the SVN repository
==================================================
You first need to install SVN (aka Subversion) if it is not included
right away on your system. It can be downloaded from:
http://subversion.tigris.org/project_packages.html
Beware: you need SSL support to be activated in subversion, which
badly enough is not always the case in prebuild binaries
(e.g. fink). On Mac OS X, you want to choose the Universal Subversion
Installer; you possibly also want the graphical interface:
http://www.lachoseinteractive.net/en/community/subversion/svnx/features/
On Linux, you may need the open-ssl package, or even open-ssl-devel if
you recompile subversion yourself.
Then (from the command line, or within your prefered graphical
interface), checkout a working copy of MuPAD-Combinat:
svn co https://mupad-combinat.svn.sourceforge.net/svnroot/mupad-combinat/trunk/MuPAD-Combinat
Once checked out, the rest of the configuration and installation is as
usual (./configure; make; make install). Later on, you just need to
run `svn update` in the MuPAD-Combinat directory to update to the
latest version.
Project developpers can further use this working copy at any point for
write access by typing in their sourceforge login and password.
See http://sourceforge.net/docs/E09 for more information on subversion
usage.
==============================================================================
Directory structure of the distribution
=======================================
Combinat-<version>/
lib/ // MuPAD source code of the package
init.mu // Main initialization file
LIBFILES/ // Initialization files of the libraries
combinat.mu
muEC.mu
COMBINAT/ // Library combinat
partitions.mu // source code of combinat::partitions
...
TEST/ // test files
partitions.tst // test file for combinat::partitions
...
DOC/ // XML source for the documentation
partitions.mupdoc// documentation for combinat::partitions
...
PICTURES/combinat/ // pictures for the combinat documentation
picture.png
picture.pdf
...
MUEC/ // Library muEC
COMP/ // Library muEC::COMP
DOC/ // documentation for muEC::COMP
PART/, SYMF/, SG/, SP/, ERR/, TYP/
TEST/ // test files for muEC
DOMAINS/ // Domains, axioms and categories
AXIOM/
CATEGORY/
DOMAIN/
DOC/ // Overview documents (tutorial, ...)
DOC/demo/ // Reusable slides for live demonstrations
src/ // C / C++ source code that is needed
// for the dynamic modules
MAPITL/ // standard distribution of MAPITL
GLIP/ // standard distribution of GLIP
Symmetrica/ // standard? distribution of symmetrica
// C++ source code of the dynamic modules
gordan/
GLIP-module/
Symmetrica-module/
doc/ // Documentation
en/ // English documentation in XML format
combinat.muphlp // Doc for the combinat library
Dom_Combinat.muphlp // Doc for extensions to the Dom library
...
index.html // Html documentation
combinat/index.html // doc of combinat
combinat/partitions.html // doc of combinat::partitions
ascii/ // Ascii documentation
ascii/combinat/partitions.help // doc of combinat::partitions
// Log of documentation building for:
muphlplog // all the documentation
combinat.muphlplog // the doc of combinat
combinat/partitions.xmllog // the doc of combinat::partitions
...
// Log of example checks for:
checklog // all the documentation
combinat.checklog // the doc of combinat
combinat/partitions.checklog // the doc of combinat::partitions
...
dvi/ // Documentation in large format for
// the MuPAD help tool
combinat.mdvi
...
TOOLS/ DTD/ XSL/ // documentation tools from the MuPAD distrib
modules/
<arch>/<version> // contains links/copies of the dynamic modules
// to enable preinstallation tests and use
// with package(".");
test/ // Results of test files
checklog // complete log of all the tests
checklog.summary // Quick summary thereof
COMBINAT/
combinat.res // results of tests for combinat
combinat.checklog // log of tests for combinat
partitions.res // results of tests for combinat::partitions
partitions.checklog // log of the tests for combinat::partitions
combinat.checklog.summary // quick summary thereof
...
MUEC/
DOMAINS/
AXIOM/
CATEGORY/
DOMAIN/
Papers/ // Papers, posters, talks about MuPAD-Combinat
SLC49/main.pdf, main.dvi, ...
Poster/main.pdf, main.dvi, ...
2004-...tex
experimental/
Various worksheets written for special occasions.
Directory structure after installation:
<prefix>/MuPAD-Combinat
lib // As in the distribution
modules/
<arch> // contains all the dynamic modules
doc/ // As in the distribution
==============================================================================
Notes for the maintainer
========================
The configure script is generated by automake/autoconf. You need
automake >= 1.8, autoconf >= 2.59, and libtool >= 1.5.18. Here is the
sequence of commands to recompile fully from scratch:
make maintainer-clean
rm -f config.cache configure
autoreconf
./configure --enable-maintainer-mode --config-cache
make
make check
make install
Building binary packages (rpm's, deb's, ...)
--------------------------------------------
This requires epm (http://www.easysw.com/epm/) and, obviously, the
appropriate package building tools (rpmbuild, dpkg, ...). Here is how
to build a rpm:
make epm-prepare
make epm-rpm # or epm-deb, epm-osx, epm-pkg, ...
make epm-clean
Similar rules exist for most packaging systems; see the doc of epm for
details. The binary packages are put in the distribution/
subdirectory.
Creating a new release
----------------------
Update the files configure.ac, NEWS and ChangeLog, rerun bootstrap as
above, and issue:
make release
Adding a new dynamic module called bla
--------------------------------------
- Create a new directory src/bla, taking example over src/gordan/
- The main source file should be src/bla/bla.mcc
- Edit the file src/bla/Makefile.am appropriately
- Edit the file configure.in:
- Add src/bla/Makefile in AC_OUTPUT
- Add a new conditional bla, taking example over what's done for gordan
- rerun bootstrap as above
------------------------------------------------------------------------------
Updating files on the MuPAD CVS server (DANGEROUS)
------------------------------------------------------------------------------
Editing the list of files to be transfered to the MuPAD standard library:
-------------------------------------------------------------------------
See the variables MUPAD_LIBRARY_FILES and MUPAD_DOC_FILES in the main
Makefile.am
Commiting the files to the MuPAD standard library CVS repository:
-----------------------------------------------------------------
Be really sure that you know what you are doing!
You need to have a developers login on the MuPAD CVS server, and to
have the mupad library and documentation directories checked out
somewhere on your system with read-write permissions. The variables
MUPAD_LIBRARY_CVS MUPAD_DOC_CVS in the main Makefile.am specifies
where those directories are. You can also specify them on the command
line.
make mupad-update-cvs MUPAD_LIBRARY_CVS=... MUPAD_DOC_CVS=...
Commiting the package to the MuPAD standard packages CVS repository:
--------------------------------------------------------------------
Be really sure that you know what you are doing!
You need to have a developers login on the MuPAD CVS server. The
variable MUPAD_CVS_LOGIN in the main Makefile.am specifies your
developers login on the MuPAD CVS server. You can also specify it on
the command line.
make update-mupad-cvs-package MUPAD_CVS_LOGIN=nthiery
==============================================================================
Notes for developers:
=====================
This section has moved to the Wiki:
http://mupad-combinat.sourceforge.net/Wiki/index.php/ProgrammingTipsAndTricks