HowTo:Contribute an ApCoCoA-2 Package

From ApCoCoAWiki

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> exists. 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