Difference between revisions of "HowTo:Contribute an ApCoCoA-2 Package"

From ApCoCoAWiki
(Structure; most of the content outsourced to HowTo:Implement an ApCoCoA-2 Package and HowTo:Document an ApCoCoA-2 Package)
Line 1: Line 1:
−
There are three main steps for contributing an ApCoCoA Package:
+
This page describes how to contribute a package to ApCoCoA. There are three main steps for contributing an ApCoCoA Package:
−
# Implementing the package functions.
+
# Implementing the package functions, see [[HowTo:Implement an ApCoCoA-2 Package]],
−
# Adding a manual, a version info and the copyright licence to the package file
+
# Send your package to one of our [[Team|Team members]],
−
# Send us your package
+
# Describe your package in this Wiki, see [[HowTo:Document an ApCoCoA-2 Package]].
−
# Describing the package in the ApCoCoA Wiki.
 
  
−
In the following description, words marked as <code><span style="color:red;"><<word>></span></code> are placeholders, i.e. you should replace this text after copying.
+
== Example for an ApCoCoA package ==
−
 
 
−
== Implementation ==
 
−
At the very first, you have to create a file <code><span style="color:red;"><<package name>></span>.cpkg5</code>. This is the package file and will later be located in the folder
 
−
/plugins/apcocoa/lib/cocoa/packages/apcocoa/
 
−
in the apcocoa directory. If the package is self-contained, you can first put it anywhere and load it into ApCoCoA or CoCoA-5 for testing the functions. Otherwise, we recommend putting it in the ApCoCoA package directory on your system and test it using ApCoCoA. The package can be reloaded for testing using the command
 
−
Source MEMORY_ApCoCoA_Packages_Path + "<span style="color:red;"><<package name>></span>.cpkg5";
 
−
 
 
−
The following is a minimal example for the package:
 
−
Package $apcocoa/<span style="color:red;"><<package name>></span>
 
−
export skip;
 
−
 
−
EndPackage;
 
−
 
 
−
The line <code>export skip;</code> is needed in order to tell CoCoA that this package does not export any functions. If you want to export functions, you can delete this line.
 
−
 
 
−
Afterwards you can now add the functions you want to have in the package. For instance, if you write
 
−
Package $apcocoa/<span style="color:red;"><<package name>></span>
 
−
export skip;
 
−
 
−
Define Foo()
 
−
  PrintLn "Foo";
 
−
EndDefine; -- Foo
 
−
 
−
EndPackage;
 
−
 
 
−
you can call this function from CoCoA with <code>$apcocoa/<span style="color:red;"><<package name>></span>.foo();</code>.
 
−
 
 
−
== Adding package info ==
 
−
At first, add the following copyright information at the top of the package file (above <code>Package $apcocoa/<span style="color:red;"><<package name>></span></code>):
 
−
<div class="mw-collapsible mw-collapsed">
 
−
<div style="font-weight:bold;line-height:1.6; padding:1em; border:1px solid #c8ccd1; background-color: #f8f9fa;">Copyright information</div>
 
−
<div class="mw-collapsible-content">
 
−
--
 
−
-- This file is part of the ApCoCoA package pool.
 
−
--
 
−
--  Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
 
−
--
 
−
--  Authors: <span style="color:red;"><<year>> <<author name>></span>
 
−
--
 
−
-- Visit <nowiki>http://apcocoa.org/</nowiki> for more information regarding ApCoCoA.
 
−
-- Visit <nowiki>http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues</nowiki> for bugs, problems
 
−
-- and known issues.
 
−
--
 
−
-- The ApCoCoA package pool is free software; you can redistribute it and/or
 
−
-- modify it under the terms of the GNU General Public License (version 3 or
 
−
-- later) as published by the Free Software Foundation. A copy of the full
 
−
-- licence may be found in the file COPYING in this directory.
 
−
--
 
−
-- The ApCoCoA package pool is distributed in the hope that it will be useful,
 
−
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
 
−
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 
−
-- GNU General Public License for more details.
 
