Getting Started with Sage

The first line declares the name of the function and the argument list. Don't forget the colon after the argument list! It's also valid to define a function without any arguments, in which case the parenthesis must be empty.

The body of the function is a block of code that is uniformly indented. A unique feature of the Python language is that indentation is used to delimit blocks of code, rather than using symbols like curly braces. That is why it is so important to indent each line in the body of the function by the same amount. The first item within the function body is called the docstring. While this is optional, it's good to get in the habit of including it. Sage displays the docstring when the user asks for help on the function. The docstring is triple-quoted, which means that Sage will display its contents exactly as you format them. Next, the function can have any number of statements. Note that our function has its own local variable, tau. You can also define functions within functions. The final line of the function definition is the return keyword, followed by one or more variables whose values will be returned. If the function doesn't return anything, the return keyword can be used without any variable names, or return can be omitted.

If you find a block of code occurring more than once in your program, stop and move that block of code to a function. Duplicate blocks of code will make your programs harder to read and more prone to bugs.

Functions with keyword arguments

There are two good reasons to use keyword arguments when defining a function. One reason is to allow the user to omit arguments that are seldom changed from their default value. The other is to reduce confusion when calling the function. In the example above, it might be easy to accidentally interchange the resistance and capacitance values when calling the function, resulting in a bug that's hard to track down.

Timeforaction–definingafunctionwithkeywordarguments

Let's re-define our function with keyword arguments:

def RC_voltage(t, v0=100, R=1000, C=1e-9):

Getting Started with Sage

Timeforaction–workingwithobjects

If you are already familiar with objects from another programming language (such as Java or C++), then you will immediately be familiar with objects in Sage. If not, this example should help you understand the concept:

real_number = RR(10/3) print(type(real_number)) print('Value: ' + real_number.str()) print(real_number.n(digits=5))

print('Precision: ' + str(real_number.precision())) print(real_number.ceil())

The result should look like this:

What just happened?

We've already been using objects without knowing it—every number in Sage is actually an object! An object is a construct that consists of data (called attributes) and behaviours (called methods). An object's attributes and methods are defined by a class. We say that an object is an instance of a particular class. In our example, the object called real_number is an instance of a class called RR. We create an object using syntax that is just like a function call:

new_object = Class_Name(arg1, arg2, …)

The number and type of arguments (positional vs. keyword) will depend upon the class definition.

The object called real_number has an attribute that stores a representation of the floatingpoint number 1.4372. It has another attribute that stores the precision of the floating-point number. Objects can have other objects as attributes, leading to very complicated structures. An object's attributes can be interrogated and manipulated using methods. Methods are functions that are associated with an object. For example, the precision method returns the number of bits of precision for the real number:

real_number.precision()

We can use the str method to obtain a string representation of a real number:

real_number.str()

[ 74 ]

Chapter 3

Methods are called with the syntax:

result = object_name.method_name(argument_1, argument_2, … , argument_n)

One of the strengths of object-oriented programming is that the design of the object limits the ways that we can manipulate its data. For example, it wouldn't make any sense if we were allowed to change the value of a floating-point number without updating the number of bits of precision.

As you start using objects, you may be frustrated by the lack of direct access to the data. You may find yourself tempted to avoid using the methods, and directly manipulate the data in an object. This defeats the purpose of using objects! If the methods seem to be hindering your use of the object, you probably aren't using them right. Take another look at the documentation and examples, and re-think your approach.

Gettinghelpwithobjects

If you know an object's class, you can use the help function to see its architecture. In the previous example, we used the type function to determine that a real number's class is sage.rings.real_mpfr.RealNumber. We can use the help function to learn more about it. In the interactive shell, the class documentation looks like this:

sage: help(sage.rings.real_mpfr.RealLiteral)

Help on class RealNumber in module sage.rings.real_mpfr:

class RealNumber(sage.structure.element.RingElement)