Lie Methods and Related Combinatorics (tutorial)

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

This patch adds a tutorial about Lie Methods and Related Combinatorics to Sage.

A copy of the html documentation built with dvipng may be found at:

http://match.stanford.edu/bump/thematic_tutorials/lie.html

or built with jsmath:

http://match.stanford.edu/bump/thematic_tutorials-js/lie.html

Note: only the second js version is up to date. I will update the other one later.

Apply:

Then build the doc with

sage -docbuild thematic_tutorials html

add the -j flag to use jsmath.

See also #8470.

CC: @sagetrac-sage-combinat @nilesjohnson

Component: documentation

Author: Daniel Bump

Reviewer: Minh Van Nguyen, Mark Jordan, Dmitrii Pasechnik

Merged: sage-4.6.2.alpha3

Issue created by migration from https://trac.sagemath.org/ticket/8442

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:1

Attachment: wcf1.png

This patch adds a tutorial about Lie Methods and Related Combinatorics to Sage.

Apply the patch and also copy the file wcf1.png into $SAGE_ROOT/devel/sage-queue/doc/en/lie/. Then you can build the documentation with the commands:

sage -docbuild lie html

sage -docbuild lie pdf

There is supposed to be a chapter on Crystals but that is not written yet.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Work Issues: Crystal chapter not written yet

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -1 +1,12 @@

+This patch adds a tutorial about Lie Methods and Related Combinatorics to Sage.
+
+Apply the patch and also copy the file wcf1.png into $SAGE_ROOT/devel/sage-queue/doc/en/lie/. Then you can build the documentation with the commands:
+
+sage -docbuild lie html
+
+sage -docbuild lie pdf
+
+There is supposed to be a chapter on Crystals but that is not written yet.
+
+Depends on #8411 and #8414 since it documents the behavior of Sage after these patches.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -1,7 +1,6 @@
-
 This patch adds a tutorial about Lie Methods and Related Combinatorics to Sage.

-Apply the patch and also copy the file wcf1.png into $SAGE_ROOT/devel/sage-queue/doc/en/lie/. Then you can build the documentation with the commands:
+Apply the patch and also copy the file wcf1.png into $SAGE_ROOT/devel/sage/doc/en/lie/. Then you can build the documentation with the commands:

 sage -docbuild lie html

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Description changed:

--- 
+++ 
@@ -9,3 +9,7 @@
 There is supposed to be a chapter on Crystals but that is not written yet.

 Depends on #8411 and #8414 since it documents the behavior of Sage after these patches.
+
+
+
+**Notes:** The current ticket needs to be coordinated with #8470.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Attachment: a2rho.png

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Attachment: standard1.png

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -6,10 +6,16 @@

 sage -docbuild lie pdf

-There is supposed to be a chapter on Crystals but that is not written yet.
-
 Depends on #8411 and #8414 since it documents the behavior of Sage after these patches.

 **Notes:** The current ticket needs to be coordinated with #8470.
+
+A copy of the html documentation may be found at:
+
+http://sporadic.stanford.edu/bump/trac_8442/
+
+I think an html link should be added from 
+`$SAGE_ROOT/devel/sage/doc/output/html/en/index.html`. I
+did not add such a link in the patch. See #8470.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Changed work issues from Crystal chapter not written yet to none

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -1,6 +1,6 @@
 This patch adds a tutorial about Lie Methods and Related Combinatorics to Sage.

-Apply the patch and also copy the file wcf1.png into $SAGE_ROOT/devel/sage/doc/en/lie/. Then you can build the documentation with the commands:
+Apply the patch and also copy the files wcf1.png, a2rho.png and standard1.png into $SAGE_ROOT/devel/sage/doc/en/lie/. Then you can build the documentation with the commands:

 sage -docbuild lie html

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Lie methods and related combinatorics tutorial

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:7

Attachment: trac_8442_lie_documentation.patch.gz

Revised to take into account changes in #8414.

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

comment:8

I'm rebasing trac_8442_lie_documentation.patch on top of the prerequisites at #8470.

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Attachment: trac_8442-lie-rebased.patch.gz