−
--
 
−
-- You should have received a copy of the GNU General Public License
 
−
-- along with the ApCoCoA package pool; if not, write to the Free Software
 
−
-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 
−
</div>
 
−
 
 
−
Then create two functions:
 
−
 
 
−
Define About()
 
−
  PrintLn "    Topic  : <span style="color:red;"><<Topic name (single word)>></span>";
 
−
  PrintLn "    Keywords: <span style="color:red;"><<keywords>></span>";
 
−
  PrintLn "    Authors : <span style="color:red;"><<author name>></span>";
 
−
  PrintLn "    Version : <span style="color:red;"><<current CoCoA version>></span>";
 
−
  PrintLn "    Date    : <span style="color:red;"><<release date>></span>";
 
−
EndDefine; -- About
 
−
 
−
Define Man()
 
−
  PrintLn "Recommended Alias:";
 
−
  PrintLn "  Alias <span style="color:red;"><<alias>></span> := $apcocoa/<span style="color:red;"><<package name>></span>;";
 
−
  PrintLn;
 
−
  ...
 
−
EndDefine; -- Man
 
−
 
 
−
The function <code>Man()</code> should contain a short description for every function contained in the package.
 
−
For a clearer description of <code>About()</code> see the example below.
 
−
 
 
−
== Send us your package ==
 
−
This point should be clear. Send the package to one of our [[Team|team members]] with a short description what this package is for, why it is important and which global alias you would like to get for it. Then we can give you feedback whether everything is correct and add the global alias to the meta package <code>meta.cpkg5</code>.
 
−
 
 
−
== Wiki Description ==
 
−
Please note that for step you need a wiki account. Such an account can only be created by a wiki admin, so please contact the ApCoCoA team so we can create an account for you.
 
−
 
 
−
Currently, the ApCoCoA help is exported from time to time from this wiki. For this to work properly, carefully proceed with the following steps:
 
−
# Create the page '''Category:Package <span style="color:red;"><<package name>></span>.
 
−
# Create the page '''Package <span style="color:red;"><<package name>></span>''' and add the code <code><nowiki>[[</nowiki>Category:Package <span style="color:red;"><<package name>></span><nowiki>]]</nowiki></code>. Here you can describe the package using all wiki tools including [https://www.mediawiki.org/wiki/Extension:Math latex].
 
−
# For every function in the package you want to describe, create a page '''Package <span style="color:red;"><<package name>></span>/<span style="color:red;"><<alias>></span>.<span style="color:red;"><<function name>></span>''', e.g. [[Package sagbi/SB.IsInSubalgebra]]
 
−
# (optional) If there was already a similar package in ApCoCoA-1, then you can replace <code><nowiki>{{Version|1}}</nowiki></code> by <code><nowiki>{{Version|1|</nowiki><span style="color:red;"><<link to new function page>></span><nowiki>}}</nowiki></code> on the old page and <code><nowiki>{{Version|2}}</nowiki></code> by <code><nowiki>{{Version|2|</nowiki><span style="color:red;"><<link to old function page>></span><nowiki>}}</nowiki></code> on the new page. For more information, see [[Template:Version]].
 
−
 
 
−
For the third step to work correctly, it is necessary to use the following XML template (see also [[Documentation Principles]] for ApCoCoA-1):
 
−
<!--------------------------------------------------------------------------------------------------------------------------->
 
−
<div class="mw-collapsible mw-collapsed">
 
−
<div style="font-weight:bold;line-height:1.6; padding:1em; border:1px solid #c8ccd1; background-color: #f8f9fa;">Wikipage template</div>
 
−
<div class="mw-collapsible-content">
 
−
<nowiki>{{Version|2}}
 
−
<command>
 
−
  <title></nowiki><span style="color:red;"><<alias>></span>.<span style="color:red;"><<function name>></span><nowiki></title>
 
−
  <short_description></nowiki><span style="color:red;">Function description in one sentence</span><nowiki></short_description>
 
