INTRODUCTION

© 2010 John Abbott, Anna Bigatti
GNU Free Documentation License, Version 1.2



CoCoALib Documentation Index

Quick Summary

How to join in

Compile CoCoALib

You need to have the GMP library already installed.

  cd CoCoALib-0.99
  ./configure
  make

(if you have N cores you may use them typing make -jN).

This will compile the library and run a series of tests. The code is quite portable, so just wait faithfully (don't worry about some warnings), and after a few minutes you'll get the reassuring message:

  Good news: all tests passed

If not, you probably have some problems with your gmp or g++ installation. If you think it is a genuine problem with CoCoALib send an email to cocoa at dima.unige.it

Use CoCoALib

As we know that no one likes to read documentation, we provide an examples/ directory full of sample code using CoCoALib. To run an example do this:

  cd examples
  make ex-yyyyy      <--- without the ".C"
  ./ex-yyyyy

Your own programs

If you want to experiment with CoCoALib in your personal directory, say MyExperiments, just copy the Makefile from the examples directory into MyExperiments/Makefile, and change its line

  COCOA_ROOT=..

with the full path (no ~) for CoCoALib-XX, for example

  COCOA_ROOT=/Users/bigatti/CoCoALib-0.99

In particular ex-empty.C is a useful starting point: just make a copy of it into MyExperiments/MyFirstProgram.C and put your code in the function void program() under the line

  // Put your code here.

Then compile it and run it as above:

  make MyFirstProgram
  ./MyFirstProgram

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:

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.

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.