# Add documentation for FpGroup file and fix separate bug #11460

Merged
merged 27 commits into from Aug 22, 2016

None yet

### 2 participants

Member
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.
 gxyd Add the documentation for FpGroup file, separate bug 435083b
This was referenced Aug 1, 2016
Closed

Closed

#### [WIP] Improvements to fp_groups file #11403

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 Member 'coset table which is represented ...', or maybe just 'coset table as a list of lists'.
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 Member which puts a tuple
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 Member returns
 gxyd rename free_group.py -> free_groups.py 2ea4832
Member
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.
added some commits Aug 3, 2016
 gxyd Add user methods for FpGroup 8810aa4 gxyd Fix #11449, also modify the test-case of coset_enumeration_r/c 8a8cc97 gxyd documentation fixes 0d6140c
added the GSoC label Aug 8, 2016
added some commits Aug 11, 2016
 gxyd improve doctest of free_groups.py b25790d gxyd fix single, double back-quotes in perm_groups.py 69bbcc9 gxyd Add, improve docstrings for methods in fp_groups.py 2adbee6
Member
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.
Member
commented Aug 15, 2016
 There should be doc/src/modules/combinatorics/fp_groups.rst. It could also contain the references to free groups.
added some commits Aug 15, 2016
 gxyd Add docstring for coincidence and related methods 8d926c9 gxyd star Sphinx documentation for finitely presented groups 6ea8373 gxyd Add "words" documentation 7b55e2d
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 Member associated
 gxyd Add documentation for construction of finitely presented group a96d6c3
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 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 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 Member Also \mid is a version of | that automatically adds a little extra space on either side.
Member
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 
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 Member .generators[i] is code, hence double backquotes.
 gxyd Fix "make html" for fp_groups.py 434c52e
Member
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.
 gxyd Fix import errors in documentation 8177182
commented on the diff Aug 17, 2016
doc/src/modules/combinatorics/fp_groups.rst
 @@ -0,0 +1,185 @@ +Introduction
 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 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 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 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.
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 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 Member I think it could be left here for now. There is currently no combinatorics/literature.rst.
added some commits Aug 17, 2016
 gxyd Add example of group exceeding coset_table_max_limit db34cd4 gxyd Add documentation for strategies of enumeration c90ba5f
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 Member This could be omitted. It is strictly for internal use. omega contains the important information. gxyd Member I thought so. Okay will mention only the user-related attributes.
added some commits Aug 17, 2016
 gxyd Fix attributes of CosetTable 714c833 gxyd change formatting for headings 5e7a85e
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 Member Should this really be 'Ex'?
added some commits Aug 20, 2016
 gxyd Initialise documentation for presentation of subgroups 51772fc gxyd fix reidemeister schreier documentation d65629a gxyd Add example for low_index_subgroups d813e6b
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 =  +(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 =  +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 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 Member No, worries I got it fixed now (locally) :) .
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 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 Remove un-necessary headings 2c4c99f
Member
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.
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
 gxyd Add about "construction of words" 1fb9fc1
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 Member \ldots cannot be used in code. Write ..., instead.
doc/src/modules/combinatorics/fp_groups.rst
 + +>>> F = xfree_group("x, y") +>>> F +(, (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 +_ , 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 Member This \prod representation can only be used in commutative groups. In a reduced word the exponents cannot be combined in general. jksuom 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.
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 Member coloumn -> column
doc/src/modules/combinatorics/fp_groups.rst
 +For example to find all subgroups of G =  +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 Member Maybe 'subgroups of given index' instead of 'interested subgroups'.
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 Member * is not needed in the latex representation of a*b. ab will suffice.
 gxyd Fix LaTex issues in documentation 0e00c6e
Member
commented Aug 22, 2016
 I have addressed the comments. Also the \langle and \rangle issue with brackets as well.
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 + + +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 Member Upper case Obviously?
and 1 other commented on an outdated diff Aug 22, 2016
doc/src/modules/combinatorics/fp_groups.rst
 +>>> F = xfree_group("x, y") +>>> F +(, (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 +_ , 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 Member I'd prefer having 'for all k' after the latex string. gxyd 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 Member I think we should use plain text instead of the inverted A. gxyd 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 +(, (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 asFpGroup. +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 groupGdefined onngenerators +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}wheres_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.
added some commits Aug 22, 2016
 gxyd Make fixes in documentation 30871b7 gxyd use "for all" as plain text instead of LaTex in documentation 7feb425 gxyd Fix typo 2d35e16
Member
commented Aug 22, 2016
 I think this can be merged now.
merged commit 4b7a36e` into sympy:master Aug 22, 2016

#### 1 check passed

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