# Ticket #5542: trac_5542-docstring-fixes.patch

File trac_5542-docstring-fixes.patch, 37.9 KB (added by mvngu, 4 years ago)
• ## sage/groups/perm_gps/permgroup.py

# HG changeset patch
# User Minh Van Nguyen <nguyenminh2@gmail.com>
# Date 1237275995 25200
# Node ID 664f5d732bc8c38fa5df8c48c054201eee39eaba
diff -r 5f82fbe330b3 -r 664f5d732bc8 sage/groups/perm_gps/permgroup.py
 a r""" Permutation groups A permutation group is a finite group G whose elements are permutations of a given finite set X (i.e., bijections X -> X) and whose group operation is the composition of permutations. The number of elements of X is called the degree of G. A permutation group is a finite group G whose elements are permutations of a given finite set X (i.e., bijections X \longrightarrow X) and whose group operation is the composition of permutations. The number of elements of X is called the degree of G. In Sage a permutation is represented as either a string that In Sage, a permutation is represented as either a string that defines a permutation using disjoint cycle notation, or a list of tuples, which represent disjoint cycles. :: tuples, which represent disjoint cycles. That is:: (a,...,b)(c,...,d)...(e,...,f)  <--> [(a,...,b), (c,...,d),..., (e,...,f)] () = identity <--> [] constructions: - permutation group generated by elements, - direct_product_permgroups, which takes a list of permutation - direct_product_permgroups, which takes a list of permutation groups and returns their direct product. JOKE: Q: What's hot, chunky, and acts on a polygon? A: Dihedral def load_hap(): """ Load the GAP hap package into the default GAP interpreter interface, and if this fails, try one more time to load it. interface. If this fails, try one more time to load it. EXAMPLES: EXAMPLES:: sage: sage.groups.perm_gps.permgroup.load_hap() """ try: def direct_product_permgroups(P): """ Takes the direct product of the permutation groups listed in P. Takes the direct product of the permutation groups listed in P. EXAMPLES:: def from_gap_list(G, src): r""" Convert a string giving a list of GAP permutations into a list of elements of G. Convert a string giving a list of GAP permutations into a list of elements of G. EXAMPLES:: INPUT: -  gens - list of generators -  gens - list of generators (default: None) -  gap_group - a gap permutation group -  gap_group - a gap permutation group (default: None) -  canonicalize - bool (default: True), if True -  canonicalize - bool (default: True); if True, sort generators and remove duplicates OUTPUT: a permutation group OUTPUT: - A permutation group. EXAMPLES:: [(1,2,3,4), (1,3)] We can also create permutation groups whose generators are Gap permutation objects. :: permutation objects:: sage: p = gap('(1,2)(3,7)(4,6)(5,8)'); p (1,2)(3,7)(4,6)(5,8) sage: PermutationGroup([p]) Permutation Group with generators [(1,2)(3,7)(4,6)(5,8)] EXAMPLES: There is an underlying gap object that implements each permutation group. :: There is an underlying gap object that implements each permutation group:: sage: G = PermutationGroup([[(1,2,3,4)]]) sage: G._gap_() INPUT: -  gens - list of generators -  gens - list of generators (default: None) -  gap_group - a gap permutation group -  gap_group - a gap permutation group (default: None) -  canonicalize - bool (default: True), if True -  canonicalize - bool (default: True); if True, sort generators and remove duplicates OUTPUT: a permutation group OUTPUT: - A permutation group. EXAMPLES: We explicitly construct the alternating group on four elements. :: EXAMPLES: We explicitly construct the alternating group on four elements:: sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 Permutation Group with generators [(2,3,4), (1,2,3)] def _gap_init_(self): r""" Returns a string showing how to declare / initialize self in Gap. Returns a string showing how to declare / initialize self in Gap. Stored in the self._gap_string attribute. EXAMPLES: The _gap_init_ method shows how you EXAMPLES: The _gap_init_ method shows how you would define the Sage PermutationGroup_generic object in Gap:: def _magma_init_(self, magma): r""" Returns a string showing how to declare / intialize self in Magma. Returns a string showing how to declare / initialize self in Magma. EXAMPLES: We explicitly construct the alternating group on four EXAMPLES: We explicitly construct the alternating group on four elements. In Magma, one would type the string below to construct the group. :: the group:: sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 Permutation Group with generators [(2,3,4), (1,2,3)] def __cmp__(self, right): """ Compare self and right. Compare self and right. The ordering is whatever it is in Gap. def __call__(self, x, check=True): """ Coerce x into this permutation group. Coerce x into this permutation group. The input can be either a string that defines a permutation in cycle notation, a permutation group element, a list of integers that gives the permutation as a mapping, a list of tuples, or the integer 1. EXAMPLES: We illustrate each way to make a permutation in S4:: EXAMPLES: We illustrate each way to make a permutation in S_4:: sage: G = SymmetricGroup(4) sage: G((1,2,3,4)) def _coerce_impl(self, x): r""" Implicit coercion of x into self. Implicit coercion of x into self. EXAMPLES: We illustrate some arithmetic that involves implicit coercion of elements in different permutation groups. :: EXAMPLES: We illustrate some arithmetic that involves implicit coercion of elements in different permutation groups:: sage: g1 = PermutationGroupElement([(1,2),(3,4,5)]) sage: g1.parent() def __contains__(self, item): """ Returns boolean value of "item in self" Returns boolean value of item in self. EXAMPLES:: def has_element(self, item): """ Returns boolean value of "item in self" - however *ignores* Returns boolean value of item in self - however *ignores* parentage. EXAMPLES:: sage: G.gens() [(1,2), (1,2,3)] Note that the generators need not be minimal though duplicates are removed. :: Note that the generators need not be minimal, though duplicates are removed:: sage: G = PermutationGroup([[(1,2)], [(1,3)], [(2,3)], [(1,2)]]) sage: G.gens() [(2,3), (1,2), (1,3)] :: We can use index notation to access the generators returned by self.gens:: sage: G = PermutationGroup([[(1,2,3,4), (5,6)], [(1,2)]]) sage: g = G.gens() sage: g[1] (1,2,3,4)(5,6) TESTS: We make sure that the trivial group gets handled correctly. :: TESTS: We make sure that the trivial group gets handled correctly:: sage: SymmetricGroup(1).gens() [()] def gens_small(self): """ Returns a generating set of G which has few elements. As neither irredundancy, nor minimal length is proven, it is fast. Returns a generating set of a group G, which has few elements. As neither irredundancy nor minimal length is proven, it is fast. EXAMPLES:: def gen(self, i): r""" Returns the ith generator of self; that is, the ith element of the list self.gens(). Returns the i-th generator of self; that is, the i-th element of the list self.gens(). EXAMPLES: We explicitly construct the alternating group on four EXAMPLES: We explicitly construct the alternating group on four elements:: sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 def cayley_table(self, names="x"): """ Returns the multiplication table, or Cayley table, of the finite group G in the form of a matrix with symbolic coefficients. This group G in the form of a matrix with symbolic coefficients. This function is useful for learning, teaching, and exploring elementary group theory. Of course, G must be a group of low order. group theory. Of course, G must be a group of low order. EXAMPLES: As the last line below illustrates, the ordering used here in the first row is the same as in G.list(). EXAMPLES:: first row is the same as in G.list():: sage: G = PermutationGroup(['(1,2,3)', '(2,3)']) sage: G.cayley_table() def exponent(self): """ Computes the exponent of the group. The exponent e of a group G is the lcm of the orders of its elements, that group G is the LCM of the orders of its elements, that is, e is the smallest integer such that g^e=1 for all g \in G. def _repr_(self): r""" Returns a string describing self. Returns a string describing self. EXAMPLES: We explicitly construct the alternating group on four EXAMPLES: We explicitly construct the alternating group on four elements. Note that the AlternatingGroup class has its own representation string. :: its own representation string:: sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 Permutation Group with generators [(2,3,4), (1,2,3)] def _latex_(self): r""" Method for describing self in LaTeX. Encapsulates self.gens() in angle brackets to denote that self in generated by these elements. Called by the Method for describing self in LaTeX. Encapsulates self.gens() in angle brackets to denote that self is generated by these elements. Called by the latex() function. EXAMPLES: We explicitly construct the alternating group on four elements. :: EXAMPLES: We explicitly construct the alternating group on four elements:: sage: A4 = PermutationGroup([[(1,2,3)],[(2,3,4)]]); A4 Permutation Group with generators [(2,3,4), (1,2,3)] def id(self): """ (Same as self.group_id().) Return the ID code of this group, which (Same as self.group_id().) Return the ID code of this group, which is a list of two integers. Requires "optional" database_gap-4.4.x package. def center(self): """ Return the subgroup of elements of that commute with every element Return the subgroup of elements that commute with every element of this group. EXAMPLES:: def direct_product(self,other,maps=True): """ Wraps GAP's DirectProduct, Embedding, and Projection. Wraps GAP's DirectProduct, Embedding, and Projection. Sage calls GAP's DirectProduct, which chooses an efficient Sage calls GAP's DirectProduct, which chooses an efficient representation for the direct product. The direct product of permutation groups will be a permutation group again. For a direct product D, the GAP operation Embedding(D,i) returns the homomorphism embedding the i-th factor into D. The GAP operation Projection(D,i) gives the projection of D onto the i-th factor. product D, the GAP operation Embedding(D,i) returns the homomorphism embedding the i-th factor into D. The GAP operation Projection(D,i) gives the projection of D onto the i-th factor. This method returns a 5-tuple: a permutation group and 4 morphisms. INPUT: -  self, other - permutation groups This method returns a 5-tuple - a permutation groups and 4 morphisms. OUTPUT: -  D - a direct product of the inputs, returned as a permutation group as well -  iota1 - an embedding of self into D -  iota1 - an embedding of self into D -  iota2 - an embedding of other into D -  iota2 - an embedding of other into D -  pr1 - the projection of D onto self (giving a -  pr1 - the projection of D onto self (giving a splitting 1 - other - D - self - 1) -  pr2 - the projection of D onto other (giving a -  pr2 - the projection of D onto other (giving a splitting 1 - self - D - other - 1) def subgroup(self, gens): """ Wraps the PermutationGroup_subgroup constructor. The argument gens is a list of elements of self. Wraps the PermutationGroup_subgroup constructor. The argument gens is a list of elements of self. EXAMPLES:: def cohomology(self, n, p = 0): r""" Computes the group cohomology H_n(G, F), where F = Z if p=0 and F = Z/pZ if p 0 is a prime. Wraps HAP's GroupHomology function, written by Graham Ellis. Computes the group cohomology H^n(G, F), where F = \mathbb{Z} if p=0 and F = \mathbb{Z} / p \mathbb{Z} if p > 0 is a prime. Wraps HAP's GroupHomology function, written by Graham Ellis. REQUIRES: GAP package HAP (in gap_packages-\*.spkg). ... ValueError: p must be 0 or prime This computes H^4(S_3,ZZ), H^4(S_3,ZZ/2ZZ), resp. This computes H^4(S_3, \mathbb{Z}) and H^4(S_3, \mathbb{Z} / 2 \mathbb{Z}), respectively. AUTHORS: def cohomology_part(self, n, p = 0): """ Computes the p-part of the group cohomology H^n(G, F), where F = Z if p=0 and F = Z/pZ if p >0 is a prime. Wraps HAP's Homology function, written where F = \mathbb{Z} if p=0 and F = \mathbb{Z} / p \mathbb{Z} if p > 0 is a prime. Wraps HAP's Homology function, written by Graham Ellis, applied to the p-Sylow subgroup of G. def homology(self, n, p = 0): r""" Computes the group homology H_n(G, F), where F = Z if p=0 and F = Z/pZ if p >0 is a prime. Wraps HAP's GroupHomology function, F = \mathbb{Z} if p=0 and F = \mathbb{Z} / p \mathbb{Z} if p > 0 is a prime. Wraps HAP's GroupHomology function, written by Graham Ellis. REQUIRES: GAP package HAP (in gap_packages-\*.spkg). - David Joyner and Graham Ellis The example below computes H_7(S_5,ZZ), H_7(S_5,ZZ/2ZZ), H_7(S_5,ZZ/3ZZ), and H_7(S_5,ZZ/5ZZ), resp. To compute the 2-part of H_7(S_5,ZZ), use the homology_part The example below computes H_7(S_5, \mathbb{Z}), H_7(S_5, \mathbb{Z} / 2 \mathbb{Z}), H_7(S_5, \mathbb{Z} / 3 \mathbb{Z}), and H_7(S_5, \mathbb{Z} / 5 \mathbb{Z}), respectively. To compute the 2-part of H_7(S_5, \mathbb{Z}), use the homology_part function. EXAMPLES:: def homology_part(self, n, p = 0): r""" Computes the p-part of the group homology H_n(G, F), where F = Z if p=0 and F = Z/pZ if p >0 is a prime. Wraps HAP's Homology function, written by Graham Ellis, applied to the H_n(G, F), where F = \mathbb{Z} if p=0 and F = \mathbb{Z} / p \mathbb{Z} if p > 0 is a prime. Wraps HAP's Homology function, written by Graham Ellis, applied to the p-Sylow subgroup of G. REQUIRES: GAP package HAP (in gap_packages-\*.spkg). r""" Returns the matrix of values of the irreducible characters of a permutation group G at the conjugacy classes of G. The columns represent the the conjugacy classes of G. The columns represent the conjugacy classes of G and the rows represent the different irreducible characters in the ordering given by GAP. [(1, 1, 1, 1, 1, 1, 1), (5, 1, 2, -1, -1, 0, 0), (5, 1, -1, 2, -1, 0, 0), (8, 0, -1, -1, 0, zeta5^3 + zeta5^2 + 1, -zeta5^3 - zeta5^2), (8, 0, -1, -1, 0, -zeta5^3 - zeta5^2, zeta5^3 + zeta5^2 + 1), (9, 1, 0, 0, 1, -1, -1), (10, -2, 1, 1, 0, 0, 0)] Suppose that you have a class function f(g) on G and you know the values v_1, ..., v_n on G and you know the values v_1, \dots, v_n on the conjugacy class elements in conjugacy_classes_representatives(G) = [g_1, \ldots, g_n]. Since the irreducible characters a linear combination of these basis elements, f = c_1\rho_1 + \cdots + c_n\rho_n. To find the coefficients c_i, you simply solve the linear system character_table_values(G)\*[v_1, ..., v_n] = [c_1, ..., c_n], where [v_1, ...,v_n] = character_table_values(G) ^{-1}[c_1, ...,c_n]. character_table_values(G)\* [v_1, ..., v_n] = [c_1, ..., c_n], where [v_1, ..., v_n] = character_table_values(G) ^(-1)[c_1, ..., c_n]. AUTHORS: .. note:: The ordering of the columns of the character table of a group corresponds to the ordering of the list. However, in general there is no way to canonically list (or index) the conjugacy classes of a group. Therefore the ordering of  the columns of the character table of a group is somewhat random. corresponds to the ordering of the list. However, in general there is no way to canonically list (or index) the conjugacy classes of a group. Therefore the ordering of the columns of the character table of a group is somewhat random. """ current_randstate().set_seed_gap() G    = self._gap_() def irreducible_characters(self): r""" Returns a list of the irreducible characters of self. Returns a list of the irreducible characters of self. EXAMPLES:: def trivial_character(self): r""" Returns the trivial character of self. Returns the trivial character of self. EXAMPLES:: def character(self, values): r""" Returns a group character of from values, where values is a list of the values of the character evaluated on the conjugacy classes. Returns a group character of from values, where values is a list of the values of the character evaluated on the conjugacy classes. EXAMPLES:: def conjugacy_classes_representatives(self): """ Returns a complete list of representatives of conjugacy classes in a permutation group G. The ordering is that given by GAP. a permutation group G. The ordering is that given by GAP. EXAMPLES:: def conjugacy_classes_subgroups(self): """ Returns a complete list of representatives of conjugacy classes of subgroups in a permutation group G. The ordering is that given by subgroups in a permutation group G. The ordering is that given by GAP. EXAMPLES:: def normalizer(self, g): """ Returns the normalizer of g in self. Returns the normalizer of g in self. EXAMPLES:: def centralizer(self, g): """ Returns the centralizer of g in self. Returns the centralizer of g in self. EXAMPLES:: def isomorphism_type_info_simple_group(self): """ Is the group is simple, then this returns the name of the group. If the group is simple, then this returns the name of the group. EXAMPLES:: def is_abelian(self): """ Return True if this group is abelian. Return True if this group is abelian. EXAMPLES:: def is_commutative(self): """ Return True if this group is commutative. Return True if this group is commutative. EXAMPLES:: def is_cyclic(self): """ Return True if this group is cyclic. Return True if this group is cyclic. EXAMPLES:: def is_elementary_abelian(self): """ Return True if this group is elementary abelian. An elementary abelian group is a finite Abelian group, where every nontrivial element has order p, where p is a prime. Return True if this group is elementary abelian. An elementary abelian group is a finite abelian group, where every nontrivial element has order p, where p is a prime. EXAMPLES:: def isomorphism_to(self,right): """ Return an isomorphism self to right if the groups are isomorphic, otherwise None. Return an isomorphism from self to right if the groups are isomorphic, otherwise None. INPUT: -  right - a permutation group OUTPUT: None or a morphism of permutation groups. OUTPUT: - None or a morphism of permutation groups. EXAMPLES:: def is_isomorphic(self, right): """ Return True if the groups are isomorphic. If mode="verbose" then an Return True if the groups are isomorphic. If mode="verbose" then an isomorphism is printed. INPUT: -  right - a permutation group OUTPUT: bool OUTPUT: - boolean; True if self and right are isomorphic groups; False otherwise. EXAMPLES:: def is_monomial(self): """ Returns True if the group is monomial. A finite group is monomial Returns True if the group is monomial. A finite group is monomial if every irreducible complex character is induced from a linear character of a subgroup. def is_nilpotent(self): """ Return True if this group is nilpotent. Return True if this group is nilpotent. EXAMPLES:: def is_normal(self, other): """ Return True if this group is a normal subgroup of other. Return True if this group is a normal subgroup of other. EXAMPLES:: def is_perfect(self): """ Return True if this group is perfect. A group is perfect if it Return True if this group is perfect. A group is perfect if it equals its derived subgroup. EXAMPLES:: def is_pgroup(self): """ Returns True if the group is a p-group. A finite group is a p-group if its order is of the form p^n for a prime integer p and a nonnegative integer n. Returns True if this group is a p-group. A finite group is a p-group if its order is of the form p^n for a prime integer p and a nonnegative integer n. EXAMPLES:: def is_polycyclic(self): r""" Return True if this group is polycyclic. A group is polycyclic if it has a subnormal series with cyclic factors. (For finite groups Return True if this group is polycyclic. A group is polycyclic if it has a subnormal series with cyclic factors. (For finite groups, this is the same as if the group is solvable - see is_solvable)].) is_solvable.) EXAMPLES:: def is_simple(self): """ Returns True if the group is simple. A group is simple if it has no Returns True if the group is simple. A group is simple if it has no proper normal subgroups. EXAMPLES:: def is_solvable(self): """ Returns True if the group is solvable. Returns True if the group is solvable. EXAMPLES:: def is_subgroup(self,other): """ Returns true if self is a subgroup of other. Returns True if self is a subgroup of other. EXAMPLES:: def is_supersolvable(self): """ Returns True if the group is supersolvable. A finite group is Returns True if the group is supersolvable. A finite group is supersolvable if it has a normal series with cyclic factors. EXAMPLES:: def is_transitive(self): """ Return True if self is a transitive group, i.e., if the action Return True if self is a transitive group, i.e., if the action of self on [1..n] is transitive. EXAMPLES:: False Note that this differs from the definition in GAP, where IsTransitive returns whether the group is transitive on the IsTransitive returns whether the group is transitive on the set of points moved by the group. :: def normalizes(self,other): r""" Returns True if the group other is normalized by the self. Wraps GAP's IsNormal function. Returns True if the group other is normalized by self. Wraps GAP's IsNormal function. A group G normalizes a group U if and only if for every A group G normalizes a group U if and only if for every g \in G and u \in U the element u^g is a member of U. Note that U need not be a subgroup of G. is a member of U. Note that U need not be a subgroup of G. EXAMPLES:: sage: H.normalizes(G) True In the last example, G and H are disjoint, so each normalizes the In the last example, G and H are disjoint, so each normalizes the other. """ return self._gap_().IsNormal(other._gap_()).bool() Return the composition series of this group as a list of permutation groups. EXAMPLES: These computations use pseudo-random numbers, so we set EXAMPLES: These computations use pseudo-random numbers, so we set the seed for reproducible testing. :: Return the derived series of this group as a list of permutation groups. EXAMPLES: These computations use pseudo-random numbers, so we set EXAMPLES: These computations use pseudo-random numbers, so we set the seed for reproducible testing. :: Return the lower central series of this group as a list of permutation groups. EXAMPLES: These computations use pseudo-random numbers, so we set EXAMPLES: These computations use pseudo-random numbers, so we set the seed for reproducible testing. :: def molien_series(self): r""" Returns the Molien series of a transtive permutation group. The Returns the Molien series of a transitive permutation group. The function .. math:: M(x) = (1/|G|)\sum_{g\in G} det(1-x*g)^(-1) M(x) = (1/|G|)\sum_{g\in G} \det(1-x*g)^{-1} is sometimes called the "Molien series" of G. GAP's is sometimes called the "Molien series" of G. GAP's MolienSeries is associated to a character of a group G. How are these related? A group G, given as a permutation group on n points, has a "natural" representation of dimension n, given by permutation matrices. The Molien series of G is the one associated to that permutation representation of G using the above group G. How are these related? A group G, given as a permutation group on n points, has a "natural" representation of dimension n, given by permutation matrices. The Molien series of G is the one associated to that permutation representation of G using the above formula. Character values then count fixed points of the corresponding permutations. Return the normal subgroups of this group as a (sorted in increasing order) list of permutation groups. The normal subgroups of H = PSL(2,7)xPSL(2,7) are The normal subgroups of H = PSL(2,7) \cdot PSL(2,7) are 1, two copies of PSL(2,7) and H itself, as the following example shows. EXAMPLES:: itself, as the following example shows. EXAMPLES:: sage: G = PSL(2,7) sage: D = G.direct_product(G) def poincare_series(self, p=2, n=10): """ Returns the Poincare series of G mod p (p must be a prime), for n1 large. In other words, if you input a finite group G, a prime p, and a positive integer n, it returns a quotient of polynomials f(x)=P(x)/Q(x) whose coefficient of x^k equals the rank of the vector space H_k(G,ZZ/pZZ), for all k in the range 1\leq k \leq n. Returns the Poincare series of G \mod p (p \geq 2 must be a prime), for n large. In other words, if you input a finite group G, a prime p, and a positive integer n, it returns a quotient of polynomials f(x) = P(x) / Q(x) whose coefficient of x^k equals the rank of the vector space H_k(G, \mathbb{Z} / p \mathbb{Z}), for all k in the range 1 \leq k \leq n. REQUIRES: GAP package HAP (in gap_packages-\*.spkg). def sylow_subgroup(self, p): """ Returns a Sylow p-subgroups of the finite group G, where p is a prime. This is a p-subgroup of G whose index in G is coprime to p. Wraps the GAP function SylowSubgroup. Returns a Sylow p-subgroup of the finite group G, where p is a prime. This is a p-subgroup of G whose index in G is coprime to p. Wraps the GAP function SylowSubgroup. EXAMPLES:: Return the upper central series of this group as a list of permutation groups. EXAMPLES: These computations use pseudo-random numbers, so we set EXAMPLES: These computations use pseudo-random numbers, so we set the seed for reproducible testing. :: class PermutationGroup_subgroup(PermutationGroup_generic): """ Subgroup subclass of PermutationGroup_generic, so instance methods Subgroup subclass of PermutationGroup_generic, so instance methods are inherited. EXAMPLES:: Initialization method for the PermutationGroup_subgroup class. INPUTS: ambient - the ambient group from which to construct this subgroup gens - the generators of the subgroup from_group - True: subroup is generated from a Gap string representation of the generators check- True: checks if gens are indeed elements of the ambient group canonicalize - bool (default: True), if True sort generators and remove duplicates INPUTS: - ambient - the ambient group from which to construct this subgroup - gens - the generators of the subgroup - from_group - True: subgroup is generated from a Gap string representation of the generators (default: False) - check - True: checks if gens are indeed elements of the ambient group - canonicalize - boolean (default: True); if True, sort generators and remove duplicates EXAMPLES: An example involving the dihedral group on four elements. EXAMPLES: An example involving the dihedral group on four elements. D_8 contains a cyclic subgroup or order four:: sage: G = DihedralGroup(4) def __cmp__(self, other): r""" Compare self and other. If self and other are in a common ambient group, then self = other precisely if self is contained in other. Compare self and other. If self and other are in a common ambient group, then self = other precisely if self is contained in other. EXAMPLES:: Returns a string representation / description of the permutation subgroup. EXAMPLES: An example involving the dihedral group on four elements, EXAMPLES: An example involving the dihedral group on four elements, D_8:: sage: G = DihedralGroup(4) def _latex_(self): r""" Return latex representation of this group. Return LaTeX representation of this group. EXAMPLES: An example involving the dihedral group on four elements, EXAMPLES: An example involving the dihedral group on four elements, D_8:: sage: G = DihedralGroup(4) def ambient_group(self): """ Return the ambient group related to self. Return the ambient group related to self. EXAMPLES: An example involving the dihedral group on four elements, EXAMPLES: An example involving the dihedral group on four elements, D_8:: sage: G = DihedralGroup(4) """ Return the generators for this subgroup. EXAMPLES: An example involving the dihedral group on four elements, EXAMPLES: An example involving the dihedral group on four elements, D_8:: sage: G = DihedralGroup(4)