API Reference

The Recommended Algebra Constructor

The function, make_finite_algebra, is the recommended way to create any finite algebra. It analyzes the input and returns the appropriate finite algebra: Group, Ring, Field, VectorSpace, Module, Monoid, Semigroup, Quasigroup, Loop, or Magma.

finite_algebras.make_finite_algebra(*args)[source]

This is the recommended function to use to create any finite algebra. It analyzes the input and returns the appropriate finite algebra: Group, Ring, Field, VectorSpace, Module, Monoid, Semigroup, or Magma.

If only 1 input argument, then it must either be a string or a Python dictionary. If it’s a string, then it must be a path to a JSON file that defines a FiniteAlgebra (i.e., Magma, Semigroup, Monoid, Group, Ring, or Field), as described below for the first five arguments. If it’s a Python dictionary, then it must be the dictionary version of such a JSON file. (No JSON or dictionary formats are defined for FiniteCompositeAlgebras.)

Otherwise, the first argument should always be the name (str) of the algebra and the second argument should be a description (str) of the algebra.

The remaining arguments depend on whether the algebra being constructed is a FiniteAlgebra (i.e, Magma, Semigroup, Monoid, Group, Ring, or Field) or a FiniteCompositeAlgebra (i.e., Module or Vector Space).

If constructing a FiniteAlgebra:

The third argument should be a list of element names (str).

The fourth argument should be a list of lists of either all integers or all strings that represent a finite binary operation. That is, a 2-dimensional, square “table” (Cayley table). The meaning of a table entry C corresponding to row A and column B, is that A * B = C, where * is the binary operator. If the items in the table are all integers, then they must all represent the positions of elements in the element list given by the third argument, above. If they are all strings, then they must all be members of the list of strings given by the third argument.

A fifth argument is required only if a Ring or Field is being constructed, and it should also be a table with structure similar to the fourth argument.

If constructing a FiniteCompositeAlgebra:

The third argument should be a Ring or Field (the “scalars”).

The fourth argument should be a Group (the “vectors”).

And the fifth argument should be a function that implements the binary operation for “scaling vectors”.

See the definitions and examples at https://abstract-algebra.readthedocs.io

FiniteOperator

The FiniteOperator is a callable class that implements the binary operators used by the various algebras supported here. This class is automatically created whenever an algebra is created. It is based on the algebra’s Cayley table.

class finite_algebras.FiniteOperator(elements, identity, table)[source]

A callable class that implements a binary operation based on a multiplication table (i.e., Cayley table). Although intended for use as the binary operation of a finite algebra (e.g., Group operation), the implementation here can be called with zero, one, two, or more arguments (similar to how arithmetic operators work in Lisp).

If no arguments are provided, it will return the identity element if it exists; otherwise it will return None. e.g., op() ==> e | None

If only one argument is provided, it will check whether the argument is a valid element of the algebra, and if so, return the same value, otherwise it will raise an exception. e.g., op(a) ==> a | ValueError

If two arguments are provided, it will return their ‘product’. e.g., op(a, b) ==> ab

If more than two arguments are provided, it will return their product by associating left-to-right. e.g., op(a, b, c, d) = (((ab)c)d). The order of association is only important for a Magma, because it is the only non-associative algebraic structure supported here.

FiniteAlgebra

This is the top-level class for all algebras that have a single set of elements (Magma, Quasigroup, Loop, Semigroup, Monoid, Group, Ring, Field). It is an abstract base class (ABC) and is NOT INTENDED TO BE INSTANTIATED.

class finite_algebras.FiniteAlgebra(name, description, elements, table)[source]

Bases: ABC

A top-level container class for functionality that is common to all finite algebras that only have one set of elements. THIS CLASS IS NOT INTENDED TO BE INSTANTIATED.

copy_algebra(new_elements=(), new_name=False, new_description=False)[source]: Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict()[source]: Returns a dictionary that maps each of the algebra’s elements to its inverse element.

dump(json_filename)[source]: Writes the algebra to the given filename in JSON format.

dumps()[source]: Returns a JSON string that represents the algebra.

element_map()[source]: Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

property elements: Returns the algebra’s element names (list of strings).

has_cancellation(verbose=False)[source]: Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity()[source]: A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses()[source]: Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element)[source]: Return the inverse of an element

is_abelian()[source]: Returns True if the algebra is abelian; returns False otherwise.

is_associative()[source]: Returns True if the algebra is associative; returns False otherwise.

is_commutative()[source]: Returns True if the algebra is commutative; returns False otherwise.

property order: Returns the order of the algebra.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False)[source]: Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

Magma

A Magma is a set of elements with a closed, binary operation.

class finite_algebras.Magma(name, description, elements, table)[source]

Bases: FiniteAlgebra

A Magma is a finite algebra with a binary operation that returns a unique value, in the algebra, for all pairs in the cross-product of the algebra’s set of elements with itself. With a binary operation, we can compute the direct product of two or more algebras. Also, we can check to see if two Magmas are isomorphic.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False)[source]: Prints out information about the algebra. Tables larger than max_size are not printed out.

center()[source]: Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False)[source]: Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses)[source]: Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses)[source]: Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None)[source]: If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_pairs_where_sum_equals(elem_name)[source]: Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True)[source]: Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems)[source]: Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1)[source]: If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic()[source]: Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping)[source]: Returns True if the input mapping from this algebra to the other algebra is isomorphic.

isomorphic(other)[source]: If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra)[source]: Returns an iterator that returns lists of left cosets.

make_element_mappings(other)[source]: Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements. The orders of self and other must be equal.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True)[source]: Return a list of proper subalgebras of the algebra.

reorder_elements(reordered_elements)[source]: Return a new group made from this one with the elements reordered.

right_cosets(subalgebra)[source]: Returns an iterator that returns lists of right cosets.

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description')[source]: Return the algebra constructed from the given closed subset of elements.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

Quasigroup

A Quasigroup is a Magma that has the cancellation property.

class finite_algebras.Quasigroup(name, description, elements, table)[source]

Bases: Magma

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Prints out information about the algebra. Tables larger than max_size are not printed out.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True): Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements. The orders of self and other must be equal.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

Loop

A Loop is a Quasigroup with an identity element.

class finite_algebras.Loop(name, description, elements, table)[source]

Bases: Quasigroup

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Prints out information about the algebra. Tables larger than max_size are not printed out.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True): Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements. The orders of self and other must be equal.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

Semigroup

A Semigroup is an associative Magma.

