Group morphisms¶

Group morphisms are used in RepLAB to relate groups to one another. For example, there is always a (trivial) injection map that embeds a subgroup into the group that contains it.

A morphism is simply a function between groups that preserve the multiplicative structure (\(f(x y) = f(x) f(y)\)). An isomorphism is an invertible (or bijective) morphism.

Isomorphisms are used in RepLAB to compute with finite groups, by translating the operations into an isomorphic permutation group.

Isomorphisms are also used when the user asks RepLAB to recognize a finite group (FiniteGroup.recognize). RepLAB then returns the isomorphism from the abstract group to the user-defined group. Thus, the generators of the “platonic” abstract group can be identified as elements of the user-defined group.

Morphisms are used to describe how symmetry groups relate to one another in the convex optimization framework (see equiop).

Morphism is the most general class and a base for all the classes below.
FiniteMorphism is a morphism between finite groups; in particular, it allows the computation of preimages.
Isomorphism is a bijective morphism.
FiniteIsomorphism is a bijective finite morphism.

Morphism¶

class replab.Morphism¶

Bases: replab.Obj

Describes a morphism between groups

If both groups are compact groups with a replab.CompactGroup.reconstruction available, the torusMap linear map expresses the relationship between elements of the maximal torus of the source and the target. More specifically, let s be an element of the torus .source.reconstruction.source, there is a corresponding element t of the torus .target.reconstruction.source such that t = s * torusMap.

Class members list

Properties

source – Source group
target – Target group
torusMap – Relation between the tori of source and target if known

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Morphism composition

andThen – Composition of morphisms, the right hand side applied last
compose – Composition of morphisms, the right hand side applied first
mtimes – Shorthand for compose

Images

imageElement – Returns the image of the given source element
imageTorusElement – Returns the image of an element of the source torus (used in optimizations)

Morphism creation

lambda – Creates a morphism from an image function

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

cache(self, name, value, handleExisting)¶: Documentation in replab.Obj.cache()

cached(self, name, fun)¶: Documentation in replab.Obj.cached()

cachedOrDefault(self, name, defaultValue)¶: Documentation in replab.Obj.cachedOrDefault()

cachedOrEmpty(self, name)¶: Documentation in replab.Obj.cachedOrEmpty()

check(self)¶: Documentation in replab.Obj.check()

checkAndContinue(self)¶: Documentation in replab.Obj.checkAndContinue()

disp(self)¶: Documentation in replab.Str.disp()

eq(self, rhs)¶: Documentation in replab.Obj.eq()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

id(self)¶: Documentation in replab.Obj.id()

inCache(self, name)¶: Documentation in replab.Obj.inCache()

isequal(lhs, rhs)¶: Documentation in replab.Obj.isequal()

laws(self)¶: Documentation in replab.Obj.laws()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

ne(self, rhs)¶: Documentation in replab.Obj.ne()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

Own members

source¶

Source group

Type: Group

target¶

Target group

Type: Group

torusMap¶

Relation between the tori of source and target if known

Type: integer(*,*) or []

andThen(self, applyLast)¶

Composition of morphisms, the right hand side applied last

Parameters: applyLast (Morphism) – Morphism to apply last
Returns: The composition of this morphism applied first, followed by the given morphism
Return type: Morphism

compose(self, applyFirst)¶

Composition of morphisms, the right hand side applied first

Note: if both morphisms are finite morphisms, the resulting morphism is also a finite morphism. Note: if both morphisms are isomorphisms, the resulting morphism is also an isomorphism.

Parameters: applyFirst (Morphism) – Morphism to apply first
Returns: The composition of the given morphism applied first, followed by this morphism.
Return type: Morphism

imageElement(self, s)¶

Returns the image of the given source element

Parameters: s (element of source) – Element to compute the image of
Returns: Image
Return type: element of target

imageTorusElement(self, s)¶

Returns the image of an element of the source torus (used in optimizations)

Parameters: s (element of source.reconstruction.source) – Torus element of source
Returns: Torus element of target
Return type: element of target.reconstruction.source)

static lambda(source, target, imageElementFun, torusMap)¶

Creates a morphism from an image function

Parameters

source (Group) – Source group
target (Group) – Target group
imageElementFun (function_handle) – Function computing images of elements
torusMap (integer(*,*)) – Torus map to use in the morphism construction

Returns

Constructed morphism

Return type

replab.Morphism

