Changeset 1e9048 in git for factory/README


Ignore:
Timestamp:
Nov 4, 2013, 2:46:12 PM (10 years ago)
Author:
Hans Schoenemann <hannes@…>
Branches:
(u'spielwiese', '17f1d200f27c5bd38f5dfc6e8a0879242279d1d8')
Children:
564e397d4ea84b6bd1320621916a970d7ecb1f14
Parents:
763c4ddb0c6304b684b9b52b91d2713df4bbb4eea9b7f77507baced4cd75ddcfb401a377e267a851
Message:
Merge pull request #411 from mmklee/factory40

Factory40
File:
1 edited

Legend:

Unmodified
Added
Removed

  • factory/README

    r763c4d r1e9048  
    11
    22
    3   --- This `README' file corresponds to Singular-Factory version 3.1 ---
     3  --- This `README' file corresponds to Singular-Factory version 4.0 ---
    44
    55
    … …  
    17174.  Distribution
    18185.  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. Linking Factory with Your Application
    26 13. Factory Template Instantiation
    27 14. Documentation
    28 15. Examples and Tests
    29 16. Editing Factory
    30 17. Files in the Distribution
    31 
     196.  Stream IO
     207.  Diagnostic Messages
     218.  GF(q) Tables
     229.  A Note on Singular
     2311. Factory Template Instantiation
     2412. Documentation
     2513. Examples and Tests
    3226
    33271. What is Factory?
    3428===================
    3529  Factory is a C++ class library that implements a recursive representation
    36 of multivariate polynomial data.  It is being developed by Ruediger Stobbe
     30of multivariate polynomial data.  It was developed by Ruediger Stobbe
    3731and Jens Schmidt at the University of Kaiserslautern as an independent and
    3832self-contained part of the computer algebra system Singular (developed by
    39 G.-M. Greuel, G. Pfister and H. Schoenemann).
     33G.-M. Greuel, G. Pfister and H. Schoenemann) and is now developed by Martin Lee.
    4034
    4135  Factory handles sparse multivariate polynomials over different
    … …  
    4337extensions over Q and GF(q) in an efficient way.  Factory includes
    4438algorithms for computing univariate and multivariate gcds, resultants,
    45 chinese remainders, and several algorithms to factorize univariate
    46 polynomials over the integers and over finite fields.  Factorization of
    47 multivariate polynomials over the integers is in beta test stage.
     39chinese remainders, and algorithms to factorize multivariate polynomials
     40and to compute the absolute factorization of multivariate polynomials with integer
     41coefficients.
    4842
    4943  The interface to the polynomial system of Factory is provided by a single
    … …  
    5751  There are a couple of utility classes provided by Factory such as lists,
    5852arrays, polynomial maps, etc.  These make the usage more comfortable.
    59 
    60 
    6153
    62542. Comments, Questions, Bug Reports
    … …  
    8678information, see the section "A Note on Singular".
    8779
    88   See the `INSTALL' file for instructions on how to install Factory.  The
    89 installation procedure on UNIX platforms conforms more or less to the GNU
     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
    9083standard:
    9184
    92   ./configure; make; make gftables; make install; make installgftables
    93 
    94 However, I recommend to read the instructions since there are a lot of
    95 non-standard options to configure.
    96 
    97   On platforms other than UNIX, where there is no `configure', you have to
    98 configure and install Factory by hand.  In particular, you have to
    99 create/edit the files `config.h', `factory.h', `factoryconf.h', and
    100 `GNUmakefile'.  For Microsoft Windows NT 4.0 with the Microsoft Visual C++
    101 5.0 compiler there is a preconfigured environment in the `winnt/' directory
    102 which you may use as an example.  For more information, confer to
    103 corresponding section in the `INSTALL' file and to the `INSTALL.nt' file in
    104 the `winnt/' directory.
     85  ./configure --without-Singular; make; make check; make install;
    10586
    10687  In general, this `README' as well as the `INSTALL' file are written for
    … …  
    10990too.
    11091
    111 
    112 
    113924. Distribution
    11493===============
    115   The latest version of Factory is always available by anonymous ftp from
     94  The latest stable version of Factory is always available from
    11695
    117                 www.mathematik.uni-kl.de:/pub/Math/Singular/Factory
     96                www.singular.uni-kl.de
    11897
    119 The Factory distribution consists of three archives:
     98  For the latest development version visit
    12099
    121 o the Factory source code (`factory-<version>.tgz');
    122 o some preliminary documentation on Factory (`factory-doc-prelim.tgz');
    123 o Factory GF(q) addition tables (`factory-gftables.tgz', see below).
    124 
     100               www.github.com/Singular
    125101
    1261025. Prerequisites
    127103================
    128104  You need GNU make to build and install Factory.  Furthermore, I strongly
    129 recommend to build Factory with GNU CC (version 2.7 or newer).  To build
     105recommend to build Factory with GNU CC.  To build
    130106Factory and to link your programs with Factory you need the GNU Multiple
    131 Precision Library (GMP, version 2.0 or newer).  The GMP library is
    132 available at ftp.gnu.ai.mit.edu or its mirrors.  Alternatively, Factory may
    133 be linked with the so called small GMP library which comes with the full
    134 version of Singular (not recommended).
     107Precision Library (GMP).
    135108
    136109Configure options:
    137110------------------
    138   --with-gmp(=<gmp_inc_path>(,<gmp_lib_path>))
    139                           specify where to find the GMP library.
    140   --enable-gmp            together with `--with-Singular' means: installation
    141                           in process, be graceful when there is no `gmp.h'
     111  --with-gmp=<path to GMP> enabled by default
    142112
    143   If <gmp_lib_path> is not given, but <gmp_inc_path> is,
    144 `<gmp_inc_path>/../lib/' is used as <gmp_lib_path>.  If neither
    145 <gmp_lib_path> nor <gmp_inc_path> is specified, `configure' looks in the
    146 standard system locations for GMP.
    147 
    148   Furthermore, you may specify the symbolic directory `$(includedir)' for
    149 <gmp_inc_path>:
    150 
    151   --with-gmp='$(includedir)'
    152 
    153 Do not forget the single quotes or otherwise your shell might complain.
    154 
    155   This is useful when Factory is delivered as part of a larger package
    156 which also provides the GMP library.  In this case, at configuration time
    157 there would not be any `gmp.h'.  Without this option, Factory's `configure'
    158 script would exit with an error message.  If this symbolic directory is
    159 given, the `configure' script does not look for `gmp.h' and `libgmp.a'.
    160 Rather, it adds the option `-I$(includedir)' to its `$(CXXFLAGS)' and the
    161 option `-L$(libdir)' to its `$(LDFLAGS)' assuming that at compilation-time
    162 `gmp.h' and `libgmp.a' will reside in these directories.
    163   The option `--enable-gmp' does the same, but it is a special (and ugly)
    164 gift to Singular, so it may be used with option `--with-Singular' only.
    165 
    166 
    167 
    168 6. Memory Manager
    169 =================
    170   You can use one of the memory management tools provided with Factory.
    171 There are the "new" and the "old" memory manager.  In fact, on some systems
    172 the old memory management seems to be faster then the new one, but so far
    173 there have not been systematic timings.  If you configure Factory with
    174 `--with-memman=no' it will use the standard C++ operators `new'/`delete',
    175 which is not recommended.
    176   You may trace the actions (allocate/free) of the new memory manager by
    177 enabling memory management debugging.  This produces a *lot* of output.
     113  For full functionality NTL (www.shoup.net/ntl) is required.
    178114
    179115Configure options:
    180116------------------
    181   --with-memman(=<memman>) specify Factory memory manager.
    182                           <memman> is either `old' (default), `new', or `no'.
    183   --enable-memdebug=<level> switch on memory management debugging.  Meaningful
    184                           with `--with-memman=new' only.  <level> may be either
    185                           `no' (default), `normal', or `full'.
     117  --with-ntl=<path to NTL> enabled by default
    186118
     119  For optimal preformance we recommend to use FLINT (www.flintlib.org) and to use
     120  Singular's memory manager omalloc
    187121
    188 7. Stream IO
     122Configure 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
     1286. Stream IO
    189129============
    190130  For use with other systems which have their own IO routines to print
    191 polynomials it is possible to switch off Factory's stream IO.  In this
    192 case, you do not need to link libg++ or libiostream with Factory.
     131polynomials it is possible to switch off Factory's stream IO.
    193132
    194133Configure options:
    … …  
    197136
    198137
    199 8. Diagnostic Messages
     1387. Diagnostic Messages
    200139======================
    201140Factory has three types of diagnostic messages:
    … …  
    210149  Since all diagnostic messages are implemented using preprocessor macros,
    211150they will completely cease when disabled, thus avoiding any impact on
    212 speed.  For more information, see section "Configuring and building Factory
    213 for different configurations" in the `INSTALL' file.  By default, all
    214 diagnostic messages are disabled.
     151speed.  By default, all diagnostic messages are disabled.
    215152
    216153Configure options:
    … …  
    220157  --enable-debugoutput    build Factory so it will print debugging information
    221158
    222 
    223 
    224 9. GF(q) Tables
     1598. GF(q) Tables
    225160===============
    226 
    227 NOTE: Since the format of the GF(q) tables changed from Factory Version
    228 1.2b to Factory Version 1.3a you should get/create them by new!
    229161
    230162  Factory uses addition tables to calculate in GF(p^n) in an efficient way.
    231163
    232 There are two possibilities to get these tables:
    233 o get them from the net (`factory-gftables.tgz') where you got Factory
    234   from.  The files unpack into a directory `gftables/'.
    235 o create them with `gengftables' which is a part of Factory.  Building
    236   the tables takes quite a while!
    237 See the `INSTALL' file for more information.
     164  They can be created with `make gengftables'.  Building the tables takes quite
     165   a while!
    238166
    239 
    240 10. A Note on Singular
     1679. A Note on Singular
    241168=====================
    242169  If you have received this Factory distribution together with Singular you
    243170do not have to worry about compilation or installation at all.  The
    244 installation procedure for Singular should do everything for you.  If you
    245 want to configure/build the package on your own instead of letting
    246 Singular's `configure' do the work you should:
     171installation procedure for Singular should do everything for you.
    247172
    248   ./configure --with-Singular --enable-gmp
    249         (or, equivalently: )
    250   ./configure --with-Singular --with-gmp='${includedir}'
    251 
    252   Furthermore, you should specify `--prefix' so `make install' will install
    253 the files in the places where Singular looks for them.  By default, this is
    254 the top directory of the Singular distribution.  In this case you have to
    255 specify `--prefix=..'.
    256 
    257   The Singular GF(q) tables are the same as the Factory GF(q) tables.
    258 However, Singular uses a different naming scheme.  Therefore, a Factory
    259 configured with `--without-Singular' will not find Singular's GF(q) tables
    260 as well as a Factory configured with `--with-Singular' will not find the
    261 GF(q) tables created by gengftables.  But this is not a major drawback
    262 since Singular is distributed with ready-to-use GF(q) tables.
    263 
    264   The latest version of Singular is always available at
    265 www.mathematik.uni-kl.de:/pub/Math/Singular.
    266 
    267 Configure options:
    268 ------------------
    269   --with-Singular         build for use with computer algebra system Singular.
    270 
    271   Except from setting the `#define SINGULAR', this option only changes the
    272 defaults to: `--with-memman=no --disable-streamio'.
    273 
    274 
    275 
    276 11. Configure Options, Dependencies
    277 ===================================
    278 o do not configure `--with-Singular --with-memman'.  In this case
    279   both Singular and the library will try to initialize their own memory
    280   management.
    281 
    282 o do not configure `--disable-streamio --enable-debugoutput'.  The
    283   "DEBOUT macros" need stream IO.
    284 
    285 o you may configure `--with-Singular --enable-streamio', but this
    286   is not supported by Singular.  You will have to change manually
    287   Singular's `Makefile'.  The same is true for `--with-Singular
    288   --enable-streamio --enable-debugoutput'.
    289 
    290 o you may configure `--with-Singular --enable-timing', but this
    291   will not have any visible effect (except from a slightly slower
    292   running time) because Singular will not print the timing
    293   results.
    294 
    295 o `--enable-gmp' has an effect only together with `--with-Singular'
    296 
    297 o `--with-memdebug' has an effect only together with
    298   `--with-memman=new'
    299 
    300 
    301 12. Linking Factory With Your Application
    302 =========================================
    303   To translate your application you need (apart from your
    304 application, of course):
    305 
    306 o the Factory user interface header file (`factory.h')
    307 
    308   To link your application with Factory you need:
    309 
    310 o the Factory library (`libcf.a')
    311 o unless you configured Factory `--without-memman' you need one of the
    312   Factory memory manager libraries (`libcfmem.a')
    313 
    314 o the instantiated Factory templates (`ftmpl_inst.o').
    315 
    316 o unless you configured Factory `--without-streamio' you need the stream IO
    317   libraries.  With GNU CC, you do not need to care about this because they
    318   are linked automatically to your application if you call the compiler
    319   either as `g++' or as `c++'.  Otherwise, you need to link with library
    320   `libiostream.a'.
    321 o The GNU Multiple Precision Library (`libgmp.a').  See section
    322   "Prerequisites" in this file for more information.
    323 o The standard mathematical library (`libm.a')
    324 
    325   `factory.h', `libcf.a', and `libcfmem.a' are created when you build
    326 Factory and installed by `make install'.  `libiostream.a', `libgmp.a', and
    327 `libm.a' should be already installed on your system, otherwise your
    328 application will fail to link.  `ftmpl_inst.o' is not installed by Factory.
    329 Instead, its source file `ftmpl_inst.cc' is installed and you have to build
    330 `ftmpl_inst.o' when you are building your application.  For more
    331 information on template instantiation and `ftmpl_inst.cc', see the
    332 following section "Factory Template Instantiation".
    333 
    334   To give an example, look at the following one-shot solution to the
    335 problem "linking Factory with your application" where the "application" is
    336 a small test program (`application.cc') from the subdirectory `examples/'
    337 of the Factory source directory ('\' at the end of a line denotes line
    338 continuation):
    339 
    340   g++ -c /usr/local/include/templates/ftmpl_inst.cc -fno-implicit-templates -O2 -fomit-frame-pointer -o ftmpl_inst.o
    341   g++ -c application.cc -fno-implicit-templates -O2 -fomit-frame-pointer ftmpl_inst.o -lcf -lcfmem -lm -lgmp
    342 
    343   This should work fine provided that you installed Factory in a location
    344 where `g++' may find it (here I have assumed `/usr/local/') and all the
    345 other files mentioned above are installed properly and where `g++' looks
    346 for them.
    347 
    348   You may find a small `GNUmakefile' which translates `application.cc' and
    349 other examples in the `examples/' subdirectory of the Factory source
    350 directory.  For more information, see the section "Examples and Tests".
    351 
    352 
    353 13. Factory Template Instantiation
     17310. Factory Template Instantiation
    354174==================================
    355175  There are a couple of classes provided by Factory such as lists, arrays,
    … …  
    358178factorization (a list of factors), and you may use them to create new
    359179derived abstract data types.  These classes are realized using C++
    360 "templates", which you need to "instantiate" befor you use them (refer to
    361 some introduction to C++ if you do not know these terms).
     180templates, which are instantiated in one single file namely ftmpl_inst.cc .
    362181
    363   With GNU CC the most reliable way to instantiate templates is to
    364 
    365 o explicitely instantiate all necessary templates, and compile with option
    366   `-fno-implicit-templates' and to
    367 o collect all explicit template instantiations in one single file.
    368 
    369   This approach is the one Factory uses.  All object files of the library
    370 are generated with option `--fno-implicit-templates' and the explicit
    371 template instantiations are collected in `ftmpl_inst.cc'.  You could
    372 translate this file using the `make' target `ftmpl_inst.o' (see section
    373 "Building Factory" in the `INSTALL' file).
    374 
    375   The consequence of this approach: since you may want to add template
    376 instantiations of Factory's or your own templates after the installation of
    377 Factory, it is necessary to install `ftmpl_inst.cc' as well as the template
    378 source files together with the library.  They are automatically installed
    379 in `$(includedir)/templates/' when you type `make install'.
    380 
    381   To join your own template instantiations with the ones from
    382 `ftmpl_inst.cc' there are several possibilities:
    383 
    384 o you copy `ftmpl_inst.cc' file from the directory where it was installed
    385   into your working directory and add your template instantiations after
    386   the corresponig comment at the end of the file;
    387 o you cut the template instantiations from `ftmpl_inst.cc' and paste
    388   them into your own template instantiation file.
    389 
    390 Both methods suffer from one disadvantage: each time `ftmpl_inst.cc'
    391 changes in a new version of Factory you will have to redo these steps.  The
    392 best method therefore is maybe this one:
    393 
    394 o you write your own template instantiation file with a
    395   `#include <templates/ftmpl_inst.cc>' statement at the beginning of it.
    396 
    397 
    398 
    399 14. Documentation
     18211. Documentation
    400183=================
    401184  So far there are only preliminary versions of a user/reference manual and
    … …  
    407190
    408191
    409 15. Examples and Tests
     19212. Examples and Tests
    410193======================
    411194  The directory `examples/' in the Factory source directory contains some
    412 example applications for Factory and a `GNUmakefile' to build them.  The
    413 main purpose of the examples is to show how to link applications with an
    414 installed version of Factory.  This means that you have to install Factory
    415 before you can build the examples (but it is not necessary to install the
    416 GF(q) tables).  For the same reason, the `GNUmakefile' is not configured
    417 automatically by `configure'.  You will have to change some of the
    418 variables manually.
     195example applications for Factory.
    419196
    420   Furthermore, you may have a look at `gengftables.cc' in the Factory
    421 source directory which is another application of the most basic Factory
    422 features.
     197  'make check' will run some simple test as well.
    423198
    424   To test whether Factory (including GF(q) tables) has been installed
    425 properly, use `make' target `installtest'.
    426 
    427 
    428 16. Editing Factory
    429 ===================
    430   Parts of Factory are written using GNU Emacs' `folding-mode'.  You may
    431 load this mode from Emacs with
    432 
    433   M-x load-file RET factory-<version>/bin/folding.el RET
    434 
    435 To switch it on, say `M-x folding-mode RET'.  Alternatively, you may load
    436 `factory-<version>/bin/fold-docu.el' which contains some additional functions
    437 to fold only the documentation.  If you add the following lines to your
    438 `.emacs' file, all this would be done automatically for you:
    439 
    440   (load-file "factory-<version>/bin/folding.el")
    441   (load-file "factory-<version>/bin/fold-docu.el")
    442   (add-hook 'c-mode-common-hook 'folding-mode)
    443   (setq fold-fold-on-startup nil
    444         fold-mode-marks-alist '((c++-mode "//{{{" "//}}}")))
    445   (set-default 'fold-internal-margins nil)
    446 
    447   For more information, see the respective files.
    448 
    449 
    450 
    451 17. Files in the Distribution
    452 =============================
    453 ChangeLog       - history of changes
    454 INSTALL         - installation instructions
    455 NEWS            - new Factory features
    456 README          - this file
    457 
    458 bin/install-sh  - a script version of the BSD `install' program
    459 bin/makeheader  - creates headers from header templates (`*.template')
    460 bin/mkinstalldirs - recursive `mkdir'
    461 bin/folding.el  - Emacs `folding-mode'
    462 bin/fold-docu.el - some extensions to it
    463 
    464 GNUmakefile.in  - master makefile and
    465 config.h.in     - configuration include file.  Run `configure' to create
    466                   `GNUmakefile' and `config.h', resp.
    467 configure
    468 configure.in    - `configure' script generated with Autoconf 2.10
    469                   from `configure.in'
    470 
    471 factory.template
    472 factoryconf.template - header templates for the user interface header
    473                   files.  Run `makeheader' to create `factory.h' and
    474                   `factoryconf.h', resp.
    475 
    476 ffops.cc
    477 ffops.h
    478 gf_tabutil.cc
    479 gf_tabutil.h
    480 gfops.cc
    481 gfops.h
    482 imm.h
    483 int_*.cc
    484 int_*.h         - low level classes and functions
    485 
    486 canonicalform.cc
    487 canonicalform.h
    488 cf_*.cc
    489 cf_*.h
    490 variable.cc
    491 variable.h      - high level classes and functions.  User interface to
    492                   the polynomial (and other) arithmetic.
    493 
    494 templates/      - Factory templates
    495 ftmpl_inst.cc   - template instantiation for Factory templates
    496 
    497 fac_*.cc
    498 fac_*.h         - high level algorithms (factorization, gcd, sqfr
    499                   computation, etc.)
    500 sm_*.c
    501 sm_*.h          - sparse modular gcd.  Contributed by Marion Bruder
    502                   <bruder@math.uni-sb.de>
    503 
    504 parseutil.cc
    505 parseutil.h
    506 readcf.cc
    507 readcf.y        - Factory parser to read canonical forms.  `readcf.cc'
    508                   translated with Bison 1.18 from `readcf.y'.
    509 
    510 gmpext.h
    511 initgmp.cc      - Factories interface to GNU MP
    512 singext.cc
    513 singext.h       - Factories interface to Singular
    514 
    515 NTLconvert.*    - some conversion routines for using NTL
    516 
    517 memutil.c
    518 memutil.h       - "old" Factory memory manager
    519 memman.h
    520 mm*.c
    521 mm*.h           - "new" Factory memory manager
    522 newdelete.cc    - C++ interface to the memory managers
    523 
    524 cf_assert.h     - the "ASSERT macros"
    525 debug.h
    526 debug.cc        - the "DEBOUT macros"
    527 timing.h        - the "TIMING macros"
    528 
    529 examples/       - some example applications for Factory and a `GNUmakefile'
    530                   to build them
    531 gengftables.cc  - run `gengftables' to create the GF(q) addition tables
    532                   necessary to work with Factory
    533 test_install.cc - a small program to test whether installation has
    534                   been successful.  Built and called by `make' target
    535                   `installtest'
Note: See TracChangeset for help on using the changeset viewer.