Discrete Math with SageMath: Learn math with open-source software

Sage comes with many built-in functions. While Math terminology is not always standard, be sure to refer to the documentation to understand the exact functionality of these built-in functions and know how to use them. You can also define custom functions to suit your specific needs. You are welcome to use the custom functions we define in this book. However, since these custom functions are not part of the Sage source code, you will need to copy and paste the functions into your Sage environment. In this section, we’ll explore how to define custom functions and use them.

To define a custom function in Sage, use the def keyword followed by the function name and the function’s arguments. The body of the function is indented, and it should contain a return statement that outputs a value. Note that the function definition will only be stored in memory after executing the cell. You won’t see any output when defining the function, but once it is defined, you can use it in other cells. If the cell is successfully executed, you will see a green box underneath it. If the box is not green, run the cell again to define the function.

A simple example of defining a function is one that returns the \(n^{th}\) (0-indexed) row of Pascal’s Triangle. Pascal’s Triangle is a triangular array of numbers where each number is the sum of the two numbers directly above it.

Here’s a function definition that computes a specific row of Pascal’s Triangle. You need execute the cell to store the function in memory. You can only call the pascal_row() function once the definition has been executed. If you attempt to use the function without defining it first, you will receive a NameError.

After defining the function above, let’s try calling it. :

Sage functions can sometimes produce unexpected results if given improper input. For instance, passing a string or a decimal value into the function will raise a TypeError:

However, if you pass a negative integer, the function will silently return an empty list. This lack of error handling can lead to unnoticed errors or unexpected behaviors that are difficult to debug, so it is essential to incorporate input validation. Let’s add a ValueError to handle negative input properly:

With the updated function definition above, try calling the function again with a negative integer. You will now receive an informative error message rather than an empty list:

Functions can also include a docstring in the function definition to describe its purpose, inputs, outputs, and any examples of usage. The docstring is a string that appears as the first statement in the function body. This documentation can be accessed using the help() function or the ? operator.

After redefining the function, you can view the docstring by calling the help() function on the function name:

Alternatively, you can access the source code using the ?? operator:

To learn more on code style conventions and writing documentation strings, refer to the General Conventions article in the Sage Developer’s Guide.