opycleid.categoryaction

This module defines the basic classes needed for building musical transformations.

CatObject

opycleid.categoryaction.CatObject(name,elements)

Defines a category object, which is simply a named finite set. Elements of the set are indexed internally from 0 to len(elements).

Arguments

name: a string used to name the set.
elements: a list of strings representing the elements of the set.

Methods

get_idx_by_name

get_idx_by_name(elem)

Returns the integer index associated with the element elem. Raises an exception if the element cannot be found.

get_name_by_idx

get_name_by_idx(idx)

Returns the element associated with the integer index idx.

get_elements

get_elements()

Returns the list of elements contained in this set.

get_cardinality

get_cardinality()

Returns the cardinality of the set.

is_in

is_in(elem)

Returns True if the element elem is in the set.

CatMorphism

opycleid.categoryaction.CatMorphism(name,source,target,mapping=None)

Defines a category morphism between two category objects. It is defined by its source, its target, and a relation between the source sets and the target sets.

Arguments

name: a string used to name the morphism.
source: an instance of opycleid.categoryaction.CatObject representing the source of the morphism.
target: an instance of opycleid.categoryaction.CatObject representing the target of the morphism.
mapping: an optional argument representing the mapping between the source and the target. It can be given either in matrix form, as a NumPy array of booleans, or as a dictionary (see the set_mapping method for the structure of the dictionary).

Methods

set_name

set_name(name)

Sets the name of the morphism to name.

set_to_identity

set_to_identity()

If the source and target are identical, sets the morphism to be the identity on this category object, i.e. the relation between the corresponding sets is the identity function.

set_mapping

set_mapping(mapping)

Defines the relation between the source sets and the target sets. The argument mapping should be a dictionary, whose keys are elements in the source set, and whose values are lists of elements in the target set corresponding to the images of the source elements by the given relation.

set_mapping_matrix

set_mapping_matrix(matrix)

Defines the relation between the source sets and the target sets using a matrix description. The argument mapping should be a NumPy array of type bool. The rows of this matrix corresponds to the elements of the target sets, and the columns corresponds to the elements of the source sets, in both cases indexed as in the corresponding CatObject. Use only if you are sure about the correspondence between elements and element indices.

get_mapping

get_mapping()

Returns the relation defined by this morphism as a dictionary, whose keys are elements in the source set, and whose values are lists of elements in the target set corresponding to the images of the source elements.

get_mapping_matrix

get_mapping_matrix()

Returns the relation defined by this morphism as a NumPy array of type bool.

str

Overloads Python str to return a string description of the morphism, including its source, target, and the relation between them.

call

Makes the current instance callable. A typical use is CatMorphism(elem) where elem is a string representing an element in the source set. Returns a list of images in the target set.

mul

Overloads the * operator in order to represent morphism composition. A typical use is CatMorphism_2 * CatMorphism_1. If the target of CatMorphism_1 is identical to the source of CatMorphism_2, this returns the corresponding composite morphism. Otherwise, the two morphisms are not composable and it returns None.

pow

Overloads the ** operator in order to represent morphism iterated multiplication. A typical use is CatMorphism ** int. If CatMorphism is an endomorphism, i.e. its target is the same object as its source, this returns the corresponding iterated morphism. Otherwise, an exception will be raised.

eq

Overloads the == operator in order to check for morphism equality. A typical use is CatMorphism_2 == CatMorphism_1. Returns True if the sources, targets, and relations of both morphisms are equal.

le

Overloads the <= operator in order to check for morphism inclusion. A typical use is CatMorphism_2 <= CatMorphism_1. Returns True if the sources, and targets of both morphisms are equal, and if the relation of CatMorphism_2 is equal or included in the relation of CatMorphism_1.

lt

Overloads the < operator in order to check for strict morphism inclusion. A typical use is CatMorphism_2 < CatMorphism_1. Returns True if the sources, and targets of both morphisms are equal, and if the relation of CatMorphism_2 is non-trivially included in the relation of CatMorphism_1 (i.e. it is included but not equal).

CategoryAction

opycleid.categoryaction.CategoryAction(objects=None,generators=None,generate=True)

