3.7 Integrated Help System

Sage features an integrated help facility. Type a function name followed by ? for the documentation for that function.

sage: V = QQ^3
sage: V.coordinates?
Type:           instancemethod
Base Class:     <type 'instancemethod'>
String Form:    <bound method FreeModule_ambient_field.coordinates of Vector 
space of dimension 3 over Rational Field>
Namespace:      Interactive
File:           /home/was/s/local/lib/python2.4/site-packages/sage/modules/f
ree_module.py
Definition:     V.coordinates(self, v)
Docstring:
    Write v in terms of the basis for self.

    Returns a list c such that if B is the basis for self, then

            sum c_i B_i = v.

    If v is not in self, raises an ArithmeticError exception.

    EXAMPLES:
        sage: M = FreeModule(IntegerRing(), 2); M0,M1=M.gens()
        sage: W = M.submodule([M0 + M1, M0 - 2*M1])
        sage: W.coordinates(2*M0-M1)
        [2, -1]

As shown above, the output tells you the type of the object, the file in which it is defined, and a useful description of the function with examples that you can paste into your current session. Almost all of these examples are regularly automatically tested to make sure they work and behave exactly as claimed.

Another feature that is very much in the spirit of the open source nature of Sage is that if f is a Python function, then typing f?? displays the source code that defines f. For example,

sage: V = QQ^3
sage: V.coordinates??
Type:           instancemethod
...
Source:
def coordinates(self, v):
        """
        Write $v$ in terms of the basis for self.
        ...
        """
        return self.coordinate_vector(v).list()

This tells us that all the coordinates function does is call the coordinate_vector function and change the result into a list. What does the coordinate_vector function do?

sage: V = QQ^3
sage: V.coordinate_vector??
...
def coordinate_vector(self, v):
        ...
        return self.ambient_vector_space()(v)
The coordinate_vector function coerces its input into the ambient space, which has the effect of computing the vector of coefficients of $ v$ in terms of $ V$ . The space $ V$ is already ambient since it's just $ \mathbf{Q}^3$ . There is also a coordinate_vector function for subspaces, and it's different. We create a subspace and see:

sage: V = QQ^3; W = V.span_of_basis([V.0, V.1])
sage: W.coordinate_vector??
...
def coordinate_vector(self, v):
        """
         ...
        """
        # First find the coordinates of v wrt echelon basis.
        w = self.echelon_coordinate_vector(v)
        # Next use transformation matrix from echelon basis to
        # user basis.
        T = self.echelon_to_user_matrix()
        return T.linear_combination_of_rows(w)
(If you think the implementation is inefficient, please sign up to help optimize linear algebra.)

You may also type help(command_name) or help(class) for a manpage-like help file about a given class.

sage: help(VectorSpace)
Help on class VectorSpace ...

class VectorSpace(__builtin__.object)
 |  Create a Vector Space.
 |
 |  To create an ambient space over a field with given dimension
 |  using the calling syntax ...
 :
 :
When you type q to exit the help system, your session appears just as it was. The help listing does not clutter up your session, unlike the output of function_name? sometimes does. It's particularly helpful to type help(module_name). For example, vector spaces are defined in sage.modules.free_module, so type help(sage.modules.free_module) for documentation about that whole module. When viewing documentation using help you can search by typing / and in reverse by typing ?.

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