rebased Lie tutorial

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Attachment: trac_8442-reviewer.patch.gz

reviewer patch

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Reviewer: Minh Van Nguyen

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Description changed:

--- 
+++ 
@@ -19,3 +19,5 @@
 I think an html link should be added from 
 `$SAGE_ROOT/devel/sage/doc/output/html/en/index.html`. I
 did not add such a link in the patch. See #8470.
+
+**Prerequisites:** #8468

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

comment:9

I have rebased Dan's patch; see the result at trac_8442-lie-rebased.patch. I have also attached a reviewer patch that makes substantial clean-ups in terms of style and consistency. Changes include:

Remove the use of ":math:". That is not necessary, as the Sage docbuilder can handle typeset mathematics without that syntax. Also, the resulting text is easier to read without heaps of ":math:" scattered throughout a ReST document.
Some stylistic clean-ups.
Make the formatting consistent.
Using the syntax ".. MATH::" to center math expressions.

Both Dan's rebased patch and my reviewer patch need reviewing. This ticket now depends on #8468.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:10

Looks very good after the rebased patch and the reviewer's patch.

The three .png files must be in doc/en/thematic_tutorials/static/ .

The patch will require minor revision if #8414 is not merged. (There is also a dependence on #8411 but less important.) If this proves necessary I will provide a revision. It is a matter of changing "space" back to "lattice" in a few places.

I give a positive review to the rebased and reviewer's patch. I am not changing the patch status since I am the author of the original patch.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Attachment: trac_8442-weyl_groups-revision.patch.gz

Additional patch taking into account changes in #8414

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -16,8 +16,14 @@

 http://sporadic.stanford.edu/bump/trac_8442/

-I think an html link should be added from 
-`$SAGE_ROOT/devel/sage/doc/output/html/en/index.html`. I
-did not add such a link in the patch. See #8470.
+There are three patches to merge:
+
+```
+ trac_8442-lie-rebased.patch
+ trac_8442-reviewer.patch
+ trac_8442-weyl_groups-revision.patch
+```
+
+In addition, the three .png files must be where they get properly linked.

 **Prerequisites:** #8468

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:11

Due to changes in #8414, there is an additional small patch called trac_8442-weyl_groups-revision.patch.

6985fd69-200c-47fd-825b-715f5da6d75f commented 14 years ago

comment:12

Looks good! I tested it fine using the three latest patches and the three PNG files. Pictures were inserted properly and looked fine. ~Mark

6985fd69-200c-47fd-825b-715f5da6d75f commented 14 years ago

comment:13

Tested with Sage Version 4.4.2.alpha0, Release Date: 2010-05-08 and index.rst under thematic tutorials fails to apply now. ~Mark

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Attachment: trac_8442-lie-rebased-to-4.4.2.alpha0.gz

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:14

I have uploaded the patch trac_8442-lie-rebased-to-4.4.2.alpha0.

This contains the three patches:

trac_8442-lie-rebased.patch 
trac_8442-reviewer.patch-reviewer patch
trac_8442-weyl_groups-revision.patch

The purpose of this patch is simply to address mjordan's comment that the patch does not apply cleanly. In order to accomplish a clean this the patch adds files doc/en/thematic_tutorials/index.rst and bibliography.rst. These files presume that three other thematic tutorials will also be included in sage - otherwise they will produce broken links.

The release manager may prefer to work with the original three patches.

Note that in addition to the patch three .png files must be included.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -24,6 +24,15 @@
  trac_8442-weyl_groups-revision.patch

+The patches do not apply to sage-4.4.2.alpha0 because two files +in doc/en/thematic_tutorials are missing: index.rst and bibliography.rst. +An alternative patch + + `+trac_8442-lie-rebased-to-4.4.2.alpha0 +` + +includes these files, and applies cleanly to sage-4.4.2.alpha0. Otherwise it is +identical to the union of the three patches. + In addition, the three .png files must be where they get properly linked.

-Prerequisites: #8468

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Attachment: trac_8442-config.patch.gz

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Attachment: trac_8442-lie-rebased-4.4.2.rc0.patch.gz

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Description changed:

