Opened 3 years ago
Last modified 21 months ago
#26357 new enhancement
Add thematic tutorial to the polymake interface, based on polymake tutorials
Reported by: | mkoeppe | Owned by: | |
---|---|---|---|
Priority: | major | Milestone: | sage-8.4 |
Component: | documentation | Keywords: | |
Cc: | SimonKing, jipilab, vdelecroix, tscrim, tmonteil, dimpase, lorenz@… | Merged in: | |
Authors: | Matthias Koeppe | Reviewers: | |
Report Upstream: | N/A | Work issues: | |
Branch: | u/mkoeppe/add_polymake_tutorial (Commits, GitHub, GitLab) | Commit: | 59a2cc14b218bc02a5b2311aa802a8b0ceb4add5 |
Dependencies: | #28265 | Stopgaps: |
Description
polymake has a number of tutorials in two formats
- polymake website html: https://polymake.org/doku.php/tutorial/start - apparently released under CC BY-NC-SA
- ipynb at https://github.com/polymake/polymake/tree/Releases/demo - apparently released under GPL
In this ticket, we add a translation of the Perl-based tutorials to Python (via the polymake pexpect interface) as a thematic tutorial. (Upstream has been contacted regarding precise license status / possible relicensing under CC-BY-SA or similar to make it suitable for the Sage documentation.)
(This will also serve as an extended testsuite for the polymake pexpect interface.)
Preview of one translated tutorial: https://www.math.ucdavis.edu/~mkoeppe/art/icerm-2018/index.html#polymake-tutorial-on-polytopes-translated-to-python
Change History (25)
comment:1 Changed 3 years ago by
- Cc tmonteil added
comment:2 Changed 3 years ago by
- Branch set to u/mkoeppe/add_polymake_tutorial
comment:3 Changed 3 years ago by
- Commit set to 50b2a9e1021f25c571bd06e00e8d57e1ef3ed8f0
comment:4 Changed 2 years ago by
- Commit changed from 50b2a9e1021f25c571bd06e00e8d57e1ef3ed8f0 to 4dacfe969a6961be9fe5fd9d83af8ba4fe9411e8
Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:
624ac01 | polymake: Also provide core functions
|
666db96 | Added two missing optional tags
|
4e91dcc | Change format of a 'not tested' doc test annotation
|
05f3e61 | update docs, as discussed on #24905
|
53c8ee6 | Mention libterm-readkey-perl
|
b613e57 | Mention libterm-readline-gnu-perl
|
e5c3249 | polymake: Mention MOngoDB for polydb
|
b89376a | polymake: Update info on macOS
|
0c1b044 | polymake: update MongoDB information for linux distros
|
4dacfe9 | Merge branch 't/24905/public/upgrade_polymake_to_version_3_2r4' into t/26357/add_polymake_tutorial
|
comment:5 Changed 2 years ago by
- Dependencies changed from #26350 to #24905
comment:6 Changed 2 years ago by
- Commit changed from 4dacfe969a6961be9fe5fd9d83af8ba4fe9411e8 to 1ab08895becfbac5e323adc938d55594b23db0f3
comment:7 Changed 2 years ago by
- Cc dimpase added
comment:8 follow-up: ↓ 10 Changed 2 years ago by
Wouldn't it make more sense to put polymake
documentation in local/share/doc/polymake
? I don't see any reference to Sage at all in the tutorials, so it really doesn't belong in Sage's thematic_tutorials
directory. This is especially the case since this is an experimental package.
comment:9 Changed 2 years ago by
it doesn't build:
[dochtml] OSError: /home/dimpase/Sage/sagetrac-mirror/src/doc/en/thematic_tutorials/polymake/apps_graph.rst:206: WARNING: Inline interpreted text or phrase reference start-string without end-string. Makefile:2032: recipe for target 'doc-html' failed
I agree with John that the proper place for this needs to be found.
comment:10 in reply to: ↑ 8 Changed 2 years ago by
Replying to jhpalmieri:
Wouldn't it make more sense to put
polymake
documentation inlocal/share/doc/polymake
? I don't see any reference to Sage at all in the tutorials, so it really doesn't belong in Sage'sthematic_tutorials
directory. This is especially the case since this is an experimental package.
This ticket is not ready for review. So far this is just an automatic conversion of the polymake tutorials (interactions in Perl). When done, the Perl interactions will be replaced by Sage doctests.
comment:11 Changed 2 years ago by
Still, does it make sense to have a long multi-page document as part of the standard Sage documentation, based on an experimental package? Is there a way to include this as part of the polymake package, so it is only included when the package is installed?
comment:12 Changed 2 years ago by
perhaps one can wrap it as an experimental package.
comment:13 follow-ups: ↓ 15 ↓ 16 Changed 2 years ago by
I think it is a good idea to include this because it helps advertise things that Sage can do (with an add-on installed). Also, if it was included when the experimental package was installed, then essentially nobody would read it (at least, I don't think many non-developers even know where to find the built documentation). Now perhaps including everything is not what we should do, but instead distill it down to a more fundamental set of examples and capabilities with the full examples currently here as an extra file as part of the spkg's test suite.
Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?
comment:14 Changed 2 years ago by
polymake is far from being available on all platforms we support, see last comments on #24905
comment:15 in reply to: ↑ 13 Changed 2 years ago by
Replying to tscrim:
I think it is a good idea to include this because it helps advertise things that Sage can do (with an add-on installed).
The impression came across that the suggestion is to merely have the upstream (perl based!) documentation available. This would clearly not qualify as a Sage tutorial.
But even if the intention was to create a tutorial that is a SageMath tutorial (i.e., a document that exposes how to compute with polytopes in Sage using Polymake as a backend and leaving perl out of the picture): We are talking about an optional or experimental package, and so far the documentation of such packages is, by default, in SAGE_LOCAL/share/doc/<package name>.
Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?
If I understand correctly, a substantial part of the recent polymake tickets and also some threads on Sage-devel and sage-support included discussion on how to make it build. That would be reason enough demote an optional package to an experimental one.
comment:16 in reply to: ↑ 13 Changed 2 years ago by
- Cc lorenz@… added
Replying to tscrim:
Actually, why is the polymake an experimental package and not an optional one? Is it not considered reliable enough to build on all supported platforms?
1) As Dima said, at the moment there are still some (minor) portability problems:
a) On Centos because of the layout of the Perl installation. Upstream (Benjamin Lorenz) is aware of it and is working on a fix.
b) Also (per Dima) apparently gcc 6.3 as on Debian stable is too old to build polymake.
2) Because of Perl package dependencies, the installation not yet as fully automatic as other sage packages. See #27763 - any help and ideas there are welcome.
Polymake historically had a reputation of being hard to install, but the polymake team has made great improvements there. The remaining portability issues can be addressed in the same way as it is done for other packages.
comment:17 Changed 2 years ago by
- Commit changed from 1ab08895becfbac5e323adc938d55594b23db0f3 to 07636a9294708713a1f1357b39cbd4fc21b42439
comment:18 Changed 2 years ago by
- Commit changed from 07636a9294708713a1f1357b39cbd4fc21b42439 to c5f533a0954bfd3066f90371ce9be549eb48f0f2
comment:19 Changed 23 months ago by
- Commit changed from c5f533a0954bfd3066f90371ce9be549eb48f0f2 to 93c99f675e4233e5ff70239d7095670cb66e1624
Branch pushed to git repo; I updated commit sha1. New commits:
93c99f6 | Add sage doctests to apps_tropical tutorial
|
comment:20 Changed 21 months ago by
- Dependencies changed from #24905 to #28265
comment:21 Changed 21 months ago by
- Commit changed from 93c99f675e4233e5ff70239d7095670cb66e1624 to 5887a3bebcb63f218a1bf99ec92c8ab54936f1be
Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:
8b539c7 | Remove perl_intro.rst
|
e6e6342 | Add sage doctests to apps_polytope tutorial
|
2ff61b8 | Update polymake demo conversion template
|
7d95754 | Add sage doctests to apps_graph tutorial
|
95c47fc | Add sage doctests to apps_matroid tutorial
|
76a6dba | Add sage doctests to apps_fan tutorial
|
8420d70 | Add sage doctests to apps_tropical tutorial
|
acc1ecb | Update section titles
|
d7705de | sage.env: Add POLYMAKE_DATA_DIR
|
5887a3b | Translate 'polymake and Optimization' tutorial to Python
|
comment:22 Changed 21 months ago by
Rebased on top of #28265, 8.9.beta3
comment:23 Changed 21 months ago by
- Commit changed from 5887a3bebcb63f218a1bf99ec92c8ab54936f1be to 1270269082e8e31b2d0feb30f8460aa0380e37fa
Branch pushed to git repo; I updated commit sha1. New commits:
1270269 | Update polymake intro and some section titles
|
comment:24 Changed 21 months ago by
The tutorials are currently listed in alphabetical order by file name; they should probably be structured in the same way as here: https://polymake.org/doku.php/user_guide/start
comment:25 Changed 21 months ago by
- Commit changed from 1270269082e8e31b2d0feb30f8460aa0380e37fa to 59a2cc14b218bc02a5b2311aa802a8b0ceb4add5
First attempt at automatic conversion.
New commits:
Add citations to polymake publications
Add variant of src/bin/sage-ipynb2rst for converting polymake tutorials
src/doc/en/thematic_tutorials: Add polymake tutorial