Add documentation for FpGroup file and fix separate bug #11460

Merged
merged 27 commits into from Aug 22, 2016

Projects

None yet

2 participants

@gxyd
Member
gxyd commented Aug 1, 2016

This PR is supposed to contain the content (with some changes) of #11411 and #11403 .
Since the documentation should comply with the changes that would go along with the new introduced methods in fp_groups.py file. So I intent to make those changes in a single to comply with each other.

@jksuom jksuom commented on an outdated diff Aug 2, 2016
sympy/combinatorics/fp_groups.py
@@ -125,6 +133,8 @@ def __init__(self, fp_grp, subgroup):
self.p = [0]
self.A = list(chain.from_iterable((gen, gen**-1) \
for gen in self.fp_group.generators))
+ # the mathematical coset table which represented using the list of
@jksuom
jksuom Aug 2, 2016 Member

'coset table which is represented ...', or maybe just 'coset table as a list of lists'.

@jksuom jksuom commented on an outdated diff Aug 2, 2016
sympy/combinatorics/fp_groups.py
# append to deduction stack
self.deduction_stack.append((alpha, x))
def scan_f(self, alpha, word):
+ """
+ A variation of ``scan`` routine which makes puts tuple, whenever a
@jksuom
jksuom Aug 2, 2016 Member

which puts a tuple

@jksuom jksuom commented on an outdated diff Aug 2, 2016
sympy/combinatorics/fp_groups.py
# otherwise scan is incomplete and yields no information
# used in the low-index subgroups algorithm
def scan_check(self, alpha, word):
- """
- Another version of "scan" routine, it checks whether ฮฑ scans correctly
- under w, it is a straightforward modification of "scan". "scan_check"
- return false (rather than calling "coincidence") if the scan completes
- incorrectly; otherwise it returns true.
+ r"""
+ Another version of ``scan`` routine, it checks whether `\alpha` scans
+ correctly under `word`, it is a straightforward modification of ``scan``.
+ ``scan_check`` return false (rather than calling ``coincidence``) if
@jksuom
jksuom Aug 2, 2016 Member

returns

@gxyd
Member
gxyd commented Aug 2, 2016

Just to be clear: When I say "mathematical coset table", I mean: an instance of list of lists. And "coset table" means an instance of coset table.

@gxyd gxyd added the GSoC label Aug 8, 2016
@gxyd
Member
gxyd commented Aug 12, 2016

Changes in the recent commits are better viewed using "git word diff" i.e git diff --word-diff command. Though a few of the methods still miss the docstrings.

@jksuom
Member
jksuom commented Aug 15, 2016

There should be doc/src/modules/combinatorics/fp_groups.rst. It could also contain the references to free groups.

@jksuom jksuom commented on an outdated diff Aug 16, 2016
doc/src/modules/combinatorics/fp_groups.rst
The Construction of Finitely Presented Groups
---------------------------------------------
Finitely presented groups are construced by factoring a free group by a
-set of relators.
+set of relators. The set of relators is taken in as a list of words in
+generators of free group in SymPy, using a list provides ordering to the
+relators. If the list of relators is empty, the assosciated free group is
@jksuom
jksuom Aug 16, 2016 Member

associated

@gxyd gxyd and 1 other commented on an outdated diff Aug 16, 2016
doc/src/modules/combinatorics/fp_groups.rst
+
+For a description of fundamental algorithms of finitely presented groups
+we often make use of *Handbook of Computational Group Theory*.
+
+The Construction of Finitely Presented Groups
+---------------------------------------------
+
+Finitely presented groups are construced by factoring a free group by a
+set of relators. The set of relators is taken in as a list of words in
+generators of free group in SymPy, using a list provides ordering to the
+relators. If the list of relators is empty, the associated free group is
+returned.
+
+Example of construction of a finitely-presented group.
+The symmetric group of degree 4 may be represented as a two generator group
+with presentation `< a, b | a^2, b^3, (a*b)^4 >`. Giving the relations as a
@gxyd
gxyd Aug 16, 2016 Member

Probably I will have to do the :math: thing to be able to do render it correctly (since github doesn't show it correctly in expected latex rendered when "view" button is clicked)?
Or will the building on docs do that correctly (i.e using make html) with the current formatting?

@jksuom
jksuom Aug 16, 2016 Member

It seems that :math: is not needed, single backquotes alone suffice. The angle brackets could probably be \langle and \rangle. The * in the product ab is not necessary here in the documentation since it is not intended to be machine readable.

@jksuom
jksuom Aug 16, 2016 Member

Also \mid is a version of | that automatically adds a little extra space on either side.

@jksuom
Member
jksuom commented Aug 16, 2016
checking consistency... /home/jks/test/sympy/doc/src/modules/combinatorics/fp_groups.rst:: WARNING: document isn't included in any toctree
@jksuom jksuom commented on an outdated diff Aug 16, 2016
doc/src/modules/combinatorics/fp_groups.rst
+
+>>> F, r, s = free_group("r, s")
+>>> G = FpGroup(F, [r**2, s**2, t**2, r*s*t*r**-1*t**-1*s**-1, s*t*r*s**-1*r**-1*t**-1])
+
+obviously this is not a unique way to make such a group, but the point is that
+in case of equality with non-identity the user has to manually do that.
+
+Free Groups and Words
+=====================
+
+Construction of a Free Group
+----------------------------
+
+``free_group("gen0, gen1, \ldots gen_(n-1)")`` constructs a free group ``F`` on ``n``
+generators, where ``n`` is a positive integer.
+The `i`-th generator of `F` may be obtained using the method `.generators[i]`, `i = 0, \ldots n-1`.
@jksuom
jksuom Aug 16, 2016 Member

.generators[i] is code, hence double backquotes.

@gxyd
Member
gxyd commented Aug 16, 2016

Seems like I had not added fp_groups.py to index.rst. I have fixed that.

On 08/16/2016 03:48 PM, Kalevi Suominen wrote:

|checking consistency...
/home/jks/test/sympy/doc/src/modules/combinatorics/fp_groups.rst::
WARNING: document isn't included in any toctree |

โ€”
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
#11460 (comment), or
mute the thread
https://github.com/notifications/unsubscribe-auth/AHWt8ZgdXL8hY9Q9xlD69J3QoZwFvOlCks5qgY6RgaJpZM4JZ7kc.

@jksuom jksuom commented on the diff Aug 17, 2016
doc/src/modules/combinatorics/fp_groups.rst
@@ -0,0 +1,185 @@
+Introduction
@jksuom
jksuom Aug 17, 2016 edited Member

This should probably be a next level header (underlined -----). The main header "FInitely Presented Groups" would come first (with ==== underline). The lowest level headers, currently with ----. can then have e.g. `````.

@gxyd
gxyd Aug 17, 2016 edited Member

I am afraid I don't understand it completely. Is it " ````` " (for lowest level headers) indeed five backquotes [forwardquotes] that you intend that I should use, or something else?

@gxyd
gxyd Aug 17, 2016 Member

I believe I could use something like this

=====================
Finitely Presented Groups (main)
=====================


Introduction (headings)
==========


Overview of functionalities (lover-level functionalities)
----------------------------------

Would that be fine?

@jksuom
jksuom Aug 17, 2016 Member

I only wanted to say that backquotes could indicate the third level. Their number should be the same as the length of the header.

@gxyd gxyd and 1 other commented on an outdated diff Aug 17, 2016
doc/src/modules/combinatorics/fp_groups.rst
+ does not have finite index, and even if it has it may take many more
+ intermediate cosets than the actual index of the subgroup is. To avoid a
+ coset enumeration "running away" therefore SymPy has a "safety stop"
+ built-in. This is controlled by this variable.
+
+* ``max_stack_size``: manipulate the maximum size of ``deduction_stack`` above
+ to equal to which the stack is emptied.
+
+Compression and Standardization
+-------------------------------
+
+
+Subgroups of Finite Index: Low Index Subgroups algorithm
+========================================================
+
+Bibliography
@gxyd
gxyd Aug 17, 2016 Member

Should this be a part of literature as is the case with the polys module. https://github.com/sympy/sympy/blob/master/doc/src/modules/polys/literature.rst ?

@jksuom
jksuom Aug 17, 2016 Member

I think it could be left here for now. There is currently no combinatorics/literature.rst.

@jksuom jksuom and 1 other commented on an outdated diff Aug 17, 2016
doc/src/modules/combinatorics/fp_groups.rst
+total it has ``2*G.rank()`` coloumns. Each coloumn is simply a list of integers.
+If ``l`` is the generator list for the generator `g` and if ``l[i] = j`` then
+generator ``g`` takes the coset `i` to the coset `j` by multiplication from the
+right.
+
+For finitely presented groups, a coset table is computed by a Todd-Coxeter
+coset enumeration. Note that you may influence the performance of that
+enumeration by changing the values of the variable
+``CosetTable.coset_table_max_limit``.
+
+Attributes of CosetTable
+------------------------
+
+For ``CosetTable(G, H)`` where ``G`` is the group and ``H`` is the subgroup.
+
+* ``p``:
@jksuom
jksuom Aug 17, 2016 Member

This could be omitted. It is strictly for internal use. omega contains the important information.

@gxyd
gxyd Aug 17, 2016 Member

I thought so. Okay will mention only the user-related attributes.

@jksuom jksuom commented on an outdated diff Aug 20, 2016
doc/src/modules/combinatorics/fp_groups.rst
+>>> G = FpGroup(F, [r**2, s**2, t**2, r*s*t*r**-1*t**-1*s**-1, s*t*r*s**-1*r**-1*t**-1])
+
+obviously this is not a unique way to make such a group, but the point is that
+in case of equality with non-identity the user has to manually do that.
+
+Free Groups and Words
+---------------------
+
+Construction of a Free Group
+````````````````````````````
+
+``free_group("gen0, gen1, \ldots gen_(n-1)")`` constructs a free group ``F`` on ``n``
+generators, where ``n`` is a positive integer.
+The `i`-th generator of `F` may be obtained using the method ``.generators[i]``, `i = 0, \ldots n-1`.
+
+Ex
@jksuom
jksuom Aug 20, 2016 Member

Should this really be 'Ex'?

@gxyd gxyd commented on the diff Aug 20, 2016
doc/src/modules/combinatorics/fp_groups.rst
+Low Index Subgroups
+```````````````````
+
+``low_index_subgroups(G, N)``: Given a finitely presented group `G = <X \mid R>`
+(can be a free group), and ``N`` a positive integer, determine the conjugacy classes of
+subgroups of ``G`` whose indices is less than or equal to ``N``.
+
+For example to find all subgroups of `G = <a, b \mid a^2 = b^3 = (ab)^4 = 1>`
+having index <= 4, can be found as follows:
+
+>>> from sympy.combinatorics.fp_groups import low_index_subgroups
+>>> F, a, b = free_group("a, b")
+>>> G = FpGroup(F, [a**2, b**3, (a*b)**4])
+>>> l = low_index_subgroups(G, 4)
+>>> for coset_table in l:
+... print(coset_table.table)
@gxyd
gxyd Aug 20, 2016 Member

I get an error currently

gaurav@stallman:~/Public/sympy$ python3 ./bin/doctest doc/src/modules/combinatorics/fp_groups.rst 
**********************************************************************
File "/home/gaurav/Public/sympy/doc/src/modules/combinatorics/fp_groups.rst", line 238, in fp_groups.rst
Failed example:
    for coset_table in l:
        print(coset_table.table)
Expected nothing
Got:
    [[0, 0, 0, 0]]
    [[0, 0, 1, 2], [1, 1, 2, 0], [3, 3, 0, 1], [2, 2, 3, 3]]
    [[0, 0, 1, 2], [2, 2, 2, 0], [1, 1, 0, 1]]
    [[1, 1, 0, 0], [0, 0, 1, 1]]
**********************************************************************
1 items had failures:
   1 of  24 in fp_groups.rst
***Test Failed*** 1 failures.
========================================================================== rst doctests start ===========================================================================
executable:         /usr/bin/python3  (3.4.3-final-0) [CPython]
architecture:       64-bit
cache:              yes
ground types:       python 
hash randomization: on (PYTHONHASHSEED=2510432324)

doc/src/modules/combinatorics/fp_groups.rst [24]                                                                                                                      [1]

DO *NOT* COMMIT!

Do you know what is the problem with this? I expected print statement to work fine.

@gxyd
gxyd Aug 20, 2016 Member

No, worries I got it fixed now (locally) :) .

@gxyd gxyd commented on an outdated diff Aug 20, 2016
doc/src/modules/combinatorics/fp_groups.rst
+creates a free group of rank 2 and assigns the variables ``x`` and ``y`` to the two
+generators.
+
+>>> F = vfree_group("x, y")
+
+creates a free group ``F[0]`` of rank 2, and a tuple of generators ``F[1]``.
+
+
+Construction of words
+`````````````````````
+
+Can be called with different public versions of ``FreeGroup`` i.e
+``free_group``, ``vfree_group`` and ``xfree_group``.
+
+Methods for manipulating Words
+``````````````````````````````
@gxyd
gxyd Aug 20, 2016 Member

I am unsure if it would be a good idea to explain each of the methods here. Since we already have the docstring (for each method in in sympy/combinatorics/free_groups.py) to address these methods in a more better way.

@gxyd
Member
gxyd commented Aug 20, 2016

Would it okay, to think about merging this much documentation. Since of two reasons, I could add this to the "Product Submission" and there are changes like renaming of file free_group.py -> free_groups.py and PR is already big enough.

@gxyd gxyd changed the title from [WIP] Add the documentation for FpGroup file, separate bug to Add documentation for FpGroup file and fix separate bug Aug 21, 2016
@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+Currently groups with relators having presentation like
+`< r, s, t \mid r^2, s^2, t^2, rst = str = trs >` will have to be specified as:
+
+>>> F, r, s, t = free_group("r, s, t")
+>>> G = FpGroup(F, [r**2, s**2, t**2, r*s*t*r**-1*t**-1*s**-1, s*t*r*s**-1*r**-1*t**-1])
+
+obviously this is not a unique way to make such a group, but the point is that
+in case of equality with non-identity the user has to manually do that.
+
+Free Groups and Words
+---------------------
+
+Construction of a Free Group
+````````````````````````````
+
+``free_group("gen0, gen1, \ldots gen_(n-1)")`` constructs a free group ``F`` on ``n``
@jksuom
jksuom Aug 22, 2016 Member

\ldots cannot be used in code. Write ..., instead.

@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+
+>>> F = xfree_group("x, y")
+>>> F
+(<free group on the generators (x, y)>, (x, y))
+
+creates a free groups ``F[0]`` of rank 2, with tuple of generators ``F[1]``.
+
+Construction of words
+`````````````````````
+
+This section is applicable to words of ``FreeGroup`` as well as ``FpGroup``.
+When we say *word* in SymPy, it actually means a `reduced word
+<https://en.wikipedia.org/wiki/Word_(group_theory)#Reduced_words>`_ , since the
+words are automatically reduced. Given a group ``G`` defined on `n` generators
+`x_1, x_2, x_3, \ldots, x_n`, a word is constructed as
+`\prod{x_i^{r_j}}` where `i \in [1, 2, \ldots, n]` and `j \in \mathbb{Z}`.
@jksuom
jksuom Aug 22, 2016 Member

This \prod representation can only be used in commutative groups. In a reduced word the exponents cannot be combined in general.

@jksuom
jksuom Aug 22, 2016 Member

There are two ways to denote the interval of integers from 1 to n, either \{1, 2, \ldots, n\} (set notation) or [1, n] (interval notation, implicitly restricted to integers). In SymPy, I think the set notation should be chosen to avoid confusion.

@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+ enumeration to be used, possible values are *"relator_based"* or
+ *"coset_table_based"*.
+
+CosetTable
+``````````
+
+Class used to manipulate the information regarding the coset enumeration of
+the finitely presented group ``G`` on the cosets of the subgroup ``H``.
+
+Basically a *coset table* ``CosetTable(G,H)``, is the permutation representation
+of the finitely presented group on the cosets of a subgroup. Most of the set
+theoretic and group functions use the regular representation of ``G``, i.e.,
+the coset table of ``G`` over the trivial subgroup.
+
+The actual mathematical coset table is obtained using ``.table`` attribute and
+is a list of lists. For each generator ``g`` of ``G`` it contains a coloumn and
@jksuom
jksuom Aug 22, 2016 Member

coloumn -> column

@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+For example to find all subgroups of `G = <a, b \mid a^2 = b^3 = (ab)^4 = 1>`
+having index <= 4, can be found as follows:
+
+>>> from sympy.combinatorics.fp_groups import low_index_subgroups
+>>> F, a, b = free_group("a, b")
+>>> G = FpGroup(F, [a**2, b**3, (a*b)**4])
+>>> l = low_index_subgroups(G, 4)
+>>> for coset_table in l:
+... print(coset_table.table)
+...
+[[0, 0, 0, 0]]
+[[0, 0, 1, 2], [1, 1, 2, 0], [3, 3, 0, 1], [2, 2, 3, 3]]
+[[0, 0, 1, 2], [2, 2, 2, 0], [1, 1, 0, 1]]
+[[1, 1, 0, 0], [0, 0, 1, 1]]
+
+This returns the coset tables of the interested subgroups.
@jksuom
jksuom Aug 22, 2016 Member

Maybe 'subgroups of given index' instead of 'interested subgroups'.

@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+
+For a description of fundamental algorithms of finitely presented groups
+we often make use of *Handbook of Computational Group Theory*.
+
+The Construction of Finitely Presented Groups
+---------------------------------------------
+
+Finitely presented groups are construced by factoring a free group by a
+set of relators. The set of relators is taken in as a list of words in
+generators of free group in SymPy, using a list provides ordering to the
+relators. If the list of relators is empty, the associated free group is
+returned.
+
+Example of construction of a finitely-presented group.
+The symmetric group of degree 4 may be represented as a two generator group
+with presentation `< a, b \mid a^2, b^3, (a*b)^4 >`. Giving the relations as a
@jksuom
jksuom Aug 22, 2016 Member

* is not needed in the latex representation of a*b. ab will suffice.

@gxyd
Member
gxyd commented Aug 22, 2016

I have addressed the comments. Also the \langle and \rangle issue with brackets as well.

@jksuom jksuom commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+The symmetric group of degree 4 may be represented as a two generator group
+with presentation `\langle a, b \mid a^2, b^3, (ab)^4 \rangle`. Giving the relations as a
+list of relators, the presentation of would be specified as:
+
+>>> F, a, b = free_group("a, b")
+>>> G = FpGroup(F, [a**2, b**3, (a*b)**4])
+>>> G
+<fp group on the generators (a, b)>
+
+Currently groups with relators having presentation like
+`\langle r, s, t \mid r^2, s^2, t^2, rst = str = trs \rangle` will have to be specified as:
+
+>>> F, r, s, t = free_group("r, s, t")
+>>> G = FpGroup(F, [r**2, s**2, t**2, r*s*t*r**-1*t**-1*s**-1, s*t*r*s**-1*r**-1*t**-1])
+
+obviously this is not a unique way to make such a group, but the point is that
@jksuom
jksuom Aug 22, 2016 Member

Upper case Obviously?

@jksuom jksuom and 1 other commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
+>>> F = xfree_group("x, y")
+>>> F
+(<free group on the generators (x, y)>, (x, y))
+
+creates a free groups ``F[0]`` of rank 2, with tuple of generators ``F[1]``.
+
+Construction of words
+`````````````````````
+
+This section is applicable to words of ``FreeGroup`` as well as ``FpGroup``.
+When we say *word* in SymPy, it actually means a `reduced word
+<https://en.wikipedia.org/wiki/Word_(group_theory)#Reduced_words>`_ , since the
+words are automatically reduced. Given a group ``G`` defined on `n` generators
+`x_1, x_2, x_3, \ldots, x_n`, a word is constructed as
+`s_1^{r_1}s_2^{r_2} \cdots s_k^{r_k}` where `s_i \in \{x_1, x_2, \ldots, x_n\}`
+, `r_i \in \mathbb{Z} \forall k`.
@jksuom
jksuom Aug 22, 2016 Member

I'd prefer having 'for all k' after the latex string.

@gxyd
gxyd Aug 22, 2016 Member

You want this because \forall k produces the two symbols very close to each other? I have always wanted this to have a little more space in-between them.

@jksuom
jksuom Aug 22, 2016 Member

I think we should use plain text instead of the inverted A.

@gxyd
gxyd Aug 22, 2016 Member

I've fixed that now.

On 08/22/2016 03:41 PM, Kalevi Suominen wrote:

In doc/src/modules/combinatorics/fp_groups.rst
#11460 (comment):

+>>> F = xfree_group("x, y")
+>>> F
+(<free group on the generators (x, y)>, (x, y))
+
+creates a free groups F[0] of rank 2, with tuple of generators F[1].
+
+Construction of words
+````````````````````
+
+This section is applicable to words ofFreeGroupas well as`FpGroup`.
+When we say word in SymPy, it actually means a `reduced word
+https://en.wikipedia.org/wiki/Word_(group_theory)#Reduced_words`_ , since the
+words are automatically reduced. Given a group`G``defined on`n`generators
+`x_1, x_2, x_3, \ldots, x_n`, a word is constructed as
+`s_1^{r_1}s_2^{r_2} \cdots s_k^{r_k}`where`s_i \in {x_1, x_2, \ldots, x_n}`
+,`r_i \in \mathbb{Z} \forall k`.

I think we should use plain text instead of the inverted A.

โ€”
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub
https://github.com/sympy/sympy/pull/11460/files/0e00c6e414a5cca04f15c2ad7cdf7cb1e725f27c#r75651603,
or mute the thread
https://github.com/notifications/unsubscribe-auth/AHWt8cfyBd29N3y7uLB9rW1hkQ9rvesVks5qiXW4gaJpZM4JZ7kc.

@jksuom
Member
jksuom commented Aug 22, 2016

I think this can be merged now.

@jksuom jksuom merged commit 4b7a36e into sympy:master Aug 22, 2016

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@gxyd gxyd deleted the gxyd:documentation_fp_groups branch Aug 24, 2016
@skirpichev skirpichev referenced this pull request in diofant/diofant Dec 7, 2016
Open

[wip] Backport some sympy fixes #390

81 of 99 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment