CoCoALib:Contribute

Contribute with an example

The easiest way to help the CoCoALib project is to have a look at the "example" directory, run the examples, play with them, and send a comment about what can be improved.

You could also create a new example to be added to the distibution.

How do I run an example?

Download CoCoALib-xxx and compile it: (you will need GMP)

cd CoCoALib-xxx
./configure
make

to run an example do this:

cd examples
make ex-yyyyy
./ex-yyyy

How do I contribute an example?

Let's say you have written an example "ex-MyExample.C". To add your code to the CoCoALib examples follow the instructions below:

1. Put your file into the right place:
   • Copy the example file "ex-MyExample.C" into the subdirectory "CoCoALib-xxx/examples".
2. Edit "CoCoALib-xxx/examples/Makefile":
   • Add "ex-MyExample.C" to the variable definition of "SRC".

Now everything is ready to start a test build. First you have to rebuild the Makefile dependencies:

cd CoCoALib-xxx
cd examples
rm Makefile_dependencies
make dependencies

Next you should follow the instructions under How do I run an example? to test-run your example.

Contibute with a new class

Let's say you have written a new class "MyClass". Let "MyClass.C" and "MyClass.H" be the files that contain your source code. To add your code the CoCoALib follow the instructions below:

1. Put your files into the right place:
   • Copy the source file "MyClass.C" into the subdirectory "CoCoALib-xxx/src".
   • Copy the header file "MyClass.H" into the subdirectory "CoCoALib-xxx/include/CoCoA".
2. Edit "CoCoALib-xxx/include/CoCoA/library.H":
   • Add an include directive for your header file "MyClass.H".
3. Edit "CoCoALib-xxx/src/Makefile":
   • Add "MyClass.C" to the variable definition of "SRC".

Now everything is ready to start a test build. First you have to rebuild the Makefile dependencies:

cd CoCoALib-xxx
rm src/Makefile_dependencies
make dependencies

Next you should trigger a full build to see if everything works:

make all

If the build process terminates without an error you should write an example for your class and check if it works correctly. See How do I contribute an example? for more information.

Contribute a new CoCoAServer function

It is assumed that you already have done the steps listed in Contribute a CoCoA 4 function that calls the CoCoAServer.

All actions take place in "CoCoAServer.C".

1. Add your computation type
Look for

 enum ComputationType {none,GBasis,LT,...};

and add a new computation type that describes your computation.

2. Add your computation type to std::ostream& operator<<(std::ostream& out, ComputationType x)
Look for

 std::ostream& operator<<(std::ostream& out, ComputationType x) {...}

and add your computation type to the list. This will be the text that the CoCoAServer outputs when it is called.

3. Set correct computation type
In the "void program()" function look for the code block that starts with

 // Read Special Data
 SkipTag("<SpecialData>");
 GlobalInput() >> tag;
 while (tag!="</SpecialData>")
 {
   switch (tag[0])
   {
   case 'o':

The CoCoAServer reads a tag from CoCoA 4 containing the type of computation that is requested (i.e. the value of "ComputationType" you specified before calling "$cocoa5.OperationCommunication(...)" within CoCoA 4). The first character of "ComputationType" is used to identify the computation type. Extend the "switch" cases so that the current computation type is set correctly.

4. Carry out computation and return result
First you have to decide whether your computation is carried out over a graded free module or a polynomial ring (if neither of these fits you have to adjust the code in "CoCoAServer.C"):

Graded free module: Look for the code block that starts with

 double T = CpuTime();
 GlobalInput() >> tag;
 if (tag == "<graded_free_module>")

Polynomial ring: Look for the code block that starts with

 AssertTag(tag, "<polynomial_ring>");
 {      
   const SparsePolyRing P(ReadPolyRing());
   SkipTag("<polynomial_list>");

In either case you have to extend the "switch(computation)" block by adding a case that handles your type of computation. Look at the other cases to see what you have to do if you have to read more input from CoCoA 4 before you can start your computation.

General notes
The "ReadXY" and "WriteXY" functions are used to read/write from/to CoCoA 4.