View source for 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:

# Put your file into the right place:
#* Copy the example file "ex-MyExample.C" into the subdirectory "CoCoALib-xxx/examples".
# 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 [[Contribute_to_CoCoALib#How do I run an example?|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:

# 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".
# Edit "CoCoALib-xxx/include/CoCoA/library.H":
#* Add an include directive for your header file "MyClass.H".
# 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 [[Contribute_to_CoCoALib#How do I contribute an example?|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 [[HowTo:Contribute a CoCoA 4 function that calls the CoCoAServer|Contribute a CoCoA 4 function that calls the CoCoAServer]].

All actions take place in "CoCoAServer.C".

'''1. Add your computation type'''<br />
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)'''<br />
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'''<br />
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'''<br />
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'''<br />
The "ReadXY" and "WriteXY" functions are used to read/write from/to CoCoA 4.
[[Category:CoCoALib]]