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)

Bases: sage.structure.element.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: sage.structure.unique_representation.UniqueRepresentation, sage.structure.parent.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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: sage.structure.factory.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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: sage.groups.misc_gps.argument_groups.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)
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