class finite_algebras.Semigroup(name, description, elements, table, check_inputs=True)[source]

Bases: Magma

A Semigroup is an associative Magma.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Prints out information about the algebra. Tables larger than max_size are not printed out.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True): Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

is_regular()[source]: Returns True if for all elements, a, there exists an element, x, such that axa=a. Otherwise, False is returned.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements. The orders of self and other must be equal.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

weak_inverses()[source]: Returns a dictionary of weak inverses, where each key is one of the algebra’s elements and its value is a list of its weak inverses. If the algebra is regular, then there will be at least 1 weak inverse for each element. Otherwise, some elements may not have a weak inverse.

Monoid

A Monoid is a Semigroup with an identity element.

class finite_algebras.Monoid(name, description, elements, table, check_inputs=True)[source]

Bases: Semigroup

A Monoid is a Semigroup with an identity element. With an identity element, we can compute element orders. So, that happens here.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Prints out information about the algebra. Tables larger than max_size are not printed out.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_order(element) → int[source]: Returns the order of the given element within the algebra.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True): Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

is_regular(): Returns True if for all elements, a, there exists an element, x, such that axa=a. Otherwise, False is returned.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_element_mappings(other)[source]: Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements, where the identity of this algebra is always mapped to the identity of other.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

regular_representation(sparse='')[source]: Given a group, this function returns four things: (1) A dictionary that maps each group element to its corresponding regular representation, (2) A (reverse) dictionary that maps each regular representation (in the form of a tuple of tuples) back to its corresponding group element, (3) A function that maps a group element to its corresponding regular representation matrix, and (4) Another function that maps in the opposite direction, from regular representation matrix to group element. By default, the matrices are dense arrays. SciPy sparse arrays can be output instead, by setting the input variable, “sparse”, to one of the following seven strings: “BSR”, “COO”, “CSC”, “CSR”, “DIA”, “DOK”, or “LIL”. Each of the seven strings corresponds to one of the seven classes of sparse array supported by SciPy.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

units(return_names=True)[source]: Return a sorted list of the Monoid’s units. By default, the names of elements are returned. Setting ‘return_names’ to False will return element indices instead. NOTE: This method is used to compute the units of a Ring.

units_subgroup()[source]: Return the Unit Subgroup of this algebra. Makes sense for Monoids or Rings, where the multiplicative portion of the Ring is a Monoid. It will also work for Groups and Fields, but will return the entire Group or the entire multiplicative Group of a Field.

verify_regular_representation(elem_to_arr, arr_to_elem)[source]: Verifies that the regular representation satisfies the two requirements of it. This requires that the regular representation use dense matrices, NOT sparse matrices.

weak_inverses(): Returns a dictionary of weak inverses, where each key is one of the algebra’s elements and its value is a list of its weak inverses. If the algebra is regular, then there will be at least 1 weak inverse for each element. Otherwise, some elements may not have a weak inverse.

Group

A Group is a Monoid with inverse elements.

class finite_algebras.Group(name, description, elements, table, check_inputs=True)[source]

Bases: Monoid

A Group is a Monoid with inverses.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False)[source]: Print information about the Group.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

commutator(a, b)[source]: Return [a, b] = a * b * inv(a) * inv(b), the commutator of a & b

commutator_subalgebra()[source]: Return the commutator subalgebra (Group, Ring, or Field) of this Group, Ring, or Field.

commutators()[source]: Return the list of commutators of the group.

conjugate(a, g)[source]: Return g * a * inv(g), the conjugate of a with respect to g

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_order(element) → int: Returns the order of the given element within the algebra.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True): Return the n_th power of the given element. n must be an integer. If n == 0 and an identity element exists, then it will be returned; otherwise, a ValueError is raised. If n < 0, and the algebra has inverses, then the inverse of the element raised to the absolute value of the power is returned, e.g., b^-4 = inv(b^4). If n < 0 and the algebra does not have inverses, then a ValueError is raised. For non-associative algebras (Magmas), the default is for products to be associated from the left, e.g., b^4 = ((b * b) * b) * b. Set left_associative to False, to associate from the right, instead.

property elements: Returns the algebra’s element names (list of strings).

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element)[source]: Return the inverse of an element

inverse_mapping()[source]: Returns a dictionary that maps each element to its inverse.

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

is_normal(subgrp)[source]: Returns True if the subgroup is normal, otherwise False is returned

is_regular(): Returns True if for all elements, a, there exists an element, x, such that axa=a. Otherwise, False is returned.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements, where the identity of this algebra is always mapped to the identity of other.

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

quotient_group(subgroup)[source]: Given a normal subgroup, return the quotient group of this group. The elements of the quotient group will be representative elements from cosets, prefixed with ‘~’.

regular_representation(sparse=''): Given a group, this function returns four things: (1) A dictionary that maps each group element to its corresponding regular representation, (2) A (reverse) dictionary that maps each regular representation (in the form of a tuple of tuples) back to its corresponding group element, (3) A function that maps a group element to its corresponding regular representation matrix, and (4) Another function that maps in the opposite direction, from regular representation matrix to group element. By default, the matrices are dense arrays. SciPy sparse arrays can be output instead, by setting the input variable, “sparse”, to one of the following seven strings: “BSR”, “COO”, “CSC”, “CSR”, “DIA”, “DOK”, or “LIL”. Each of the seven strings corresponds to one of the seven classes of sparse array supported by SciPy.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

sub(x, y)[source]: Group subtraction: Return x - y; i.e., x + inv(y).

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

subgroups()[source]: Return a list of all subgroups, including trivial subgroups.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

trivial_subgroups()[source]: Return the group’s two trivial subgroups.

unique_proper_subgroups(subgroups=None)[source]: Return a list of proper subgroups that are unique, up to isomorphism. If no subgroups are provided, then they will be derived.

units(return_names=True): Return a sorted list of the Monoid’s units. By default, the names of elements are returned. Setting ‘return_names’ to False will return element indices instead. NOTE: This method is used to compute the units of a Ring.

units_subgroup(): Return the Unit Subgroup of this algebra. Makes sense for Monoids or Rings, where the multiplicative portion of the Ring is a Monoid. It will also work for Groups and Fields, but will return the entire Group or the entire multiplicative Group of a Field.

verify_regular_representation(elem_to_arr, arr_to_elem): Verifies that the regular representation satisfies the two requirements of it. This requires that the regular representation use dense matrices, NOT sparse matrices.

