Up One Level SAGE Reference Manual Contents Module Index Index
Previous: Up: 5. Basic Structure Next:

5.2 Base class for objects with generators

Module: sage.structure.gens

PYREX: sage.structure.gens

Many 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 $ x$ , $ y$ , and $ z$ . In SAGE the $ i$ 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.

A class that derives from Generators must define a gen(i) function.

The gens function returns a tuple of all generators, the ngens function returns the number of generators, and the assign_names, name and names functions allow one to change or obtain the way generators are printed. (They only affect printing!)

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

sage: R = MPolynomialRing(IntegerRing(), 3)
sage: R.ngens()
3
sage: R.gen(0)
x0
sage: R.gens()
(x0, x1, x2)
sage: R.variable_names()
('x0', 'x1', 'x2')
sage: R.assign_names(['a', 'b', 'c'])
sage: R
Polynomial Ring in a, b, c over Integer Ring

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

sage: M = FreeModule(IntegerRing(), 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))

The names of the generators of a free module aren't really used anywhere, but they are still defined: 

sage: M.variable_names()   
('x0', 'x1', 'x2', 'x3')

Class: AdditiveAbelianGenerators

class AdditiveAbelianGenerators

Functions: generator_orders

Special Functions: __generator_orders,$ $ __iter__

Class: Generators

class Generators

Functions: assign_names,$ $ gen,$ $ gens,$ $ gens_dict,$ $ hom,$ $ latex_name,$ $ latex_variable_names,$ $ list,$ $ ngens,$ $ objgen,$ $ objgens,$ $ variable_name,$ $ variable_names

gens( self)

Return a tuple whose entries are the generators for this object, in order.

gens_dict( self)

Return a dictionary whose entries are var_name:variable.

hom( self, im_gens, codomain=None, check=True)

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).objgen()
sage: f = R.hom([5], QQ)
sage: f(x^2 - 19)
6


sage: R, x = PolynomialRing(QQ).objgen()
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)).objgen()
sage: f = R.hom([3], GF(49))
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
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.

list( self)

Return a list of all elements in this object, if possible (the object must define an iterator).

objgen( self, names=None)

Return self and the generator of self, possibly re-assigning the name of this generator. 

INPUT:
    names -- tuple or string

OUTPUT:
    self  -- this object
    an object -- self.gen()


sage: R, x = PolynomialRing(QQ).objgen()
sage: R
Univariate Polynomial Ring in x over Rational Field
sage: x
x
sage: S, a = (R/(x^2+1)).objgen('a')
sage: S
Univariate Quotient Polynomial Ring in a over Rational Field with modulus
x^2 + 1

objgens( self, names=None)

Return self and the generators of self as a tuple, possibly re-assigning the names of self. 

INPUT:
    names -- tuple or string

OUTPUT:
    self  -- this object
    tuple -- self.gens()


sage: R, x = MPolynomialRing(QQ,3).objgens()
sage: R
Polynomial Ring in x0, x1, x2 over Rational Field
sage: x
(x0, x1, x2)
sage: R, (a,b,c) = R.objgens('abc')
sage: a^2 + b^2 + c^2
c^2 + b^2 + a^2

Special Functions: __certify_names,$ $ __gens,$ $ __gens_dict,$ $ __getitem__,$ $ __getslice__,$ $ __getstate__,$ $ __latex_names,$ $ __len__,$ $ __list,$ $ __names,$ $ __setstate__,$ $ _is_valid_homomorphism_,$ $ _names_from_obj

_is_valid_homomorphism_( self, codomain, im_gens)

Return True if im_gens defines a valid homomorphism from self to codomain; otherwise return False.

If determining whether or not a homomorphism is valid has not been implemented for this ring, then a NotImplementedError exception is raised.

Class: MultiplicativeAbelianGenerators

class MultiplicativeAbelianGenerators

Functions: generator_orders

Special Functions: __generator_orders,$ $ __iter__

Up One Level SAGE Reference Manual Contents Module Index Index
Previous: Up: 5. Basic Structure Next:
Release 1.4.1, documentation updated on October 18, 2006.
See About this document... for information on suggesting changes.