- 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
