Functions

As programs grow, the same calculation turns up in several places: the stress check for every beam, the unit conversion for every input, the root-finder for every equation. Copying and pasting the code works until you find a mistake in it and have to fix it in seven places, missing one. Functions solve this. A function packages a calculation under a name, takes inputs, and returns a result, so it can be written once, tested once, and used everywhere.

Functions are also the main tool for managing complexity. A well-named function lets you think "check the beam" instead of the five lines that do it, just as an engineer thinks "use the moment formula" without re-deriving it. This chapter covers defining and calling functions, parameters and return values, documentation, default and keyword arguments, scope, testing with assert, passing functions to other functions, and organizing functions into modules.

Defining and calling a function

A function definition starts with def, then the function's name, its parameters in brackets, and a colon. The indented body does the work, and a return statement sends the result back to the caller.

import math

def pipe_velocity(flow_Ls, diameter_mm):
    """Return the mean flow velocity in m/s for a full circular pipe."""
    flow_m3s = flow_Ls / 1000
    diameter_m = diameter_mm / 1000
    area_m2 = math.pi * diameter_m ** 2 / 4
    return flow_m3s / area_m2

v = pipe_velocity(12, 100)
print(f"{v:.3f} m/s")
print(f"{pipe_velocity(12, 150):.3f} m/s")

Output: 1.528 m/s, then 0.679 m/s.

Defining a function does not run it; it only creates it. The body runs each time the function is called, as in pipe_velocity(12, 100). The values in the call (12 and 100) are arguments; they are assigned, in order, to the parameters in the definition (flow_Ls and diameter_mm). When the body reaches return, the function stops and the call is replaced by the returned value.

A function with no return statement returns the special value None. A common beginner bug is a function that prints its answer instead of returning it: the result appears on screen, but the calling code cannot use it in further calculations. As a rule, calculation functions should return values, and only the top level of a program should print.

Docstrings

The string on the first line of the body, in triple quotes, is a docstring. It documents what the function does, its parameters and units, and what it returns. Python keeps it with the function, so help(pipe_velocity) displays it, and code editors show it when you type the function's name. Write one for every function others might use, which in engineering means nearly every function.

def bending_stress(moment_Nmm, b_mm, h_mm):
    """Maximum bending stress in a solid rectangular section.

    Parameters
    ----------
    moment_Nmm : bending moment in N.mm
    b_mm, h_mm : section width and depth in mm

    Returns
    -------
    Stress in MPa (N/mm^2), from sigma = 6M / (b h^2).
    """
    return 6 * moment_Nmm / (b_mm * h_mm ** 2)

print(bending_stress(45e6, 100, 300))

Output: 30.0, matching the result from Lesson 2.

Why functions: removing repetition

Two new features appear in that example. A function can return several values separated by commas; Python packs them into a tuple, and the caller unpacks them into separate names (stress, ok = …). And the conditional expression "OK" if ok else "FAILS" chooses between two values in one line.

Parameters: defaults and keywords

Parameters can have default values, used when the caller leaves them out. Callers can also name arguments explicitly (keyword arguments), which makes calls with many parameters much easier to read and less error-prone, since the order no longer matters.

def to_kPa(value, unit="psi"):
    """Convert a pressure to kPa. unit is "psi", "bar" or "atm"."""
    if unit == "psi":
        return value * 6.894757
    elif unit == "bar":
        return value * 100
    elif unit == "atm":
        return value * 101.325
    else:
        raise ValueError(f"Unknown unit: {unit}")

print(to_kPa(250))               # default unit, psi
print(to_kPa(3, "bar"))          # positional
print(to_kPa(unit="atm", value=2))   # keywords, any order

1723.6892500000001
300
202.65

The raise statement deliberately stops the program with an error when the function is given a unit it does not know. That is far better than silently returning a wrong number: a loud failure is found immediately, a quiet one may be found after construction.

Scope: where names exist

Variables created inside a function (including its parameters) are local: they exist only while the function runs and are invisible outside it. Variables created at the top level of a script are global and can be read inside functions.

Reading global constants (like ALLOWABLE_MPa) inside a function is fine. Changing global variables from inside functions is possible with the global keyword, but it makes programs hard to follow and test; pass values in as arguments and return results instead.

Testing functions

Because a function is a self-contained unit with defined inputs and outputs, it is easy to test on its own. The assert statement checks that a condition is True and stops with an AssertionError if it is not. A handful of asserts with hand-calculated answers, run every time the code changes, catches mistakes early.

import math

def pipe_velocity(flow_Ls, diameter_mm):
    """Mean velocity in m/s for a full circular pipe."""
    area_m2 = math.pi * (diameter_mm / 1000) ** 2 / 4
    return (flow_Ls / 1000) / area_m2

# Tests with answers worked out by hand
assert math.isclose(pipe_velocity(0, 100), 0.0)
# 1 m^3/s through an area of exactly 1 m^2 (D = 1128.379 mm) gives 1 m/s
assert math.isclose(pipe_velocity(1000, 1128.379), 1.0, rel_tol=1e-6)
# halving the diameter quarters the area, so velocity rises 4 times
assert math.isclose(pipe_velocity(12, 50), 4 * pipe_velocity(12, 100))
print("All tests passed")

The tests use special cases (zero flow), a case with a known answer, and a physical relationship (velocity scales as 1/D²). Larger projects use testing frameworks such as pytest, which run hundreds of tests automatically, but the idea is the same.

Functions as arguments

In Python, a function is a value like any other: it can be stored in a variable or passed to another function. This lets you write general tools, such as a root-finder that works on any equation.

For short one-off functions, Python offers lambda expressions: bisect(lambda x: math.cos(x) - x, 0, 1) does the same as the second call without defining cos_minus_x separately.

Modules: organizing your functions

Once you have useful functions, put them in their own file and import them wherever needed. If engcalc.py contains pipe_velocity, bending_stress and to_kPa, any script in the same folder can write:

import engcalc

v = engcalc.pipe_velocity(12, 100)

# or import particular names directly
from engcalc import bending_stress
s = bending_stress(45e6, 100, 300)

This is exactly how math works: it is a module of functions someone else wrote and tested. Building your own library of trusted, tested, documented functions is one of the best investments an engineer who programs can make; many firms maintain shared libraries of verified calculation routines for exactly this reason.

Recursion, briefly

A function may call itself, which is called recursion. It suits problems defined in terms of smaller versions of themselves, such as walking through a tree of folders or a nested structure. Each recursive function needs a base case that stops the recursion. For most numerical engineering work, plain loops are simpler and faster, so treat recursion as a tool to recognize rather than one to reach for first.