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:

Status badges

Description

polymake has a number of tutorials in two formats

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 tmonteil

  • Cc tmonteil added

comment:2 Changed 3 years ago by mkoeppe

  • Branch set to u/mkoeppe/add_polymake_tutorial

comment:3 Changed 3 years ago by mkoeppe

  • Commit set to 50b2a9e1021f25c571bd06e00e8d57e1ef3ed8f0

First attempt at automatic conversion.


New commits:

a89a9fbAdd citations to polymake publications
dc29c9fAdd variant of src/bin/sage-ipynb2rst for converting polymake tutorials
50b2a9esrc/doc/en/thematic_tutorials: Add polymake tutorial

comment:4 Changed 2 years ago by git

  • Commit changed from 50b2a9e1021f25c571bd06e00e8d57e1ef3ed8f0 to 4dacfe969a6961be9fe5fd9d83af8ba4fe9411e8

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

624ac01polymake: Also provide core functions
666db96Added two missing optional tags
4e91dccChange format of a 'not tested' doc test annotation
05f3e61update docs, as discussed on #24905
53c8ee6Mention libterm-readkey-perl
b613e57Mention libterm-readline-gnu-perl
e5c3249polymake: Mention MOngoDB for polydb
b89376apolymake: Update info on macOS
0c1b044polymake: update MongoDB information for linux distros
4dacfe9Merge branch 't/24905/public/upgrade_polymake_to_version_3_2r4' into t/26357/add_polymake_tutorial

comment:5 Changed 2 years ago by mkoeppe

  • Dependencies changed from #26350 to #24905

comment:6 Changed 2 years ago by git

  • Commit changed from 4dacfe969a6961be9fe5fd9d83af8ba4fe9411e8 to 1ab08895becfbac5e323adc938d55594b23db0f3

Branch pushed to git repo; I updated commit sha1. New commits:

470c358Update automatically converted polymake tutorials from polymake 3.4
d8668a9update list of polymake tutorials
1ab0889Remove perl_intro.rst

comment:7 Changed 2 years ago by mkoeppe

  • Cc dimpase added

New commits:

470c358Update automatically converted polymake tutorials from polymake 3.4
d8668a9update list of polymake tutorials
1ab0889Remove perl_intro.rst

comment:8 follow-up: Changed 2 years ago by jhpalmieri

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.

Last edited 2 years ago by jhpalmieri (previous) (diff)

comment:9 Changed 2 years ago by dimpase

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 mkoeppe

Replying to jhpalmieri:

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.

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 jhpalmieri

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?

Last edited 2 years ago by jhpalmieri (previous) (diff)

comment:12 Changed 2 years ago by dimpase

perhaps one can wrap it as an experimental package.

comment:13 follow-ups: Changed 2 years ago by 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). 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 dimpase

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 SimonKing

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 mkoeppe

  • 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 git

  • Commit changed from 1ab08895becfbac5e323adc938d55594b23db0f3 to 07636a9294708713a1f1357b39cbd4fc21b42439

Branch pushed to git repo; I updated commit sha1. New commits:

ecb38fbMerge tag '8.8.beta5' into t/26357/add_polymake_tutorial
e003668Add sage doctests to apps_polytope tutorial
07636a9Update polymake demo conversion template

comment:18 Changed 2 years ago by git

  • Commit changed from 07636a9294708713a1f1357b39cbd4fc21b42439 to c5f533a0954bfd3066f90371ce9be549eb48f0f2

Branch pushed to git repo; I updated commit sha1. New commits:

ccc5c0cAdd sage doctests to apps_graph tutorial
f5e66b0Add sage doctests to apps_matroid tutorial
c5f533aAdd sage doctests to apps_fan tutorial

comment:19 Changed 23 months ago by git

  • Commit changed from c5f533a0954bfd3066f90371ce9be549eb48f0f2 to 93c99f675e4233e5ff70239d7095670cb66e1624

Branch pushed to git repo; I updated commit sha1. New commits:

93c99f6Add sage doctests to apps_tropical tutorial

comment:20 Changed 21 months ago by mkoeppe

  • Dependencies changed from #24905 to #28265

comment:21 Changed 21 months ago by git

  • Commit changed from 93c99f675e4233e5ff70239d7095670cb66e1624 to 5887a3bebcb63f218a1bf99ec92c8ab54936f1be

Branch pushed to git repo; I updated commit sha1. This was a forced push. Last 10 new commits:

8b539c7Remove perl_intro.rst
e6e6342Add sage doctests to apps_polytope tutorial
2ff61b8Update polymake demo conversion template
7d95754Add sage doctests to apps_graph tutorial
95c47fcAdd sage doctests to apps_matroid tutorial
76a6dbaAdd sage doctests to apps_fan tutorial
8420d70Add sage doctests to apps_tropical tutorial
acc1ecbUpdate section titles
d7705desage.env: Add POLYMAKE_DATA_DIR
5887a3bTranslate 'polymake and Optimization' tutorial to Python

comment:22 Changed 21 months ago by mkoeppe

Rebased on top of #28265, 8.9.beta3

comment:23 Changed 21 months ago by git

  • Commit changed from 5887a3bebcb63f218a1bf99ec92c8ab54936f1be to 1270269082e8e31b2d0feb30f8460aa0380e37fa

Branch pushed to git repo; I updated commit sha1. New commits:

1270269Update polymake intro and some section titles

comment:24 Changed 21 months ago by mkoeppe

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 git

  • Commit changed from 1270269082e8e31b2d0feb30f8460aa0380e37fa to 59a2cc14b218bc02a5b2311aa802a8b0ceb4add5

Branch pushed to git repo; I updated commit sha1. New commits:

ec05386polymake/apps_tropical.rst: Work around polymake interface limitations using getattr, get_member_function, function_call
59a2cc1polymake/optimization.rst: Use getattr
Note: See TracTickets for help on using tickets.