Improve Sandpiles thematic tutorial

[tscrim]

There are a number of things that could use some polish. This is just to fix the issues I see.

CC: @sagetrac-dperkinson

Component: documentation

Author: Travis Scrimshaw

Branch/Commit: e7d9fb4

Reviewer: Darij Grinberg

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

[tscrim]

New commits:

4debab9

Doing some polishing of the sandpile tutorial.

[tscrim]

Branch: public/doc/fix_sandpile_tutorial-22264

[tscrim]

Commit: 4debab9

[sagetrac-git]

Changed commit from 4debab9 to 826950f

[sagetrac-git]

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

2645cc6	Merge branch 'public/doc/fix_sandpile_tutorial-22264' of git://trac.sagemath.org/sage into sand
e2849dc	various improvements
8acc059	s is accessible from itself
826950f	some further improvements

[darijgr]

comment:3

Some changes made, more to come...

[sagetrac-git]

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

a72a9bb

oops typo

[sagetrac-git]

Changed commit from 826950f to a72a9bb

[darijgr]

comment:5

The *minimal burning configuration* is the one with the minimal script (its
components are no larger than the components of any other script for a burning
configuration).

Does the "no larger" mean "less or equal", or does it really mean "not larger"? (Due to the tacit all-quantor here, this makes a difference.)

The following are equivalent for a configuration `c` with burning
configuration `b` having script `\sigma`:

- `c` is recurrent;
- `c + b` stabilizes to `c`;
- the firing vector for the stabilization of `c + b` is `\sigma`.

Am I seeing it right that the b has nothing to do with c? Because the "with" suggests that it does, but I'm not sure what...

[darijgr]

Reviewer: Darij Grinberg

[tscrim]

comment:7

Two things I see from a quick look:

• Instead of \mathbb{Z} use \ZZ.
• I think every vertex is accessible from some vertex in its support. is ambiguous, in contrast saying there is a path.

For comment:5. I don't see the difference since I am interpreting it as something compared component-by-component. My guess is that b is related to c by the underlying graph. So they are not quite completely separate.

[darijgr]

comment:8

Thanks! The "accessible" is defined further above in that .rst file, so I thought it makes sense. But I'll add both wordings.

Yes, b and c have nothing to do with each other, as I've just found out from http://www.dam.brown.edu/people/cklivans/Dynkin.pdf . And the "no larger" is indeed componentwise (Theorem 2.28 in https://arxiv.org/pdf/1112.6163.pdf ). I will clarify these tomorrow when I am back on a Linux machine.

[sagetrac-git]

Changed commit from a72a9bb to 01171dc

[sagetrac-git]

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

01171dc

some more improvements/corrections

[darijgr]

comment:10

I don't understand what is_alive does (the example isn't definitive here). The doc is also not quite clear (what is "the resulting cycle"?).

Also, how can this be true?

The *zero set* for the sandpile ideal `I` is

.. MATH::

    Z(I) = \{p\in\CC^n: f(p)=0\mbox{ for all $f\in I$}\},

the set of simultaneous zeros of the polynomials in `I`.  Letting `S^1` denote
the unit circle in the complex plane, `Z(I)` is a finite
subgroup of `S^1 \times \cdots \times S^1 \subset \CC^n`

The circle S^1 is not a subvariety of \CC in the sense of algebraic geometry over \CC...

[sagetrac-git]

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

2353f7f

a few more

[sagetrac-git]

Changed commit from 01171dc to 2353f7f

[darijgr]

comment:12

I'm done with my review of everything up until the "methods" section. What remains are the two questions in comment:10; also, what exactly is the Tutte polynomial?

[sagetrac-git]

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

b637b1f

and a few more

[sagetrac-git]

Changed commit from 2353f7f to b637b1f

[tscrim]

comment:14

ping

[tscrim]

comment:15

Wait, that's a ping to myself...

The short answer is I have no idea. I was just trying to clean it a little bit.

[darijgr]

comment:28

And I thought we were becoming unicode-compatible with py3 :)