Defines a category action object, i.e. a faithful functor $F \colon \mathbf{C} \to \mathbf{Rel}$ , where $\mathbf{C}$ is a small category, and $\mathbf{Rel}$ is the 2-category of finite sets and relations. Instances of this class store internally

a dictionary of opycleid.categoryaction.CatObject instances, indexed by their name
a dictionary of opycleid.categoryaction.CatMorphism instances, indexed by their name, corresponding to the generators of the category,
a dictionary of opycleid.categoryaction.CatMorphism instances, indexed by their name, corresponding to all the operations of the category.

Arguments

objects: optional argument. A list of opycleid.categoryaction.CatObject instances with distinct names representing the objects in the category.
generators: optional argument. A list of opycleid.categoryaction.CatMorphism instances with distinct names (an exception will be raised if this is not the case) representing the generators of the category.
generate: boolean, optional argument. If objects and generators are given at instantiation, specifies whether the category should immediately be generated.

Methods

set_objects

set_objects(list_objects)

The argument list_objects should be a list of opycleid.categoryaction.CatObject instances. Calling this method stores the CatObject instances in the internal dictionary, and resets the generators and operations of the category. The objects must have distinct elements and names; an exception will be raised if this is not the case.

get_objects()

get_objects()

Returns the objects in this category, as a list of tuples (String,CatObject), where the CatObject instance is an object of the category, and String corresponds to its name.

set_generators

set_generators(list_morphisms)

The argument list_morphisms should be a list of opycleid.categoryaction.CatMorphism instances with distinct names (an exception will be raised if this is not the case). Calling this method will erase the previous internal dictionaries of generators and morphisms (but not objects). The internal dictionary of generators is then updated with the instances of list_morphisms.

generate_category

generate_category()

Generates the category from the internal dictionary of generators. This means that for any operation $f$ and any generator $g$ of this category, the composite operation $g \circ f$ will be added to the internal dictionary of operations, if not already present, until the generation is complete.

get_generators()

get_generators()

Returns the objects in this category, as a list of tuples (String,CatMorphism), where the CatMorphism instance is a generator morphism of the category, and String corresponds to its name.

get_morphisms()

get_morphisms()

Returns the objects in this category, as a list of tuples (String,CatMorphism), where the CatMorphism instance is a morphism of the category, and String corresponds to its name.

rename_operation

rename_operation(name,new_name)

The arguments name and new_name are the name of a category operation, and the specified new name respectively. Renames an operation in the category.

rewrite_operations

rewrite_operations()

Rewrite/simplify operation names in the category. Calling this method will examine all operation names, trying to identify repeated instances of the names of the generators, and simplifying them to "([name]^p)" where p is the corresponding power.

mult

mult(operation_2,operation_1)

The arguments operation_2 and operation_1 are the names of category operations. Returns the name of the composite operation $\text{operation_2} \circ \text{operation_1}$ if present. If operation_2 and operation_1 are not composable, returns None.

apply_operation

apply_operation(name,elem)

The argument name is the name of a category operation, and the argument elem is an element in its source set. Returns the images of elem by the category operation with name name.

get_operation

get_operation(elem_1,elem_2)

The arguments elem_1 and elem_2 are elements in the objects of the category. Returns all the operations $f$ in the category such that elem_2 is the image of elem_1 by $f$ .

get_description

get_description(name)

Returns a string description of the morphism with name name.

get_automorphisms

get_automorphisms()

Computes the automorphisms of the category $\mathbf{C}$ of the current category action $F \colon \mathbf{C} \to \mathbf{Rel}$ . Returns a list of CategoryFunctor instances, each one corresponding to an automorphism $\mathbf{C} \to \mathbf{C}$ .

In the current implementation, calling this method enumerates every mapping from the generators to the morphisms. It is not optimized, and therefore should not be used for large category actions.

MonoidAction

opycleid.categoryaction.MonoidAction()

Defines a monoid action object, i.e. a faithful functor $F \colon \mathbf{C} \to \mathbf{Rel}$ , where $\mathbf{C}$ is a single-object category, and $\mathbf{Rel}$ is the 2-category of finite sets and relations. This class inherits from opycleid.categoryaction.CategoryAction, and implements methods specific to the case of monoids and groups.

