ASKSAGE: Sage Q&A Forum - RSS feedhttps://ask.sagemath.org/questions/Q&A Forum for SageenCopyright Sage, 2010. Some rights reserved under creative commons license.Wed, 24 Jan 2018 13:26:07 +0100"Future-proof" Sage documentshttps://ask.sagemath.org/question/40698/future-proof-sage-documents/ I'm writing a paper and will be using a bundle of Sage scripts to help with various computations. I plan to post the script to the arxiv and submit it to a journal along with the paper.
I am curious whether there are any guidelines for writing Sage that is intended to be readable (and verifiable) in the medium- to long-term. Even assuming Sage is still around in 30 years, I am doubtful that current files will run. (For that matter, most of my programs won't run as soon as Sage switches to python3 due to the new print syntax.) I'd like to write the code in such a way that it could easily be adapted to whatever Sage-like software exists in the future, or such that future readers will at least be able trust the results of the computations.
In addition to generous comments, I plan to provide a human-readable file containing output of the main objects computed in the course of the work (matrices, algebraic expressions, ...). In my case, this is probably enough; the calculations are mostly just linear algebra at the end of the day. What else should I do? Has anyone ever worked with a university library or archive on for advice on writing future-proof Sage code?
Of course, this question applies to any paper relying on computer algebra calculations, not just those in Sage. I would also appreciate pointers to more broadly applicable articles on this topic.
I realize that old versions of Sage will probably still be accessible, and that a suitably-motivated mathematical historian might be able to get my code to compile. But this paper is not such a big deal -- I am looking for a solution that would lead someone to be able to reconstruct the results without so much effort.Fri, 19 Jan 2018 21:57:05 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/Comment by FrédéricC for <p>I'm writing a paper and will be using a bundle of Sage scripts to help with various computations. I plan to post the script to the arxiv and submit it to a journal along with the paper.</p>
<p>I am curious whether there are any guidelines for writing Sage that is intended to be readable (and verifiable) in the medium- to long-term. Even assuming Sage is still around in 30 years, I am doubtful that current files will run. (For that matter, most of my programs won't run as soon as Sage switches to python3 due to the new print syntax.) I'd like to write the code in such a way that it could easily be adapted to whatever Sage-like software exists in the future, or such that future readers will at least be able trust the results of the computations. </p>
<p>In addition to generous comments, I plan to provide a human-readable file containing output of the main objects computed in the course of the work (matrices, algebraic expressions, ...). In my case, this is probably enough; the calculations are mostly just linear algebra at the end of the day. What else should I do? Has anyone ever worked with a university library or archive on for advice on writing future-proof Sage code?</p>
<p>Of course, this question applies to any paper relying on computer algebra calculations, not just those in Sage. I would also appreciate pointers to more broadly applicable articles on this topic.</p>
<p>I realize that old versions of Sage will probably still be accessible, and that a suitably-motivated mathematical historian might be able to get my code to compile. But this paper is not such a big deal -- I am looking for a solution that would lead someone to be able to reconstruct the results without so much effort.</p>
https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40727#post-id-40727You can use python3 print syntax in python2, with some care.Sun, 21 Jan 2018 20:18:47 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40727#post-id-40727Answer by Sébastien for <p>I'm writing a paper and will be using a bundle of Sage scripts to help with various computations. I plan to post the script to the arxiv and submit it to a journal along with the paper.</p>
<p>I am curious whether there are any guidelines for writing Sage that is intended to be readable (and verifiable) in the medium- to long-term. Even assuming Sage is still around in 30 years, I am doubtful that current files will run. (For that matter, most of my programs won't run as soon as Sage switches to python3 due to the new print syntax.) I'd like to write the code in such a way that it could easily be adapted to whatever Sage-like software exists in the future, or such that future readers will at least be able trust the results of the computations. </p>
<p>In addition to generous comments, I plan to provide a human-readable file containing output of the main objects computed in the course of the work (matrices, algebraic expressions, ...). In my case, this is probably enough; the calculations are mostly just linear algebra at the end of the day. What else should I do? Has anyone ever worked with a university library or archive on for advice on writing future-proof Sage code?</p>
<p>Of course, this question applies to any paper relying on computer algebra calculations, not just those in Sage. I would also appreciate pointers to more broadly applicable articles on this topic.</p>
<p>I realize that old versions of Sage will probably still be accessible, and that a suitably-motivated mathematical historian might be able to get my code to compile. But this paper is not such a big deal -- I am looking for a solution that would lead someone to be able to reconstruct the results without so much effort.</p>
https://ask.sagemath.org/question/40698/future-proof-sage-documents/?answer=40729#post-id-40729What people do since 10 years to solve this question is the following. This method was [suggested by William Stein in December 2008](http://groups.google.com/group/sage-support/msg/3ea7ed2eeab0824a) and has been used many times especially in the cases of books using Sage. Every example appearing in their book/paper is added as a doctests in a file which is included in Sage (in the folder src/sage/tests) that are then guarrenteed to continue running at each new release of Sage.
For example, all the code examples from the french book about Sage is in the subfolder [src/sage/tests/french_book]( https://github.com/sagemath/sage/tree/master/src/sage/tests/french_book) where "*each file corresponds to a chapter of the book*".
Another example which was added by Dan Drake in 2008 is named after a paper he submitted on arxiv [src/sage/tests/arxiv_0812_2725.py](https://github.com/sagemath/sage/blob/master/src/sage/tests/arxiv_0812_2725.py)
Another option is to publish your code in [ReScience](http://rescience.github.io/): "*ReScience is a peer-reviewed journal that targets computational research and encourages the explicit replication of already published research, promoting new and open-source implementations in order to ensure that the original research is reproducible.*"Sun, 21 Jan 2018 22:31:37 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/?answer=40729#post-id-40729Comment by Emmanuel Charpentier for <p>What people do since 10 years to solve this question is the following. This method was <a href="http://groups.google.com/group/sage-support/msg/3ea7ed2eeab0824a">suggested by William Stein in December 2008</a> and has been used many times especially in the cases of books using Sage. Every example appearing in their book/paper is added as a doctests in a file which is included in Sage (in the folder src/sage/tests) that are then guarrenteed to continue running at each new release of Sage.</p>
<p>For example, all the code examples from the french book about Sage is in the subfolder <a href="https://github.com/sagemath/sage/tree/master/src/sage/tests/french_book">src/sage/tests/french_book</a> where "<em>each file corresponds to a chapter of the book</em>".</p>
<p>Another example which was added by Dan Drake in 2008 is named after a paper he submitted on arxiv <a href="https://github.com/sagemath/sage/blob/master/src/sage/tests/arxiv_0812_2725.py">src/sage/tests/arxiv_0812_2725.py</a></p>
<p>Another option is to publish your code in <a href="http://rescience.github.io/">ReScience</a>: "<em>ReScience is a peer-reviewed journal that targets computational research and encourages the explicit replication of already published research, promoting new and open-source implementations in order to ensure that the original research is reproducible.</em>"</p>
https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40730#post-id-40730A couple remarks :
* This applies to Sage developers, not to the whole of Sage users. Unless the development team commits itself to include all doctests from all papers using Sage ever published...
* This may be a hindrance if the need fornot-packward-compatible changes appears...
That would be a nice subject for `sage-devel`...Mon, 22 Jan 2018 08:22:03 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40730#post-id-40730Comment by vdelecroix for <p>What people do since 10 years to solve this question is the following. This method was <a href="http://groups.google.com/group/sage-support/msg/3ea7ed2eeab0824a">suggested by William Stein in December 2008</a> and has been used many times especially in the cases of books using Sage. Every example appearing in their book/paper is added as a doctests in a file which is included in Sage (in the folder src/sage/tests) that are then guarrenteed to continue running at each new release of Sage.</p>
<p>For example, all the code examples from the french book about Sage is in the subfolder <a href="https://github.com/sagemath/sage/tree/master/src/sage/tests/french_book">src/sage/tests/french_book</a> where "<em>each file corresponds to a chapter of the book</em>".</p>
<p>Another example which was added by Dan Drake in 2008 is named after a paper he submitted on arxiv <a href="https://github.com/sagemath/sage/blob/master/src/sage/tests/arxiv_0812_2725.py">src/sage/tests/arxiv_0812_2725.py</a></p>
<p>Another option is to publish your code in <a href="http://rescience.github.io/">ReScience</a>: "<em>ReScience is a peer-reviewed journal that targets computational research and encourages the explicit replication of already published research, promoting new and open-source implementations in order to ensure that the original research is reproducible.</em>"</p>
https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40738#post-id-40738The frontier between developer and user is meant to be as thin as possible. If you care about your tests being future-proof, then you might want to become a developer.Mon, 22 Jan 2018 19:20:19 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40738#post-id-40738Comment by nbruin for <p>What people do since 10 years to solve this question is the following. This method was <a href="http://groups.google.com/group/sage-support/msg/3ea7ed2eeab0824a">suggested by William Stein in December 2008</a> and has been used many times especially in the cases of books using Sage. Every example appearing in their book/paper is added as a doctests in a file which is included in Sage (in the folder src/sage/tests) that are then guarrenteed to continue running at each new release of Sage.</p>
<p>For example, all the code examples from the french book about Sage is in the subfolder <a href="https://github.com/sagemath/sage/tree/master/src/sage/tests/french_book">src/sage/tests/french_book</a> where "<em>each file corresponds to a chapter of the book</em>".</p>
<p>Another example which was added by Dan Drake in 2008 is named after a paper he submitted on arxiv <a href="https://github.com/sagemath/sage/blob/master/src/sage/tests/arxiv_0812_2725.py">src/sage/tests/arxiv_0812_2725.py</a></p>
<p>Another option is to publish your code in <a href="http://rescience.github.io/">ReScience</a>: "<em>ReScience is a peer-reviewed journal that targets computational research and encourages the explicit replication of already published research, promoting new and open-source implementations in order to ensure that the original research is reproducible.</em>"</p>
https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40761#post-id-40761It puts a little more inertia on changes, but it won't prevent them. Tests get adjusted if changes in sage behaviour are intentional. Truly future-proofing and making your results reproducible consists of documenting and archiving the particular sage version used. Running old software is a separate problem, but a widely encountered one and something that archivists will solve (VMs perhaps?)Wed, 24 Jan 2018 13:26:07 +0100https://ask.sagemath.org/question/40698/future-proof-sage-documents/?comment=40761#post-id-40761