--- 
+++ 
@@ -36,3 +36,10 @@
 identical to the union of the three patches.

 In addition, the three .png files must be where they get properly linked.
+
+**Apply:**
+
+1. #8464
+2. [trac_8442-config.patch](https://github.com/sagemath/sage-prod/files/10648393/trac_8442-config.patch.gz)
+3. [trac_8442-lie-rebased-4.4.2.rc0.patch](https://github.com/sagemath/sage-prod/files/10648394/trac_8442-lie-rebased-4.4.2.rc0.patch.gz)
+4. Copy [wcf1.png](https://github.com/sagemath/sage/files/ticket8442/wcf1.png), [a2rho.png](https://github.com/sagemath/sage/files/ticket8442/a2rho.png), and [standard1.png](https://github.com/sagemath/sage/files/ticket8442/standard1.png) to the directory `doc/en/thematic_tutorials/static/`.

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

Changed reviewer from Minh Van Nguyen to Minh Van Nguyen, Mark Jordan

7c09a680-e216-4024-bb8e-9bfd4aa7f313 commented 14 years ago

comment:16

In addition to applying cleanly, the thematic tutorials must also show up on the standard documentation and be linked from there. I have uploaded the patch trac_8442-config.patch in order to configure the documentation build system to link to the thematic tutorials. The patch trac_8442-lie-rebased-4.4.2.rc0.patch is a rebase of Dan's patch against Sage 4.4.2.rc0. This rebase also configures the doc build system to build the Lie tutorial. The situation now is that anyone but myself can sign off on the two latest patches I uploaded. That is, anyone but myself need to only review those two patches. See the ticket description for instruction on how to apply patches on this ticket.

1d7ec08f-60ae-4512-91a6-8324c06eab9f commented 14 years ago

comment:17

This is a very impressive contribution to the documentation and will be a great example for the thematic section. Applied #8464, the two patches, and the added the three PNG's. Everything applied and built cleanly, once I caught the proper location for the three PNG files.

However, running doctests produced 22 errors across several of the files. On 4.4.2.rc0

sage -t doc/en/thematic_tutorials/lie

yields

The following tests failed:

        sage -t  "devel/sage-main/doc/en/thematic_tutorials/lie/weyl_groups.rst"
        sage -t  "devel/sage-main/doc/en/thematic_tutorials/lie/weight_ring.rst"
        sage -t  "devel/sage-main/doc/en/thematic_tutorials/lie/crystals.rst"
        sage -t  "devel/sage-main/doc/en/thematic_tutorials/lie/weyl_character_ring.rst" # Exception from doctest framework
        sage -t  "devel/sage-main/doc/en/thematic_tutorials/lie/branching_rules.rst"

I did not investigate the source of the failures very carefully, Many of them were of the "name 'foo' not defined" variety rather than mis-matched outputs. Hopefully this isn't a false alarm.

I'd be happy to give this another look after somebody investigates/fixes the doctests.

Rob

jhpalmieri commented 14 years ago

comment:18

In addition to the doctest failures, here are some other issues:

The documentation page that you get by clicking "help" in the notebook, then "fast static versions ...", does not look good with the new section on thematic tutorials: I don't think the three-column layout looks good.

The command \mathfrak is not recognized by jsMath, so if you make the documentation with the --jsmath flag, it has a lot of errors.

Also, I would suggest creating a directory doc/en/thematic_tutorials/media/ (just like in the reference directory, and we put pictures there. Wherever the pictures go, they need to be included in SAGE_ROOT/devel/sage/MANIFEST.in so they get included in the Sage library spkg -- you need a line like

recursive-include doc/en/thematic_tutorials/media *

By the way, you can include the png files in the patch by using the command

$ hg add (path to file)/standard1.png
$ hg commit ...
$ hg export -g ...

(See [#9074 comment:4] for a similar explanation.)

jhpalmieri commented 14 years ago

comment:19

If #8465 gets merged, then trac_8442-config.patch will not be needed.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Attachment: trac_8442-lie-rebased-4.5.2.patch.gz

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -43,3 +43,5 @@
 2. [trac_8442-config.patch](https://github.com/sagemath/sage-prod/files/10648393/trac_8442-config.patch.gz)
 3. [trac_8442-lie-rebased-4.4.2.rc0.patch](https://github.com/sagemath/sage-prod/files/10648394/trac_8442-lie-rebased-4.4.2.rc0.patch.gz)
 4. Copy [wcf1.png](https://github.com/sagemath/sage/files/ticket8442/wcf1.png), [a2rho.png](https://github.com/sagemath/sage/files/ticket8442/a2rho.png), and [standard1.png](https://github.com/sagemath/sage/files/ticket8442/standard1.png) to the directory `doc/en/thematic_tutorials/static/`.
+
+

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:20

Attachment: trac_8442-lie-rebased-4.5.2.2.patch.gz

I have added two revised patches:

trac_8442-lie-rebased-4.5.2.patch
trac_8442-png-files.patch

By mistake I added the first patch twice.

These address most of the problems found by rbeezer and jhpalmieri.

Now passes sage -t
New doc/en/thematic_tutorials/media/*png
doc/en/thematic_tutorials/*png added to MANIFEST.in
.png files are in a patch.

The one matter I did not try to address is the problem with jsMath. Is there a jsMath way to get fraktur fonts?

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

Description changed:

--- 
+++ 
@@ -44,4 +44,14 @@
 3. [trac_8442-lie-rebased-4.4.2.rc0.patch](https://github.com/sagemath/sage-prod/files/10648394/trac_8442-lie-rebased-4.4.2.rc0.patch.gz)
 4. Copy [wcf1.png](https://github.com/sagemath/sage/files/ticket8442/wcf1.png), [a2rho.png](https://github.com/sagemath/sage/files/ticket8442/a2rho.png), and [standard1.png](https://github.com/sagemath/sage/files/ticket8442/standard1.png) to the directory `doc/en/thematic_tutorials/static/`.

+**Revised instructions. Apply:**

+```
+ trac_8442-lie-rebased-4.5.2.patch
+ trac_8442-png-files.patch
+```
+
+
+
+
+

1d7ec08f-60ae-4512-91a6-8324c06eab9f commented 14 years ago

comment:22

Replying to @dwbump:

The one matter I did not try to address is the problem with jsMath. Is there a jsMath way to get fraktur fonts?

MathJAX is slated to replace jsMath. It has been released, but I can't guess at how much work it will be to get it into the notebook. https://github.com/sagemath/sage-prod/issues/9774

It would appear from the discussion below that Fraktur fonts will be possible (maybe standard) then. http://meta.mathoverflow.net/discussion/473/help-test-mathjax/

It seems Fraktur is available now for jsMath, but maybe we don't ship that with the notebook? http://www.math.union.edu/~dpvc/jsMath/download/extra-fonts/welcome.html

I'll look closer at reviewing this again when I've got a bit more time.

Rob

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:23

I just discovered that after the patch this still does not pass sage -t.

Maybe I uploaded the wrong patch.

I am changing the status back to needs_work.

Dan

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:24

Evidently I made a mercurial mistake and uploaded the wrong patch. (I probably forgot to commit before exporting.)

Furthermore, the fraktur problem is serious enough that it needs to be fixed. Unfortunately frakture jsmath fonts are available but not installed by default. Perhaps the best short-term option is to find another font.

Finally, I can make use of the information here:

http://groups.google.com/group/sage-devel/msg/086441965eb4f20b

to improve the document. This addresses the cause of many of the failures. I am leaving the status needs_work for the time being.

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:25

I am posting corrected files that pass sage -t with sage-4.5.3.

Regarding the --jsmath issue, the \mathfrak problem is not the end of the story. There are further problems. Matrices of size > 2 look awful with jsmath, and in the section crystals.rst there are some tableaux. I tried two different methods of creating these in tex. One failed since jsmath doesn't know \raisebox, and the other (based on arrays) failed since jsmath doesn't know \hline.

I therefore feel it is better not to try revising the files to work with jsmath. I recommend building them without jsmath and can revisit the issue after the switch to mathjax. The built documentation (with dvipng) is here:

http://match.stanford.edu/bump/thematic_tutorials/lie.html

I am changing the status back to needs_review.

1d7ec08f-60ae-4512-91a6-8324c06eab9f commented 14 years ago

comment:26

Replying to @dwbump:

Matrices of size > 2 look awful with jsmath, and in the section crystals.rst there are some tableaux. I tried two different methods of creating these in tex. One failed since jsmath doesn't know \raisebox, and the other (based on arrays) failed since jsmath doesn't know \hline.

Hi Dan,

I've had good luck with jsMath if I use \begin{tabular}\end{tabular} and then wrap individual entries with dollar signs. Then the \hline's seem to workout OK. The PDF doesn't really seem to suffer too much from this abuse.

I don't know if MathJAX or jsMath will ever be too happy about a \raisebox - the notion of a precise length doesn't always translate from printed page to web page very well.

Anyway, I didn't even look at your tableau, but you might experiment with a single one using the tabular environment and decide from there.

Rob

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:27

I've had good luck with jsMath if I use \begin{tabular}\end{tabular} and then wrap individual entries with dollar signs. Then the \hline's seem to workout OK. The PDF doesn't really seem to suffer too much from this abuse.

Can you give an example?

My hope is that the patch can be reviewed without making jsmath a prerequisite. The doc looks good with dvipng, but not so good with jsmath. I could substitute another font for fraktur (I tried mathbf), and I could try again with your suggestion for making tableaux, and I could try to overlook the fact that the large matrices really awful with mathjs, but given that the dvipng doc looks fine, I'd rather leave it as it is and revisit the issue when mathjax rolls in.

Dan

jhpalmieri commented 14 years ago

comment:28

I almost always use the --jsmath option for docbuilding because it's faster than not using it. I would guess that some other people do the same. We really try to avoid warnings when building the docs, so I don't know if this should get a positive review if it doesn't build right with jsmath, especially since there is an easy fix: use something other than mathfrak.

Wait, here's an idea: we can add a jsMath macro (as described here) to define \mathfrak in jsMath to be boldface, for example. Since this is defined in jsMath, it doesn't override the ordinary definition if you're not using the jsmath option. This is easy to do: we just patch the configuration file for the thematic tutorials document. I'm attaching a patch.

jhpalmieri commented 14 years ago

Attachment: trac_8442-mathfrak.patch.gz

avoid jsmath errors about mathfrak

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:29

I have revised the patch. The resulting patch produces a tutorial that looks OK with both dvipng and jsmath. This addressed three problems.

(1) For \mathfrak, it includes trac_8442-mathfrak.patch (thanks!)

(2) The problems with matrices turned out to be only on a particular machine. On this machine, every browser I've tried (firefox, seamonkey and konqueror) makes jsmath matrices look very broken. But the same html looks OK on other machines.

(3) For the tableaux, I hand-made png images for all of these. I also did some other rewriting of the section on crystals.

Thanks to jhpalmieri and rbeezer for feedback.

Dan

1d7ec08f-60ae-4512-91a6-8324c06eab9f commented 14 years ago

comment:30

Hi Dan,

I think I was a bit too cavalier. I've been converting a lot of Latex to jsMath (using the tex4ht converter) and switching to tabular solves lots of gotchas, but I don't think I can make that approach work directly. In other words, no - I don't have an example, despite trying quite a few things last night. I hope I didn't send you on too wild of a goose chase.

On the plus side, MathJax looks good - I've been fiddling with it (outside of the notebook).

I think PNGs are a good compromise. I've been helping Tom Judson with his open source textbook and he's redone the diagrams in tikz. There's code in the CVS version of PGF that will "externalize" the graphics. So the PDF has "native" diagrams, and the web page versions suck in the externalized PNG graphics versions as images. Real similar to your workaround here.

Rob

6bbcde06-8197-41f1-b9a3-c998bb839000 commented 14 years ago

comment:31

I reposted the two relevant patches, trac_8442-png-files.patch and trac_8442-rebased-4.5.3.patch.

I made some further changes to crystals.rst and I found that one of the png files had been obsoleted by the revisions, hence removed it from the distributed files.

Dan

sagemath / sage

Lie Methods and Related Combinatorics (tutorial) #8442