Agent Skills: numpy-ufuncs

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

1. Need to perform an operation without creating a new array?
   • Pass the destination array to the out parameter.
2. 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).
3. Performing a reduction on small integers?
   • Check for overflow; small types (int8) will silently wrap.

Workflows

1. 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.

2. 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.

3. 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

• numpy (Python)

References

• references/README.md