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 | 11. Factory Template Instantiation |
---|
24 | 12. Documentation |
---|
25 | 13. Examples and Tests |
---|
26 | |
---|
27 | 1. What is Factory? |
---|
28 | =================== |
---|
29 | Factory is a C++ class library that implements a recursive representation |
---|
30 | of multivariate polynomial data. It was developed by Ruediger Stobbe |
---|
31 | and Jens Schmidt at the University of Kaiserslautern as an independent and |
---|
32 | self-contained part of the computer algebra system Singular (developed by |
---|
33 | G.-M. Greuel, G. Pfister and H. Schoenemann) and is now developed by Martin Lee. |
---|
34 | |
---|
35 | Factory handles sparse multivariate polynomials over different |
---|
36 | coefficient domains, such as Z, Q and GF(q), as well as algebraic |
---|
37 | extensions over Q and GF(q) in an efficient way. Factory includes |
---|
38 | algorithms for computing univariate and multivariate gcds, resultants, |
---|
39 | chinese remainders, and algorithms to factorize multivariate polynomials |
---|
40 | and to compute the absolute factorization of multivariate polynomials with integer |
---|
41 | coefficients. |
---|
42 | |
---|
43 | The interface to the polynomial system of Factory is provided by a single |
---|
44 | class `CanonicalForm' which can deal with elements of the coefficient |
---|
45 | domain as well as polynomials. Using operator overloading, you can handle |
---|
46 | polynomial data similarly to built-in types such as the machine integers. |
---|
47 | For example, to add two polynomials one simply uses the `+' operator. |
---|
48 | Because of this, Factory is easy to use even if you are not familiar with |
---|
49 | C++ programming. |
---|
50 | |
---|
51 | There are a couple of utility classes provided by Factory such as lists, |
---|
52 | arrays, polynomial maps, etc. These make the usage more comfortable. |
---|
53 | |
---|
54 | 2. Comments, Questions, Bug Reports |
---|
55 | ==================================== |
---|
56 | Factory is a project in evolution. That means there is no guarantee that |
---|
57 | Factory is bug free. I am sure that there are bugs or at least features. |
---|
58 | If you find bugs or if you find a strange behavior of the library, please |
---|
59 | let me know (e-mail: singular@mathematik.uni-kl.de>). |
---|
60 | Comments and questions are welcome, too. |
---|
61 | |
---|
62 | Factory version 1.2c and newer define an external variable |
---|
63 | `factoryVersion' describing the version of the library. The external |
---|
64 | variable `factoryConfiguration' (not present in versions 1.2c and 1.3a) |
---|
65 | describes the options Factory has been configured with. Please include the |
---|
66 | version number and the configuration options in your bug reports. You may |
---|
67 | either use the UNIX utility `what' to get this information (`what libcf.a') |
---|
68 | or compile and run something similar to this: |
---|
69 | |
---|
70 | #include <factory.h> |
---|
71 | main() { cout << factoryVersion << "; " << factoryConfiguration << endl; } |
---|
72 | |
---|
73 | 3. Installation |
---|
74 | =============== |
---|
75 | NOTE: If you have received this Factory distribution together with Singular |
---|
76 | you do not have to worry about compilation or installation at all. The |
---|
77 | installation procedure for Singular should do everything for you. For more |
---|
78 | information, see the section "A Note on Singular". |
---|
79 | |
---|
80 | For further information on factory's configure options see also ./configure --help. |
---|
81 | |
---|
82 | The installation procedure on UNIX platforms conforms more or less to the GNU |
---|
83 | standard: |
---|
84 | |
---|
85 | ./configure --without-Singular; make; make check; make install; |
---|
86 | |
---|
87 | In general, this `README' as well as the `INSTALL' file are written for |
---|
88 | UNIX platforms. However, you may find less specific information on the |
---|
89 | configuration and installation process which is useful for other platforms, |
---|
90 | too. |
---|
91 | |
---|
92 | 4. Distribution |
---|
93 | =============== |
---|
94 | The latest stable version of Factory is always available from |
---|
95 | |
---|
96 | www.singular.uni-kl.de |
---|
97 | |
---|
98 | For the latest development version visit |
---|
99 | |
---|
100 | www.github.com/Singular |
---|
101 | |
---|
102 | 5. Prerequisites |
---|
103 | ================ |
---|
104 | You need GNU make to build and install Factory. Furthermore, I strongly |
---|
105 | recommend to build Factory with GNU CC. To build |
---|
106 | Factory and to link your programs with Factory you need the GNU Multiple |
---|
107 | Precision Library (GMP). |
---|
108 | |
---|
109 | Configure options: |
---|
110 | ------------------ |
---|
111 | --with-gmp=<path to GMP> enabled by default |
---|
112 | |
---|
113 | For full functionality NTL (www.shoup.net/ntl) is required. |
---|
114 | |
---|
115 | Configure options: |
---|
116 | ------------------ |
---|
117 | --with-ntl=<path to NTL> enabled by default |
---|
118 | |
---|
119 | For optimal preformance we recommend to use FLINT (www.flintlib.org) and to use |
---|
120 | Singular's memory manager omalloc |
---|
121 | |
---|
122 | Configure options: |
---|
123 | ------------------ |
---|
124 | --with-flint=<path to FLINT> enabled by default |
---|
125 | --with-omalloc disabled by default |
---|
126 | --with-omalloc-dir=<path to omalloc> |
---|
127 | |
---|
128 | 6. Stream IO |
---|
129 | ============ |
---|
130 | For use with other systems which have their own IO routines to print |
---|
131 | polynomials it is possible to switch off Factory's stream IO. |
---|
132 | |
---|
133 | Configure options: |
---|
134 | ------------------ |
---|
135 | --disable-streamio build Factory without stream IO |
---|
136 | |
---|
137 | |
---|
138 | 7. Diagnostic Messages |
---|
139 | ====================== |
---|
140 | Factory has three types of diagnostic messages: |
---|
141 | o Assertions (implemented by the "ASSERT macros" in `cf_assert.h') are used to |
---|
142 | ensure preconditions before running some algorithm. A typical example is |
---|
143 | to test f != 0 before dividing by f. |
---|
144 | o Debug output (implemented by the "DEBOUT macros" in `debug.h'/`debug.cc') |
---|
145 | is used to trace complex algorithms, e.g. factorization. |
---|
146 | o Timing information may be accumulated and printed using the "TIMING macros" |
---|
147 | in `timing.h'. |
---|
148 | |
---|
149 | Since all diagnostic messages are implemented using preprocessor macros, |
---|
150 | they will completely cease when disabled, thus avoiding any impact on |
---|
151 | speed. By default, all diagnostic messages are disabled. |
---|
152 | |
---|
153 | Configure options: |
---|
154 | ------------------ |
---|
155 | --enable-assertions build Factory with assertions activated |
---|
156 | --enable-timing build Factory so it will print timing information |
---|
157 | --enable-debugoutput build Factory so it will print debugging information |
---|
158 | |
---|
159 | 8. GF(q) Tables |
---|
160 | =============== |
---|
161 | |
---|
162 | Factory uses addition tables to calculate in GF(p^n) in an efficient way. |
---|
163 | |
---|
164 | They can be created with `make gengftables'. Building the tables takes quite |
---|
165 | a while! |
---|
166 | |
---|
167 | 9. A Note on Singular |
---|
168 | ===================== |
---|
169 | If you have received this Factory distribution together with Singular you |
---|
170 | do not have to worry about compilation or installation at all. The |
---|
171 | installation procedure for Singular should do everything for you. |
---|
172 | |
---|
173 | 10. Factory Template Instantiation |
---|
174 | ================================== |
---|
175 | There are a couple of classes provided by Factory such as lists, arrays, |
---|
176 | etc, which may be used to derive new abstract data types from already |
---|
177 | existing ones. Factory uses them itself, e.g. to return the result of a |
---|
178 | factorization (a list of factors), and you may use them to create new |
---|
179 | derived abstract data types. These classes are realized using C++ |
---|
180 | templates, which are instantiated in one single file namely ftmpl_inst.cc . |
---|
181 | |
---|
182 | 11. Documentation |
---|
183 | ================= |
---|
184 | So far there are only preliminary versions of a user/reference manual and |
---|
185 | a tutorial ("A quick start into Factory"). Please do not expect them to |
---|
186 | be error-free or even complete. For this reason, the documentation is not |
---|
187 | included in the source code archive (`factory-<version>.tgz'). Instead, the |
---|
188 | sources and compiled DVI files reside in `factory-doc-prelim.tgz'. They will |
---|
189 | unpack into a directory `factory-doc-prelim/'. |
---|
190 | |
---|
191 | |
---|
192 | 12. Examples and Tests |
---|
193 | ====================== |
---|
194 | The directory `examples/' in the Factory source directory contains some |
---|
195 | example applications for Factory. |
---|
196 | |
---|
197 | 'make check' will run some simple test as well. |
---|
198 | |
---|