| name | numpy-ufuncs |
| description | Universal functions (ufuncs) for vectorization, including reductions, in-place operations, and custom Python-function wrapping. Triggers: ufunc, vectorize, reduce, accumulate, frompyfunc, in-place. |
Overview
Universal functions (ufuncs) are the engine behind NumPy's vectorization. They perform element-wise operations on ndarrays, supporting broadcasting, type casting, and efficient internal loops. They also provide methods for cumulative operations (accumulate) and reductions (reduce).
When to Use
- Performing high-speed mathematical operations across entire arrays.
- Reducing memory overhead using in-place operations (
out parameter).
- Creating custom mathematical operations that broadcast like native NumPy functions.
- Applying operations conditionally using the
where parameter.
Decision Tree
- Need to perform an operation without creating a new array?
- Pass the destination array to the
out parameter.
- Have a custom Python function to apply to an array?
- Use
np.frompyfunc for broadcasting (returns PyObjects).
- Use
np.vectorize for API convenience (not performance).
- Performing a reduction on small integers?
- Check for overflow; small types (int8) will silently wrap.
Workflows
-
Memory-Efficient In-Place Operation
- Create arrays A and B.
- Execute
np.multiply(A, B, out=A) to perform the multiplication.
- Observe that A is updated without allocating a new result array.
-
Conditional Vectorized Calculation
- Define a calculation (e.g.,
np.log).
- Define a condition mask where values are valid (e.g.,
x > 0).
- Call
np.log(x, out=result, where=mask) to avoid errors or domain warnings.
-
Creating a Custom Broad-Castable Function
- Define a Python function that takes scalar inputs.
- Wrap it with
np.frompyfunc(func, nin, nout).
- Apply the new ufunc to multidimensional arrays to automatically trigger NumPy broadcasting.
Non-Obvious Insights
- Vectorize is a Loop:
np.vectorize is a convenience wrapper for a Python for-loop and does not provide C-level speed improvements.
- Silent Wrapping: Reductions on data types with a small range (like
int8) will wrap around (e.g., 127 + 1 = -128) silently instead of raising an error.
- Out Uninitialized: If using the
where parameter with out, elements where the condition is False remain uninitialized (they retain whatever was in the output array previously).
Evidence
- "Note that the output is filled only in the places that the broadcast ‘where’ is True... elements not explicitly filled are left with their uninitialized values." Source
- "The vectorize function is provided primarily for convenience, not for performance. The implementation is essentially a for loop." Source
Scripts
scripts/numpy-ufuncs_tool.py: Demonstrates in-place multiplication and custom ufunc creation.scripts/numpy-ufuncs_tool.js: Simulated element-wise map function.
Dependencies
References
