The design of the citation service is simple.

by Burcin Erocal

  • Bibliography items (software or mathematical papers, represented with the class citable) are declared in the code through different means, either by providing a BibTeX entry or the necessary fields separately.
  • At runtime, citations are stored in a structure called citations. Each function adds citation information to this structure when it is called. The entries are unique. Calling the same function twice does not add two different entries.
  • A Python decorator ("@cite") is used to wrap functions so that they insert the necessary information in the runtime citation database.

For example, in the following code segment declares a new citable item using its BibTeX entry:

sage: from sage.citation.citable import Citable
sage: class ACitableItem(Citable):
....:     r"""
....:     @misc{acitableitem,
....:     author = {Jane Doe},
....:     title  = {A software package you should cite},
....:     note   = {\url{www.example.url}}
....:     }
....:     """
....:

In order to make a function add this citation to the runtime database, the @cites decorator is used:

sage: from sage.citation import cites
sage: @cites(ACitableItem)
....: def some_func():
....:     pass
....:

The citations object gives access to this database and allows different queries:

sage: citations
0 used citations
sage: some_func()
sage: citations
1 used citations
sage: print citations
[1] Jane Doe. A software package you should cite. \url{www.example.url}.
sage: citations.output_format='bibtex'
sage: print citations
@misc{
    acitableitem,
    author = "Doe, Jane",
    note = "\url{www.example.url}",
    title = "A software package you should cite"
}

The following shows how articles and implementations are tracked in the database. Initializing a multivariate polynomial ring adds Singular to the list of citations:

sage: R.<x,y,z> = QQ[]
sage: print citations
[1] W. Decker, G.-M. Greuel, G. Pfister, and H. Sch\"{o}nemann. {\sc Singular} {3-1-3} --- {A} computer algebra system for polynomial computations. 2011, http://www.singular.uni-kl.de.

After computing the primary decomposition of an ideal, the database is populated with both a reference to the article and to the Singular library primdec.lib:

sage: p = z^2 + 1; q = z^3 + 2
sage: I = (p*q^2, y-z^2)*R
sage: t = I.complete_primary_decomposition()
sage: print citations
[1] Takeshi Shimoyama and Kazuhiro Yokoyama. Localization and primary decomposition of polynomial ideals. J. Symb. Comput., 22:247-277, September 1996.
[2] Gerhard Pfister, Wolfram Decker, and Hans Schoenemann. {\tt primdec.lib}. {A} {\sc Singular} library for primary decomposition. Part of the {\sc Singular} distribution, May 2001.
[3] W. Decker, G.-M. Greuel, G. Pfister, and H. Sch\"{o}nemann. {\sc Singular} {3-1-3} --- {A} computer algebra system for polynomial computations. 2011, http://www.singular.uni-kl.de.

If we choose to use a different algorithm implemented in the same library, the list of references change accordingly:

sage: citations.clear()
sage: t = I.complete_primary_decomposition(algorithm='gtz')
sage: print citations
[1] Patrizia Gianni, Barry Trager, and Gail Zacharias. Gr\"obner bases and primary decomposition of polynomial ideals. J. Symb. Comput., 6:149-167, December 1988.
[2] Gerhard Pfister, Wolfram Decker, and Hans Schoenemann. {\tt primdec.lib}. {A} {\sc Singular} library for primary decomposition. Part of the {\sc Singular} distribution, May 2001.
[3] W. Decker, G.-M. Greuel, G. Pfister, and H. Sch\"{o}nemann. {\sc Singular} {3-1-3} --- {A} computer algebra system for polynomial computations. 2011, http://www.singular.uni-kl.de.

A convenient feature of this implementation is that it can keep a list of dependencies among the citable items. For instance, after the following declaration, citing slimgb will bring in singular as well:

from citable import Citable

class singular(Citable):
    pass

class slimgb(singular)
    pass