1 | |
---|
2 | |
---|
3 | --- This README file corresponds to Factory version 1.3a --- |
---|
4 | |
---|
5 | |
---|
6 | README file for Factory |
---|
7 | ======================= |
---|
8 | |
---|
9 | NOTE: The copyright state of Factory is still unclear. Sooner or later it |
---|
10 | will be free software, but by now please do *not* distribute the sources. |
---|
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. Memory manager |
---|
20 | 7. Stream IO |
---|
21 | 8. Diagnostic messages |
---|
22 | 9. GF(q) tables |
---|
23 | 10. A note on Singular |
---|
24 | 11. Configure options, dependencies |
---|
25 | 12. Documentation |
---|
26 | 13. Examples and Tests |
---|
27 | 14. Editing Factory |
---|
28 | 15. Files in the distribution |
---|
29 | |
---|
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 is being 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). |
---|
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 several algorithms to factorize univariate |
---|
44 | polynomials over the integers and over finite fields. Factorization of |
---|
45 | multivariate polynomials over the integers is in beta test stage. |
---|
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 domain |
---|
49 | 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 together two polynomials one simply uses the '+' |
---|
52 | operator. Because of this, Factory is easy to use even if you are not |
---|
53 | familar with 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 | |
---|
59 | 2. Comments, questions, bug reports |
---|
60 | ==================================== |
---|
61 | Factory is a project in evolution. That means there is no guarantee that |
---|
62 | Factory is bug free. I am sure that there are bugs or at least features. |
---|
63 | If you find bugs or if you find a strange behavior of the library, please |
---|
64 | let me know (e-mail: Jens Schmidt <schmidt@mathematik.uni-kl.de>). |
---|
65 | Comments and questions are welcome, too. |
---|
66 | |
---|
67 | |
---|
68 | 3. Installation |
---|
69 | =============== |
---|
70 | |
---|
71 | NOTE: If you have received this Factory distribution together with Singular |
---|
72 | you do not have to worry about compilation or installation at all. The |
---|
73 | installation procedure for Singular should do everything for you. For more |
---|
74 | information, see the section 'A note on Singular'. |
---|
75 | |
---|
76 | See the INSTALL file for instructions on how to install Factory. The |
---|
77 | installation procedure conforms more or less to the GNU standard: |
---|
78 | |
---|
79 | ./configure; make; make gftables; make install; make installgftables |
---|
80 | |
---|
81 | However, I recommend to read the instructions since there are a lot of |
---|
82 | non-standard options to configure. |
---|
83 | |
---|
84 | |
---|
85 | 4. Distribution |
---|
86 | =============== |
---|
87 | The newest version of Factory is always available by anonymous ftp from |
---|
88 | |
---|
89 | www.mathematik.uni-kl.de:/pub/Math/Factory |
---|
90 | |
---|
91 | The Factory distribution consists of three archives: |
---|
92 | |
---|
93 | o the Factory source code (factory-<version>.tgz); |
---|
94 | o some preliminary documentation on Factory (factory-doc-prelim.tgz); |
---|
95 | o Factory GF(q) addition tables (factory-gftables.tgz, see below). |
---|
96 | |
---|
97 | |
---|
98 | 5. Prerequisites |
---|
99 | ================ |
---|
100 | You need GNU make to build and install Factory. Furthermore, I strongly |
---|
101 | recommend to build Factory with GNU CC (version 2.7 or newer). To build |
---|
102 | Factory and to link your programs with Factory you need the GNU Multiple |
---|
103 | Precision Library (GMP, version 2.0 or newer). The GMP library is |
---|
104 | available at ftp.gnu.ai.mit.edu or its mirrors. Alternatively, Factory may |
---|
105 | be linked with the so called small GMP library which comes with the full |
---|
106 | version of Singular (not recommended). |
---|
107 | |
---|
108 | Configure options: |
---|
109 | ------------------ |
---|
110 | --with-gmp(=<gmp_inc_path>(,<gmp_lib_path>)) |
---|
111 | specify where to find gmp library. |
---|
112 | --enable-gmp together with --with-Singular means: installation |
---|
113 | in process, be graceful when there is no gmp.h |
---|
114 | |
---|
115 | If <gmp_lib_path> is not given, but <gmp_inc_path> is, |
---|
116 | '<gmp_inc_path>/../lib/' is used as <gmp_lib_path>. If neither |
---|
117 | <gmp_lib_path> nor <gmp_inc_path> is specified, configure looks in the |
---|
118 | standard system locations for GMP. |
---|
119 | |
---|
120 | Furthermore, you may specify the symbolic directory '$(includedir)' for |
---|
121 | <gmp_inc_path>: |
---|
122 | |
---|
123 | --with-gmp='$(includedir)' |
---|
124 | |
---|
125 | This is useful when Factory is delivered as part of a larger package |
---|
126 | which also provides the GMP library. In this case, at configuration time |
---|
127 | there would not be any gmp.h. Without this option, Factory's configure |
---|
128 | script would exit with an error message. If this symbolic directory is |
---|
129 | given, the configure script does not look for gmp.h and libgmp.a. Rather, |
---|
130 | it adds the option '-I$(includedir)' to its $(CXXFLAGS) and the option |
---|
131 | '-L$(libdir)' to its $(LDFLAGS) assuming that at compilation-time gmp.h and |
---|
132 | libgmp.a will reside in these directories. |
---|
133 | The option --enable-gmp does the same, but it is a special (and ugly) |
---|
134 | gift to Singular, so it may be used with option --with-Singular only. |
---|
135 | |
---|
136 | |
---|
137 | 6. Memory manager |
---|
138 | ================= |
---|
139 | You can use one of the memory management tools provided with Factory. |
---|
140 | There are the 'new' and the 'old' memory manager. In fact, on some systems |
---|
141 | the 'old' memory management seems to be faster then the new one, but so far |
---|
142 | there have not been systematic timings. If you configure Factory with |
---|
143 | '--with-memman=no' it will use the standard C++ operators new/delete, which |
---|
144 | is not recommended. |
---|
145 | You may trace the actions (alloc/free) of the new memory manager by |
---|
146 | enabling memory management debugging. This produces a *lot* of output. |
---|
147 | |
---|
148 | Configure options: |
---|
149 | ------------------ |
---|
150 | --with-memman(=<memman>) specify Factory memory manager. |
---|
151 | <memman> is either 'old' (default), 'new', or 'no'. |
---|
152 | --enable-memdebug=<level> switch on memory management debugging. Meaningful |
---|
153 | with --with-memman=new only. <level> may be either |
---|
154 | 'no' (default), 'normal', or 'full'. |
---|
155 | |
---|
156 | |
---|
157 | 7. Stream IO |
---|
158 | ============ |
---|
159 | For use with other systems which have their own IO routines to print |
---|
160 | polynomials it is possible to switch off Factory's stream IO. In this |
---|
161 | case, you do not need to link libg++ or libiostream with Factory. |
---|
162 | |
---|
163 | Configure options: |
---|
164 | ------------------ |
---|
165 | --disable-streamio build Factory without stream IO |
---|
166 | |
---|
167 | |
---|
168 | 8. Diagnostic messages |
---|
169 | ====================== |
---|
170 | Factory has three types of diagnostic messages: |
---|
171 | - Assertions (implemented by the ASSERT macros in assert.h) are used to |
---|
172 | ensure preconditions before running some algorithm. A typical example is |
---|
173 | to test f != 0 before dividing by f. |
---|
174 | - Debug output (implemented by the DEBOUT macros in debug.h/debug.cc) is |
---|
175 | used to trace complex algorithms, e.g. factorization. |
---|
176 | - Timing information may be accumulated and printed using the TIMING macros |
---|
177 | in timing.h. |
---|
178 | |
---|
179 | Since all diagnostic messages are implemented using preprocessor macros, |
---|
180 | they will completely cease when disabled, thus avoiding any impact on |
---|
181 | speed. For more information, see section 'Configuring and building Factory |
---|
182 | for different configurations' in the INSTALL file. By default, all |
---|
183 | diagnostic messages are disabled. |
---|
184 | |
---|
185 | Configure options: |
---|
186 | ------------------ |
---|
187 | --enable-assertions build Factory with assertions activated |
---|
188 | --enable-timing build Factory so it will print timing information |
---|
189 | --enable-debugoutput build Factory so it will print debugging information |
---|
190 | |
---|
191 | |
---|
192 | 9. GF(q) tables |
---|
193 | =============== |
---|
194 | Factory uses addition tables to calculate in GF(p^n) in an efficient way. |
---|
195 | |
---|
196 | NOTE: Since the format of the GF(q) tables changed from Factory Version |
---|
197 | 1.2b to Factory Version 1.3a you should get/create them by new! |
---|
198 | |
---|
199 | There are two possibilities to get these tables: |
---|
200 | o get them from the net (factory-gftables.tgz) where you got Factory |
---|
201 | from. The files unpack into a directory gftables/. |
---|
202 | o create them with gengftables which is a part of Factory. Building |
---|
203 | the tables takes quite a while! |
---|
204 | See the INSTALL file for more information. |
---|
205 | |
---|
206 | |
---|
207 | 10. A note on Singular |
---|
208 | ===================== |
---|
209 | If you have received this Factory distribution together with Singular you |
---|
210 | do not have to worry about compilation or installation at all. The |
---|
211 | installation procedure for Singular should do everything for you. If you |
---|
212 | want to configure/build the package on your own instead of letting |
---|
213 | Singulars configure do the work you should: |
---|
214 | |
---|
215 | ./configure --with-Singular --enable-gmp |
---|
216 | (or, equivalently: ) |
---|
217 | ./configure --with-Singular --with-gmp='${includedir}' |
---|
218 | |
---|
219 | Furthermore, you should specify --prefix so 'make install' will install |
---|
220 | the files in the places where Singular looks for them. By default, this is |
---|
221 | the top directory of the Singular distribution. In this case you have to |
---|
222 | specify '--prefix=..'. |
---|
223 | |
---|
224 | The Singular GF(q) tables are the same as the Factory GF(q) tables. |
---|
225 | However, Singular uses a different naming scheme. Therefore, a Factory |
---|
226 | configured with '--without-Singular' will not find Singular's GF(q) tables |
---|
227 | as well as a Factory configured with '--with-Singular' will not find the |
---|
228 | GF(q) tables created by gengftables. But this is not a major drawback |
---|
229 | since Singular is distributed with ready-to-use GF(q) tables. |
---|
230 | |
---|
231 | The newest version of Singular is always available at |
---|
232 | www.mathematik.uni-kl.de:/pub/Math/Singular. |
---|
233 | |
---|
234 | Configure options: |
---|
235 | ------------------ |
---|
236 | --with-Singular build for use with computer algebra system Singular. |
---|
237 | |
---|
238 | Except from setting the #define SINGULAR, this option only changes the |
---|
239 | defaults to: '--with-memman=no --disable-streamio'. |
---|
240 | |
---|
241 | |
---|
242 | 11. Configure options, dependencies |
---|
243 | =================================== |
---|
244 | - do not configure '--with-Singular --with-memman'. In this case |
---|
245 | both Singular and the library will try to initialize their own memory |
---|
246 | management. |
---|
247 | |
---|
248 | - do not configure '--disable-streamio --enable-debugoutput'. The |
---|
249 | DEBOUT macros need stream IO. |
---|
250 | |
---|
251 | - you may configure '--with-Singular --enable-streamio', but this |
---|
252 | is not supported by Singular. You will have to change manually |
---|
253 | Singular's Makefile. The same is true for '--with-Singular |
---|
254 | --enable-streamio --enable-debugoutput'. |
---|
255 | |
---|
256 | - you may configure '--with-Singular --enable-timing', but this |
---|
257 | will not have any visible effect (except from a slightly slower |
---|
258 | running time) because Singular will not print the timing |
---|
259 | results. |
---|
260 | |
---|
261 | - --enable-gmp has an effect only together with --with-Singular |
---|
262 | |
---|
263 | - --with-memdebug has an effect only together with |
---|
264 | --with-memman=new |
---|
265 | |
---|
266 | |
---|
267 | 12. Documentation |
---|
268 | ================= |
---|
269 | So far there are only preliminary versions of a user/reference manual and |
---|
270 | a tutorial ('A quick start into Factory'). Please do not expect them to |
---|
271 | be complete or even error-free. For this reason, the documentation is not |
---|
272 | included in the source code archive (factory-<version>.tgz). Instead, the |
---|
273 | sources and compiled dvi files reside in factory-doc-prelim.tgz. They will |
---|
274 | unpack into a directory factory-doc-prelim/. |
---|
275 | |
---|
276 | |
---|
277 | 13. Examples and Tests |
---|
278 | ====================== |
---|
279 | So far neither examples nor tests, sorry. You may have a look at |
---|
280 | gengftables.cc which is an application of the most basic Factory features. |
---|
281 | |
---|
282 | |
---|
283 | 14. Editing Factory |
---|
284 | =================== |
---|
285 | Parts of Factory are written using Emacs' folding-mode. You may load |
---|
286 | this mode from Emacs with 'M-x load-file RET |
---|
287 | factory-<version>/bin/folding.el RET'. |
---|
288 | To switch it on, say 'M-x folding-mode RET'. Alternatively, you may load |
---|
289 | factory-<version>/bin/fold-docu.el which contains some additional functions |
---|
290 | to fold only the documentation. If you add the following lines to your |
---|
291 | .emacs-file, all this would be done automatically for you: |
---|
292 | |
---|
293 | (add-hook 'c-mode-common-hook 'folding-mode) |
---|
294 | (setq fold-fold-on-startup nil |
---|
295 | fold-mode-marks-alist '((c++-mode "//{{{" "//}}}"))) |
---|
296 | (set-default 'fold-internal-margins nil) |
---|
297 | (load-file "factory-<version>/bin/fold-docu.el") |
---|
298 | |
---|
299 | For more information, see the respective files. |
---|
300 | |
---|
301 | |
---|
302 | 15. Files in the distribution |
---|
303 | ============================= |
---|
304 | ChangeLog - history of changes |
---|
305 | INSTALL - installation instructions |
---|
306 | README - this file |
---|
307 | NEWS - new Factory features |
---|
308 | |
---|
309 | bin/install-sh - a script version of the BSD install program |
---|
310 | bin/makeheader - creates headers from header templates (*.template) |
---|
311 | bin/mkinstalldirs - recursive mkdir |
---|
312 | bin/folding.el - Emacs folding-mode |
---|
313 | bin/fold-docu.el - some extensions to it |
---|
314 | |
---|
315 | GNUmakefile.in - master makefile and |
---|
316 | config.h.in - configuration include file. Run configure to create |
---|
317 | GNUmakefile and config.h, resp. |
---|
318 | configure |
---|
319 | configure.in - configure script generated with Autoconf 2.10 |
---|
320 | from configure.in |
---|
321 | |
---|
322 | factory.template |
---|
323 | factoryconf.template - header templates for the user interface header |
---|
324 | files. Run makeheader to create factory.h and |
---|
325 | factoryconf.h, resp. |
---|
326 | |
---|
327 | ffops.cc |
---|
328 | ffops.h |
---|
329 | gf_tabutil.cc |
---|
330 | gf_tabutil.h |
---|
331 | gfops.cc |
---|
332 | gfops.h |
---|
333 | imm.h |
---|
334 | int_*.cc |
---|
335 | int_*.h - low level classes and functions |
---|
336 | |
---|
337 | canonicalform.cc |
---|
338 | canonicalform.h |
---|
339 | cf_*.cc |
---|
340 | cf_*.h |
---|
341 | variable.cc |
---|
342 | variable.h - high level classes and functions. User interface to |
---|
343 | the polynomial (and other) arithmetic. |
---|
344 | |
---|
345 | templates/ - Factory templates |
---|
346 | ftmpl_inst.cc - template instantiation for Factory templates |
---|
347 | |
---|
348 | fac_*.cc |
---|
349 | fac_*.h - high level algorithms (factorization, gcd, sqfr |
---|
350 | computation, etc.) |
---|
351 | sm_*.c |
---|
352 | sm_*.h - sparse modular gcd. Contributed by Marion Bruder |
---|
353 | <bruder@math.uni-sb.de> |
---|
354 | |
---|
355 | parseutil.cc |
---|
356 | parseutil.h |
---|
357 | readcf.cc |
---|
358 | readcf.y - Factory parser to read canonical forms. readcf.cc |
---|
359 | translated with Bison 1.18 from readcf.y. |
---|
360 | |
---|
361 | gmpext.h |
---|
362 | initgmp.cc - Factories interface to GNU MP |
---|
363 | singext.cc |
---|
364 | singext.h - Factories interface to Singular |
---|
365 | |
---|
366 | memutil.c |
---|
367 | memutil.h - 'old' Factory memory manager |
---|
368 | memman.h |
---|
369 | mm*.c |
---|
370 | mm*.h - 'new' Factory memory manager |
---|
371 | newdelete.cc - C++ interface to the memory managers |
---|
372 | |
---|
373 | assert.h - the ASSERT macros |
---|
374 | debug.h |
---|
375 | debug.cc - the DEBOUT macros |
---|
376 | timing.h - the TIMING macros |
---|
377 | |
---|
378 | gengftables.cc - run gengftables to create the GF(q) addition tables |
---|
379 | necessary to work with Factory |
---|