Groups of elements representing (complex) arguments.#

This includes

RootsOfUnityGroup (containing all roots of unity)
UnitCircleGroup (representing elements on the unit circle by \(e^{2\pi\cdot\mathit{exponent}}\))
ArgumentByElementGroup (whose elements are defined via formal arguments by \(e^{I\cdot\mathrm{arg}(\mathit{element})}\).

Use the factory ArgumentGroup for creating such a group conveniently.

Note

One main purpose of such groups is in an asymptotic ring's growth group when an element like \(z^n\) (for some constant \(z\)) is split into \(\lvert z \rvert^n \cdot e^{I\cdot \mathrm{arg}(z) n}\). (Note that the first factor determines the growth of that product, the second does not influence the growth.)

AUTHORS:

Daniel Krenn (2018)

Classes and Methods#

class sage.groups.misc_gps.argument_groups.AbstractArgument(parent, element, normalize=True)#

Bases: MultiplicativeGroupElement

An element of AbstractArgumentGroup. This abstract class encapsulates an element of the parent’s base, i.e. it can be seen as a wrapper class.

INPUT:

parent – a SageMath parent
element – an element of parent’s base
normalize – a boolean (default: True)

class sage.groups.misc_gps.argument_groups.AbstractArgumentGroup(base, category)#

Bases: UniqueRepresentation, Parent

A group whose elements represent (complex) arguments.

INPUT:

base – a SageMath parent
category – a category

Element#: alias of AbstractArgument

class sage.groups.misc_gps.argument_groups.ArgumentByElement(parent, element, normalize=True)#

Bases: AbstractArgument

An element of ArgumentByElementGroup.

INPUT:

parent – a SageMath parent
element – a nonzero element of the parent’s base
normalize – a boolean (default: True)

class sage.groups.misc_gps.argument_groups.ArgumentByElementGroup(base, category)#

Bases: AbstractArgumentGroup

A group of (complex) arguments. The arguments are represented by a the formal argument of an element, i.e., by \(\mathrm{arg}(\mathit{element})\).

INPUT:

base – a SageMath parent representing a subset of the complex plane
category – a category

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import ArgumentByElementGroup
sage: C = ArgumentByElementGroup(CC); C
Unit Circle Group with Argument of Elements in
Complex Field with 53 bits of precision
sage: C(1 + 2*I)
e^(I*arg(1.00000000000000 + 2.00000000000000*I))

Element#: alias of ArgumentByElement

sage.groups.misc_gps.argument_groups.ArgumentGroup = <sage.groups.misc_gps.argument_groups.ArgumentGroupFactory object>#

A factory for argument groups.

This is an instance of ArgumentGroupFactory whose documentation provides more details.

class sage.groups.misc_gps.argument_groups.ArgumentGroupFactory#

Bases: UniqueFactory

A factory for creating argument groups.

INPUT:

data – an object

The factory will analyze data and interpret it as specification or domain.
specification – a string

The following is possible:
- 'Signs' give the SignGroup
- 'UU' give the RootsOfUnityGroup
- 'UU_P', where 'P' is a string representing a SageMath parent which is interpreted as exponents
- 'Arg_P', where 'P' is a string representing a SageMath parent which is interpreted as domain
domain – a SageMath parent representing a subset of the complex plane. An instance of ArgumentByElementGroup will be created with the given domain.
exponents – a SageMath parent representing a subset of the reals. An instance of :class`UnitCircleGroup` will be created with the given exponents

Exactly one of data, specification, exponents has to be provided.

Further keyword parameters will be carried on to the initialization of the group.

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import ArgumentGroup

sage: ArgumentGroup('UU')
Group of Roots of Unity

sage: ArgumentGroup(ZZ)
Sign Group
sage: ArgumentGroup(QQ)
Sign Group
sage: ArgumentGroup('UU_QQ')
Group of Roots of Unity
sage: ArgumentGroup(AA)
Sign Group

sage: ArgumentGroup(RR)
Sign Group
sage: ArgumentGroup('Arg_RR')
Sign Group
sage: ArgumentGroup(RIF)
Sign Group
sage: ArgumentGroup(RBF)
Sign Group

sage: ArgumentGroup(CC)
Unit Circle Group with Exponents in
Real Field with 53 bits of precision modulo ZZ
sage: ArgumentGroup('Arg_CC')
Unit Circle Group with Exponents in
Real Field with 53 bits of precision modulo ZZ
sage: ArgumentGroup(CIF)
Unit Circle Group with Exponents in
Real Interval Field with 53 bits of precision modulo ZZ
sage: ArgumentGroup(CBF)
Unit Circle Group with Exponents in
Real ball field with 53 bits of precision modulo ZZ

sage: ArgumentGroup(CyclotomicField(3))
Unit Circle Group with Argument of Elements in
Cyclotomic Field of order 3 and degree 2

create_key_and_extra_args(data=None, specification=None, domain=None, exponents=None, **kwds)#

Normalize the input.

See ArgumentGroupFactory for a description and examples.

create_object(version, key, **kwds)#: Create an object from the given arguments.

class sage.groups.misc_gps.argument_groups.RootOfUnity(parent, element, normalize=True)#

Bases: UnitCirclePoint

A root of unity (i.e. an element of RootsOfUnityGroup) which is \(e^{2\pi\cdot\mathit{exponent}}\) for a rational exponent.

exponent_denominator()#

Return the denominator of the rational quotient in \([0,1)\) representing the exponent of this root of unity.

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import RootsOfUnityGroup
sage: U = RootsOfUnityGroup()
sage: a = U(exponent=2/3); a
zeta3^2
sage: a.exponent_denominator()
3

exponent_numerator()#

Return the numerator of the rational quotient in \([0,1)\) representing the exponent of this root of unity.

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import RootsOfUnityGroup
sage: U = RootsOfUnityGroup()
sage: a = U(exponent=2/3); a
zeta3^2
sage: a.exponent_numerator()
2

class sage.groups.misc_gps.argument_groups.RootsOfUnityGroup(category)#

Bases: UnitCircleGroup

The group of all roots of unity.

INPUT:

category – a category

This is a specialized UnitCircleGroup with base \(\QQ\).

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import RootsOfUnityGroup
sage: U = RootsOfUnityGroup(); U
Group of Roots of Unity
sage: U(exponent=1/4)
I

Element#: alias of RootOfUnity

class sage.groups.misc_gps.argument_groups.Sign(parent, element, normalize=True)#

Bases: AbstractArgument

An element of SignGroup.

INPUT:

parent – a SageMath parent
element – a nonzero element of the parent’s base
normalize – a boolean (default: True)

is_minus_one()#

Return whether this sign is \(-1\).

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import SignGroup
sage: S = SignGroup()
sage: S(1).is_minus_one()
False
sage: S(-1).is_minus_one()
True

is_one()#

Return whether this sign is \(1\).

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import SignGroup
sage: S = SignGroup()
sage: S(-1).is_one()
False
sage: S(1).is_one()
True

class sage.groups.misc_gps.argument_groups.SignGroup(category)#

Bases: AbstractArgumentGroup

A group of the signs \(-1\) and \(1\).

INPUT:

category – a category

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import SignGroup
sage: S = SignGroup(); S
Sign Group
sage: S(-1)
-1

Element#: alias of Sign

class sage.groups.misc_gps.argument_groups.UnitCircleGroup(base, category)#

Bases: AbstractArgumentGroup

A group of points on the unit circle. These points are represented by \(e^{2\pi\cdot\mathit{exponent}}\).

INPUT:

base – a SageMath parent representing a subset of the reals
category – a category

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import UnitCircleGroup

sage: R = UnitCircleGroup(RR); R
Unit Circle Group with Exponents in Real Field with 53 bits of precision modulo ZZ
sage: R(exponent=2.42)
e^(2*pi*0.420000000000000)

sage: Q = UnitCircleGroup(QQ); Q
Unit Circle Group with Exponents in Rational Field modulo ZZ
sage: Q(exponent=6/5)
e^(2*pi*1/5)

Element#: alias of UnitCirclePoint

class sage.groups.misc_gps.argument_groups.UnitCirclePoint(parent, element, normalize=True)#

Bases: AbstractArgument

An element of UnitCircleGroup which is \(e^{2\pi\cdot\mathit{exponent}}\).

INPUT:

parent – a SageMath parent
exponent – a number (of a subset of the reals)
normalize – a boolean (default: True)

property exponent#

The exponent of this point on the unit circle.

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import UnitCircleGroup
sage: C = UnitCircleGroup(RR)
sage: C(exponent=4/3).exponent
0.333333333333333

is_minus_one()#

Return whether this point on the unit circle is \(-1\).

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import UnitCircleGroup
sage: C = UnitCircleGroup(QQ)
sage: C(exponent=0).is_minus_one()
False
sage: C(exponent=1/2).is_minus_one()
True
sage: C(exponent=2/3).is_minus_one()
False

is_one()#

Return whether this point on the unit circle is \(1\).

EXAMPLES:

sage: from sage.groups.misc_gps.argument_groups import UnitCircleGroup
sage: C = UnitCircleGroup(QQ)
sage: C(exponent=0).is_one()
True
sage: C(exponent=1/2).is_one()
False
sage: C(exponent=2/3).is_one()
False
sage: C(exponent=42).is_one()
True