Often, one ends up with a set that forms an Abelian group. It would be nice if one could return an Abelian group class to encapsulate the data. However, AbelianGroup() is an abstract Abelian group defined by generators and relations. This module implements AbelianGroupWithValues that allows the group elements to be decorated with values.
An example where this module is used is the unit group of a number field, see sage.rings.number_field.unit_group. The units form a finitely generated Abelian group. We can think of the elements either as abstract Abelian group elements or as particular numbers in the number field. The AbelianGroupWithValues() keeps track of these associated values.
Warning
Really, this requires a group homomorphism from the abstract Abelian group to the set of values. This is only checked if you pass the check=True option to AbelianGroupWithValues().
EXAMPLES:
Here is with value
assigned to the generator:
sage: Z6 = AbelianGroupWithValues([-1], [6], names='g')
sage: g = Z6.gen(0)
sage: g.value()
-1
sage: g*g
g^2
sage: (g*g).value()
1
sage: for i in range(7):
... print i, g^i, (g^i).value()
0 1 1
1 g -1
2 g^2 1
3 g^3 -1
4 g^4 1
5 g^5 -1
6 1 1
The elements come with a coercion embedding into the values_group(), so you can use the group elements instead of the values:
sage: CF3.<zeta> = CyclotomicField(3)
sage: Z3.<g> = AbelianGroupWithValues([zeta], [3])
sage: Z3.values_group()
Cyclotomic Field of order 3 and degree 2
sage: g.value()
zeta
sage: CF3(g)
zeta
sage: g + zeta
2*zeta
sage: zeta + g
2*zeta
Construct an Abelian group with values associated to the generators.
INPUT:
values – a list/tuple/iterable of values that you want to associate to the generators.
from gens_orders.
, typically written in increasing
order. This list is padded with zeros if it has length less
than n. The orders of the commuting generators, with
denoting an infinite cyclic factor.
names – (optional) names of generators
values_group – a parent or None (default). The common parent of the values. This might be a group, but can also just contain the values. For example, if the values are units in a ring then the values_group would be the whole ring. If None it will be derived from the values.
EXAMPLES:
sage: G = AbelianGroupWithValues([-1], [6])
sage: g = G.gen(0)
sage: for i in range(7):
... print i, g^i, (g^i).value()
0 1 1
1 f -1
2 f^2 1
3 f^3 -1
4 f^4 1
5 f^5 -1
6 1 1
sage: G.values_group()
Integer Ring
The group elements come with a coercion embedding into the values_group(), so you can use them like their value()
sage: G.values_embedding()
Generic morphism:
From: Multiplicative Abelian group isomorphic to C6
To: Integer Ring
sage: g.value()
-1
sage: 0 + g
-1
sage: 1 + 2*g
-1
Bases: sage.groups.abelian_gps.abelian_group_element.AbelianGroupElement
An element of an Abelian group with values assigned to generators.
INPUT:
EXAMPLES:
sage: F = AbelianGroupWithValues([1,-1], [2,4])
sage: a,b = F.gens()
sage: TestSuite(a*b).run()
Return the inverse element.
EXAMPLE:
sage: G.<a,b> = AbelianGroupWithValues([2,-1], [0,4])
sage: a.inverse()
a^-1
sage: a.inverse().value()
1/2
sage: a.__invert__().value()
1/2
sage: (~a).value()
1/2
sage: (a*b).value()
-2
sage: (a*b).inverse().value()
-1/2
Return the value of the group element.
OUTPUT:
The value according to the values for generators, see gens_values().
EXAMPLES:
sage: G = AbelianGroupWithValues([5], 1)
sage: G.0.value()
5
Bases: sage.categories.morphism.Morphism
The morphism embedding the Abelian group with values in its values group.
INPUT:
EXAMPLES:
sage: Z4.<g> = AbelianGroupWithValues([I], [4])
sage: embedding = Z4.values_embedding(); embedding
Generic morphism:
From: Multiplicative Abelian group isomorphic to C4
To: Symbolic Ring
sage: embedding(1)
1
sage: embedding(g)
I
sage: embedding(g^2)
-1
Bases: sage.groups.abelian_gps.abelian_group.AbelianGroup_class
The class of an Abelian group with values associated to the generator.
INPUT:
EXAMPLES:
sage: G.<a,b> = AbelianGroupWithValues([2,-1], [0,4])
sage: TestSuite(G).run()
alias of AbelianGroupWithValuesElement
The -th generator of the abelian group.
INPUT:
OUTPUT:
A group element.
EXAMPLES:
sage: F = AbelianGroupWithValues([1,2,3,4,5], 5,[],names='a')
sage: F.0
a0
sage: F.0.value()
1
sage: F.2
a2
sage: F.2.value()
3
sage: G = AbelianGroupWithValues([-1,0,1], [2,1,3])
sage: G.gens()
(f0, 1, f2)
Return the values associated to the generators.
OUTPUT:
A tuple.
EXAMPLES:
sage: G = AbelianGroupWithValues([-1,0,1], [2,1,3])
sage: G.gens()
(f0, 1, f2)
sage: G.gens_values()
(-1, 0, 1)
Return the embedding of self in values_group().
OUTPUT:
A morphism.
EXAMPLES:
sage: Z4 = AbelianGroupWithValues([I], [4])
sage: Z4.values_embedding()
Generic morphism:
From: Multiplicative Abelian group isomorphic to C4
To: Symbolic Ring
The common parent of the values.
The values need to form a multiplicative group, but can be embedded in a larger structure. For example, if the values are units in a ring then the values_group() would be the whole ring.
OUTPUT:
The common parent of the values, containing the group generated by all values.
EXAMPLES:
sage: G = AbelianGroupWithValues([-1,0,1], [2,1,3])
sage: G.values_group()
Integer Ring
sage: Z4 = AbelianGroupWithValues([I], [4])
sage: Z4.values_group()
Symbolic Ring