1 | |
---|
2 | |
---|
3 | --- This `README' file corresponds to Singular-Factory version 4.0 --- |
---|
4 | |
---|
5 | |
---|
6 | README file for Singular-Factory |
---|
7 | ================================ |
---|
8 | |
---|
9 | NOTE: The copyright of Singular-Factory is described in the |
---|
10 | file COPYING |
---|
11 | |
---|
12 | Overview |
---|
13 | ======== |
---|
14 | 1. What is Factory? |
---|
15 | 2. Comments, Questions, Bug Reports |
---|
16 | 3. Installation |
---|
17 | 4. Distribution |
---|
18 | 5. Prerequisites |
---|
19 | 6. Stream IO |
---|
20 | 7. Diagnostic Messages |
---|
21 | 8. GF(q) Tables |
---|
22 | 9. A Note on Singular |
---|
23 | 10. Factory Template Instantiation |
---|
24 | 11. Documentation |
---|
25 | 12. Examples and Tests |
---|
26 | 13. Remark on Characteristic Sets |
---|
27 | 14. Adding new code |
---|
28 | 15. Nomenclature |
---|
29 | 16. Limitations |
---|
30 | |
---|
31 | 1. What is Factory? |
---|
32 | =================== |
---|
33 | Factory is a C++ class library that implements a recursive representation |
---|
34 | of multivariate polynomial data. It was developed by Ruediger Stobbe |
---|
35 | and Jens Schmidt at the University of Kaiserslautern as an independent and |
---|
36 | self-contained part of the computer algebra system Singular (developed by |
---|
37 | G.-M. Greuel, G. Pfister and H. Schoenemann) and is now developed by Martin Lee. |
---|
38 | |
---|
39 | Factory handles sparse multivariate polynomials over different |
---|
40 | coefficient domains, such as Z, Q and GF(q), as well as algebraic |
---|
41 | extensions over Q and GF(q) in an efficient way. Factory includes |
---|
42 | algorithms for computing univariate and multivariate gcds, resultants, |
---|
43 | chinese remainders, and algorithms to factorize multivariate polynomials |
---|
44 | and to compute the absolute factorization of multivariate polynomials with integer |
---|
45 | coefficients. |
---|
46 | |
---|
47 | The interface to the polynomial system of Factory is provided by a single |
---|
48 | class `CanonicalForm' which can deal with elements of the coefficient |
---|
49 | domain as well as polynomials. Using operator overloading, you can handle |
---|
50 | polynomial data similarly to built-in types such as the machine integers. |
---|
51 | For example, to add two polynomials one simply uses the `+' operator. |
---|
52 | Because of this, Factory is easy to use even if you are not familiar with |
---|
53 | C++ programming. |
---|
54 | |
---|
55 | There are a couple of utility classes provided by Factory such as lists, |
---|
56 | arrays, polynomial maps, etc. These make the usage more comfortable. |
---|
57 | |
---|
58 | 2. Comments, Questions, Bug Reports |
---|
59 | ==================================== |
---|
60 | Factory is a project in evolution. That means there is no guarantee that |
---|
61 | Factory is bug free. I am sure that there are bugs or at least features. |
---|
62 | If you find bugs or if you find a strange behavior of the library, please |
---|
63 | let me know (e-mail: singular@mathematik.uni-kl.de>). |
---|
64 | Comments 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 |
---|
68 | variable `factoryConfiguration' (not present in versions 1.2c and 1.3a) |
---|
69 | describes the options Factory has been configured with. Please include the |
---|
70 | version number and the configuration options in your bug reports. You may |
---|
71 | either use the UNIX utility `what' to get this information (`what libcf.a') |
---|
72 | or compile and run something similar to this: |
---|
73 | |
---|
74 | #include <factory.h> |
---|
75 | main() { cout << factoryVersion << "; " << factoryConfiguration << endl; } |
---|
76 | |
---|
77 | 3. Installation |
---|
78 | =============== |
---|
79 | NOTE: If you have received this Factory distribution together with Singular |
---|
80 | you do not have to worry about compilation or installation at all. The |
---|
81 | installation procedure for Singular should do everything for you. For more |
---|
82 | information, 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 |
---|
87 | standard: |
---|
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 |
---|
92 | UNIX platforms. However, you may find less specific information on the |
---|
93 | configuration and installation process which is useful for other platforms, |
---|
94 | too. |
---|
95 | |
---|
96 | 4. 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 | |
---|
106 | 5. Prerequisites |
---|
107 | ================ |
---|
108 | You need GNU make to build and install Factory. Furthermore, I strongly |
---|
109 | recommend to build Factory with GNU CC. To build |
---|
110 | Factory and to link your programs with Factory you need the GNU Multiple |
---|
111 | Precision Library (GMP). |
---|
112 | |
---|
113 | Configure options: |
---|
114 | ------------------ |
---|
115 | --with-gmp=<path to GMP> enabled by default |
---|
116 | |
---|
117 | For full functionality NTL (www.shoup.net/ntl) is required. |
---|
118 | |
---|
119 | Configure 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 | |
---|
126 | Configure 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 | |
---|
132 | 6. Stream IO |
---|
133 | ============ |
---|
134 | For use with other systems which have their own IO routines to print |
---|
135 | polynomials it is possible to switch off Factory's stream IO. |
---|
136 | |
---|
137 | Configure options: |
---|
138 | ------------------ |
---|
139 | --disable-streamio build Factory without stream IO |
---|
140 | |
---|
141 | |
---|
142 | 7. Diagnostic Messages |
---|
143 | ====================== |
---|
144 | Factory has three types of diagnostic messages: |
---|
145 | o 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. |
---|
148 | o Debug output (implemented by the "DEBOUT macros" in `debug.h'/`debug.cc') |
---|
149 | is used to trace complex algorithms, e.g. factorization. |
---|
150 | o 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, |
---|
154 | they will completely cease when disabled, thus avoiding any impact on |
---|
155 | speed. By default, all diagnostic messages are disabled. |
---|
156 | |
---|
157 | Configure 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 | |
---|
163 | 8. 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 | |
---|
171 | 9. A Note on Singular |
---|
172 | ===================== |
---|
173 | If you have received this Factory distribution together with Singular you |
---|
174 | do not have to worry about compilation or installation at all. The |
---|
175 | installation procedure for Singular should do everything for you. |
---|
176 | |
---|
177 | 10. Factory Template Instantiation |
---|
178 | ================================== |
---|
179 | There are a couple of classes provided by Factory such as lists, arrays, |
---|
180 | etc, which may be used to derive new abstract data types from already |
---|
181 | existing ones. Factory uses them itself, e.g. to return the result of a |
---|
182 | factorization (a list of factors), and you may use them to create new |
---|
183 | derived abstract data types. These classes are realized using C++ |
---|
184 | templates, which are instantiated in one single file namely ftmpl_inst.cc . |
---|
185 | |
---|
186 | 11. Documentation |
---|
187 | ================= |
---|
188 | So far there are only preliminary versions of a user/reference manual and |
---|
189 | a tutorial ("A quick start into Factory"). Please do not expect them to |
---|
190 | be error-free or even complete. For this reason, the documentation is not |
---|
191 | included in the source code archive (`factory-<version>.tgz'). Instead, the |
---|
192 | sources and compiled DVI files reside in `factory-doc-prelim.tgz'. They will |
---|
193 | unpack into a directory `factory-doc-prelim/'. |
---|
194 | |
---|
195 | |
---|
196 | 12. Examples and Tests |
---|
197 | ====================== |
---|
198 | The directory `examples/' in the Factory source directory contains some |
---|
199 | example applications for Factory. |
---|
200 | |
---|
201 | 'make check' will run some simple test as well. |
---|
202 | |
---|
203 | 13. Remark on Characteristic Sets |
---|
204 | ================================= |
---|
205 | Algorithms for manipulation of polynomial ideals via the characteristic set |
---|
206 | methods (e.g., calculating the characteristic set and the irreducible |
---|
207 | characteristic series) are now incorpareted into factory. |
---|
208 | If you want to learn about characteristic sets, the next is a good point |
---|
209 | to 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 | |
---|
216 | 14. 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 |
---|
220 | available via factory's global interface 'factory.h' add |
---|
221 | |
---|
222 | /*MAKEHEADER PUBLIC ONLY*/ |
---|
223 | foo.h |
---|
224 | |
---|
225 | to 'factory.template' and enclose the functions in 'foo.h', that you like to |
---|
226 | add, by '/*BEGINPUBLIC*/' and '/*ENDPUBLIC*/'. |
---|
227 | |
---|
228 | 15. Nomenclature |
---|
229 | ================ |
---|
230 | Factorization related functions are contained in files with the prefix 'fac'. |
---|
231 | Functions operating on CanonicalForm's are contained in files with the prefix |
---|
232 | 'cf'. Functions operating on the internal structures of a CanonicalForm are |
---|
233 | contained in files with the prefix 'int'. Exceptions are gfops.cc/.h, |
---|
234 | ffops.cc/.h, imm.cc/.h as they use intrinsic data types. |
---|
235 | |
---|
236 | 16. Limitations |
---|
237 | =============== |
---|
238 | The largest characteristic of a finite field is limited to 536870909. The |
---|
239 | number of elements of a finite fields represented by Conway polynomials has to |
---|
240 | be < 2^16 (see gfops.cc). |
---|
241 | |
---|