mtimes(self, applyFirst)¶: Shorthand for compose

Isomorphism¶

class replab.Isomorphism¶

Bases: replab.Morphism

Describes an isomorphism between groups

Class members list

Properties

source – Source group
target – Target group
torusMap – Relation between the tori of source and target if known

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Morphism composition

andThen – Composition of morphisms, the right hand side applied last
compose – Composition of morphisms, the right hand side applied first
inverse –
mtimes – Shorthand for compose

Images

imageElement – Returns the image of the given source element
imageTorusElement – Returns the image of an element of the source torus (used in optimizations)

Morphism creation

lambda – Creates a morphism from an image function

General

identity – Returns the identity morphism from a group to itself

Preimages

preimageElement – Returns an the preimage of an element of the range

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

andThen(self, applyLast)¶: Documentation in replab.Morphism.andThen()

cache(self, name, value, handleExisting)¶: Documentation in replab.Obj.cache()

cached(self, name, fun)¶: Documentation in replab.Obj.cached()

cachedOrDefault(self, name, defaultValue)¶: Documentation in replab.Obj.cachedOrDefault()

cachedOrEmpty(self, name)¶: Documentation in replab.Obj.cachedOrEmpty()

check(self)¶: Documentation in replab.Obj.check()

checkAndContinue(self)¶: Documentation in replab.Obj.checkAndContinue()

compose(self, applyFirst)¶: Documentation in replab.Morphism.compose()

disp(self)¶: Documentation in replab.Str.disp()

eq(self, rhs)¶: Documentation in replab.Obj.eq()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

id(self)¶: Documentation in replab.Obj.id()

imageElement(self, s)¶: Documentation in replab.Morphism.imageElement()

imageTorusElement(self, s)¶: Documentation in replab.Morphism.imageTorusElement()

inCache(self, name)¶: Documentation in replab.Obj.inCache()

inverse()¶: No documentation

isequal(lhs, rhs)¶: Documentation in replab.Obj.isequal()

laws(self)¶: Documentation in replab.Obj.laws()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

mtimes(self, applyFirst)¶: Documentation in replab.Morphism.mtimes()

ne(self, rhs)¶: Documentation in replab.Obj.ne()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

source¶: Documentation in replab.Morphism.source

target¶: Documentation in replab.Morphism.target

torusMap¶: Documentation in replab.Morphism.torusMap

Own members

static identity(group)¶

Returns the identity morphism from a group to itself

Parameters: group (Group) – Group
Returns: The identity automorphism on the given group
Return type: Isomorphism

static lambda(source, target, preimageElementFun, imageElementFun, torusMap)¶

Creates a morphism from an image function

Parameters

source (Group) – Source group
target (Group) – Target group
preimageElementFun (function_handle) – Function computing preimages of elements
imageElementFun (function_handle) – Function computing images of elements
torusMap (integer(*,*)) – Torus map to use in the morphism construction

Returns

Constructed isomorphism

Return type

replab.Isomorphism

preimageElement(t)¶

Returns an the preimage of an element of the range

Returns the s such that self.imageElement(s) == t .

If the argument is not in the range of this isomorphism, the behavior is undefined.

Parameters: t (element of target) – Element to compute the preimage of
Returns: Preimage
Return type: element of source

FiniteMorphism¶

class replab.FiniteMorphism¶

Bases: replab.Morphism

Describes a morphism between finite groups

Class members list

Properties

source – Source group
target – Target group
torusMap – Relation between the tori of source and target if known

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Morphism composition

andThen – Composition of morphisms, the right hand side applied last
compose – Composition of morphisms, the right hand side applied first
mtimes – Shorthand for compose

Images

image – Returns the image of this morphism
imageElement – Returns the image of the given source element
imageGroup – Computes the image of a group
imageTorusElement – Returns the image of an element of the source torus (used in optimizations)

Preimages

kernel – Returns the kernel of this morphism
preimageGroup – Returns the group of source elements that map to a given group of target elements
preimageRepresentative – Returns an arbitrary preimage of the given element
preimagesElement – Returns the set of all source elements that map to a given element

Conversions

restrictedSource – Returns a finite morphism with its source restricted
toIsomorphism – If this morphism is injective, returns an isomorphism such that the target is restricted to the image

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

andThen(self, applyLast)¶: Documentation in replab.Morphism.andThen()

cache(self, name, value, handleExisting)¶: Documentation in replab.Obj.cache()

