ApCoCoALib:ReadMe: Difference between revisions

From ApCoCoAWiki
Dheldt (talk | contribs)
pushing in current readme from the rcs.
 
Dheldt (talk | contribs)
first corrections
Line 1: Line 1:
This is a copy of ApCoCoALib's README file:
This is a copy of ApCoCoALib's README file:


  CoCoALib README
  ApCoCoALib README
  ===============
  ===============
   
   
  Date: 9 March 2007
  Date: 13 December 2007
    
    
  This subtrree contains the sources of the C++ library CoCoALib.  The CoCoA
  This subtrree contains the sources of the C++ library ApCoCoALib.  The ApCoCoA
  library offers functions to perform calculations in Computational Commutative  
  library offers functions to perform calculations in Computational Commutative  
  Algebra, and some other related areas.  Our intention is that the library
  Algebra, and some other related areas.  Our intention is that the library
Line 15: Line 15:
  Where to start
  Where to start
  --------------
  --------------
  (a) Compile CoCoALib following the instructions in the file INSTALL.
  (a) Compile ApCoCoALib following the instructions in the file INSTALL.
  (b) Look at the example programs in the directory examples/, and try
  (b) Look at the example programs in the directory examples/, and try
     compiling and running them.  See the file examples/README.
     compiling and running them.  See the file examples/README.
  (c) Read a little documentation (in the directory doc/): we suggest
  (c) Read a little documentation (in the directory doc/): we suggest
     starting with ring.txt.
     starting with FGLM.txt.
   
   
   
   
  Documentation and how to use the library
  Documentation and how to use the library
  ----------------------------------------
  ----------------------------------------
  The documentation for CoCoALib comes in three parts:-
  The documentation for ApCoCoALib comes in three parts:-
   (1) example programs in the directory examples/
   (1) example programs in the directory examples/
   (2) hand-written documentation in the directory doc/
   (2) hand-written documentation in the directory doc/
  (3) automatically generated documentation in the directory doc/doxygen/
   
   
  We believe that many simple questions are probably best answered by looking
  We believe that many simple questions are probably best answered by looking
Line 33: Line 32:
  The hand-written documentation in the directory doc/ is supposed to be
  The hand-written documentation in the directory doc/ is supposed to be
  exhaustive (and is doubtless also rather exhausting).  The Doxygen files
  exhaustive (and is doubtless also rather exhausting).  The Doxygen files
  will be of more use to those already experienced in using CoCoALib.
  will be of more use to those already experienced in using ApCoCoALib.
   
   
   
   
  Writing and compiling your own programs
  Writing and compiling your own programs
  ---------------------------------------
  ---------------------------------------
  An easy way to write your own program using CoCoALib is to make a copy of
  An easy way to write your own program using ApCoCoALib is to make a copy of
  the file ex-empty.C (in the examples/ directory), and then insert your code
  the file ex-empty.C (in the examples/ directory), and then insert your code
  inside the procedure called "program".  Assuming you have called your program
  inside the procedure called "program".  Assuming you have called your program
Line 46: Line 45:
   
   
   
   
  The CoCoA Forum
  The (Ap-) CoCoA Forum
  ---------------
  ---------------
  You can find discussions about various aspects of CoCoALib on the CoCoA
  You can find discussions about various aspects of ApCoCoALib on the ApCoCoA
  forum which is hosted at the following address:
  forum which is hosted at the following address:
     http://cocoa.mathematik.uni-dortmund.de/forum/
     http://apcocoa.org/forum/
  It is also be a good place to seek help and advice about using CoCoALib,
  It is also be a good place to seek help and advice about using ApCoCoALib or CoCoALib,
  and to contribute to CoCoALib with your own comments and opinions.
  and to contribute to ApCoCoALib with your own comments and opinions.
   
   
   
   
  Principal Changes from CoCoALib-0.94
  Principal Changes from ApCoCoALib-1.00
  ------------------------------------
  -----------------------
Here are the main changes from version 0.94:
  * ???
   
- operations on ideals (and major rewriting of G* files)
- ref counting template (SmartPtrIRC)
- operations on ideals and modules
- GBases on FrF(R)[x] are now performed in R[x]
- preprocessing routines for approximate points (ApproxPts.H/C)
- code cleaner and better organized
- improved code portability (even to some Microsoft platforms)
   
   
  Debugging with CoCoALib
  Debugging with ApCoCoALib
  -----------------------
  -----------------------
  CoCoALib does offer some help in tracking down bugs in programs which
  ApCoCoALib does offer some help in tracking down bugs in programs which
  use it.  If the preprocessor symbol CoCoA_DEBUG is set then various
  use it.  If the preprocessor symbol CoCoA::CoCoA_DEBUG is set then various
  run-time assertions are enabled which perform extra checks in various
  run-time assertions are enabled which perform extra checks in various
  functions.  If you use the compiler  g++  then the simplest way to
  functions.  If you use the compiler  g++  then the simplest way to
  activate debugging is to modify two lines in the file
  activate debugging is to modify two lines in the file
  configuration/autoconf.mk -- the file contains comments to guide you.
  configuration/autoconf.mk -- the file contains comments to guide you.
  You may like to read doc/assert.txt to learn about CoCoA_ASSERT.
  You may like to read doc/assert.txt in CoCoALib to learn about CoCoA_ASSERT.
   
   
  If your program seems to have memory leaks, or other problems to do with
  If your program seems to have memory leaks, or other problems to do with
  memory alloccation, try reading the files doc/MemPool.txt, doc/debug_new.txt
  memory alloccation, try reading the files doc/MemPool.txt, doc/debug_new.txt
  and doc/leak_checker.txt which give advice on tracking down such problems.
  and doc/leak_checker.txt of CoCoALib which give advice on tracking down such problems.
  NB these are oriented towards programmers with a fair amount of experience.
  NB these are oriented towards programmers with a fair amount of experience.
      
      
