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 – 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 – 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

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)                                                                # needs sage.symbolic
e^(I*arg(1.00000000000000 + 2.00000000000000*I))

Python

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

Sage Live

from sage.groups.misc_gps.argument_groups import ArgumentByElementGroup
C = ArgumentByElementGroup(CC); C
C(1 + 2*I)                                                                # needs sage.symbolic

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 – 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

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

sage: ArgumentGroup('UU')                                                       # needs sage.rings.number_field
Group of Roots of Unity

sage: # needs sage.rings.number_field
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)                                                         # needs sage.rings.number_field
Sign Group
sage: ArgumentGroup('Arg_RR')                                                   # needs sage.rings.number_field
Sign Group
sage: ArgumentGroup(RIF)                                                        # needs sage.rings.real_interval_field
Sign Group
sage: ArgumentGroup(RBF)
Sign Group

sage: ArgumentGroup(CC)                                                         # needs sage.rings.number_field
Unit Circle Group with Exponents in
Real Field with 53 bits of precision modulo ZZ
sage: ArgumentGroup('Arg_CC')                                                   # needs sage.rings.number_field
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))                                         # needs sage.rings.number_field
Unit Circle Group with Argument of Elements in
Cyclotomic Field of order 3 and degree 2

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import ArgumentGroup

>>> ArgumentGroup('UU')                                                       # needs sage.rings.number_field
Group of Roots of Unity

>>> # needs sage.rings.number_field
>>> ArgumentGroup(ZZ)
Sign Group
>>> ArgumentGroup(QQ)
Sign Group
>>> ArgumentGroup('UU_QQ')
Group of Roots of Unity
>>> ArgumentGroup(AA)
Sign Group

>>> ArgumentGroup(RR)                                                         # needs sage.rings.number_field
Sign Group
>>> ArgumentGroup('Arg_RR')                                                   # needs sage.rings.number_field
Sign Group
>>> ArgumentGroup(RIF)                                                        # needs sage.rings.real_interval_field
Sign Group
>>> ArgumentGroup(RBF)
Sign Group

>>> ArgumentGroup(CC)                                                         # needs sage.rings.number_field
Unit Circle Group with Exponents in
Real Field with 53 bits of precision modulo ZZ
>>> ArgumentGroup('Arg_CC')                                                   # needs sage.rings.number_field
Unit Circle Group with Exponents in
Real Field with 53 bits of precision modulo ZZ
>>> ArgumentGroup(CIF)
Unit Circle Group with Exponents in
Real Interval Field with 53 bits of precision modulo ZZ
>>> ArgumentGroup(CBF)
Unit Circle Group with Exponents in
Real ball field with 53 bits of precision modulo ZZ

>>> ArgumentGroup(CyclotomicField(Integer(3)))                                         # needs sage.rings.number_field
Unit Circle Group with Argument of Elements in
Cyclotomic Field of order 3 and degree 2

Sage Live

from sage.groups.misc_gps.argument_groups import ArgumentGroup
ArgumentGroup('UU')                                                       # needs sage.rings.number_field
# needs sage.rings.number_field
ArgumentGroup(ZZ)
ArgumentGroup(QQ)
ArgumentGroup('UU_QQ')
ArgumentGroup(AA)
ArgumentGroup(RR)                                                         # needs sage.rings.number_field
ArgumentGroup('Arg_RR')                                                   # needs sage.rings.number_field
ArgumentGroup(RIF)                                                        # needs sage.rings.real_interval_field
ArgumentGroup(RBF)
ArgumentGroup(CC)                                                         # needs sage.rings.number_field
ArgumentGroup('Arg_CC')                                                   # needs sage.rings.number_field
ArgumentGroup(CIF)
ArgumentGroup(CBF)
ArgumentGroup(CyclotomicField(3))                                         # needs sage.rings.number_field

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

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

Python

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

Sage Live

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

exponent_numerator()

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

EXAMPLES:

Sage

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

Python

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

Sage Live

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

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

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

Python

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

Sage Live

from sage.groups.misc_gps.argument_groups import RootsOfUnityGroup
U = RootsOfUnityGroup(); U
U(exponent=1/4)

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 – boolean (default: True)

is_minus_one()

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

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import SignGroup
>>> S = SignGroup()
>>> S(Integer(1)).is_minus_one()
False
>>> S(-Integer(1)).is_minus_one()
True

Sage Live

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

is_one()

Return whether this sign is \(1\).

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import SignGroup
>>> S = SignGroup()
>>> S(-Integer(1)).is_one()
False
>>> S(Integer(1)).is_one()
True

Sage Live

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

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

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

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import SignGroup
>>> S = SignGroup(); S
Sign Group
>>> S(-Integer(1))
-1

Sage Live

from sage.groups.misc_gps.argument_groups import SignGroup
S = SignGroup(); S
S(-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

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)

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import UnitCircleGroup

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

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

Sage Live

from sage.groups.misc_gps.argument_groups import UnitCircleGroup
R = UnitCircleGroup(RR); R
R(exponent=2.42)
Q = UnitCircleGroup(QQ); Q
Q(exponent=6/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 – boolean (default: True)

property exponent

The exponent of this point on the unit circle.

EXAMPLES:

Sage

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

Python

>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import UnitCircleGroup
>>> C = UnitCircleGroup(RR)
>>> C(exponent=Integer(4)/Integer(3)).exponent
0.333333333333333

Sage Live

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

is_minus_one()

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

EXAMPLES:

Sage

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

Python

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

Sage Live

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

is_one()

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

EXAMPLES:

Sage

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

Python

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

Sage Live

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

Make live