cached(self, name, fun)¶: Documentation in replab.Obj.cached()

cachedOrDefault(self, name, defaultValue)¶: Documentation in replab.Obj.cachedOrDefault()

cachedOrEmpty(self, name)¶: Documentation in replab.Obj.cachedOrEmpty()

check(self)¶: Documentation in replab.Obj.check()

checkAndContinue(self)¶: Documentation in replab.Obj.checkAndContinue()

compose(self, applyFirst)¶: Documentation in replab.Morphism.compose()

disp(self)¶: Documentation in replab.Str.disp()

eq(self, rhs)¶: Documentation in replab.Obj.eq()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

id(self)¶: Documentation in replab.Obj.id()

imageElement(self, s)¶: Documentation in replab.Morphism.imageElement()

imageTorusElement(self, s)¶: Documentation in replab.Morphism.imageTorusElement()

inCache(self, name)¶: Documentation in replab.Obj.inCache()

isequal(lhs, rhs)¶: Documentation in replab.Obj.isequal()

laws(self)¶: Documentation in replab.Obj.laws()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

mtimes(self, applyFirst)¶: Documentation in replab.Morphism.mtimes()

ne(self, rhs)¶: Documentation in replab.Obj.ne()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

source¶: Documentation in replab.Morphism.source

target¶: Documentation in replab.Morphism.target

torusMap¶: Documentation in replab.Morphism.torusMap

Own members

image(self)¶

Returns the image of this morphism

Returns: Subgroup of target generated by the image of source
Return type: FiniteGroup

imageGroup(self, S)¶

Computes the image of a group

Parameters: S (FiniteGroup) – Group to compute the image of, subgroup of source
Returns: Subgroup of target
Return type: FiniteGroup

kernel(self)¶

Returns the kernel of this morphism

Returns: Maximal subgroup of source with trivial image
Return type: replab.FiniteGroup

preimageGroup(self, T)¶

Returns the group of source elements that map to a given group of target elements

Parameters: T (FiniteGroup) – Subgroup of target
Returns: Subgroup of source
Return type: FiniteGroup

preimageRepresentative(self, t)¶

Returns an arbitrary preimage of the given element

Returns an s such that self.imageElement(s) == t .

If the argument is not in the range of this morphism, the behavior is undefined.

Parameters: t (element of target) – Element to compute the preimage of
Returns: Preimage representative
Return type: element of source

preimagesElement(self, t)¶

Returns the set of all source elements that map to a given element

If the argument is not in the range of this morphism, the behavior is undefined.

Parameters: t (element of target) – Element to compute the preimages of
Returns: Set of source elements
Return type: FiniteSet

restrictedSource(self, newSource)¶

Returns a finite morphism with its source restricted

Note that the return type may be more precise.

Parameters: newSource (FiniteGroup) – Subgroup of source
Returns: The restricted morphism
Return type: FiniteMorphism

toIsomorphism(self)¶

If this morphism is injective, returns an isomorphism such that the target is restricted to the image

Returns: The isomorphism
Return type: FiniteIsomorphism

FiniteIsomorphism¶

class replab.FiniteIsomorphism¶

Bases: replab.Isomorphism, replab.FiniteMorphism

Describes an isomorphism between finite groups

Class members list

Properties

source – Source group
target – Target group
torusMap – Relation between the tori of source and target if known

Prettyprinting

additionalFields – Returns the name/value pairs corresponding to additional fields to be printed
disp – Standard MATLAB/Octave display method
headerStr – Tiny single line description of the current object type
hiddenFields – Returns the names of the fields that are not printed as a row vector
longStr – Multi-line description of the current object
shortStr – Single line text description of the current object

Property cache

cache – Sets the value of the designated property in the cache
cached – Returns the cached property if it exists, computing it if necessary
cachedOrDefault – Returns the cached property if it exists, or the provided default value if it is unknown yet
cachedOrEmpty – Returns the cached property if it exists, or [] if it is unknown yet
inCache – Returns whether the value of the given property has already been computed

Laws

check – Checks the consistency of this object
checkAndContinue – Checks the consistency of this object
laws – Returns the laws that this object obeys

Unique ID

eq – Equality test
id – Returns the unique ID of this object (deprecated)
isequal – Equality test
ne – Non-equality test

Morphism composition

