Opened 12 years ago

Last modified 4 years ago

#3317 needs_work enhancement

a citation system for Sage components

Reported by: mhampton Owned by: mhampton
Priority: major Milestone: sage-feature
Component: misc Keywords: citations, sd34
Cc: burcin, novoselt, ranosch, PolyBoRi, jakobkroeker Merged in:
Authors: Niels Ranosch, Michael Brickenstein, Burcin Erocal Reviewers:
Report Upstream: N/A Work issues: merge conflicts
Branch: Commit:
Dependencies: #11851, #11852 Stopgaps:

Description (last modified by burcin)

This ticket implements a citation tracking system for Sage which can give fine grained information on the algorithms and implementations used for a specific computation. This is in contrast to the current method in sage.misc.citation that relies on running a smaller example through the profiler.

The new citation module allows developers to add annotations with citation data in the code directly via decorators tuned to minimize performance overhead. Citations can be provided and obtained in several different formats, thanks to the pybtex package. This includes bibtex and plain text output.

Sample user session:

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

If a different algorithm is requested, the citations reflect this change:

sage: citations.clear()
sage: t = I.complete_primary_decomposition(algorithm='gtz')
sage: print citations
[1] Patrizia Gianni, Barry Trager, and Gail Zacharias. Groebner 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. Schoenemann. {\sc
    Singular} {3-1-3} --- {A} computer algebra system for polynomial
computations. 2011, http://www.singular.uni-kl.de.

Only apply:

Attachments (7)

trac-3317-bib-data.patch (14.2 KB) - added by ranosch 9 years ago.
bibtex-data of some components
trac-3317-example-usage.2.patch (2.2 KB) - added by ranosch 9 years ago.
trac-3317-citation-system-integrated.patch (85.4 KB) - added by ranosch 8 years ago.
New citation system
trac-3317-citation-environment.patch (2.6 KB) - added by ranosch 8 years ago.
environment changes for the citation system
trac-3317-citation-system.patch (68.0 KB) - added by ranosch 8 years ago.
New citation system
trac-3317-bibtex-data.patch (14.8 KB) - added by ranosch 8 years ago.
bibtex-data of some components
trac-3317-example-usage.patch (1.6 KB) - added by ranosch 8 years ago.
Example usage in multipolynomial-libsingular

Download all attachments as: .zip

Change History (39)

comment:1 Changed 12 years ago by mhampton

Some thoughts:

From: "Fernando Perez" <fperez....@…> Date: May 27, 7:02 pm Subject: Citing Sage and Used Systems To: sage-devel

This is certainly not an easy problem if one wants a '100%' solution, in the sense that tracking down every single line of code in any given computation isn't easy. But here's a quick idea that can give an '80%' solution for all in-process sage/python/extension code (it won't work for code done by external processes like maxima, I'm afraid). If you run in the ipython console a program via '%run -p' it will be executed under the control of the profiler, and the result will tell you what functions were called, how many times, etc. Similarly %prun lets you execute single statements with profiler control. The profiler results object can be returned and analyzed further, if I recall correctly there is some information in there about where functions come from.

comment:2 Changed 9 years ago by burcin

  • Cc burcin added
  • Report Upstream set to N/A

comment:3 follow-up: Changed 9 years ago by jhpalmieri

Right now we have the code in sage/misc/citation.pyx. Is that good enough so that this ticket should be closed?

comment:4 in reply to: ↑ 3 Changed 9 years ago by burcin

Replying to jhpalmieri:

Right now we have the code in sage/misc/citation.pyx. Is that good enough so that this ticket should be closed?

This basically does what is described in comment:1. We need to do much better than that.

We are working on a system which allows developers to annotate (decorate?) functions with citation information. The decorated functions will add the citation entries to a central database at runtime. This database can be queried to get the list of packages/papers/algorithms used in various formats.

In short, I don't think we can close this yet.

comment:5 Changed 9 years ago by ranosch

  • Cc ranosch added

comment:6 Changed 9 years ago by ranosch

Burcin Erocal, Michael Brickenstein and I (Niels Ranosch) have been working on a new citation system for about a month now: https://bitbucket.org/niels_mfo/sage-citation

The patches will be attached. What do you think about it?

You'll need our pybtex-spkg in order to make it work: http://sage.math.washington.edu/home/burcin/spkg/pybtex-0.15.spkg

Cheers.

comment:7 Changed 9 years ago by novoselt

  • Cc novoselt added

comment:8 follow-up: Changed 9 years ago by kcrisman

Hi! If this doesn't slow things down, it is a really good idea, especially given that Sage is not trying to cover up the other programs inside of it. I assume that (given the comments on the blog) you will post timing information in critical areas eventually.

I have one substantive comment, I think:

