Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Added Documentation for Polycyclic Groups #17399

Merged
merged 7 commits into from Aug 18, 2019
Merged
Changes from 1 commit
Commits
File filter...
Filter file types
Jump to…
Jump to file or symbol
Failed to load files and symbols.

Always

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\}`.

This comment has been minimized.

Copy link
@jksuom

jksuom Aug 17, 2019

Member

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

This comment has been minimized.

Copy link
@divyanshu132

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.

This comment has been minimized.

Copy link
@jksuom

jksuom Aug 18, 2019

Member

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

This comment has been minimized.

Copy link
@divyanshu132

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 ---|

This comment has been minimized.

Copy link
@jksuom

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

Computation of Leading Exponent
```````````````````````````````

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
>>> collector.leading_exponent(G[1])
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.