Line 93: Line 83:
  indication of what you think the program should do, and where it  
  indication of what you think the program should do, and where it  
  apparently goes wrong.  The best way to inform us of the problem is to
  apparently goes wrong.  The best way to inform us of the problem is to
  send a description of the bug to the CoCoA Forum (its URL is
  send a description of the bug to the (Ap-) CoCoA Forum (its URL is
  http://cocoa.mathematik.uni-dortmund.de/forum/); specifically put your
  http://apcocoa.org/forum/); specifically put your
  message in the group "CoCoA 5 Users".
  message in the group "ApCoCoA Users".
If you'd rather not post to the CoCoA Forum, you can send email to:
  cocoa@dima.unige.it
=============================================================================
RCS header/log
$Header: /Volumes/Home/cocoa/cvs-repository/CoCoALib-0.99/README,v 1.2 2007/03/20 12:34:32 abbott Exp $
$Log: README,v $
Revision 1.2  2007/03/20 12:34:32  abbott
Minor rephrasing.
Revision 1.1.1.1  2007/03/09 15:16:10  abbott
Imported files
   
   
Revision 1.2  2006/06/21 17:04:12  cocoa
Improved README, INSTALL and configure script.
(perhaps I should have done this prior to release?)
[[Category:ApCoCoALib]]
[[Category:ApCoCoALib]]

Revision as of 16:09, 13 December 2007

This is a copy of ApCoCoALib's README file:

ApCoCoALib README
===============

Date: 13 December 2007
 
This subtrree contains the sources of the C++ library ApCoCoALib.  The ApCoCoA
library offers functions to perform calculations in Computational Commutative 
Algebra, and some other related areas.  Our intention is that the library
should be pleasant to use while offering good run-time performance.  To use
the library you will need to have some knowledge of C++.


Where to start
--------------
(a) Compile ApCoCoALib following the instructions in the file INSTALL.
(b) Look at the example programs in the directory examples/, and try
    compiling and running them.  See the file examples/README.
(c) Read a little documentation (in the directory doc/): we suggest
    starting with FGLM.txt.


Documentation and how to use the library
----------------------------------------
The documentation for ApCoCoALib comes in three parts:-
 (1) example programs in the directory examples/
 (2) hand-written documentation in the directory doc/

We believe that many simple questions are probably best answered by looking
at the example programs (and perhaps applying a little intelligent guesswork).
The hand-written documentation in the directory doc/ is supposed to be
exhaustive (and is doubtless also rather exhausting).  The Doxygen files
will be of more use to those already experienced in using ApCoCoALib.


Writing and compiling your own programs
---------------------------------------
An easy way to write your own program using ApCoCoALib is to make a copy of
the file ex-empty.C (in the examples/ directory), and then insert your code
inside the procedure called "program".  Assuming you have called your program
"proc.C" and placed it in the examples/ directory, compiling it is very easy:
just type the command "make prog"; if compilation succeeded, your program will
be in the file "prog".


The (Ap-) CoCoA Forum
---------------
You can find discussions about various aspects of ApCoCoALib on the ApCoCoA
forum which is hosted at the following address:
    http://apcocoa.org/forum/
It is also be a good place to seek help and advice about using ApCoCoALib or CoCoALib,
and to contribute to ApCoCoALib with your own comments and opinions.


Principal Changes from ApCoCoALib-1.00
-----------------------
* ???

Debugging with ApCoCoALib
-----------------------
ApCoCoALib does offer some help in tracking down bugs in programs which
use it.  If the preprocessor symbol CoCoA::CoCoA_DEBUG is set then various
run-time assertions are enabled which perform extra checks in various
functions.  If you use the compiler  g++  then the simplest way to
activate debugging is to modify two lines in the file
configuration/autoconf.mk -- the file contains comments to guide you.
You may like to read doc/assert.txt in CoCoALib to learn about CoCoA_ASSERT.

If your program seems to have memory leaks, or other problems to do with
memory alloccation, try reading the files doc/MemPool.txt, doc/debug_new.txt
and doc/leak_checker.txt of CoCoALib which give advice on tracking down such problems.
NB these are oriented towards programmers with a fair amount of experience.
   
  
  
Bugs and other problems
-----------------------
The code here is still quite young, and has been little tested.  It is
likely that you will come across some bugs or other undesirable 
behaviour.  If that happens, please let us know.  Your bug report should
include a SMALL program which exhibits the bad behaviour with a clear
indication of what you think the program should do, and where it 
apparently goes wrong.  The best way to inform us of the problem is to
send a description of the bug to the (Ap-) CoCoA Forum (its URL is
http://apcocoa.org/forum/); specifically put your
message in the group "ApCoCoA Users".