You'll need our pybtex-spkg in order to make it work: http://sage.math.washington.edu/home/burcin/spkg/pybtex-0.15.spkg

Hmm, so does that mean we would need to make pybtex a standard package in order for this to work? (Currently there is a probationary period needed, which we have recently been enforcing.)

Or are you suggesting this would be an optional spkg (for now), which means your examples would have to be optional for now?

Here follow a couple silly comments that don't actually review much, but might still be worthwhile to ponder.

  • Missing "to": in order make it faster
  • A lot of the examples refer to Michael Brickenstein, which seems somewhat less than advisable. I mean no disrespect here - clearly he is contributing loads and deserves citations! But for the first-time reader of this documentation, it would be nice to have a bigger variety of citations, perhaps even beyond Sage components to the subcomponents. For instance, the ones in the bibtex patch.
  • What does [trac-3317-example-usage.patch] exactly have an example of? I see the @cites(citable_items.slimgb) - is this demonstrating that we get the same thing through the new decorator as we would have from sage.misc.citation? This comment is probably just my ignorance speaking, feel free to ignore it.

Good luck!

comment:9 follow-up: Changed 9 years ago by jhpalmieri

Should some of the new code (e.g., citation/__init__.py) be in the reference manual?

comment:10 in reply to: ↑ 8 Changed 9 years ago by ranosch

Replying to kcrisman:

Hi! If this doesn't slow things down, it is a really good idea, especially given that Sage is not trying to cover up the other programs inside of it. I assume that (given the comments on the blog) you will post timing information in critical areas eventually.

At least that's what I plan to do. I'm not quite sure on how to benchmark (and what), but I'm open for suggestions. Benchmarking the decorated pass-function is unsatisfying.

I have one substantive comment, I think:

You'll need our pybtex-spkg in order to make it work: http://sage.math.washington.edu/home/burcin/spkg/pybtex-0.15.spkg

Hmm, so does that mean we would need to make pybtex a standard package in order for this to work? (Currently there is a probationary period needed, which we have recently been enforcing.)

Well, I put the design, as if pybtex was a standard-spkg. But it might as well be a good idea to make it optional: If people really pybtex' features, they can install it. It could be the following: If pybtex is not installed, the printed citations will just be the exact content of the bibfile, otherwise parsed (and maybe converted). But there might be disadvantages: If the bibtex is parsed by pybtex, syntax-errors and illegal formatting might be found by pybtex. The output would probably be more consistent (more homogeneous and more compliant to design).

I am in favour of pre-parsing everything through pybtex, but I don't know, what is actually better.

Or are you suggesting this would be an optional spkg (for now), which means your examples would have to be optional for now?

Here follow a couple silly comments that don't actually review much, but might still be worthwhile to ponder.

  • Missing "to": in order make it faster

Thanks.

  • A lot of the examples refer to Michael Brickenstein, which seems somewhat less than advisable. I mean no disrespect here - clearly he is contributing loads and deserves citations! But for the first-time reader of this documentation, it would be nice to have a bigger variety of citations, perhaps even beyond Sage components to the subcomponents. For instance, the ones in the bibtex patch.

You are right. It is more a coincidence than anything else; still, it has to be changed.

  • What does [trac-3317-example-usage.patch] exactly have an example of? I see the @cites(citable_items.slimgb) - is this demonstrating that we get the same thing through the new decorator as we would have from sage.misc.citation? This comment is probably just my ignorance speaking, feel free to ignore it.

I won't :-). For this citation system, it is indispensable, that the decorator gets widespread into sage. In my opinion, it is best if people decorate their own functions (and possibly make their own bibtex-entries). The example shows, how a function should be decorated. (The deprecation-message can be uncommented later, as soon as the "new" citation system is more accurate than the old one.)

comment:11 in reply to: ↑ 9 Changed 9 years ago by ranosch

  • Cc polybori added

Replying to jhpalmieri:

Should some of the new code (e.g., citation/__init__.py) be in the reference manual?

Ehm .. I think so, but don't know. Still, I'm quite a newbie.

comment:12 Changed 9 years ago by ranosch

  • Cc PolyBoRi added; polybori removed

comment:13 Changed 9 years ago by ranosch