andThen – Composition of morphisms, the right hand side applied last
compose – Composition of morphisms, the right hand side applied first
inverse –
mtimes – Shorthand for compose

Images

image – Returns the image of this morphism
imageElement – Returns the image of the given source element
imageGroup – Computes the image of a group
imageTorusElement – Returns the image of an element of the source torus (used in optimizations)

General

identity – Returns the identity morphism from a finite group to itself
preservesTypeOrder – Returns whether, for sure, this isomorphism preserves element ordering

Preimages

kernel – Returns the kernel of this morphism
preimageElement – Returns an the preimage of an element of the range
preimageGroup – Returns the group of source elements that map to a given group of target elements
preimageRepresentative – Returns an arbitrary preimage of the given element
preimagesElement – Returns the set of all source elements that map to a given element

Conversions

restrictedSource – Returns a finite morphism with its source restricted
toIsomorphism – If this morphism is injective, returns an isomorphism such that the target is restricted to the image

Inherited elements

additionalFields(self)¶: Documentation in replab.Str.additionalFields()

andThen(self, applyLast)¶: Documentation in replab.Morphism.andThen()

cache(self, name, value, handleExisting)¶: Documentation in replab.Obj.cache()

cached(self, name, fun)¶: Documentation in replab.Obj.cached()

cachedOrDefault(self, name, defaultValue)¶: Documentation in replab.Obj.cachedOrDefault()

cachedOrEmpty(self, name)¶: Documentation in replab.Obj.cachedOrEmpty()

check(self)¶: Documentation in replab.Obj.check()

checkAndContinue(self)¶: Documentation in replab.Obj.checkAndContinue()

compose(self, applyFirst)¶: Documentation in replab.Morphism.compose()

disp(self)¶: Documentation in replab.Str.disp()

eq(self, rhs)¶: Documentation in replab.Obj.eq()

headerStr(self)¶: Documentation in replab.Str.headerStr()

hiddenFields(self)¶: Documentation in replab.Str.hiddenFields()

id(self)¶: Documentation in replab.Obj.id()

image(self)¶: Documentation in replab.FiniteMorphism.image()

imageElement(self, s)¶: Documentation in replab.Morphism.imageElement()

imageGroup(self, S)¶: Documentation in replab.FiniteMorphism.imageGroup()

imageTorusElement(self, s)¶: Documentation in replab.Morphism.imageTorusElement()

inCache(self, name)¶: Documentation in replab.Obj.inCache()

inverse()¶: No documentation

isequal(lhs, rhs)¶: Documentation in replab.Obj.isequal()

kernel(self)¶: Documentation in replab.FiniteMorphism.kernel()

laws(self)¶: Documentation in replab.Obj.laws()

longStr(self, maxRows, maxColumns)¶: Documentation in replab.Str.longStr()

mtimes(self, applyFirst)¶: Documentation in replab.Morphism.mtimes()

ne(self, rhs)¶: Documentation in replab.Obj.ne()

preimageElement(t)¶: Documentation in replab.Isomorphism.preimageElement()

preimageGroup(self, T)¶: Documentation in replab.FiniteMorphism.preimageGroup()

preimageRepresentative(self, t)¶: Documentation in replab.FiniteMorphism.preimageRepresentative()

preimagesElement(self, t)¶: Documentation in replab.FiniteMorphism.preimagesElement()

restrictedSource(self, newSource)¶: Documentation in replab.FiniteMorphism.restrictedSource()

shortStr(self, maxColumns)¶: Documentation in replab.Str.shortStr()

source¶: Documentation in replab.Morphism.source

target¶: Documentation in replab.Morphism.target

toIsomorphism(self)¶: Documentation in replab.FiniteMorphism.toIsomorphism()

torusMap¶: Documentation in replab.Morphism.torusMap

Own members

static identity(group)¶

Returns the identity morphism from a finite group to itself

Parameters: group (FiniteGroup) – Group
Returns: The identity automorphism on the given group
Return type: FiniteIsomorphism

preservesTypeOrder(self)¶

Returns whether, for sure, this isomorphism preserves element ordering

When this method returns true, we must have, for x and y in source, self.source.type.compare(x, y) == self.target.type.compare(self.imageElement(x), self.imageElement(y))
When this method returns false, it does not necessarily means that there exists a pair (x, y) that violates the condition above. It simply means the order preservation is not known.

Returns: Whether, for sure, this isomorphism preserves element ordering
Return type: logical