weak_inverses(): Returns a dictionary of weak inverses, where each key is one of the algebra’s elements and its value is a list of its weak inverses. If the algebra is regular, then there will be at least 1 weak inverse for each element. Otherwise, some elements may not have a weak inverse.

Ring

A Ring is an abelian Group with a second binary operation, over which it is a Semigroup, where the second operation distributes over the first operation.

class finite_algebras.Ring(name, description, elements, table, table2, check_inputs=True, conjugate_mapping=None)[source]

Bases: Group

A Ring is a commutative Group with an ‘addition’ operator, along with an associative ‘multiplication’ operator, where multiplication distributes over addition. The operator inherited from Group becomes ‘addition’, while ‘multiplication’ is defined by a second Cayley table, table2.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_conjugates=False, show_generators=False)[source]: Print information about the Ring.

add(*args)[source]: Use the inherited group operator as the ring’s addition operator.

property add_identity: Returns the additive identity element

property add_table: Returns the CayleyTable for addition.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

commutator(a, b)[source]: Return [a, b] = (a * b) - (b * a), the ring commutator of a & b

commutator_subalgebra(): Return the commutator subalgebra (Group, Ring, or Field) of this Group, Ring, or Field.

commutators(): Return the list of commutators of the group.

conj(elem)[source]: Given an element name, return the element name of its conjugate value.

conjugate(a, g): Return g * a * inv(g), the conjugate of a with respect to g

conjugates()[source]: Return the dictionary that maps elements to their conjugate values. If it’s None, then the element is its own conjugate.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

elem_conj(elem)[source]: For use only when making a Cayley-Dickson algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_order(element) → int: Returns the order of the given element within the algebra.

element_pairs_where_product_equals(elem_name)[source]: Return all pairs of elements where the product is equal to elem_name.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True)[source]: Overrides the Magma method by the same name, so that we use the multiplication operation of the Ring to raise an element to a power.

property elements: Returns the algebra’s element names (list of strings).

extract_additive_algebra()[source]: A Ring’s elements over addition, alone, should be a commutative Group. This function returns that Group.

extract_multiplicative_algebra()[source]: A Ring’s elements over multiplication, alone, should be a Semigroup. This function returns that Semigroup.

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

has_mult_identity()[source]: A convenience function that returns True or False, depending on whether the algebra has a multiplicative identity element, in addition to its additive identity element.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

inverse_mapping(): Returns a dictionary that maps each element to its inverse.

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_gaussian_prime(elem)[source]: This method only works for elements of Rings or Fields created by the function, ‘generate_algebra_mod_n’, or by a single application of the Ring method, ‘make_cayley_dickson_algebra’, to the output of ‘generate_algebra_mod_n’. That is, elements that look like 7 or 07:12.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

is_normal(subgrp): Returns True if the subgroup is normal, otherwise False is returned

is_regular(): Returns True if for all elements, a, there exists an element, x, such that axa=a. Otherwise, False is returned.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_cayley_dickson_algebra(mu=None, version=1)[source]

Constructs the Cayley-Dickson algebra using this Ring or Field.

Several different versions of multiplication are supported: version=1: (DEFAULT) No mu & no conjugation are used version=2: Definition in Schafer, 1966 version=3: Definition in Schafer, 1954 version=4: Definition in Baez, 2001.

See the documentation on readthedocs for more information regarding versions.

Versions 2 & 3 require a value for mu. If mu is None (the default), then mu will be automatically set to be the additive inverse of the Ring’s multiplicative identity element (i.e., “-1”) if it exists. If it does not exist, then an exception will be raised.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements, where the identity of this algebra is always mapped to the identity of other.

property minus_one: Return the Ring’s ‘minus one’ element. That is, the additive inverse of its multiplicative identity element.

mult(*args)[source]: Ring multiplication, based on the second table.

property mult_identity: Returns the multiplicative identity element, if it exists. If it doesn’t exist, then None is returned.

mult_is_commutative()[source]: By definition, Ring addition is commutative, but Ring multiplication only needs to be associative. This method tells us whether multiplication is commutative for this Ring.

property mult_table: Returns the CayleyTable for multiplication

norm(elem)[source]: Return the product of the input element and its conjugate.

property one: Another way to get the multiplicative identity element

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

quotient_group(subgroup): Given a normal subgroup, return the quotient group of this group. The elements of the quotient group will be representative elements from cosets, prefixed with ‘~’.

regular_representation(sparse=''): Given a group, this function returns four things: (1) A dictionary that maps each group element to its corresponding regular representation, (2) A (reverse) dictionary that maps each regular representation (in the form of a tuple of tuples) back to its corresponding group element, (3) A function that maps a group element to its corresponding regular representation matrix, and (4) Another function that maps in the opposite direction, from regular representation matrix to group element. By default, the matrices are dense arrays. SciPy sparse arrays can be output instead, by setting the input variable, “sparse”, to one of the following seven strings: “BSR”, “COO”, “CSC”, “CSR”, “DIA”, “DOK”, or “LIL”. Each of the seven strings corresponds to one of the seven classes of sparse array supported by SciPy.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

scalar_mult(scalar_name, elem_name)[source]: Scalar multiplication. ‘a’ * ‘c:d’ = ‘a*c:a*d’ Example: scalar_mult(‘2’, ‘1:2’, F3) ==> ‘2:1’

split_element(element)[source]: If the element is a compound element created by a direct product or the Cayley-Dickson construction, then it contains at least one delimiter (e.g., ‘1:2’ or ‘1:2:3:4’). This method splits the element at the middle delimiter and returns the two pieces (e.g., ‘1’, ‘2’ or ‘1:2’, ‘3:4’). If the element is not a compound element, then it is returned unchanged.

sqr()[source]: The Cayley-Dickson construction/algebra. Returns the direct product of this Ring with itself, where multiplication is defined as: (a, b) * (c, d) = (ac - bd, ad + bc)

square_root_mapping()[source]: Return a dictionary where the keys are ring’s elements and the values are the ring elements’ square roots. Some elements may have no square roots, and some may have one or more square roots.

square_roots(elem_name)[source]: Return a list of the square roots of elem_name. If the list is empty, there are none.

sub(x, y): Group subtraction: Return x - y; i.e., x + inv(y).

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

subgroups(): Return a list of all subgroups, including trivial subgroups.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

trivial_subgroups(): Return the group’s two trivial subgroups.