Corrected some of the errors and included my benchmark results for the decorated pass-function (in citation/__init__.py's _benchmark_-function).

Another problem came to my mind: If a user tries to make an instance of one of the citables, strange things will happen. But I'm not sure, if we should really care about that.

Is the documentation alright?

Cheers.

comment:14 Changed 9 years ago by ranosch

  • Authors set to Niels Ranosch, Michael Brickenstein, Burcin Erocal
  • Status changed from new to needs_review

The benchmarking results are available on http://sage-citation.blogspot.com/2011/08/awful-benchmarks.html and https://bitbucket.org/niels_mfo/sage-citation/src/74ea62a5c9b3/benchmark/.

I still think, it would be best, if pybtex would become a standard package.

Is there any work needed for the reference manual (referring to jhpalmieri's comment)?

comment:15 Changed 9 years ago by ranosch

  • Keywords sd34 added

comment:16 Changed 9 years ago by ranosch

  • Dependencies set to #11851, #11852

Changed 9 years ago by ranosch

bibtex-data of some components

Changed 9 years ago by ranosch

comment:17 Changed 9 years ago by ranosch

  • Description modified (diff)

Uploaded an updated version (with the sage citation included) and accidently added trac-3317-example-usage.2.patch ... please ignore this file.

comment:18 Changed 8 years ago by mhansen

I'm not convinced that it is the best idea to have it so that anytime a function is called we have to log that its citation, even in the case where we don't care about that data.

comment:19 Changed 8 years ago by itaibn

  • Reviewers set to itaibn

comment:20 follow-up: Changed 8 years ago by itaibn

  • Description modified (diff)
  • Status changed from needs_review to needs_work

This patch doesn't fail nicely when you don't have pybtex. I didn't know it was a dependency and so sage was unable to start. I modified the ticket to indicate the dependency.

comment:21 in reply to: ↑ 20 ; follow-ups: Changed 8 years ago by AlexanderDreyer

Replying to itaibn:

This patch doesn't fail nicely when you don't have pybtex. I didn't know it was a dependency and so sage was unable to start. I modified the ticket to indicate the dependency.

The dependency had been explicitly mentioned in the ticket already. Since the only intention of this ticket is to integrate pybtex into Sage, it make sense to explicitly mention the spkg for convenience.

But you also set the ticket to needs_work. The authors might be interested what you require them to change. (You say that Sage won't start, but this is true for all integration patches when you forget to install the spkg in question.)

comment:22 in reply to: ↑ 21 Changed 8 years ago by AlexanderDreyer

Replying to AlexanderDreyer:

The dependency had been explicitly mentioned in the ticket already. Since the only intention of this ticket is to integrate pybtex into Sage, it make sense to explicitly mention the spkg for convenience.

Correction myself: of course it is not the only intention of the ticket, but an important one.

comment:23 in reply to: ↑ 21 Changed 8 years ago by itaibn

  • Description modified (diff)
  • Reviewers itaibn deleted
  • Status changed from needs_work to needs_review

I'm sorry, I didn't read the ticket description carefully enough. I have modified the ticket to redact my earlier modifications.

comment:24 Changed 8 years ago by ranosch

Sorry for not having responded.

Replying to mhansen:

I'm not convinced that it is the best idea to have it so that anytime a function is called we have to log that its citation, even in the case where we don't care about that data.

What exactly are your concerns? Speed? Integrity?

In my opinion it would be very nice to have tracked the used components, no matter if we care for this data. And it's not meant to log every function call. Only rather important functions should be decorated (could say "cite-worthy", but that's a vague term). Maybe there should be rules on what makes some worth citing in Sage.


Replying to itaibn:

Well thanks for pointing out, that it might be unclear that you need the spkg. I thought it will be enough if the dependency is mentioned as the dependency of the corresponding ticket, but I'm willing to change the description if that's not clear enough.

I'm currently updating the spkg to a newer version, should I directly include the link to it when done?


Replying to AlexanderDreyer:

The intention of this ticket (as far as I see it) is to track sage's components and their citations. Pybtex is our tool of choice. Therefore, yes, it is important.

Changed 8 years ago by ranosch

New citation system

comment:25 Changed 8 years ago by ranosch

  • Description modified (diff)

Fixed bugs and doctests.

Changed 8 years ago by ranosch

environment changes for the citation system

Changed 8 years ago by ranosch

New citation system

Changed 8 years ago by ranosch

bibtex-data of some components

Changed 8 years ago by ranosch

Example usage in multipolynomial-libsingular

comment:26 Changed 8 years ago by ranosch

  • Description modified (diff)

comment:27 Changed 6 years ago by zimmerma

would it be possible to add in the description some concrete example demonstrating what functionality this ticket adds to Sage?

Paul

comment:28 Changed 6 years ago by burcin

  • Description modified (diff)
  • Type changed from task to enhancement

comment:29 Changed 5 years ago by jdemeyer

  • Component changed from packages: standard to misc

comment:30 Changed 5 years ago by jakobkroeker

  • Cc jakobkroeker added

comment:31 Changed 4 years ago by saraedum

  • Status changed from needs_review to needs_work
  • Work issues set to merge conflicts

The patches do not apply anymore (not too surprising after so many years.)

comment:32 Changed 4 years ago by saraedum

To be honest I like the approach used by citation.pyx better because it does not add any performance overhead unless you care. Then again, the output generated by the patches here is really nice…

Note: See TracTickets for help on using tickets.