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 )
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)
Change History (39)
comment:1 Changed 12 years ago by
comment:2 Changed 9 years ago by
- Cc burcin added
- Report Upstream set to N/A
comment:3 follow-up: ↓ 4 Changed 9 years ago by
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
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
- Cc ranosch added
comment:6 Changed 9 years ago by
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
- Cc novoselt added
comment:8 follow-up: ↓ 10 Changed 9 years ago by
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 fromsage.misc.citation
? This comment is probably just my ignorance speaking, feel free to ignore it.
Good luck!
comment:9 follow-up: ↓ 11 Changed 9 years ago by
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
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 fromsage.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
- 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
- Cc PolyBoRi added; polybori removed
comment:13 Changed 9 years ago by
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
- 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
- Keywords sd34 added
comment:16 Changed 9 years ago by
- Dependencies set to #11851, #11852
Changed 9 years ago by
comment:17 Changed 9 years ago by
- 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
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
- Reviewers set to itaibn
comment:20 follow-up: ↓ 21 Changed 8 years ago by
- 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: ↓ 22 ↓ 23 Changed 8 years ago by
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
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
- 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
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.
comment:26 Changed 8 years ago by
- Description modified (diff)
comment:27 Changed 6 years ago by
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
- Description modified (diff)
- Type changed from task to enhancement
comment:29 Changed 5 years ago by
- Component changed from packages: standard to misc
comment:30 Changed 5 years ago by
- Cc jakobkroeker added
comment:31 Changed 4 years ago by
- 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
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…
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.