--- This README file corresponds to Factory version 1.3a --- README file for Factory ======================= NOTE: The copyright state of Factory is still unclear. Sooner or later it will be free software, but by now please do *not* distribute the sources. Overview ======== 1. What is Factory? 2. Comments, questions, bug reports 3. Installation 4. Distribution 5. Prerequisites 6. Memory manager 7. Stream IO 8. Diagnostic messages 9. GF(q) tables 10. A note on Singular 11. Configure options, dependencies 12. Documentation 13. Examples and Tests 14. Editing Factory 15. Files in the distribution 1. What is Factory? =================== Factory is a C++ class library that implements a recursive representation of multivariate polynomial data. It is being developed by Ruediger Stobbe and Jens Schmidt at the University of Kaiserslautern as an independent and self-contained part of the computer algebra system Singular (developed by G.-M. Greuel, G. Pfister and H. Schoenemann). Factory handles sparse multivariate polynomials over different coefficient domains, such as Z, Q and GF(q), as well as algebraic extensions over Q and GF(q) in an efficient way. Factory includes algorithms for computing univariate and multivariate gcds, resultants, chinese remainders and several algorithms to factorize univariate polynomials over the integers and over finite fields. Factorization of multivariate polynomials over the integers is in beta test stage. The interface to the polynomial system of Factory is provided by a single class CanonicalForm which can deal with elements of the coefficient domain as well as polynomials. Using operator overloading, you can handle polynomial data similarly to built-in types such as the machine integers. For example, to add together two polynomials one simply uses the '+' operator. Because of this, Factory is easy to use even if you are not familiar with C++ programming. There are a couple of utility classes provided by Factory such as lists, arrays, polynomial maps, etc. These make the usage more comfortable. 2. Comments, questions, bug reports ==================================== Factory is a project in evolution. That means there is no guarantee that Factory is bug free. I am sure that there are bugs or at least features. If you find bugs or if you find a strange behavior of the library, please let me know (e-mail: Jens Schmidt ). Comments and questions are welcome, too. Factory version 1.2c and newer define an external variable 'factoryVersion' describing the version of the library. Please include this version number in your bug reports. You may either use the UNIX utility 'what' to get this number ('what libcf.a') or compile and run something similar to this: #include main() { cout << factoryVersion << endl; } 3. Installation =============== NOTE: If you have received this Factory distribution together with Singular you do not have to worry about compilation or installation at all. The installation procedure for Singular should do everything for you. For more information, see the section 'A note on Singular'. See the INSTALL file for instructions on how to install Factory. The installation procedure conforms more or less to the GNU standard: ./configure; make; make gftables; make install; make installgftables However, I recommend to read the instructions since there are a lot of non-standard options to configure. 4. Distribution =============== The newest version of Factory is always available by anonymous ftp from www.mathematik.uni-kl.de:/pub/Math/Factory The Factory distribution consists of three archives: o the Factory source code (factory-.tgz); o some preliminary documentation on Factory (factory-doc-prelim.tgz); o Factory GF(q) addition tables (factory-gftables.tgz, see below). 5. Prerequisites ================ You need GNU make to build and install Factory. Furthermore, I strongly recommend to build Factory with GNU CC (version 2.7 or newer). To build Factory and to link your programs with Factory you need the GNU Multiple Precision Library (GMP, version 2.0 or newer). The GMP library is available at ftp.gnu.ai.mit.edu or its mirrors. Alternatively, Factory may be linked with the so called small GMP library which comes with the full version of Singular (not recommended). Configure options: ------------------ --with-gmp(=(,)) specify where to find gmp library. --enable-gmp together with --with-Singular means: installation in process, be graceful when there is no gmp.h If is not given, but is, '/../lib/' is used as . If neither nor is specified, configure looks in the standard system locations for GMP. Furthermore, you may specify the symbolic directory '$(includedir)' for : --with-gmp='$(includedir)' This is useful when Factory is delivered as part of a larger package which also provides the GMP library. In this case, at configuration time there would not be any gmp.h. Without this option, Factory's configure script would exit with an error message. If this symbolic directory is given, the configure script does not look for gmp.h and libgmp.a. Rather, it adds the option '-I$(includedir)' to its $(CXXFLAGS) and the option '-L$(libdir)' to its $(LDFLAGS) assuming that at compilation-time gmp.h and libgmp.a will reside in these directories. The option --enable-gmp does the same, but it is a special (and ugly) gift to Singular, so it may be used with option --with-Singular only. 6. Memory manager ================= You can use one of the memory management tools provided with Factory. There are the 'new' and the 'old' memory manager. In fact, on some systems the 'old' memory management seems to be faster then the new one, but so far there have not been systematic timings. If you configure Factory with '--with-memman=no' it will use the standard C++ operators new/delete, which is not recommended. You may trace the actions (alloc/free) of the new memory manager by enabling memory management debugging. This produces a *lot* of output. Configure options: ------------------ --with-memman(=) specify Factory memory manager. is either 'old' (default), 'new', or 'no'. --enable-memdebug= switch on memory management debugging. Meaningful with --with-memman=new only. may be either 'no' (default), 'normal', or 'full'. 7. Stream IO ============ For use with other systems which have their own IO routines to print polynomials it is possible to switch off Factory's stream IO. In this case, you do not need to link libg++ or libiostream with Factory. Configure options: ------------------ --disable-streamio build Factory without stream IO 8. Diagnostic messages ====================== Factory has three types of diagnostic messages: - Assertions (implemented by the ASSERT macros in assert.h) are used to ensure preconditions before running some algorithm. A typical example is to test f != 0 before dividing by f. - Debug output (implemented by the DEBOUT macros in debug.h/debug.cc) is used to trace complex algorithms, e.g. factorization. - Timing information may be accumulated and printed using the TIMING macros in timing.h. Since all diagnostic messages are implemented using preprocessor macros, they will completely cease when disabled, thus avoiding any impact on speed. For more information, see section 'Configuring and building Factory for different configurations' in the INSTALL file. By default, all diagnostic messages are disabled. Configure options: ------------------ --enable-assertions build Factory with assertions activated --enable-timing build Factory so it will print timing information --enable-debugoutput build Factory so it will print debugging information 9. GF(q) tables =============== Factory uses addition tables to calculate in GF(p^n) in an efficient way. NOTE: Since the format of the GF(q) tables changed from Factory Version 1.2b to Factory Version 1.3a you should get/create them by new! There are two possibilities to get these tables: o get them from the net (factory-gftables.tgz) where you got Factory from. The files unpack into a directory gftables/. o create them with gengftables which is a part of Factory. Building the tables takes quite a while! See the INSTALL file for more information. 10. A note on Singular ===================== If you have received this Factory distribution together with Singular you do not have to worry about compilation or installation at all. The installation procedure for Singular should do everything for you. If you want to configure/build the package on your own instead of letting Singular's configure do the work you should: ./configure --with-Singular --enable-gmp (or, equivalently: ) ./configure --with-Singular --with-gmp='${includedir}' Furthermore, you should specify --prefix so 'make install' will install the files in the places where Singular looks for them. By default, this is the top directory of the Singular distribution. In this case you have to specify '--prefix=..'. The Singular GF(q) tables are the same as the Factory GF(q) tables. However, Singular uses a different naming scheme. Therefore, a Factory configured with '--without-Singular' will not find Singular's GF(q) tables as well as a Factory configured with '--with-Singular' will not find the GF(q) tables created by gengftables. But this is not a major drawback since Singular is distributed with ready-to-use GF(q) tables. The newest version of Singular is always available at www.mathematik.uni-kl.de:/pub/Math/Singular. Configure options: ------------------ --with-Singular build for use with computer algebra system Singular. Except from setting the #define SINGULAR, this option only changes the defaults to: '--with-memman=no --disable-streamio'. 11. Configure options, dependencies =================================== - do not configure '--with-Singular --with-memman'. In this case both Singular and the library will try to initialize their own memory management. - do not configure '--disable-streamio --enable-debugoutput'. The DEBOUT macros need stream IO. - you may configure '--with-Singular --enable-streamio', but this is not supported by Singular. You will have to change manually Singular's Makefile. The same is true for '--with-Singular --enable-streamio --enable-debugoutput'. - you may configure '--with-Singular --enable-timing', but this will not have any visible effect (except from a slightly slower running time) because Singular will not print the timing results. - --enable-gmp has an effect only together with --with-Singular - --with-memdebug has an effect only together with --with-memman=new 12. Documentation ================= So far there are only preliminary versions of a user/reference manual and a tutorial ('A quick start into Factory'). Please do not expect them to be complete or even error-free. For this reason, the documentation is not included in the source code archive (factory-.tgz). Instead, the sources and compiled dvi files reside in factory-doc-prelim.tgz. They will unpack into a directory factory-doc-prelim/. 13. Examples and Tests ====================== So far neither examples nor tests, sorry. You may have a look at gengftables.cc which is an application of the most basic Factory features. 14. Editing Factory =================== Parts of Factory are written using Emacs' folding-mode. You may load this mode from Emacs with 'M-x load-file RET factory-/bin/folding.el RET'. To switch it on, say 'M-x folding-mode RET'. Alternatively, you may load factory-/bin/fold-docu.el which contains some additional functions to fold only the documentation. If you add the following lines to your .emacs-file, all this would be done automatically for you: (load-file "factory-/bin/folding.el") (load-file "factory-/bin/fold-docu.el") (add-hook 'c-mode-common-hook 'folding-mode) (setq fold-fold-on-startup nil fold-mode-marks-alist '((c++-mode "//{{{" "//}}}"))) (set-default 'fold-internal-margins nil) For more information, see the respective files. 15. Files in the distribution ============================= ChangeLog - history of changes INSTALL - installation instructions README - this file NEWS - new Factory features bin/install-sh - a script version of the BSD install program bin/makeheader - creates headers from header templates (*.template) bin/mkinstalldirs - recursive mkdir bin/folding.el - Emacs folding-mode bin/fold-docu.el - some extensions to it GNUmakefile.in - master makefile and config.h.in - configuration include file. Run configure to create GNUmakefile and config.h, resp. configure configure.in - configure script generated with Autoconf 2.10 from configure.in factory.template factoryconf.template - header templates for the user interface header files. Run makeheader to create factory.h and factoryconf.h, resp. ffops.cc ffops.h gf_tabutil.cc gf_tabutil.h gfops.cc gfops.h imm.h int_*.cc int_*.h - low level classes and functions canonicalform.cc canonicalform.h cf_*.cc cf_*.h variable.cc variable.h - high level classes and functions. User interface to the polynomial (and other) arithmetic. templates/ - Factory templates ftmpl_inst.cc - template instantiation for Factory templates fac_*.cc fac_*.h - high level algorithms (factorization, gcd, sqfr computation, etc.) sm_*.c sm_*.h - sparse modular gcd. Contributed by Marion Bruder parseutil.cc parseutil.h readcf.cc readcf.y - Factory parser to read canonical forms. readcf.cc translated with Bison 1.18 from readcf.y. gmpext.h initgmp.cc - Factories interface to GNU MP singext.cc singext.h - Factories interface to Singular memutil.c memutil.h - 'old' Factory memory manager memman.h mm*.c mm*.h - 'new' Factory memory manager newdelete.cc - C++ interface to the memory managers assert.h - the ASSERT macros debug.h debug.cc - the DEBOUT macros timing.h - the TIMING macros gengftables.cc - run gengftables to create the GF(q) addition tables necessary to work with Factory