Ask Your Question

"Future-proof" Sage documents

asked 2018-01-19 21:57:05 +0200

ConfusedMark gravatar image

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.

edit retag flag offensive close merge delete


You can use python3 print syntax in python2, with some care.

FrédéricC gravatar imageFrédéricC ( 2018-01-21 20:18:47 +0200 )edit

1 Answer

Sort by » oldest newest most voted

answered 2018-01-21 22:31:37 +0200

Sébastien gravatar image

updated 2018-01-25 14:59:56 +0200

What people do since 10 years to solve this question is the following. This method was suggested by William Stein in December 2008 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 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/

Another option is to publish your code in ReScience: "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."

edit flag offensive delete link more


A 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...

Emmanuel Charpentier gravatar imageEmmanuel Charpentier ( 2018-01-22 08:22:03 +0200 )edit

The 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.

vdelecroix gravatar imagevdelecroix ( 2018-01-22 19:20:19 +0200 )edit

It 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?)

nbruin gravatar imagenbruin ( 2018-01-24 13:26:07 +0200 )edit

Your Answer

Please start posting anonymously - your entry will be published after you log in or create a new account.

Add Answer

Question Tools


Asked: 2018-01-19 21:57:05 +0200

Seen: 456 times

Last updated: Jan 25 '18