# Added Documentation for Polycyclic Groups #17399

Merged
merged 7 commits into from Aug 18, 2019
+302 −7
Merged

# Added Documentation for Polycyclic Groups #17399

Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
Filter file types
Failed to load files and symbols.

#### Just for now

@@ -1,12 +1,295 @@
.. _combinatorics-pc_groups:

Polycyclic Groups
=================

.. module:: sympy.combinatorics.pc_groups
Introduction
------------

This module presents the functionality designed for computing with
polycyclic groups(PcGroup for short). The name of the corresponding
SymPy object is PolycyclicGroup. The functions or classes described
here are studied under **Computational Group Theory**.

Overview of functionalities


* The construction of PolycyclicGroup from a given PermutationGroup.

* Computation of polycyclic generating sequence(pcgs for short) and
polycyclic series(pc_series).

* Computation of relative order for polycyclic series.

* Implementation of class Collector which can be treated as a base for polycylic groups.

* Implementation of polycyclic group presentation(pc_presentation for short).

* Computation of exponent vector, depth and leading exponent for a given element
of a polycyclic group.

For a description of fundamental algorithms of polycyclic groups, we
often make use of *Handbook of Computational Group Theory*.

The Construction of Polycyclic Groups
-------------------------------------

Given a Permutation Group, A Polycyclic Group is constructed by computing the
corresponding polycylic generating sequence, polycyclic series and it's
relative order.

Attributes of PolycyclicGroup


* pc_sequence : Polycyclic sequence is formed by collecting all the missing
generators between the adjacent groups in the derived series of given
permutation group.

* pc_series : Polycyclic series is formed by adding all the missing generators
of der[i+1] in der[i], where der represents derived series.

* relative_order : A list, computed by the ratio of adjacent groups in pc_series.

* collector : By default, it is None. Collector class provides the polycyclic presentation.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> len(PcGroup.pcgs)
4
>>> pc_series = PcGroup.pc_series
>>> pc_series[0]==G
True
>>> gen = pc_series[len(pc_series)-1].generators[0]
>>> gen.is_identity
True
>>> PcGroup.relative_order
[2, 3, 2, 2]

The Construction of Collector
-----------------------------

Collector is one of the attributes of class PolycyclicGroup.

Attributes of Collector


Collector posses all the attributes of PolycyclicGroup, In addition there are
few more attributes which are defined below:

* free_group : free_group provides the mapping of polycyclic generating sequence with
the free group elements.

* pc_presentation : Provides the presentation of polycyclic groups with the
help of power and conjugate relators.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> G = SymmetricGroup(3)
>>> PcGroup = G.polycyclic_group()
>>> Collector = PcGroup.collector
>>> Collector.free_group
<free group on the generators (x0, x1)>
>>> Collector.pc_presentation
{x1**3: (), x0**2: (), x0**-1*x1*x0: x1**2}

Computation of Minimal Uncollected Subword


A word V defined on generators in the free_group of pc_group is a minimal
uncollected subword of the word W if V is a subword of W and it has one of
the following form:

* v = {x_{i+1}}^{a_j}x_i
* v = {x_{i+1}}^{a_j}{x_i}^{-1}
* v = {x_i}^{a_j}

a_j \notin \{0, \ldots relative\_order[j]-1\}.

#### jksuom Aug 17, 2019

Member

This could probably be \text{relative\_order}[j].

#### divyanshu132 Aug 18, 2019

Author Member

In \text{relative\_order} \ before underscore is not working, it is printed as it is in html. So, I tried without any delimiter before underscore but that seems failing. I think we should try \mathrm.

#### jksuom Aug 18, 2019

Member

\mathrm should be ok if it works better. The font will probably be the same.

#### divyanshu132 Aug 18, 2019

Author Member

Yes, font is same for both.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.free_groups import free_group
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> F, x1, x2 = free_group("x1, x2")
>>> word = x2**2*x1**7
>>> collector.minimal_uncollected_subword(word)
((x2, 2),)

Computation of Subword Index


For a given word and it's subword, subword_index computes the
starting and ending index of the subword in the word.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.free_groups import free_group
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> F, x1, x2 = free_group("x1, x2")
>>> word = x2**2*x1**7
>>> w = x2**2*x1
>>> collector.subword_index(word, w)
(0, 3)
>>> w = x1**7
>>> collector.subword_index(word, w)
(2, 9)

Computation of Collected Word