unique_proper_subgroups(subgroups=None): Return a list of proper subgroups that are unique, up to isomorphism. If no subgroups are provided, then they will be derived.

units(return_names=True, verbose=False)[source]: Return a list of the Ring’s units.

units_subgroup(): Return the Unit Subgroup of this algebra. Makes sense for Monoids or Rings, where the multiplicative portion of the Ring is a Monoid. It will also work for Groups and Fields, but will return the entire Group or the entire multiplicative Group of a Field.

verify_regular_representation(elem_to_arr, arr_to_elem): Verifies that the regular representation satisfies the two requirements of it. This requires that the regular representation use dense matrices, NOT sparse matrices.

weak_inverses(): Returns a dictionary of weak inverses, where each key is one of the algebra’s elements and its value is a list of its weak inverses. If the algebra is regular, then there will be at least 1 weak inverse for each element. Otherwise, some elements may not have a weak inverse.

property zero: Another way to get the additive identity element

zero_divisor_pairs()[source]: Return a list of pairs of elements, neither one of which is zero, but whose product is zero.

zero_divisors()[source]: Return the Ring’s zero divisors. i.e., if neither a nor b are 0, but a*b == 0, then a and b are zero divisors.

Field

A Field is a Ring, where over the second operation it is also an abelian Group.

class finite_algebras.Field(name, description, elements, table, table2, check_inputs=True, mult_sub_grp=None, conjugate_mapping=None)[source]

Bases: Ring

A Field is a Ring, where the elements, minus the additive identity, form a commutative Group under multiplication.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_conjugates=False, show_generators=False): Print information about the Ring.

add(*args): Use the inherited group operator as the ring’s addition operator.

property add_identity: Returns the additive identity element

property add_table: Returns the CayleyTable for addition.

center(): Return the list of elements that commute with every element of the algebra. In Pinter’s book, chapter 5, exercise D3, the ‘center’ is defined for Groups, but the definition also works for any Magma.

center_algebra(verbose=False): Return the subalgebra that is the center of this algebra. If the center is part of a Semigroup, then (due to associativity) it will be closed wrt the Semigroup operation, and hence form a sub-semigroup, but the center of a Magma will not necessarily be closed. Note also that, if the algebra is commutative, then the entire algebra is its center.

closed_subsets_of_elements(divisors_only, include_inverses): Return all unique, closed, proper subsets of the algebra’s elements. This returns a list of lists. Each list represents the elements of a subalgebra. If divisors_only is True, then only subalgebras of orders that are divisors of self will be examined.

closure(subset_of_elements, include_inverses): Given a subset (in list form) of the group’s elements (name strings), return the smallest possible set of elements containing the subset that is closed under the algebra’s operation(s). If include_inverses is True and the algebra has inverses, then they will be added to the closure.

commutator(a, b): Return [a, b] = (a * b) - (b * a), the ring commutator of a & b

commutator_subalgebra(): Return the commutator subalgebra (Group, Ring, or Field) of this Group, Ring, or Field.

commutators(): Return the list of commutators of the group.

conj(elem): Given an element name, return the element name of its conjugate value.

conjugate(a, g): Return g * a * inv(g), the conjugate of a with respect to g

conjugates(): Return the dictionary that maps elements to their conjugate values. If it’s None, then the element is its own conjugate.

copy_algebra(new_elements=(), new_name=False, new_description=False): Creates a copy of the input algebra where, optionally, the existing element list can be replaced by a new element list. Same for the name & description. If there is a new element list, then it must be a list of strings and have the same length as the existing one.

create_inverse_lookup_dict(): Returns a dictionary that maps each of the algebra’s elements to its inverse element.

direct_product_delimiter(delimiter=None): If no input, then the current direct product element name delimiter will be returned (default is ‘:’). Otherwise, if a string is input (e.g., “-”) it will become the new delimiter for direct product element names, and then it will be returned.

div(x, y)[source]: Return x/y, if y is not the additive identity; otherwise return None.

dump(json_filename): Writes the algebra to the given filename in JSON format.

dumps(): Returns a JSON string that represents the algebra.

elem_conj(elem): For use only when making a Cayley-Dickson algebra.

element_map(): Instantiates an Element for each element name and returns a dictionary, where the element names are keys and corresponding Elements are the values. This method is used within the context manager, InfixNotation, to perform arithmetic using infix notation.

element_order(element) → int: Returns the order of the given element within the algebra.

element_pairs_where_product_equals(elem_name): Return all pairs of elements where the product is equal to elem_name.

element_pairs_where_sum_equals(elem_name): Return all pairs of elements where the sums are equal to elem_name. The ‘sum’ here refers to the binary operation of a Magma, Semigroup, Group, or to the additive binary operation of a Ring or Field.

element_to_power(elem, n, left_associative=True)[source]: Overrides the Ring method by the same name, so that we use don’t recreate the multiplicative Abelian subgroup already contained in the field.

property elements: Returns the algebra’s element names (list of strings).

extract_additive_algebra(): A Ring’s elements over addition, alone, should be a commutative Group. This function returns that Group.

extract_multiplicative_algebra(): A Ring’s elements over multiplication, alone, should be a Semigroup. This function returns that Semigroup.

generates(set_of_elems): Returns True if a set of one or more elements generates the algebra, otherwise False is returned.

generators(start_of_range=1): If the algebra is cyclic, then a list of individual elements that each generate the algebra is returned; otherwise, a list of lists of elements, is returned, where each sublist generates the algebra. This method looks for the smallest sets of elements that can generate the group. It stops looking once it finds all small sets of elements of a given size.

has_cancellation(verbose=False): Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_identity(): A convenience function that returns True or False, depending on whether the algebra has an identity element.

has_inverses(): Returns True if every element in the algebra has an inverse that is also in the algebra; returns False otherwise.

has_mult_identity(): A convenience function that returns True or False, depending on whether the algebra has a multiplicative identity element, in addition to its additive identity element.

property identity: Returns the algebra’s identity element if it exists; otherwise, it returns None.

inv(element): Return the inverse of an element

inverse_mapping(): Returns a dictionary that maps each element to its inverse.

is_abelian(): Returns True if the algebra is abelian; returns False otherwise.

is_associative(): Returns True if the algebra is associative; returns False otherwise.

is_commutative(): Returns True if the algebra is commutative; returns False otherwise.

is_cyclic(): Returns False if this algebra is not cyclic; otherwise a list of elements is returned, where each one can generate the entire algebra.

