Groups of elements representing (complex) arguments.

This includes

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)[source]

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)[source]

Bases: UniqueRepresentation, Parent

A group whose elements represent (complex) arguments.

INPUT:

  • base – a SageMath parent

  • category – a category

Element[source]

alias of AbstractArgument

class sage.groups.misc_gps.argument_groups.ArgumentByElement(parent, element, normalize=True)[source]

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)[source]

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

alias of ArgumentByElement

sage.groups.misc_gps.argument_groups.ArgumentGroup = <sage.groups.misc_gps.argument_groups.ArgumentGroupFactory object>[source]

A factory for argument groups.

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

class sage.groups.misc_gps.argument_groups.ArgumentGroupFactory[source]

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: 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
>>> 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
create_key_and_extra_args(data=None, specification=None, domain=None, exponents=None, **kwds)[source]

Normalize the input.

See ArgumentGroupFactory for a description and examples.

create_object(version, key, **kwds)[source]

Create an object from the given arguments.

class sage.groups.misc_gps.argument_groups.RootOfUnity(parent, element, normalize=True)[source]

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()[source]

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
>>> 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
exponent_numerator()[source]

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
>>> 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
class sage.groups.misc_gps.argument_groups.RootsOfUnityGroup(category)[source]

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
>>> 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
Element[source]

alias of RootOfUnity

class sage.groups.misc_gps.argument_groups.Sign(parent, element, normalize=True)[source]

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()[source]

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
>>> 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
is_one()[source]

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
>>> 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
class sage.groups.misc_gps.argument_groups.SignGroup(category)[source]

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
>>> from sage.all import *
>>> from sage.groups.misc_gps.argument_groups import SignGroup
>>> S = SignGroup(); S
Sign Group
>>> S(-Integer(1))
-1
Element[source]

alias of Sign

class sage.groups.misc_gps.argument_groups.UnitCircleGroup(base, category)[source]

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)
>>> 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)
Element[source]

alias of UnitCirclePoint

class sage.groups.misc_gps.argument_groups.UnitCirclePoint(parent, element, normalize=True)[source]

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: from sage.groups.misc_gps.argument_groups import UnitCircleGroup
sage: C = UnitCircleGroup(RR)
sage: C(exponent=4/3).exponent
0.333333333333333
>>> 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
is_minus_one()[source]

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
>>> 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
is_one()[source]

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