−
 
 
−
  <syntax></nowiki><span style="color:red;"><<alias>></span>.<span style="color:red;"><<function name>></span>(<span style="color:red;"><<input parameters and types>></span>):<span style="color:red;"><<output type>></span><nowiki></syntax>
 
−
  <description>
 
−
    </nowiki><span style="color:red;"><nowiki><!-- Here comes a short description of the functions --></nowiki></span><nowiki>
 
−
    <itemize>
 
−
      </nowiki><span style="color:red;"><nowiki><!-- Describe every input parameter of the function --></nowiki></span><nowiki>
 
−
      <item>@param <tt></nowiki><span style="color:red;"><nowiki><<parameter name>></nowiki></span><nowiki></tt> </nowiki><span style="color:red;"><<parameter description>></span><nowiki></item>
 
−
      <item>@param <tt></nowiki><span style="color:red;"><nowiki><<parameter name>></nowiki></span><nowiki></tt> </nowiki><span style="color:red;"><<parameter description>></span><nowiki></item>
 
−
      <item>@return </nowiki><span style="color:red;"><nowiki><<description of the return value>></nowiki></span><nowiki></item>
 
−
    </itemize>
 
−
 
−
    </nowiki><span style="color:red;"><nowiki><!-- Examples here (also only one or more than two possible) --></nowiki></span><nowiki>
 
−
    </nowiki><span style="color:red;"><nowiki><!-- It is important to omit any indentation inside the example environment --></nowiki></span><nowiki>
 
−
    </nowiki><span style="color:red;"><nowiki><!-- may also go over more lines, but the </example>-tag should not be in a new line --></nowiki></span><nowiki>
 
−
    <example></nowiki><span style="color:red;"><nowiki><<first example>></nowiki></span><nowiki></example>
 
−
    <example></nowiki><span style="color:red;"><nowiki><<second example>></nowiki></span><nowiki></example>
 
−
  </description>
 
−
 
 
−
  </nowiki><span style="color:red;"><nowiki><!-- Add related pages (also more or none possible) --></nowiki></span><nowiki>
 
−
  <seealso>
 
−
    <see></nowiki><span style="color:red;"><nowiki><<first page>></nowiki></span><nowiki></see>
 
−
    <see></nowiki><span style="color:red;"><nowiki><<second page>></nowiki></span><nowiki></see>
 
−
  </seealso>
 
−
 
 
−
  </nowiki><span style="color:red;"><nowiki><!-- Add all data types used in the signature of your function (also more or none possible) --></nowiki></span><nowiki>
 
−
  <types>
 
−
    <type></nowiki><span style="color:red;"><nowiki><<first type>></nowiki></span><nowiki></type>
 
−
    <type></nowiki><span style="color:red;"><nowiki><<second type>></nowiki></span><nowiki></type>
 
−
  </types>
 
−
 
 
−
  </nowiki><span style="color:red;"><nowiki><!-- Add keys here (first three are mandatory, other ones are optional) --></nowiki></span><nowiki>
 
−
  <key></nowiki><span style="color:red;"><<function name>></span><nowiki></key>
 
−
  <key></nowiki><span style="color:red;"><<alias>>.<<function name>></span><nowiki></key>
 
−
  <key></nowiki><span style="color:red;"><<package name>>.<<function name>></span><nowiki></key>
 
−
  <key></nowiki><span style="color:red;"><<first key>></span><nowiki></key>
 
−
  <key></nowiki><span style="color:red;"><<second key>></span><nowiki></key>
 
−
 
 
−
  <wiki-category>Package </nowiki><span style="color:red;"><<package name>></span><nowiki></wiki-category>
 
−
 
 
−
</command>
 
−
</nowiki>
 
−
</div><!--
 
−
 
 
−
 
 
−
-->
 
−
<!--------------------------------------------------------------------------------------------------------------------------->
 
−
After creating the page, you can remove the comments, i.e. the lines starting with <span style="color:red;"><nowiki><!--</nowiki></span> and ending with <span style="color:red;"><nowiki>--></nowiki></span>. Alternatively, you can use the following template comments removed:
 