is_gaussian_prime(elem): This method only works for elements of Rings or Fields created by the function, ‘generate_algebra_mod_n’, or by a single application of the Ring method, ‘make_cayley_dickson_algebra’, to the output of ‘generate_algebra_mod_n’. That is, elements that look like 7 or 07:12.

is_isomorphic_mapping(other, mapping): Returns True if the input mapping from this algebra to the other algebra is isomorphic.

is_normal(subgrp): Returns True if the subgroup is normal, otherwise False is returned

is_regular(): Returns True if for all elements, a, there exists an element, x, such that axa=a. Otherwise, False is returned.

isomorphic(other): If there is a mapping from elements of this algebra to the other algebra’s elements, return it; otherwise return False.

left_cosets(subalgebra): Returns an iterator that returns lists of left cosets.

make_cayley_dickson_algebra(mu=None, version=1)

Constructs the Cayley-Dickson algebra using this Ring or Field.

Several different versions of multiplication are supported: version=1: (DEFAULT) No mu & no conjugation are used version=2: Definition in Schafer, 1966 version=3: Definition in Schafer, 1954 version=4: Definition in Baez, 2001.

See the documentation on readthedocs for more information regarding versions.

Versions 2 & 3 require a value for mu. If mu is None (the default), then mu will be automatically set to be the additive inverse of the Ring’s multiplicative identity element (i.e., “-1”) if it exists. If it does not exist, then an exception will be raised.

make_element_mappings(other): Returns a list of mappings (dictionaries) of this algebra’s elements to all possible permutations of other’s elements, where the identity of this algebra is always mapped to the identity of other.

property minus_one: Return the Ring’s ‘minus one’ element. That is, the additive inverse of its multiplicative identity element.

mult(*args): Ring multiplication, based on the second table.

mult_abelian_subgroup()[source]: Return the abelian Group defined by the Ring elements, minus the additive identity, under Ring multiplication.

property mult_identity: Returns the multiplicative identity element, if it exists. If it doesn’t exist, then None is returned.

mult_inv(element)[source]: Return the multiplicative inverse of ‘element’, unless it’s the additive identity element, in which case, return None.

mult_is_commutative(): By definition, Ring addition is commutative, but Ring multiplication only needs to be associative. This method tells us whether multiplication is commutative for this Ring.

property mult_table: Returns the CayleyTable for multiplication

norm(elem): Return the product of the input element and its conjugate.

property one: Another way to get the multiplicative identity element

property order: Returns the order of the algebra.

proper_subalgebras(divisors_only=True, include_inverses=True): Return a list of proper subalgebras of the algebra.

quotient_group(subgroup): Given a normal subgroup, return the quotient group of this group. The elements of the quotient group will be representative elements from cosets, prefixed with ‘~’.

regular_representation(sparse=''): Given a group, this function returns four things: (1) A dictionary that maps each group element to its corresponding regular representation, (2) A (reverse) dictionary that maps each regular representation (in the form of a tuple of tuples) back to its corresponding group element, (3) A function that maps a group element to its corresponding regular representation matrix, and (4) Another function that maps in the opposite direction, from regular representation matrix to group element. By default, the matrices are dense arrays. SciPy sparse arrays can be output instead, by setting the input variable, “sparse”, to one of the following seven strings: “BSR”, “COO”, “CSC”, “CSR”, “DIA”, “DOK”, or “LIL”. Each of the seven strings corresponds to one of the seven classes of sparse array supported by SciPy.

reorder_elements(reordered_elements): Return a new group made from this one with the elements reordered.

right_cosets(subalgebra): Returns an iterator that returns lists of right cosets.

scalar_mult(scalar_name, elem_name): Scalar multiplication. ‘a’ * ‘c:d’ = ‘a*c:a*d’ Example: scalar_mult(‘2’, ‘1:2’, F3) ==> ‘2:1’

split_element(element): If the element is a compound element created by a direct product or the Cayley-Dickson construction, then it contains at least one delimiter (e.g., ‘1:2’ or ‘1:2:3:4’). This method splits the element at the middle delimiter and returns the two pieces (e.g., ‘1’, ‘2’ or ‘1:2’, ‘3:4’). If the element is not a compound element, then it is returned unchanged.

sqr(): The Cayley-Dickson construction/algebra. Returns the direct product of this Ring with itself, where multiplication is defined as: (a, b) * (c, d) = (ac - bd, ad + bc)

square_root_mapping(): Return a dictionary where the keys are ring’s elements and the values are the ring elements’ square roots. Some elements may have no square roots, and some may have one or more square roots.

square_roots(elem_name): Return a list of the square roots of elem_name. If the list is empty, there are none.

sub(x, y): Group subtraction: Return x - y; i.e., x + inv(y).

subalgebra_from_elements(closed_subset_of_elements, name='No name', desc='No description'): Return the algebra constructed from the given closed subset of elements.

subgroups(): Return a list of all subgroups, including trivial subgroups.

property table: Returns the algebra’s Cayley Table (‘multiplication’ table).

to_dict(include_classname=False): Returns a dictionary that represents the algebra. The dictionary can be fed back into make_finite_algebra, and it will return a copy of this algebra.

trivial_subgroups(): Return the group’s two trivial subgroups.

unique_proper_subgroups(subgroups=None): Return a list of proper subgroups that are unique, up to isomorphism. If no subgroups are provided, then they will be derived.

units(return_names=True, verbose=False): Return a list of the Ring’s units.

units_subgroup(): Return the Unit Subgroup of this algebra. Makes sense for Monoids or Rings, where the multiplicative portion of the Ring is a Monoid. It will also work for Groups and Fields, but will return the entire Group or the entire multiplicative Group of a Field.

verify_regular_representation(elem_to_arr, arr_to_elem): Verifies that the regular representation satisfies the two requirements of it. This requires that the regular representation use dense matrices, NOT sparse matrices.

weak_inverses(): Returns a dictionary of weak inverses, where each key is one of the algebra’s elements and its value is a list of its weak inverses. If the algebra is regular, then there will be at least 1 weak inverse for each element. Otherwise, some elements may not have a weak inverse.

property zero: Another way to get the additive identity element

zero_divisor_pairs(): Return a list of pairs of elements, neither one of which is zero, but whose product is zero.

zero_divisors(): Return the Ring’s zero divisors. i.e., if neither a nor b are 0, but a*b == 0, then a and b are zero divisors.

Support for Infix Notation

