source: git/factory/README @ 8d1432e

spielwiese
Last change on this file since 8d1432e was c86648, checked in by Martin Lee <martinlee84@…>, 10 years ago
chg: added Limitations and Nomenclature
  • Property mode set to 100644
File size: 9.1 KB
Line 
1
2
3  --- This `README' file corresponds to Singular-Factory version 4.0 ---
4
5
6                  README file for Singular-Factory
7                  ================================
8
9NOTE: The copyright of Singular-Factory is described in the
10      file COPYING
11
12Overview
13========
141.  What is Factory?
152.  Comments, Questions, Bug Reports
163.  Installation
174.  Distribution
185.  Prerequisites
196.  Stream IO
207.  Diagnostic Messages
218.  GF(q) Tables
229.  A Note on Singular
2310. Factory Template Instantiation
2411. Documentation
2512. Examples and Tests
2613. Remark on Characteristic Sets
2714. Adding new code
2815. Nomenclature
2916. Limitations
30
311. What is Factory?
32===================
33  Factory is a C++ class library that implements a recursive representation
34of multivariate polynomial data.  It was developed by Ruediger Stobbe
35and Jens Schmidt at the University of Kaiserslautern as an independent and
36self-contained part of the computer algebra system Singular (developed by
37G.-M. Greuel, G. Pfister and H. Schoenemann) and is now developed by Martin Lee.
38
39  Factory handles sparse multivariate polynomials over different
40coefficient domains, such as Z, Q and GF(q), as well as algebraic
41extensions over Q and GF(q) in an efficient way.  Factory includes
42algorithms for computing univariate and multivariate gcds, resultants,
43chinese remainders, and algorithms to factorize multivariate polynomials
44and to compute the absolute factorization of multivariate polynomials with integer
45coefficients.
46
47  The interface to the polynomial system of Factory is provided by a single
48class `CanonicalForm' which can deal with elements of the coefficient
49domain as well as polynomials.  Using operator overloading, you can handle
50polynomial data similarly to built-in types such as the machine integers.
51For example, to add two polynomials one simply uses the `+' operator.
52Because of this, Factory is easy to use even if you are not familiar with
53C++ programming.
54
55  There are a couple of utility classes provided by Factory such as lists,
56arrays, polynomial maps, etc.  These make the usage more comfortable.
57
582. Comments, Questions, Bug Reports
59====================================
60  Factory is a project in evolution.  That means there is no guarantee that
61Factory is bug free.  I am sure that there are bugs or at least features.
62If you find bugs or if you find a strange behavior of the library, please
63let me know (e-mail: singular@mathematik.uni-kl.de>).
64Comments and questions are welcome, too.
65
66  Factory version 1.2c and newer define an external variable
67`factoryVersion' describing the version of the library.  The external
68variable `factoryConfiguration' (not present in versions 1.2c and 1.3a)
69describes the options Factory has been configured with.  Please include the
70version number and the configuration options in your bug reports.  You may
71either use the UNIX utility `what' to get this information (`what libcf.a')
72or compile and run something similar to this:
73
74  #include <factory.h>
75  main() { cout << factoryVersion << "; " << factoryConfiguration << endl; }
76
773. Installation
78===============
79NOTE: If you have received this Factory distribution together with Singular
80you do not have to worry about compilation or installation at all.  The
81installation procedure for Singular should do everything for you.  For more
82information, see the section "A Note on Singular".
83
84  For further information on factory's configure options see also ./configure --help.
85
86  The installation procedure on UNIX platforms conforms more or less to the GNU
87standard:
88
89  ./configure --without-Singular; make; make check; make install;
90
91  In general, this `README' as well as the `INSTALL' file are written for
92UNIX platforms.  However, you may find less specific information on the
93configuration and installation process which is useful for other platforms,
94too.
95
964. Distribution
97===============
98  The latest stable version of Factory is always available from
99
100                www.singular.uni-kl.de
101
102  For the latest development version visit
103
104               www.github.com/Singular
105
1065. Prerequisites
107================
108  You need GNU make to build and install Factory.  Furthermore, I strongly
109recommend to build Factory with GNU CC.  To build
110Factory and to link your programs with Factory you need the GNU Multiple
111Precision Library (GMP).
112
113Configure options:
114------------------
115  --with-gmp=<path to GMP> enabled by default
116
117  For full functionality NTL (www.shoup.net/ntl) is required.
118
119Configure options:
120------------------
121  --with-ntl=<path to NTL> enabled by default
122
123  For optimal preformance we recommend to use FLINT (www.flintlib.org) and to use
124  Singular's memory manager omalloc
125
126Configure options:
127------------------
128  --with-flint=<path to FLINT> enabled by default
129  --with-omalloc               disabled by default
130  --with-omalloc-dir=<path to omalloc>
131
1326. Stream IO
133============
134  For use with other systems which have their own IO routines to print
135polynomials it is possible to switch off Factory's stream IO.
136
137Configure options:
138------------------
139  --disable-streamio      build Factory without stream IO
140
141
1427. Diagnostic Messages
143======================
144Factory has three types of diagnostic messages:
145o Assertions (implemented by the "ASSERT macros" in `cf_assert.h') are used to
146  ensure preconditions before running some algorithm.  A typical example is
147  to test f != 0 before dividing by f.
148o Debug output (implemented by the "DEBOUT macros" in `debug.h'/`debug.cc')
149  is used to trace complex algorithms, e.g. factorization.
150o Timing information may be accumulated and printed using the "TIMING macros"
151  in `timing.h'.
152
153  Since all diagnostic messages are implemented using preprocessor macros,
154they will completely cease when disabled, thus avoiding any impact on
155speed.  By default, all diagnostic messages are disabled.
156
157Configure options:
158------------------
159  --enable-assertions     build Factory with assertions activated
160  --enable-timing         build Factory so it will print timing information
161  --enable-debugoutput    build Factory so it will print debugging information
162
1638. GF(q) Tables
164===============
165
166  Factory uses addition tables to calculate in GF(p^n) in an efficient way.
167
168  They can be created with `make gengftables'.  Building the tables takes quite
169   a while!
170
1719. A Note on Singular
172=====================
173  If you have received this Factory distribution together with Singular you
174do not have to worry about compilation or installation at all.  The
175installation procedure for Singular should do everything for you.
176
17710. Factory Template Instantiation
178==================================
179  There are a couple of classes provided by Factory such as lists, arrays,
180etc, which may be used to derive new abstract data types from already
181existing ones.  Factory uses them itself, e.g. to return the result of a
182factorization (a list of factors), and you may use them to create new
183derived abstract data types.  These classes are realized using C++
184templates, which are instantiated in one single file namely ftmpl_inst.cc .
185
18611. Documentation
187=================
188  So far there are only preliminary versions of a user/reference manual and
189a tutorial ("A quick start into Factory").  Please do not expect them to
190be error-free or even complete.  For this reason, the documentation is not
191included in the source code archive (`factory-<version>.tgz').  Instead, the
192sources and compiled DVI files reside in `factory-doc-prelim.tgz'. They will
193unpack into a directory `factory-doc-prelim/'.
194
195
19612. Examples and Tests
197======================
198  The directory `examples/' in the Factory source directory contains some
199example applications for Factory.
200
201  'make check' will run some simple test as well.
202
20313. Remark on Characteristic Sets
204=================================
205Algorithms for manipulation of polynomial ideals via the characteristic set
206methods (e.g., calculating the characteristic set and the irreducible
207characteristic series) are now incorpareted into factory.
208If you want to learn about characteristic sets, the next is a good point
209to start with:
210    Dongming Wang:
211    An Implementation of the Characteristic Set Method in Maple.
212    In: Automated Practical Reasoning: Algebraic Approaches
213    (J. Pfalzgraf and D. Wang, eds.), Springer-Verlag,
214    Wien-New York, 1995, pp. 187-201.
215
21614. Adding new code
217===================
218  If you like to add new code 'foo.cc/foo.h' add 'foo.cc' to 'Makefile.am' under
219'SOURCES' and 'foo.h' under 'factory_headers'. If your new functions should be
220available via factory's global interface 'factory.h' add
221
222/*MAKEHEADER PUBLIC ONLY*/
223foo.h
224
225to 'factory.template' and enclose the functions in 'foo.h', that you like to
226add, by '/*BEGINPUBLIC*/' and '/*ENDPUBLIC*/'.
227
22815. Nomenclature
229================
230  Factorization related functions are contained in files with the prefix 'fac'.
231Functions operating on CanonicalForm's are contained in files with the prefix
232'cf'. Functions operating on the internal structures of a CanonicalForm are
233contained in files with the prefix 'int'. Exceptions are gfops.cc/.h,
234ffops.cc/.h, imm.cc/.h as they use intrinsic data types.
235
23616. Limitations
237===============
238  The largest characteristic of a finite field is limited to 536870909. The
239number of elements of a finite fields represented by Conway polynomials has to
240be < 2^16 (see gfops.cc).
241
Note: See TracBrowser for help on using the repository browser.