−
<div class="mw-collapsible mw-collapsed">
 
−
<div style="font-weight:bold;line-height:1.6; padding:1em; border:1px solid #c8ccd1; background-color: #f8f9fa;">Empty Wikipage template</div>
 
−
<div class="mw-collapsible-content">
 
−
<nowiki>{{Version|2}}
 
−
<command>
 
−
  <title></title>
 
−
  <short_description></short_description>
 
−
 
 
−
  <syntax></syntax>
 
−
  <description>
 
−
    <itemize>
 
−
      <item>@param <tt></tt>  </item>
 
−
      <item>@param <tt></tt>  </item>
 
−
      <item>@return  </item>
 
−
    </itemize>
 
−
 
 
−
    <example></example>
 
−
  </description>
 
−
 
 
−
  <seealso>
 
−
    <see></see>
 
−
    <see></see>
 
−
  </seealso>
 
−
 
 
−
  <types>
 
−
    <type></type>
 
−
    <type></type>
 
−
  </types>
 
−
 
 
−
  <key></key>
 
−
  <key></key>
 
−
  <key></key>
 
−
 
 
−
  <wiki-category>Package </wiki-category>
 
−
</command>
 
−
</nowiki>
 
−
</div>
 
−
 
 
−
=== Format options ===
 
−
Please do not use any Wiki styles on the function pages as they can not be exported to the ApCoCoA manual. Instead, use the following tags to format your text.
 
−
*For itemizations, use
 
−
<nowiki><itemize>
 
−
  <item>first item</item>
 
−
  <item>second item</item>
 
−
  ...
 
−
</itemize></nowiki>
 
−
*For bold text, use
 
−
<nowiki><em>...</em></nowiki>
 
−
*For code in the body text like variables, write
 
−
<nowiki><tt>...</tt></nowiki>
 
−
*For new paragraps (Wiki paragraphs are not exported to the Wiki manual), write:
 
−
<nowiki><par/></nowiki>
 
−
*For quotes, use
 
−
<nowiki><quotes>...</quotes></nowiki>
 
−
 
 
−
=== Important notes ===
 
−
*Do '''not''' use any quotation marks on the function pages, not even in the CoCoA examples. Instead, replace them by
 
−
<nowiki><quotes>...</quotes></nowiki>
 
−
*Do not use TeX or pictures on the function pages as they can not be exported to the Wiki manual. If you want to describe your package using TeX or pictures, please use the package page ''Package <span style="color:red;"><<package name>></span>'' you created before.
 
−
 
 
−
== Example ==
 
 
The file <code>sagbi.cpkg5</code> in the directory <code>apcocoa/</code> in the package directory starts with the following lines:
 
The file <code>sagbi.cpkg5</code> in the directory <code>apcocoa/</code> in the package directory starts with the following lines:
 
<div class="mw-collapsible mw-collapsed">
 
<div class="mw-collapsible mw-collapsed">
−
<div style="font-weight:bold;line-height:1.6; padding:1em; border:1px solid #c8ccd1; background-color: #f8f9fa;">Source code of <code>sagbi.cpkg5</code> (the relevant part)</div>
+
<div style="font-weight:bold;line-height:1.6; padding:1em; border:1px solid #c8ccd1; background-color: #f8f9fa;">Source code of sagbi.cpkg5 (the relevant part)</div>
 
<div class="mw-collapsible-content">
 
<div class="mw-collapsible-content">
 
  <nowiki>--
 
  <nowiki>--

Revision as of 10:53, 29 October 2020

This page describes how to contribute a package to ApCoCoA. There are three main steps for contributing an ApCoCoA Package:

  1. Implementing the package functions, see HowTo:Implement an ApCoCoA-2 Package,
  2. Send your package to one of our Team members,
  3. Describe your package in this Wiki, see HowTo:Document an ApCoCoA-2 Package.

Example for an ApCoCoA package