The Element class, together with the context manager class, InfixNotation, provide a way to use infix operators (+, -, , /, *) on an algebra’s “elements”.

class finite_algebras.Element(name, algebra)[source]

Bases: object

Elements of the algebras here must be strings. This class turns a string element, along with its algebra, into an object with infix arithmetic operators, +, -, , /, *, etc.

property algebra: Return the algebra associated with this Element.

property name: Return the name of this Element.

class finite_algebras.InfixNotation(algebra)[source]

Bases: object

Creates a context manager for doing finite algebra calculations using infix notation.

>>> s3 = generate_symmetric_group(3)
>>> with InfixNotation(s3) as f:
>>>     print(f['(2, 1, 3)'] + f['(3, 2, 1)'])
(3, 1, 2)

FiniteCompositeAlgebra

This is the top-level class for all algebras that are constructed from two sets of elements, scalars and vectors (Modules, VectorSpaces). NOT INTENDED TO BE INSTANTIATED.

class finite_algebras.FiniteCompositeAlgebra(name: str, description: str)[source]

Bases: ABC

This class represents Finite Algebras that have more than one element list, such as VectorSpaces and Modules.

Module

A Module is an abelian Group of vectors, V, combined with a Ring of scalars, Re, and a binary operation, R x V -> V.

finite_algebras.module_sv_mult(ring)[source]: Returns a function that scales a vector. That is, a function that takes a scalar and a vector, and returns their product, also a vector.

finite_algebras.module_dot_product(ring, vec1, vec2)[source]: Returns a scalar (ring element) that represents the dot-product of the two input vectors.

class finite_algebras.Module(name, description, ring, group, operator)[source]

Bases: FiniteCompositeAlgebra

See https://abstract-algebra.readthedocs.io for the definition of a Module

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False)[source]: Print information about the Module or Vector Space.

vector_add(v1, v2)[source]: Return the sum of two vectors using the Group operation, op.

finite_algebras.check_module_conditions(ring: Ring, group: Group, sv_mult, verbose=False)[source]: Returns True if all four conditions required of a Module hold true, otherwise this function returns False.

NDimensionalModule

An NDimensionalModule is a Module constructed from a single Ring, where the Group is constructed by computing direct products of the Ring with itself.

class finite_algebras.NDimensionalModule(ring, n, check_input_conditions=True)[source]

Bases: Module

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Print information about the Module or Vector Space.

property dimensions: Returns the dimension of the Module’s vectors.

dot_product(u, v)[source]: Computes and returns the dot-product of two Module vectors.

property origin: Returns the origin element, a vector, of the Module.

vector_add(v1, v2): Return the sum of two vectors using the Group operation, op.

VectorSpace

A VectorSpace is an abelian Group of vectors, V, combined with a Field of scalars, S, and a binary operation, S x V -> V.

class finite_algebras.VectorSpace(name, description, field, group, operator)[source]

Bases: Module

See https://abstract-algebra.readthedocs.io for the definition of a VectorSpace.

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Print information about the Module or Vector Space.

vector_add(v1, v2): Return the sum of two vectors using the Group operation, op.

NDimensionalVectorSpace

An NDimensionalVectorSpace is a VectorSpace constructed from a single Field, where the Group is constructed by computing direct products of the Field with itself.

class finite_algebras.NDimensionalVectorSpace(field, n, check_input_conditions=True)[source]

Bases: VectorSpace

about(max_size=12, max_gens=2, use_table_names=False, show_tables=True, show_elements=True, show_generators=False): Print information about the Module or Vector Space.

property dimensions: Returns the dimension of the VectorSpace’s vectors.

dot_product(u, v)[source]: Computes and returns the dot-product of two VectorSpace vectors.

property origin: Returns the origin element, a vector, of the VectorSpace.

vector_add(v1, v2): Return the sum of two vectors using the Group operation, op.

Algebra Generators

finite_algebras.generate_cyclic_group(order, elem_name='', name=None, description=None, zfill=False)[source]: Generates a cyclic group with the given order. If zfill is True, then left fill element names with zeros.

finite_algebras.generate_symmetric_group(n, name=None, description=None, alternating=False)[source]: Generates a symmetric or alternating group on n elements.

finite_algebras.generate_powerset_group(n, name=None, description=None)[source]: Generates a group on the powerset of {0, 1, 2, …, n-1}, where symmetric difference is the operator.

finite_algebras.generate_relative_primes_group(n, name=None, description=None)[source]: Generates a group based on mult mod n of relatively-prime numbers < n. In keeping with the convention in this module, the elements are converted to strings.

finite_algebras.generate_commutative_monoid(order, elem_name='a', name=None, description=None)[source]: Generates a commutative monoid over {0,1,2,…,n-1}, where op(a,b) = (a * b) % n.

finite_algebras.generate_powerset_ring(n, name=None, description=None)[source]: Generates a ring on the powerset of {0, 1, 2, …, n-1}, where n is a positive integer, symmetric difference is the addition operator, and intersection is the multiplication operator.

finite_algebras.generate_algebra_mod_n(n, elem_name='', name=None, description=None)[source]: Generate a Ring (or Field) based on integer addition and multiplication modulo n. If n is prime, then result will be a Field, otherwise it will be a Ring.

finite_algebras.generate_nxn_matrix_algebra(ring, element_name_prefix='a')[source]: Generate a ring (or field) based on all possible 2x2 abstract matrices using elements from the input ring. For now, n is hardcoded to 2. Three items are returned: (1) the generated ring, (2) a dictionary of element names (keys) to matrices (values), and (3) a reverse dictionary of matrices (as tuples of tuples) to element names.

finite_algebras.generate_algebra_from_element_dict(gen_elem_dict, bin_op, elem_eq, make_key, make_elem_key, name='Whatever', description='Created from a set of generators', max_iter=100)[source]

Return an algebra, an element mapping, and iteration counter, given…

(1) gen_elem_dict: a dictionary of generator elements, where the keys are unique string names of the elements, and the values are the actual element objects (e.g., numbers, matrices, etc.),

bin_op: a binary operation that combines the two element values into a new value,
elem_eq: a binary operation that returns True if the two element values are equal,
make_key: a function that takes a generator element and returns an immutable object to be used as a dictionary key.
make_elem_name: a function of three arguments, where the first two arguments are assumed to be element keys (str), and the third is assumed to be an element that is the product of the elements corresponding to the two keys. The function must return a string that can be used as a key for the product.