Methods

set_objects

set_objects(list_objects)

This method is the same as the one in opycleid.categoryaction.CategoryAction, except that only a single instance of opycleid.categoryaction.CatObject is allowed in the list list_objects.

get_object

get_object()

Returns the single object of the monoid action as a tuple (String,CatObject), where the CatObject instance is the single object of the monoid, and String corresponds to its name. This is equivalent to get_objects()[0].

is_simplytransitive

is_simplytransitive()

Checks if the monoid acts simply transitively. Return True if it does.

element_Rclass

element_Rclass(operation)

The argument operation should be the name of an operation in the monoid. Generates the R class for the specified operation.

Note: for a given morphism $f$ , i.e. the R class is the set of all $g$ such that we have $f \mathcal{R} g$ for Green's $\mathcal{R}$ relation, i.e. $f \mathcal{R} g$ if $fS = gS$ where $S$ is the monoid.

element_Lclass

element_Lclass(operation)

The argument operation should be the name of an operation in the monoid. Generates the L class for the specified operation.

Note: for a given morphism $f$ , i.e. the L class is the set of all $g$ such that we have $f \mathcal{L} g$ for Green's $\mathcal{L}$ relation, i.e. $f \mathcal{L} g$ if $Sf = Sg$ where $S$ is the monoid.

get_Rclasses

get_Rclasses()

Returns all R classes in this monoid as a list of lists, each list being an R class.

get_Lclasses

get_Lclasses()

Returns all L classes in this monoid as a list of lists, each list being an L class.

get_leftIdeals

get_leftIdeals()

Returns all left ideals in this monoid as a list of lists, each list being a left ideal. A left ideal is a subset $X$ of the monoid, such that for any operation $m$ in the monoid, $mX$ is included in $X$ .

get_rightIdeals

get_rightIdeals()

Returns all right ideals in this monoid as a list of lists, each list being a right ideal. A right ideal is a subset $X$ of the monoid, such that for any operation $m$ in the monoid, $Xm$ is included in $X$ .

is_leftIdeal

is_leftIdeal(S)

Returns True if the subset $S$ is a left ideal in the monoid.

is_rightIdeal

is_rightIdeal(S)

Returns True if the subset $S$ is a right ideal in the monoid.

CategoryFunctor

opycleid.categoryaction.CategoryFunctor(cat_action_source,cat_action_target)

A CategoryFunctor instance represents a functor $N \colon \mathbf{C} \to \mathbf{C}'$ between the categories $\mathbf{C}$ and $\mathbf{C}'$ corresponding to the category actions $S \colon \mathbf{C} \to \mathbf{Rel}$ and $S' \colon \mathbf{C'} \to \mathbf{Rel}$ .

It is instantiated by specifying two instances cat_action_source and cat_action_target of opycleid.categoryaction.CategoryAction, i.e. the domain and codomain of the functor $N \colon \mathbf{C} \to \mathbf{C}'$ .

Methods

set_fullmapping

set_fullmapping(object_mapping,morphism_mapping)

Sets the mapping of morphisms and objects between the domain and codomain category actions. The method checks that the given mappings are valid, i.e. that

for every morphism $f \colon X \to Y$ of $\mathbf{C}$ , the image morphism by $N$ is a morphism from $N(X)$ to $N(Y)$ .
for every morphisms $f,g$ of $\mathbf{C}$ , we have $N(g \circ f) = N(g) \circ N(f)$ .

The arguments of this method are as follows.

object_mapping is a dictionary, the keys of which are object names in the source category action, the values of which are object names in the target category action.
morphism_mapping is a dictionary, the keys of which are morphism names in the source category action, the values of which are morphism names in the target category action.

Returns True if the given mappings are valid, False otherwise.

set_fullmapping

set_from_generator_mapping(gen_mapping)

Sets the mapping of morphisms and objects between the domain and codomain category actions from a mapping of the generators of the source category action. The argument gen_mapping is a dictionary, the keys of which are generator names in the source category action, the values of which are morphism names in the target category action. The full mapping of objects and morphisms is deduced from the generator mapping. The method checks that the given generator mapping is valid, and returns True if this is case, False otherwise.