The file sagbi.cpkg5 in the directory apcocoa/ in the package directory starts with the following lines:

Source code of sagbi.cpkg5 (the relevant part)
--
-- This file is part of the ApCoCoA package pool.
--
--   Copyright (c) ApCoCoA Project (Prof. Dr. Martin Kreuzer, Uni Passau)
--
--   Authors: 2020 Bernhard Andraschko
--
-- Visit http://apcocoa.org/ for more information regarding ApCoCoA.
-- Visit http://www.apcocoa.org/wiki/ApCoCoA:KnownIssues for bugs, problems 
-- and known issues.
--
-- The ApCoCoA package pool is free software; you can redistribute it and/or
-- modify it under the terms of the GNU General Public License (version 3 or
-- later) as published by the Free Software Foundation. A copy of the full
-- licence may be found in the file COPYING in this directory.
--
-- The ApCoCoA package pool is distributed in the hope that it will be useful,
-- but WITHOUT ANY WARRANTY; without even the implied warranty of
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-- GNU General Public License for more details.
--
-- You should have received a copy of the GNU General Public License
-- along with the ApCoCoA package pool; if not, write to the Free Software
-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Package $apcocoa/sagbi

export skip;
  
Define About()
  PrintLn "    	Topic   : Subalgebras";
  PrintLn "    	Keywords: Subalgebra, SAGBI bases";
  PrintLn "    	Authors : B. Andraschko";
  PrintLn "    	Version : CoCoA 5.3.2";
  PrintLn "    	Date    : 7 September 2020";
EndDefine; -- About

Define Man()
  PrintLn "Recommended Alias:";
  PrintLn "   Alias SB := $apcocoa/sagbi;";
  PrintLn;
  PrintLn;
  PrintLn "Description:";
  PrintLn "   Contains basic functions for subalgebras of polynomial rings, e.g.";
  PrintLn "   Hilbert series, SAGBI bases of testing for subalgebra membership.";
  PrintLn "   In our context, a subalgebra is a tagged record containing all";
  PrintLn "   informations about the subalgebra as e.g. a unique ID, the base ring,";
  PrintLn "   generators, etc.";
  PrintLn "   To get these informations, one can use the getter methods described";
  PrintLn "   below. For Details about the record fields see the description of the";
  PrintLn "   function Subalgebra(...).";
  PrintLn;
  PrintLn;
  PrintLn "Function Description:";
  PrintLn "   Note: we write short \"SUBALGEBRA\" for \"TAGGED(\"$sagbi.Subalgebra\")\"";
  PrintLn "   For a short function list type in";
  PrintLn "     SB.FnList();";
  PrintLn;
  PrintLn " Main functions:";
  PrintLn;
  PrintLn "   Subalgebra(R: RING, fs: LIST) : SUBALGEBRA";
  PrintLn "     Input: a polynomial ring R and a list fs of polynomials in R";
  PrintLn "     Output: a tagged record S containing the following fields:";
  PrintLn "       ID: A unique ID";
  PrintLn "       CoeffRing: the coefficient ring K of R";
  PrintLn "       Ring: the super ring of S, i.e. R";
  PrintLn "       gens: a list of generators of the subalgebra, i.e. S = K[fs]";
  PrintLn "       SAGBI: a storage field for a (truncated) SAGBI basis of S";
  PrintLn "              - initially []";
  PrintLn "       trunc: the truncation degree of the currently computed truncated";
  PrintLn "              SAGBI basis - initially 0. If SAGBI is a complete SAGBI basis,";
  PrintLn "              then trunc is set to -1.";
  PrintLn "       HS: Hilbert Series of S - initially 0.";
  PrintLn "     Note: Assumes R is standard-graded ring";
  PrintLn;
  PrintLn "   SAGBI(G: LIST): LIST";
  PrintLn "     Input: a list of polynomials G";
  PrintLn "     Output: a SAGBI basis of K[G]";
  ...
EndDefine; -- Man

SubalgebraID := 0;

