11.2 Base class for parent objects with generators

Module: sage.structure.parent_gens

Base class for parent objects with generators.

Many parent objects in SAGE are equipped with generators, which are special elements of the object. For example, the polynomial ring $\mathbf{Z}[x,y,z]$ is generated by , , and . In SAGE the th generator of an object X is obtained using the notation X.gen(i). From the SAGE interactive prompt, the shorthand notation X.i is also allowed.

REQUIRED: A class that derives from ParentWithGens must define the ngens() and gen(i) methods.

OPTIONAL: It is also good if they define gens() to return all gens, but this is not necessary.

The gens function returns a tuple of all generators, the ngens function returns the number of generators.

The _assign_names functions is for internal use only, and is called when objects are created to set the generator names. It can only be called once.

The following examples illustrate these functions in the context of multivariate polynomial rings and free modules.

sage: R = PolynomialRing(ZZ, 3, 'x')
sage: R.ngens()
3
sage: R.gen(0)
x0
sage: R.gens()
(x0, x1, x2)
sage: R.variable_names()
('x0', 'x1', 'x2')

This example illustrates generators for a free module over $\mathbf{Z}$ .

sage: M = FreeModule(ZZ, 4)
sage: M
Ambient free module of rank 4 over the principal ideal domain Integer Ring
sage: M.ngens()
4
sage: M.gen(0)
(1, 0, 0, 0)
sage: M.gens()
((1, 0, 0, 0), (0, 1, 0, 0), (0, 0, 1, 0), (0, 0, 0, 1))

Module-level Functions

is_ParentWithAdditiveAbelianGens( )

Return True if x is a parent object with additive abelian generators, i.e., derives from sage.structure.parent.ParentWithAdditiveAbelianGens and False otherwise.

sage: is_ParentWithAdditiveAbelianGens(QQ)
False
sage: is_ParentWithAdditiveAbelianGens(QQ^3)
True

is_ParentWithGens( )

Return True if x is a parent object with generators, i.e., derives from sage.structure.parent.ParentWithGens and False otherwise.

sage: is_ParentWithGens(QQ['x'])
True
sage: is_ParentWithGens(CC)
True
sage: is_ParentWithGens(Primes())
False

is_ParentWithMultiplicativeAbelianGens( )

Return True if x is a parent object with additive abelian generators, i.e., derives from sage.structure.parent.ParentWithMultiplicativeAbelianGens and False otherwise.

sage: is_ParentWithMultiplicativeAbelianGens(QQ)
False
sage: is_ParentWithMultiplicativeAbelianGens(DirichletGroup(11))
True

normalize_names( )

Class: localvars

class localvars

Context manager for safely temporarily changing the variables names of an object with generators.

Objects with named generators are globally unique in SAGE. Sometimes, though, it is very useful to be able to temporarily display the generators differently. The new Python "with" statement and the localvars context manager make this easy and safe (and fun!)

Suppose X is any object with generators. Write

        with localvars(X, names[, latex_names] [,normalize=False]):
             some code
             ...

and the indented code will be run as if the names in X are changed to the new names. If you give normalize=True, then the names are assumed to be a tuple of the correct number of strings.

If you're writing Python library code, you currently have to put from __future__ import with_statement in your file in order to use the with statement. This restriction will disappear in Python 2.6.

sage: R.<x,y> = PolynomialRing(QQ,2)
sage: with localvars(R, 'z,w'):
...       print x^3 + y^3 - x*y
...
z^3 + w^3 - z*w

NOTES: I wrote this because it was needed to print elements of the quotient of a ring R by an ideal I using the print function for elements of R. See the code in quotient_ring_element.pyx.

Author: William Stein (2006-10-31)

Special Functions: __enter__, $\,$ __exit__, $\,$ __init__

__enter__( )

__exit__( )

__init__( )

Class: ParentWithAdditiveAbelianGens

class ParentWithAdditiveAbelianGens

Functions: generator_orders

Special Functions: __iter__

__iter__( ): Return an iterator over the elements in this object.

Class: ParentWithGens

class ParentWithGens

Functions: gen, $\,$ gens, $\,$ gens_dict, $\,$ hom, $\,$ ngens

gens( ): Return a tuple whose entries are the generators for this object, in order.

gens_dict( ): Return a dictionary whose entries are var_name:variable,....

hom( )

Return the unique homomorphism from self to codomain that sends self.gens() to the entries of im_gens. Raises a TypeError if there is no such homomorphism.

Input:

im_gens: - the images in the codomain of the generators of this object under the homomorphism
codomain: - the codomain of the homomorphism
check: - whether to verify that the images of generators extend to define a map (using only canonical coercisions).

Output: a homomorphism self -> codomain

Note: As a shortcut, one can also give an object X instead of im_gens, in which case return the (if it exists) natural map to X.

Polynomial Ring We first illustrate construction of a few homomorphisms involving a polynomial ring.

sage: R.<x> = PolynomialRing(ZZ)
sage: f = R.hom([5], QQ)
sage: f(x^2 - 19)
6

sage: R.<x> = PolynomialRing(QQ)
sage: f = R.hom([5], GF(7))
Traceback (most recent call last):
...
TypeError: images do not define a valid homomorphism

sage: R.<x> = PolynomialRing(GF(7))
sage: f = R.hom([3], GF(49,'a'))
sage: f
Ring morphism:
  From: Univariate Polynomial Ring in x over Finite Field of size 7
  To:   Finite Field in a of size 7^2
  Defn: x |--> 3
sage: f(x+6)
2
sage: f(x^2+1)
3

Natural morphism

sage: f = ZZ.hom(GF(5))
sage: f(7)
2
sage: f
Ring Coercion morphism:
  From: Integer Ring
  To:   Finite Field of size 5

There might not be a natural morphism, in which case a TypeError exception is raised.

sage: QQ.hom(ZZ)
Traceback (most recent call last):
...
TypeError: Natural coercion morphism from Rational Field to Integer Ring
not defined.

Special Functions: __getstate__, $\,$ __init__, $\,$ __setstate__, $\,$ __temporarily_change_names, $\,$ _assign_names, $\,$ _first_ngens

__getstate__( )

__setstate__( )

__temporarily_change_names( ): This is used by the variable names context manager.

_assign_names( )

Set the names of the generator of this object.

This can only be done once because objects with generators are immutable, and is typically done during creation of the object.

When we create this polynomial ring, self._assign_names is called by the constructor:

sage: R = QQ['x,y,abc']; R
Multivariate Polynomial Ring in x, y, abc over Rational Field
sage: R.2
abc

We can't rename the variables:

sage: R._assign_names(['a','b','c'])
Traceback (most recent call last):
...
ValueError: variable names cannot be changed after object creation.

_first_ngens( )

Class: ParentWithMultiplicativeAbelianGens

class ParentWithMultiplicativeAbelianGens

Functions: generator_orders

Special Functions: __iter__

__iter__( ): Return an iterator over the elements in this object.

See About this document... for information on suggesting changes.