get_image_object

get_image_object(object_name)

Returns the image of an object of the source category action by the category functor. The argument object_name is a string representing the name of an object in the source category of this functor. A string representing the image of object_name in the target category action of this functor is returned.

get_image_morphism

get_image_morphism(morphism_name)

Returns the image of a morphism of the source category action by the category functor. The argument morphism_name is a string representing the name of a morphism in the source category of this functor. A string representing the image of morphism_name in the target category action of this functor is returned.

get_object_mapping

get_object_mapping()

Returns the full mapping of objects by the category functor as a dictionary.

get_morphism_mapping

get_morphism_mapping()

Returns the full mapping of morphisms by the category functor as a dictionary.

--

is_valid

is_valid()

Checks if the category functor is a valid one, returns True if this is case, False otherwise.

--

is_automorphism

is_automorphism()

Checks if the category functor is an automorphism, i.e. the source and target categories are identical, and the mapping of objects and morphisms is bijective. Returns True if this is case, False otherwise.

mul

Overloads the * operator in order to represent category functor composition. A typical use is CategoryFunctor_2 * CategoryFunctor_1. If the target category of CategoryFunctor_1 is identical to the source category of CategoryFunctor_2, this returns the corresponding composite functor. Otherwise, the two functors are not composable and an exception will be raised.

eq

Overloads the == operator in order to represent category functor equality. A typical use is CategoryFunctor_2 == CategoryFunctor_1. Returns True if this the mapping of objects and morphisms are identical, False otherwise.

call

Makes the current instance callable. A typical use is CategoryFunctor(x), where x is either an object name, or a morphism name, and returns the corresponding image. It is a practical shorthand for get_image_object or get_image_morphism

CategoryActionFunctor

opycleid.categoryaction.CategoryActionFunctor(cat_action_source,cat_action_target,cat_functor,nat_transform)

A CategoryActionFunctor instance represents a morphism between two category actions $F \colon \mathbf{C} \to \mathbf{Rel}$ and $F' \colon \mathbf{C'} \to \mathbf{Rel}$ . Such a morphism is the data of a pair $(N,\nu)$ where

$N$ is a functor from $\mathbf{C}$ to $\mathbf{C'}$ , and
$\nu$ is a lax natural transformation from $S$ to $S'N$ .

It is instantiated by specifying

two instances cat_action_source and cat_action_target of opycleid.categoryaction.CategoryAction, i.e. the domain and codomain of the functor $N \colon \mathbf{C} \to \mathbf{C}'$ ,
an instance cat_functor of opycleid.categoryaction.CategoryFunctor representing the functor $N \colon \mathbf{C} \to \mathbf{C}'$ , and
a dictionary nat_transform representing the natural transformation $\nu \colon S \to S'N$ . The keys of this dictionary are object names in the source category action $S \colon \mathbf{C} \to \mathbf{Rel}$ , the values are instances of opycleid.categoryactionCatMorphism from the object to their images.

Methods

is_valid

is_valid()

Checks if the category action functor is a valid one, i.e. that

the functor $N \mathbf{C} \to \mathbf{C'}$ is a valid one, and
the lax natural transformation $\nu$ is valid, i.e. that for any morphism $f \colon X \to Y$ in the source category action, the relation $\nu_Y \circ S(f)$ is included in the relation $S'N(f) \circ \nu_X$ .

Returns True if the category action functor is a valid one, False otherwise.

mul

Overloads the * operator in order to represent category action functor composition. A typical use is CategoryActionFunctor_2 * CategoryActionFunctor_1. If the target category action of CategoryActionFunctor_1 is identical to the source category action of CategoryActionFunctor_2, this returns the corresponding composite category action functor, corresponding to the data of $(N_2 \circ N_1,N_1\nu_2 \circ \nu_1)$ Otherwise, the two category action functors are not composable and an exception will be raised.

eq

Overloads the == operator in order to represent category action functor equality. A typical use is CategoryActionFunctor_2 == CategoryActionFunctor_1. Returns True if this both the category functor and the natural transformation are equal, False otherwise.