This function uses bin_op to combine the input elements, and combinations of those, with each other, repeatedly, until no new elements are generated, and then returns the resulting finite algebra, assuming this happens before the max_iter number of iterations is reached.

The element mapping that is returned is the expanded set of elements generated from the initial input, gen_elem_dict.

The counter value returned is an int that represents the number of iterations required to compute the fully closed set of elements.

Cayley Table

class cayley_table.CayleyTable(arr)[source]

Here is the definition of a Cayley table in Wikipedia, edited to refer to finite algebras, in general, not just finite groups:

‘A Cayley table describes the structure of a finite algebra by arranging all the possible products of all [the algebra’s] elements in a square table reminiscent of an addition or multiplication table. Many properties of [an algebra] - such as whether or not it is abelian, which elements are inverses of which elements, [etc.] – can be discovered from its Cayley table.’ (https://en.wikipedia.org/wiki/Cayley_table)

The actual table, within a CayleyTable instance, is stored as a square NumPy array of int, where the integers correspond to the positions of elements in a list of element names (str).

Regarding the interpretation of a Cayley table, the row element is “multiplied” on the left and the column element on the right, e.g., row * col. Or, assuming functions written on the left, such as permutations, this means that the column element is applied first and the row element is applied next, e.g., row(col(x)).

about(printout=False)[source]: Printout information about the CayleyTable: order, associativity, commutativity, left/right identities, full identity, and whether inverses exist.

distributes_over(other, verbose=False)[source]: This method determines whether this CayleyTable distributes over an ‘other’, equal-sized CayleyTable. Think of ‘self’ as multiplication and ‘other’ as addition.

has_cancellation(verbose=False)[source]: Return True if, for every a & b in the algebra, there are unique x and y in the algebra such that ax=b and ya=b. Otherwise, return False. Set verbose to True to see intermediate calculations.

has_inverses()[source]: Returns True or False, depending on whether the table supports inverses for all elements.

identity()[source]: Returns the table’s identity element, if it exists, otherwise None is returned.

inverse_lookup_dict(identity, elements=None)[source]

is_associative()[source]: Returns True or False, depending on whether the table supports an associative binary operation.

is_commutative()[source]: Returns True or False, depending on whether the table supports a commutative binary operation.

left_identity()[source]: Returns the table’s left identity element, if it exists, otherwise None is returned.

property order: Returns the order of the table, e.g., a 3x3 table has order 3.

right_identity()[source]: Returns the table’s right identity element, if it exists, otherwise None is returned.

property table: Returns the table, i.e., NumPy array.

table_entries_where_equal_to(val)[source]: Return all (row, col) pairs where table entries equal val.

to_list_with_names(elements)[source]: Returns the Cayley Table as a regular Python array where the element indices have been replaces by the element names (str).

tolist()[source]: Converts the CayleyTable into a list of lists of ints.

type_of_algebra()[source]: Returns a string name of the algebra defined by the table.

Permutations

class permutations.Perm(mapping)[source]

A permutation is of size n is, essentially, a list or tuple containing the first n-1 non-negative integers. For example, (2, 0, 1, 3) or [0, 1, 2, 3], are permutations of size 4. All n-1 non-negative integers must be present, and no integers can be duplicated.

property is_even

property mapping: Returns the tuple that defines the permutation.

property parity: A convenience method. Returns the string ‘Even” or “Odd”, depending on whether the permutation is even or odd.

show()[source]: Just for testing. Prints the permutation, its size, and whether it is even (True or False).

property size: Returns the size of the permutation.

Abstract Matrix

class abstract_matrix.AbstractMatrix(array, ring)[source]

The abstract matrix class supports the creation of matrices composed of abstract Ring elements, along with operations such as addition, subtraction, multiplication, determinants, etc.

property algebra: Returns the ring, over which the abstract matrix is defined.

property array: Returns the abstract matrix’s numpy array.

cofactor_matrix()[source]: Returns the cofactor matrix of an abstract matrix

copy()[source]: Returns a copy of the abstract matrix.

determinant()[source]: Returns the determinant of a square abstract matrix.

classmethod identity(size, ring)[source]: Create and return an abstract identity matrix using the ring’s multiplicative identity element, if one exists; otherwise return None.

inverse()[source]: If the abstract matrix is defined over a field and the matrix’s determinant is equal to the field’s multiplicative identity, ‘1’, then this method returns the matrix’s inverse, otherwise it returns an inverse-like matrix that, when multiplied by the original matrix, yields a diagonal matrix (not necessarily an abstract identity matrix).

minor(i, j)[source]: Returns the i,j_th minor of the matrix

property ncols: Returns the number of columns of the abstract matrix

property nrows: Returns the number of rows of the abstract matrix

classmethod random(shape, ring)[source]: Creates and returns an abstract matrix containing randomly chosen ring elements.

property ring: Returns the ring, over which the abstract matrix is defined.

scalar_mult(scalar, left=True)[source]: Multiplies every element of an abstract matrix by a single element from the ring, over which the abstract matrix is defined. Default is left multiplication, i.e., scalar * self, otherwise right multiplication is used, i.e., self * scalar.

property shape: Returns the shape of the abstract matrix’s numpy array

to_tuple()[source]: Return the matrix’s array as a tuple of tuples. This is useful for making the array immutable, so that it can be used as a dictionary key.

transpose()[source]: Transposes the rows and columns of the abstract matrix

classmethod zeros(shape, ring)[source]: Creates and returns an abstract matrix filled with the ring’s zero element.

Examples

class finite_algebras.Examples(algebras_dir, filenames_json='examples.json')[source]

A convenience class for retrieving some example algebras in the “algebras” directory. To add or subtract algebras to its default list, see the file, ‘examples.json’, in the “algebras” directory.

about()[source]: Returns a list of example algebras with instructions on how to retrieve them.

Miscellaneous Functions and Utilities

The functions here are listed in alphabetical order by module and name

cayley_table.about_tables(list_of_cayley_tables)[source]: Prints out information about a list of CayleyTables.

finite_algebras._filter_out_conflicts(perms, perm, n)[source]: Filter out all permutations in perms that conflict with perm, and don’t have n as the first element.

finite_algebras._no_conflict(p1, p2)[source]: Returns True only if no element of p1 equals the corresponding element of p2.

finite_algebras._no_conflicts(items)[source]: Return True if each possible pair, from a list of items, has no conflicts.

finite_algebras.about_isomorphic_partition(alg, part)[source]: Print a summary of a particular partition of isomorphic subalgebras of an algebra.

finite_algebras.about_isomorphic_partitions(alg, partitions)[source]: Print a summary of the isomorphic partitions of an algebra.

finite_algebras.about_subalgebras(alg)[source]: A convenience function that finds and summarizes all proper subalgebras of the input FiniteAlgebra. The list of isomorphic partitions is returned and a summary of it is printed out.

finite_algebras.add_s(string, n)[source]: Make a string plural by adding an ‘s’ to it, or not, depending on ‘n’.

finite_algebras.are_n(n)[source]: A bit of grammar. This function returns a string with the appropriate singular or plural present indicative form of ‘to be’, along with ‘n’.

finite_algebras.check_associativity(ring, group, sv_mult, verbose=False)[source]: Return True if the special associativity condition on scalars and vectors holds true, otherwise return False.

finite_algebras.check_dist_of_scalars_over_vec_add(ring, group, sv_mult, verbose=False)[source]: Returns True if distributivity of scalars over vector addition holds true in all cases, otherwise False is Returned.

finite_algebras.check_dist_of_vec_over_scalar_add(ring, group, sv_mult, verbose=False)[source]: Returns True if distributivity of vectors over scalar addition holds true in all cases, otherwise False is Returned.

finite_algebras.check_module_conditions(ring: Ring, group: Group, sv_mult, verbose=False)[source]: Returns True if all four conditions required of a Module hold true, otherwise this function returns False.

finite_algebras.check_scaling_by_one(ring, group, sv_mult, verbose=False)[source]: Returns True if scaling by one holds true in all cases, otherwise False is Returned.

finite_algebras.delete_row_col(np_arr, row, col)[source]: Removes the specified row and col from a Numpy array. A new np array is returned, so this does not affect the input array.

finite_algebras.find_isomorphic_subalgebra(algebra, partitions)[source]: Given an algebra and the partitions output by the method about_subalgebras that was applied to a different algebra, find an algebra in the partitions that is isomorphic to the given algebra, if one exists. If one is found, return the isomorphism (dict) along with the algebra found in the partition. Otherwise, return False.

finite_algebras.get_duplicates(lst)[source]: Return a list of the duplicate items in the input list.

finite_algebras.get_int_forms(ref_group, isomorphisms)[source]: Return a list of integer forms (‘permutations’) for a list of isomorphisms, i.e., mappings, based on a reference group.

finite_algebras.get_integer_form(elem_list)[source]: For an element list like [‘e1’, ‘a1_2’, ‘a1_1’, ‘a1_3’], return the integer 213, i.e., the ‘subscripts’ of the elements that follow the identity element. Used by get_int_forms.

finite_algebras.index_table_from_name_table(elements, name_table)[source]: Converts a table (list of lists) of strings into a table (list of lists) of ints.

finite_algebras.is_field(add_id, elements, table)[source]: The elements of a Field, minus the additive identity, form a commutative Group under multiplication. This function takes the additive identity, the list of all elements, and a field’s multiplication table as input, and returns the Group under multiplication, if it exists, otherwise it returns False. If the proposed Field inputs are trivial (only one element and a 1x1 table) then False is returned. That is, a trivial Field is not allowed.

finite_algebras.is_table_associative(table)[source]: Determine whether the table supports an associative operation.

finite_algebras.make_cayley_table(table, elements)[source]: Return a CayleyTable from a table of indices or a table of strings.

finite_algebras.make_table_from_xml(table_string)[source]

This function helps turn the XML-based tables at https://groupprops.subwiki.org/wiki/Main_Page into a list of lists for use here.

Instructions for use: 1. Copy the table from there and paste it here; 2. Find & Replace the strings, “<row>” and “</row>”, with nothing; 3. Place triple quotes around the result and give it a variable name; 4. Then run make_table on the variable.

Parameters:: table_string (str) – XML-based table at https://groupprops.subwiki.org/wiki/Main_Page
Returns:: A list of lists of ints, representing a group’s multiplication table.
Return type:: list

finite_algebras.module_dot_product(ring, vec1, vec2)[source]: Returns a scalar (ring element) that represents the dot-product of the two input vectors.

finite_algebras.module_sv_mult(ring)[source]: Returns a function that scales a vector. That is, a function that takes a scalar and a vector, and returns their product, also a vector.

finite_algebras.np_arr_to_tuple(arr: ndarray) → tuple[source]

Convert a 2d numpy array into a tuple of tuples to use as a dictionary key.

EXAMPLE: This function is the ‘make_key’ input to ‘generate_algebra_from_element_dict’.

finite_algebras.partition_into_isomorphic_lists(list_of_groups)[source]: Partition the list of groups into sub-lists of groups that are isomorphic to each other. The purpose of this function is to operate on the proper subgroups of a group to determine the unique subgroups, up to isomorphism.

finite_algebras.powerset(iterable)[source]: Returns the powerset of the input iterable. e.g., powerset([1,2,3]) –> () (1,) (2,) (3,) (1,2) (1,3) (2,3) (1,2,3)

finite_algebras.same_lists_of_lists(list_of_lists1, list_of_lists2)[source]: Handy for determining, for example, whether a list of left cosets is the same as a list of right cosets.

finite_algebras.symm_diff_of_two_lists_of_lists(list1, list2)[source]: Return the symmetric difference between two lists of lists

finite_algebras.tables_to_groups(tables, identity_name='e', elem_name='a')[source]: Given a list of multiplication tables, all the same size, turn them into a list of groups.

finite_algebras.unpack_components(finalg)[source]: A convenience function. It unpacks a FiniteAlgebra and returns its components: name, description, elements, and table(s) (in list form).

finite_algebras.yes_or_no(true_or_false)[source]: A convenience function for turning True or False into Yes or No, respectively.

my_math.divisors(n, non_trivial=True)[source]: Returns a list divisors of n. If non_trivial is True, don’t include 1 and n, which is slightly different from sympy’s divisors function.

my_math.is_relatively_prime(n, m)[source]: Return True if n & m are relatively prime, otherwise return False.

my_math.relative_primes(n)[source]: Return the list of relative primes that are less than n.

my_math.totient(n)[source]: Return the number of relative primes less than n. The same function exists in SymPy.

my_math.xgcd(alpha, beta)[source]

The extended Euclidean algorithm.

Returns gcd, x, & y, such that gcd = a * x + b * y, where gcd is the Greatest Common Divisor of a & b. x & y are called Bézout’s coefficients.