[vbraun]

comment:29

sage -t --long --warn-long 64.0 src/sage/sandpiles/sandpile.py
**********************************************************************
File "src/sage/sandpiles/sandpile.py", line 387, in sage.sandpiles.sandpile.Sandpile.help
Failed example:
    Sandpile.help() # long time
Expected:
    For detailed help with any method FOO listed below,
    enter "Sandpile.FOO?" or enter "S.FOO?" for any Sandpile S.
    <BLANKLINE>
    all_k_config             -- The constant configuration with all values set to k.
    all_k_div                -- The divisor with all values set to k.
    avalanche_polynomial     -- The avalanche polynomial.
    betti                    -- The Betti table for the homogeneous toppling ideal.
    betti_complexes          -- The support-complexes with non-trivial homology.
    burning_config           -- The minimal burning configuration.
    burning_script           -- A script for the minimal burning configuration.
    canonical_divisor        -- The canonical divisor.
    dict                     -- A dictionary of dictionaries representing a directed graph.
    genus                    -- The genus: (# non-loop edges) - (# vertices) + 1.
    groebner                 -- A Groebner basis for the homogeneous toppling ideal.
    group_gens               -- A minimal list of generators for the sandpile group.
    group_order              -- The size of the sandpile group.
    h_vector                 -- The number of superstable configurations in each degree.
    help                     -- List of Sandpile-specific methods (not inherited from Graph).
    hilbert_function         -- The Hilbert function of the homogeneous toppling ideal.
    ideal                    -- The saturated homogeneous toppling ideal.
    identity                 -- The identity configuration.
    in_degree                -- The in-degree of a vertex or a list of all in-degrees.
    invariant_factors        -- The invariant factors of the sandpile group.
    is_undirected            -- Is the underlying graph undirected?
    jacobian_representatives -- Representatives for the elements of the Jacobian group.
    laplacian                -- The Laplacian matrix of the graph.
    markov_chain             -- The sandpile Markov chain for configurations or divisors.
    max_stable               -- The maximal stable configuration.
    max_stable_div           -- The maximal stable divisor.
    max_superstables         -- The maximal superstable configurations.
    min_recurrents           -- The minimal recurrent elements.
    nonsink_vertices         -- The nonsink vertices.
    nonspecial_divisors      -- The nonspecial divisors.
    out_degree               -- The out-degree of a vertex or a list of all out-degrees.
    picard_representatives   -- Representatives of the divisor classes of degree d in the Picard group.
    points                   -- Generators for the multiplicative group of zeros of the sandpile ideal.
    postulation              -- The postulation number of the toppling ideal.
    recurrents               -- The recurrent configurations.
    reduced_laplacian        -- The reduced Laplacian matrix of the graph.
    reorder_vertices         -- A copy of the sandpile with vertex names permuted.
    resolution               -- A minimal free resolution of the homogeneous toppling ideal.
    ring                     -- The ring containing the homogeneous toppling ideal.
    show                     -- Draw the underlying graph.
    show3d                   -- Draw the underlying graph.
    sink                     -- The sink vertex.
    smith_form               -- The Smith normal form for the Laplacian.
    solve                    -- Approximations of the complex affine zeros of the sandpile ideal.
    stable_configs           -- Generator for all stable configurations.
    stationary_density       -- The stationary density of the sandpile.
    superstables             -- The superstable configurations.
    symmetric_recurrents     -- The symmetric recurrent configurations.
    tutte_polynomial         -- The Tutte polynomial.
    unsaturated_ideal        -- The unsaturated, homogeneous toppling ideal.
    version                  -- The version number of Sage Sandpiles.
    zero_config              -- The all-zero configuration.
    zero_div                 -- The all-zero divisor.
Got:
    For detailed help with any method FOO listed below,
    enter "Sandpile.FOO?" or enter "S.FOO?" for any Sandpile S.
    <BLANKLINE>
    all_k_config             -- The constant configuration with all values set to k.
    all_k_div                -- The divisor with all values set to k.
    avalanche_polynomial     -- The avalanche polynomial.
    betti                    -- The Betti table for the homogeneous toppling ideal.
    betti_complexes          -- The support-complexes with non-trivial homology.
    burning_config           -- The minimal burning configuration.
    burning_script           -- A script for the minimal burning configuration.
    canonical_divisor        -- The canonical divisor.
    dict                     -- A dictionary of dictionaries representing a directed graph.
    genus                    -- The genus: (# non-loop edges) - (# vertices) + 1.
    groebner                 -- A Groebner basis for the homogeneous toppling ideal.
    group_gens               -- A minimal list of generators for the sandpile group.
    group_order              -- The size of the sandpile group.
    h_vector                 -- The number of superstable configurations in each degree.
    help                     -- List of Sandpile-specific methods (not inherited from Graph).
    hilbert_function         -- The Hilbert function of the homogeneous toppling ideal.
    ideal                    -- The saturated homogeneous toppling ideal.
    identity                 -- The identity configuration.
    in_degree                -- The in-degree of a vertex or a list of all in-degrees.
    invariant_factors        -- The invariant factors of the sandpile group.
    is_undirected            -- Is the underlying graph undirected?
    jacobian_representatives -- Representatives for the elements of the Jacobian group.
    laplacian                -- The Laplacian matrix of the graph.
    markov_chain             -- The sandpile Markov chain for configurations or divisors.
    max_stable               -- The maximal stable configuration.
    max_stable_div           -- The maximal stable divisor.
    max_superstables         -- The maximal superstable configurations.
    min_recurrents           -- The minimal recurrent elements.
    nonsink_vertices         -- The nonsink vertices.
    nonspecial_divisors      -- The nonspecial divisors.
    out_degree               -- The out-degree of a vertex or a list of all out-degrees.
    picard_representatives   -- Representatives of the divisor classes of degree d in the Picard group.
    points                   -- Generators for the multiplicative group of zeros of the sandpile ideal.
    postulation              -- The postulation number of the toppling ideal.
    recurrents               -- The recurrent configurations.
    reduced_laplacian        -- The reduced Laplacian matrix of the graph.
    reorder_vertices         -- A copy of the sandpile with vertex names permuted.
    resolution               -- A minimal free resolution of the homogeneous toppling ideal.
    ring                     -- The ring containing the homogeneous toppling ideal.
    show                     -- Draw the underlying graph.
    show3d                   -- Draw the underlying graph.
    sink                     -- The sink vertex.
    smith_form               -- The Smith normal form for the Laplacian.
    solve                    -- Approximations of the complex affine zeros of the sandpile ideal.
    stable_configs           -- Generator for all stable configurations.
    stationary_density       -- The stationary density of the sandpile.
    superstables             -- The superstable configurations.
    symmetric_recurrents     -- The symmetric recurrent configurations.
    tutte_polynomial         -- The Tutte polynomial of the underlying graph.
    unsaturated_ideal        -- The unsaturated, homogeneous toppling ideal.
    version                  -- The version number of Sage Sandpiles.
    zero_config              -- The all-zero configuration.
    zero_div                 -- The all-zero divisor.
**********************************************************************

[sagetrac-git]

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

f909546

update a doctest

[sagetrac-git]

Changed commit from cd9d8bd to f909546

[darijgr]

comment:31

Alright, let's see now.

[vbraun]

comment:32

Still fails

[sagetrac-git]

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

e7d9fb4

Fixing doctests by copying output and giving utf8 encoding to thematic tutorial.

[sagetrac-git]

Changed commit from f909546 to e7d9fb4

[tscrim]

comment:34

This should fix the doctests output because I explicitly copied the expected output. I also enabled utf8 encoding on the thematic tutorial and put back the unicode characters.

[vbraun]

comment:35

"Should fix" or "I tested that it fixes"?

[tscrim]

comment:36

"I tested that it fixes" on my machine. :)

[vbraun]

Changed branch from public/doc/fix_sandpile_tutorial-22264 to e7d9fb4