Define Subalgebra(R,fs)
  ...
EndDefine;

...

EndPackage;

In this Wiki, we have the pages Package sagbi, Category:Package sagbi and function pages like Package sagbi/SB.SAGBI:

Source code of the wiki page Package sagbi/SB.SAGBI
{{Version|2|[[ApCoCoA-1:SB.Sagbi]] and [[ApCoCoA-1:SB.ReducedSagbi]]}}
<command>
  <title>SB.SAGBI</title>
  <short_description>Computes a finite SAGBI-basis of a subalgebra if existing.</short_description>

  <syntax>SB.SAGBI(G:LIST of POLY):LIST of POLY</syntax>
  <description>
This function computes a finite SAGBI-basis of a subalgebra <tt>S</tt> generated by the polynomials of the list <tt>G</tt>, if a finite SAGBI-basis of <tt>S</tt> is existing. Then a list of polynomials is returned which form a SAGBI-basis of <tt>S</tt>. Otherwise the computation runs until it is interrupted.
    <itemize>
      <item>@param <em>G</em> A list of polynomials which generates a subalgebra.</item>
      <item>@return A list of polynomials which form a finite SAGBI-basis of the subalgebra generated by <tt>G</tt>.</item>
    </itemize>

    <example>
Use QQ[x,y,z], DegRevLex;
S := SB.SAGBI([x^2 -z^2,  x*y +z^2,  y^2 -2*z^2]);
indent(S);
-- [
--   y^2 -2*z^2,
--   x*y +z^2,
--   x^2 -z^2,
--   x^2*z^2 +x*y*z^2 +(1/2)*y^2*z^2 +(-1/2)*z^4
-- ]</example>
  </description>

  <seealso>
    <see>Package sagbi/SB.TruncSAGBI</see>
    <see>Package sagbi/SB.SAGBITimeout</see>
    <see>Package sagbi/SB.IsSAGBIOf</see>
    <see>Package sagbi/SB.GetSAGBI</see>
    <see>Package sagbi/SB.GetTruncSAGBI</see>
  </seealso>

  <types>
    <type>sagbi</type>
    <type>poly</type>
  </types>

  <key>SAGBI</key>
  <key>SB.SAGBI</key>
  <key>apcocoa/sagbi.SAGBI</key>

  <wiki-category>Package sagbi</wiki-category>
</command>

which produces

Page Package sagbi/SB.SAGBI
This article is about a function from ApCoCoA-2. If you are looking for the ApCoCoA-1 version of it, see ApCoCoA-1:SB.Sagbi and ApCoCoA-1:SB.ReducedSagbi.

SB.SAGBI

Computes a finite SAGBI-basis of a subalgebra if existing.

Syntax

SB.SAGBI(G:LIST of POLY):LIST of POLY

Description

This function computes a finite SAGBI-basis of a subalgebra S generated by the polynomials of the list G, if a finite SAGBI-basis of S is existing. Then a list of polynomials is returned which form a SAGBI-basis of S. Otherwise the computation runs until it is interrupted.

  • @param G A list of polynomials which generates a subalgebra.

  • @return A list of polynomials which form a finite SAGBI-basis of the subalgebra generated by G.

Example

Use QQ[x,y,z], DegRevLex;
S := SB.SAGBI([x^2 -z^2,  x*y +z^2,  y^2 -2*z^2]);
indent(S);
-- [
--   y^2 -2*z^2,
--   x*y +z^2,
--   x^2 -z^2,
--   x^2*z^2 +x*y*z^2 +(1/2)*y^2*z^2 +(-1/2)*z^4
-- ]

See also

Package sagbi/SB.TruncSAGBI

Package sagbi/SB.SAGBITimeout

Package sagbi/SB.IsSAGBIOf

Package sagbi/SB.GetSAGBI

Package sagbi/SB.GetTruncSAGBI

Retrieved from "http://apcocoa.uni-passau.de/wiki/index.php?title=HowTo:Contribute_an_ApCoCoA-2_Package&oldid=16018"