INTRODUCTION

• Quick Summary: CoCoALib and CoCoA-5
• Getting Started
  • Using CoCoALib
    • Writing Your Own Programs
    • Debugging with CoCoALib
  • Various Forms of Documentation
• Sundry Important Points
  • Powering and Exponentiation
  • Integers and Rationals

Quick Summary: CoCoALib and CoCoA-5

CoCoA-5 is an easy-to-use interactive system for computations in commutative algebra; it contains an on-line manual accessible via the ? command.

CoCoALib is a C++ library of functions for computations in commutative algebra.

This introduction is part of the documentation for CoCoALib; to use the library you will need some basic knowledge of the C++ programming language.

Getting Started

The first step is to compile the software: see INSTALL

Using CoCoALib

As we know that no one likes to read documentation, the best place to start is by looking at the examples/ directory full of sample code using CoCoALib.

Writing Your Own Programs

The simplest approach is to copy the example program ex-empty.C and modify that (see guide).

If you want to experiment with CoCoALib using a different directory, just copy examples/Makefile into your directory and change the line

  COCOA_ROOT=...

so that it specifies the full path of CoCoALib-XX, for instance

  COCOA_ROOT=/Users/bigatti/CoCoALib-0.99

In any case, it is best to start with a copy of ex-empty.C.

Debugging with CoCoALib

CoCoALib does offer some help in tracking down bugs in programs which use it. If the preprocessor symbol 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 [assert.html] to learn about CoCoA_ASSERT.

Various Forms of Documentation

CoCoALib comes with a collection of hand-written descriptions of its capabilities as well as a collection of example programs showing how to use many of the features of the library. The hope is that the example programs (plus perhaps a little intelligent guesswork) will suffice to answer most questions about CoCoALib. The hand-written documentation is intended to be more thorough: so less guesswork is needed, but you may have to plough through lots of tedious text to find the detail you're looking for.

The hand-written documentation is split into many files: generally there is one file of documentation for each implementation file in the source code. Furthermore, each file comprises three sections:

• User Documentation gives the information a normal user of the library may need to know, principally the function interfaces offered
• Maintainer Documentation contains notes and details about how the various functions are implemented in the library, essentially all information that might be needed to comprehend and maintain the code in the future
• Shortcomings, etc contains sundry notes about the implementation, for instance ideas on how the implementation might be improved in the future, doubts about certain design choices, and generally any thoughts to be taken into consideration for future versions.

This documentation is in the CoCoALib directory doc/txt/, and converted into html (doc/html/) and LaTeX (doc/tex/) using txt2tags.

A template file fo adding to this documentation and some basic instructions for txt2tags are in the file doc/txt/empty.txt.

There is also some automatically generated DOXYGEN documentation in [../doxygen/index.html]

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 most likely be of use to those already experienced in using CoCoALib.

Sundry Important Points

We have tried to give CoCoALib a natural interface, but this has not always been possible. Here are the main problem areas:

Powering and Exponentiation

The use of the hat symbol (^) to denote exponentiation is very widespread. CoCoALib does not allow this you must use the function power instead.

Why not? Because it would be too easy to write misleading code, i.e. valid code which does not compute what you would expect. Here is a simple example: 3*x^2 is interpreted by the compiler as (3*x)^2. Unfortunately there is no way to make the C++ compiler use the expected interpretation.

Integers and Rationals

The C++ language is not designed to compute directly with unlimited integers or with exact rational numbers; special types (namely BigInt and BigRat) to handle these sorts of values have been added as part of CoCoALib (with the real work being done by the GMP library). Nevertheless the user has to be wary of several pitfalls where code which looks correct at first glance does not produce the right answer.

• rationals must be constructed explicitly, e.g. the expression 2/3 is valid C++ but is interpreted as an integer division giving result 0; instead the rational must be constructed like this BigRat(2,3).

• large integer constants must be converted from a string representation, e.g. n = 99...99; (with 99 nines) will probably not even compile because of an error about "integer constant too big"; instead such a large value must be handled directly by CoCoALib in a call like convert(n, "99...99"); where the variable n has already been declared to be of type BigInt or BigRat.

• the compiler believes it knows how to perform arithmetic between machine integers, but the spectre of overflow continues to haunt such computations. Overflow cannot occur with values of type BigInt but the computations will be much slower than with machine integers. If you are quite sure that large values can never occur then it is fine to use machine integers; otherwise use unlimited integers.

• (AMB: add examples from talk in Kassel)

=== Reporting CoCoALib Bugs and other problems ==

Please let us know if you find any bugs in CoCoALib. Ideally 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 report an issue on

    http://cocoa.dima.unige.it/redmine/

If you'd rather not use redmine Forum, you can send email to:

   cocoa@dima.unige.it