A word W is called collected, if W = {x_{i_1}}^{a_1} \ldots {x_{i_r}}^{a_r}
with i_1 < i_2< \ldots < i_r and a_j is in \{1 \ldots s_{j-1}\}, where s_j
represents the respective relative order.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.perm_groups import PermutationGroup
>>> from sympy.combinatorics.free_groups import free_group
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> F, x0, x1, x2, x3 = free_group("x0, x1, x2, x3")
>>> word = x3*x2*x1*x0
>>> collected_word = collector.collected_word(word)
>>> free_to_perm = {}
>>> free_group = collector.free_group
>>> for sym, gen in zip(free_group.symbols, collector.pcgs):
... free_to_perm[sym] = gen
>>> G1 = PermutationGroup()
>>> for w in word:
... sym = w[0]
... perm = free_to_perm[sym]
... G1 = PermutationGroup([perm] + G1.generators)
>>> G2 = PermutationGroup()
>>> for w in collected_word:
... sym = w[0]
... perm = free_to_perm[sym]
... G2 = PermutationGroup([perm] + G2.generators)
>>> G1 == G2
True

Computation of Polycyclic Presentation
--------------------------------------

The computation of presentation starts from the bottom of the pcgs and polycyclic series.
Storing all the previous generators from pcgs and then taking the last generator
as the generator which acts as a conjugator and conjugates all the previous
generators in the list.

To get a clear picture, start with an example of SymmetricGroup(4). For S(4) there are 4
generators in pcgs say [x0, x1, x2, x3] and the relative_order vector is [2, 3, 2, 2].
Starting from bottom of this sequence the presentation is computed in order as below.

>>> x3^2 ---|

#### jksuom Aug 13, 2019

Member

It looks like there are tabs. They should be removed. In addition, the comments should start with #.

>>> x2^2 |---> using only [x3] from pcgs and pc_series[1]
>>> x2^{-1}x3x2 ---|
>>> x1^3 ---|
>>> x1^{-1}x3x1 |---> using [x3, x2] from pcgs and pc_series[2]
>>> x1^{-1}x2x1 ---|
>>> x0^2 ---|
>>> x0^{-1}x3x0 |---> using [x3, x2, x1] from pcgs and pc_series[3]
>>> x0^{-1}x2x0 |
>>> x0^{-1}x1x0 ---|
One thing to note is same group can have different pcgs due to variying derived_series which,
results in different polycyclic presentations.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.permutations import Permutation
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> pcgs = PcGroup.pcgs
>>> len(pcgs)
4
>>> free_group = collector.free_group
>>> pc_resentation = collector.pc_presentation
>>> free_to_perm = {}
>>> for s, g in zip(free_group.symbols, pcgs):
... free_to_perm[s] = g
>>> for k, v in pc_resentation.items():
... k_array = k.array_form
... if v != ():
... v_array = v.array_form
... lhs = Permutation()
... for gen in k_array:
... s = gen[0]
... e = gen[1]
... lhs = lhs*free_to_perm[s]**e
... if v == ():
... assert lhs.is_identity
... continue
... rhs = Permutation()
... for gen in v_array:
... s = gen[0]
... e = gen[1]
... rhs = rhs*free_to_perm[s]**e
... assert lhs == rhs

Computation of Exponent Vector
------------------------------

Any generator of the polycyclic group can be represented with the help of it's
polycyclic generating sequence. Hence, the length of exponent vector is equal to
the length of the pcgs.

A given generator g of the polycyclic group, can be represented as
g = x_1^{e_1} \ldots x_n^{e_n}, where x_i represents polycyclic generators
and n is the number of generators in the free_group equal to the length of pcgs.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> from sympy.combinatorics.permutations import Permutation
>>> G = SymmetricGroup(4)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> pcgs = PcGroup.pcgs
>>> collector.exponent_vector(G[0])
[1, 0, 0, 0]
>>> exp = collector.exponent_vector(G[1])
>>> g = Permutation()
>>> for i in range(len(exp)):
... g = g*pcgs[i]**exp[i] if exp[i] else g
>>> assert g == G[1]

Depth of Polycyclic generator


Depth of a given polycyclic generator is defined as the index of the first
non-zero entry in the exponent vector.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> G = SymmetricGroup(3)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
>>> collector.depth(G[0])
2
>>> collector.depth(G[1])
1



Leading exponent represents the exponent of polycyclic generator at the above depth.

>>> from sympy.combinatorics.named_groups import SymmetricGroup
>>> G = SymmetricGroup(3)
>>> PcGroup = G.polycyclic_group()
>>> collector = PcGroup.collector
1

.. autoclass:: PolycyclicGroup
:members:
Bibliography
------------

.. autoclass:: Collector
:members:
.. [Ho05] Derek F. Holt,
Handbook of Computational Group Theory.
In the series 'Discrete Mathematics and its Applications',
Chapman & Hall/CRC 2005, xvi + 514 p <https://www.crcpress.com/Handbook-of-Computational-Group-Theory/Holt-Eick-OBrien/p/book/9781584883722>_.
ProTip! Use n and p to navigate between commits in a pull request.
You can’t perform that action at this time.