unitx 0.8.2__tar.gz → 0.8.3__tar.gz

{unitx-0.8.2 → unitx-0.8.3}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.8.3] - 2026-10-20
+
+### Added
+
+- Support unit-aware `out` for sum, mean, median, std, var, cumsum,
+  concatenate, stack, and add.reduce/accumulate. Require the exact result shape,
+  preserve target identity, unit, and dtype, and stage computation, conversion,
+  and casting before writing. Argmin/argmax accept bare integer ndarray outputs.
+- Document function/reduction output casting and add regressions for scaled
+  units, positional outputs, overlapping/strided buffers, and unchanged outputs
+  on failure, plus installed-consumer type checks.
+
 ## [0.8.2] - 2026-10-20
 
 ### Fixed

{unitx-0.8.2 → unitx-0.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.8.2
+Version: 0.8.3
 Summary: A modern, intuitive Python library for units, quantities, and dimensional analysis.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Issues, https://github.com/DaitTHU/unitx/issues

{unitx-0.8.2 → unitx-0.8.3}/docs/numpy.md

@@ -79,7 +79,7 @@ methods, mixed array types, and keywords fail explicitly.
 | power, float_power / `**` | Dimensional bases require a finite real scalar exponent; dimensionless bases/exponents normalize their scales |
 | sin, cos, tan, exp, expm1, log, log2, log10, log1p | Require coherent dimensionless values; return dimensionless Quantity |
 | isfinite, isnan, isinf, signbit | Bare boolean results |
-| add.reduce, add.accumulate | Preserve unit; accept axis and dtype, plus keepdims for reduce |
+| add.reduce, add.accumulate | Preserve unit; accept axis, dtype, out, plus keepdims for reduce |
 
 Ufunc `__call__` accepts `where`, `dtype`, `casting`, `order`, `subok`, and
 single-output `out` as described below. Each kernel validates its own options.
@@ -95,25 +95,29 @@ functions, including exp/log. Python scalar numerical semantics remain native.
 | NumPy function | Unit/result rule | Supported options |
 | --- | --- | --- |
 | reshape, transpose | Preserve unit | shape/order/copy; axes |
-| concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting |
-| sum, mean | Preserve unit | axis, dtype, keepdims |
-| median | Preserve unit | axis, keepdims; overwrite_input=False |
-| std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims |
-| cumsum | Preserve unit | axis, dtype |
-| argmin, argmax | Bare indices | axis, keepdims |
+| concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting, out; dtype and out are mutually exclusive |
+| sum, mean | Preserve unit | axis, dtype, keepdims, out |
+| median | Preserve unit | axis, keepdims, out; overwrite_input=False |
+| std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims, out |
+| cumsum | Preserve unit | axis, dtype, out |
+| argmin, argmax | Bare indices | axis, keepdims, out |
 | isclose, allclose | Bare mask / Python bool | rtol, atol, equal_nan |
 
 Supply the first magnitude argument positionally; concatenate/stack take a
 sequence. Options follow each supported signature, including positional out
-checks. Function and reduction `out` and overwrite_input=True are rejected. Unsupported
-initial, statistical where, mean, correction, and other keywords raise TypeError.
+checks. Function and reduction outputs follow the rules below;
+overwrite_input=True is rejected. Unsupported initial, reduction/statistical
+where, mean, correction, and other keywords raise TypeError.
 There is no `__setitem__`; `q += other` creates a result and rebinds q.
 
-## Ufunc output buffers
+## Output buffers
 
-Supported single-output ufunc calls accept a Quantity whose magnitude is a
+Supported single-output ufunc calls, add.reduce/accumulate, and the numeric
+functions listed with `out` above accept a Quantity whose magnitude is a
 writable plain numeric ndarray. `out=target`, `out=(target,)`, and positional
-outputs return that same target. Its magnitude object, dtype, and unit stay
+outputs for ufuncs return that same target; functions accept `out=target` or
+the positional output argument in their NumPy signature, without a tuple.
+The target's magnitude object, dtype, and unit stay
 fixed. Zero-dimensional, empty, and noncontiguous output arrays are supported.
 NumPy scalars and Python scalars cannot serve as output buffers.
 
@@ -127,7 +131,10 @@ converts that result to the target unit and casts it into a staging buffer.
 The numerical kernel uses the input dtypes and any explicit `dtype`; the
 target dtype is used for the final cast. This is not a promise of NumPy's
 output-dependent kernel selection or allocation-free execution. Both the
-result and `where` mask must broadcast to the target shape. Only true mask
+result and `where` mask must broadcast to the target shape for ufunc calls.
+Function and reduction outputs must have exactly the ordinary result's shape,
+including axes retained by `keepdims`; they do not broadcast into a larger
+target. Only true mask
 positions are written; false positions retain their original target values.
 Unit conversion also skips false positions. Input/output overlap and shared
 slices are handled through temporaries; a mask sharing output storage is copied.
@@ -138,6 +145,8 @@ length target. `ScaledUnit` factors participate in the conversion. Every numeric
 result, including a coherent or scaled dimensionless result, requires a Quantity
 target; writing it to a bare ndarray would discard its unit. Boolean predicates
 and comparisons instead accept only a bare boolean ndarray output.
+`argmin` and `argmax` accept only a bare integer ndarray output, with the
+same exact shape requirement as other function outputs.
 
 Final casting uses `casting='same_kind'` by default, or the explicitly requested
 NumPy casting policy. It does not silently enable `unsafe`; nonintegral unit
@@ -148,8 +157,24 @@ The final copy is not a general transaction against concurrent changes or
 external buffer failures. Temporaries cost memory proportional to the result
 and target; `out` provides controlled writes, not a zero-allocation guarantee.
 
-`out=None` and `out=(None,)` allocate ordinary results. Multiple-output ufuncs,
-ufunc reductions with an output, and function outputs remain unsupported.
+Functions and add.reduce/accumulate use `same_kind` for the final cast and do
+not accept a new `casting` keyword. Concatenate and stack use their existing
+`casting` option for the final write as well as the kernel; their `dtype` and
+`out` options cannot be combined. Index outputs also use `same_kind`, including
+its allowance for integer narrowing. These policies intentionally do not
+reproduce every function's native output casting rule. An explicit `dtype`
+controls the temporary numerical computation for supported reductions; the
+target dtype does not select the accumulator or kernel dtype.
+
+```python
+totals = Quantity(np.empty(3), 'cm')
+assert np.sum(q, axis=0, out=totals) is totals
+indices = np.empty(3, dtype=np.intp)
+assert np.argmax(q, axis=0, out=indices) is indices
+```
+
+`out=None` and ufunc `out=(None,)` allocate ordinary results.
+Multiple-output ufuncs and product reductions remain unsupported.
 Output writes preserve the magnitude's type and dtype, so the covariant
 `Quantity[T]` contract remains valid; no setter or arbitrary replacement of T
 is introduced. NumPy's own stubs do not accept Quantity outputs or infer wrapped

{unitx-0.8.2 → unitx-0.8.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'hatchling.build'
 
 [project]
 name = 'unitx'
-version = '0.8.2'
+version = '0.8.3'
 description = 'A modern, intuitive Python library for units, quantities, and dimensional analysis.'
 readme = 'README.md'
 requires-python = '>=3.12'

{unitx-0.8.2 → unitx-0.8.3}/src/unitx/_numpy.py

@@ -3,7 +3,7 @@
 An identity scale retains storage. Integral scales use a Python int multiplier;
 nonintegral rational scales use one Python float multiplier, and irrational
 scales use Factor's approximation. NumPy then controls promotion and errors.
-No Fraction/Decimal object arrays are produced. Explicit ufunc outputs write
+No Fraction/Decimal object arrays are produced. Explicit outputs write
 only after computing, converting, and casting a temporary result.
 """
 
@@ -96,7 +96,11 @@ def _validate_where(kwargs: dict[str, Any]) -> None:
 def dispatch_ufunc(ufunc: Any, method: str, inputs: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
     outputs = kwargs.get('out', ())
     if any(x is not None for x in outputs):
-        if method != '__call__' or ufunc.nout != 1 or len(outputs) != 1:
+        if (
+            method not in ('__call__', 'reduce', 'accumulate')
+            or ufunc.nout != 1
+            or len(outputs) != 1
+        ):
             return NotImplemented
         target = outputs[0]
         predicates = (
@@ -120,33 +124,56 @@ def dispatch_ufunc(ufunc: Any, method: str, inputs: tuple[Any, ...], kwargs: dic
         result = _dispatch_ufunc(ufunc, method, inputs, options)
         if result is NotImplemented:
             return NotImplemented
-        if isinstance(target, Quantity) and type(target.value) is not np.ndarray:
-            raise TypeError('Quantity out requires a plain numeric ndarray buffer.')
-        if not (target.value if isinstance(target, Quantity) else target).flags.writeable:
-            raise ValueError('out buffer is read-only.')
-        return _write_ufunc_output(result, target, options)
+        return _write_output(
+            result,
+            target,
+            where=options.get('where', True),
+            casting=options.get('casting', 'same_kind'),
+            broadcast=method == '__call__',
+        )
     return _dispatch_ufunc(ufunc, method, inputs, kwargs)
 
 
-def _write_ufunc_output(result: Any, target: Any, options: dict[str, Any]) -> Any:
+def _write_output(
+    result: Any,
+    target: Any,
+    *,
+    where: Any = True,
+    casting: Any = 'same_kind',
+    broadcast: bool = False,
+) -> Any:
     """Stage a single output without replacing its magnitude, dtype, or unit."""
-    mask = options.get('where', True)
+    if target is None:
+        return result
     if isinstance(result, Quantity):
+        if not isinstance(target, Quantity) or type(target.value) is not np.ndarray:
+            raise TypeError('Quantity out requires a plain numeric ndarray buffer.')
         if result.dimension != target.dimension:
             raise DimensionError('out has an incompatible dimension.')
-        value = scale_magnitude(result.value, result.unit.factor / target.unit.factor, where=mask)
+        factor = result.unit.factor / target.unit.factor
         buffer = target.value
     else:
-        value, buffer = result, target
+        kinds = 'b' if np.asarray(result).dtype.kind == 'b' else 'iu'
+        if type(target) is not np.ndarray or target.dtype.kind not in kinds:
+            raise TypeError('Unitless out requires a plain ndarray with the matching result kind.')
+        factor = ONE
+        buffer = target
+    if not buffer.flags.writeable:
+        raise ValueError('out buffer is read-only.')
+    value = result.value if isinstance(result, Quantity) else result
+    if not broadcast and np.shape(value) != buffer.shape:
+        raise ValueError('out must have exactly the result shape.')
+    if isinstance(result, Quantity):
+        value = scale_magnitude(value, factor, where=where)
     # Validate broadcasting and casting before touching shared storage. Casting
     # also runs in temporary storage so e.g. float narrowing errors cannot
     # partially overwrite the caller's buffer.
     value = np.broadcast_to(value, buffer.shape)
-    mask = np.broadcast_to(mask, buffer.shape)
+    mask = np.broadcast_to(where, buffer.shape)
     if np.may_share_memory(mask, buffer):
         mask = mask.copy()
     staged = np.empty(buffer.shape, dtype=buffer.dtype)
-    np.copyto(staged, value, where=mask, casting=options.get('casting', 'same_kind'))
+    np.copyto(staged, value, where=mask, casting=casting)
     np.copyto(buffer, staged, where=mask, casting='no')
     return target
 
@@ -306,11 +333,6 @@ def isclose(
     return result
 
 
-def _reject_out(out: Any) -> None:
-    if out is not None:
-        raise TypeError('Writable out is not supported for Quantity.')
-
-
 def dispatch_function(
     func: Any, types: tuple[type, ...], args: tuple[Any, ...], kwargs: dict[str, Any]
 ) -> Any:
@@ -364,7 +386,8 @@ def _join_arrays(
     dtype: Any = None,
     casting: str = 'same_kind',
 ) -> Any:
-    _reject_out(out)
+    if out is not None and dtype is not None:
+        raise TypeError('Cannot provide both dtype and out for concatenate/stack.')
     arrays = tuple(arrays)
     if not arrays or not all(_is_supported_operand(x) for x in arrays):
         return NotImplemented
@@ -379,7 +402,8 @@ def _join_arrays(
         values.append(scale_magnitude(raw, unit.factor / first.unit.factor))
     if dtype is not None and np.dtype(dtype).kind not in 'iufc':
         raise TypeError('Only numeric output dtypes are supported.')
-    return Quantity(func(values, axis=axis, dtype=dtype, casting=casting), first.unit)
+    result = Quantity(func(values, axis=axis, dtype=dtype, casting=casting), first.unit)
+    return _write_output(result, out, casting=casting)
 
 
 def _reshape(q: Any, shape: Any, order: Literal['C', 'F', 'A'] = 'C', *, copy: Any = None) -> Any:
@@ -393,31 +417,28 @@ def _transpose(q: Any, axes: Any = None) -> Any:
 def _argmin_max(
     func: Any, q: Any, axis: Any = None, out: Any = None, *, keepdims: bool = False
 ) -> Any:
-    _reject_out(out)
-    return func(q.value, axis=axis, keepdims=keepdims)
+    return _write_output(func(q.value, axis=axis, keepdims=keepdims), out)
 
 
 def _median(
     q: Any, axis: Any = None, out: Any = None, overwrite_input: bool = False, keepdims: bool = False
 ) -> Any:
-    _reject_out(out)
     if overwrite_input:
         raise TypeError('overwrite_input is not supported for Quantity.')
-    return Quantity(np.median(q.value, axis=axis, keepdims=keepdims), q.unit)
+    return _write_output(Quantity(np.median(q.value, axis=axis, keepdims=keepdims), q.unit), out)
 
 
 def _cumsum(q: Any, axis: Any = None, dtype: Any = None, out: Any = None) -> Any:
-    _reject_out(out)
     _validate_dtype(dtype)
-    return Quantity(np.cumsum(q.value, axis=axis, dtype=dtype), q.unit)
+    return _write_output(Quantity(np.cumsum(q.value, axis=axis, dtype=dtype), q.unit), out)
 
 
 def _sum_mean(
     func: Any, q: Any, axis: Any = None, dtype: Any = None, out: Any = None, keepdims: bool = False
 ) -> Any:
-    _reject_out(out)
     _validate_dtype(dtype)
-    return Quantity(func(q.value, axis=axis, dtype=dtype, keepdims=keepdims), q.unit)
+    result = Quantity(func(q.value, axis=axis, dtype=dtype, keepdims=keepdims), q.unit)
+    return _write_output(result, out)
 
 
 def _std_var(
@@ -429,10 +450,10 @@ def _std_var(
     ddof: Any = 0,
     keepdims: bool = False,
 ) -> Any:
-    _reject_out(out)
     _validate_dtype(dtype)
     unit = q.unit**2 if func is np.var else q.unit
-    return Quantity(func(q.value, axis=axis, dtype=dtype, ddof=ddof, keepdims=keepdims), unit)
+    result = Quantity(func(q.value, axis=axis, dtype=dtype, ddof=ddof, keepdims=keepdims), unit)
+    return _write_output(result, out)
 
 
 def _validate_dtype(dtype: Any) -> None:

{unitx-0.8.2 → unitx-0.8.3}/tests/numpy_typing/check_numpy.py

@@ -78,6 +78,12 @@ def output_contracts(a: npt.NDArray[np.float64]) -> None:
     # never the magnitude object or dtype described by the narrower type.
     # NumPy's own out stubs accept ndarray only; check the protocol entry here.
     q.__array_ufunc__(np.add, '__call__', q, q, out=(widened,))
+    q.__array_ufunc__(np.add, 'accumulate', q, out=(widened,))
+    q.__array_function__(np.cumsum, (Quantity,), (q,), {'out': widened})
+    scalar_target = Quantity(np.empty(()), 'cm')
+    q.__array_ufunc__(np.add, 'reduce', q, out=(scalar_target,))
+    q.__array_function__(np.sum, (Quantity,), (q,), {'out': scalar_target})
+    assert_type(scalar_target.value.dtype, np.dtype[np.float64])
     assert_type(widened.value, Array)
     assert_type(q.value, npt.NDArray[np.float64])
     assert_type(q * Unit('s'), Quantity[npt.NDArray[np.float64]])

{unitx-0.8.2 → unitx-0.8.3}/tests/test_numpy.py

@@ -427,13 +427,14 @@ def test_unsupported_outputs_do_not_mutate():
     target = Quantity(buffer, 'm')
     with pytest.raises(TypeError):
         np.add(q, q, out=buffer)
-    for out in (buffer, target):
-        with pytest.raises(TypeError):
-            np.sum(q, out=out)
-        with pytest.raises(TypeError):
-            np.sum(q, None, None, out)
-        with pytest.raises(TypeError):
-            np.concatenate((q, q), out=out)
+    with pytest.raises(TypeError):
+        np.sum(q, out=buffer)
+    with pytest.raises(ValueError, match='result shape'):
+        np.sum(q, None, None, target)
+    with pytest.raises(TypeError):
+        np.concatenate((q, q), out=buffer)
+    with pytest.raises(ValueError, match='result shape'):
+        np.concatenate((q, q), out=target)
     np.testing.assert_array_equal(buffer, [-123] * 3)
     result = np.add(q, q, where=np.array([True, False, True]))
     np.testing.assert_array_equal(result.value[[0, 2]], [0, 4])
@@ -642,7 +643,7 @@ def test_ufunc_out_protocol():
 
     assert np.add(q, q, out=Foreign()) == 'foreign dispatched'
     target = Quantity(np.full(3, -123.0), 'm')
-    for operation in (np.add.reduce, np.multiply.accumulate, np.modf):
+    for operation in (np.multiply.reduce, np.multiply.accumulate, np.modf):
         with pytest.raises(TypeError):
             operation(q, out=(target, None)) if operation is np.modf else operation(q, out=target)
     np.testing.assert_array_equal(target.value, [-123] * 3)

unitx-0.8.3/tests/test_numpy_outputs.py

@@ -0,0 +1,229 @@
+"""Unit-aware function and reduction outputs, including shared storage."""
+
+import pytest
+
+np = pytest.importorskip('numpy')
+
+from unitx import Quantity, Unit  # noqa: E402
+from unitx.exceptions import DimensionError  # noqa: E402
+from unitx.factor import Factor  # noqa: E402
+
+
+@pytest.mark.parametrize(
+    'operation',
+    [np.sum, np.mean, np.median, np.std, np.var, np.cumsum, np.add.reduce, np.add.accumulate],
+)
+def test_numpy_function_out_conversion(operation):
+    unit = Factor(2) * Unit('m')
+    q = Quantity(np.arange(6.0).reshape(2, 3), unit)
+    natural_unit = unit**2 if operation is np.var else unit
+    target_unit = Unit('cm2' if operation is np.var else 'cm')
+    expected = Quantity(operation(q.value, axis=0), natural_unit).value_in(target_unit)
+    target = Quantity(np.full(np.shape(expected), -123.0), target_unit)
+    buffer = target.value
+    assert operation(q, axis=0, out=target) is target
+    assert target.value is buffer and target.unit is target_unit
+    np.testing.assert_allclose(buffer, expected)
+    np.testing.assert_array_equal(q.value, np.arange(6.0).reshape(2, 3))
+    ordinary = operation(q, axis=0, out=None)
+    assert ordinary.unit == natural_unit
+    np.testing.assert_allclose(ordinary.value, operation(q.value, axis=0))
+
+
+@pytest.mark.parametrize('operation', [np.sum, np.mean, np.median, np.std, np.var, np.add.reduce])
+def test_numpy_reduction_out_axes(operation):
+    q = Quantity(np.arange(24.0).reshape(2, 3, 4), 'm')
+    unit = 'm2' if operation is np.var else 'm'
+    expected = operation(q.value, axis=(0, -1), keepdims=True)
+    target = Quantity(np.empty((1, 3, 1)), unit)
+    assert operation(q, axis=(0, -1), keepdims=True, out=target) is target
+    np.testing.assert_allclose(target.value, expected)
+
+
+def test_numpy_function_out_positional():
+    q = Quantity(np.array([1.0, 2.0, 3.0]), 'm')
+    target = Quantity(np.array(-123.0), 'cm')
+    for operation in (np.sum, np.mean, np.std, np.var):
+        actual = Quantity(target.value, 'cm2') if operation is np.var else target
+        assert operation(q, None, None, actual) is actual
+    assert np.median(q, None, target) is target
+    vector = Quantity(np.empty(3), 'cm')
+    assert np.cumsum(q, None, None, vector) is vector
+    assert np.add.reduce(q, None, None, target) is target
+    assert np.add.reduce(q, out=(target,)) is target
+    assert np.add.accumulate(q, out=(vector,)) is vector
+    assert np.add.reduce(q, out=(None,)).value == 6
+    index = np.array(-1, dtype=np.intp)
+    assert np.argmax(q, None, index) is index
+    assert index == 2
+
+
+@pytest.mark.parametrize('operation', [np.concatenate, np.stack])
+def test_numpy_join_out_conversion(operation):
+    q = Quantity(np.arange(3.0), 'm')
+    other = Quantity(np.arange(3.0) * 100, 'cm')
+    expected = operation((q.value, q.value)) * 1000
+    storage = np.full((*expected.shape, 2), -123.0)
+    target = Quantity(storage[..., 0], 'mm')
+    assert operation((q, other), out=target) is target
+    np.testing.assert_array_equal(target.value, expected)
+    np.testing.assert_array_equal(storage[..., 1], -123)
+    assert operation((q, other), 0, target) is target
+
+
+def test_numpy_join_out_alias():
+    storage = np.arange(6.0)
+    q = Quantity(storage, 'm')
+    assert np.concatenate((q[3:], q[:3]), out=q) is q
+    np.testing.assert_array_equal(storage, [3, 4, 5, 0, 1, 2])
+
+
+@pytest.mark.parametrize('operation', [np.argmin, np.argmax])
+def test_numpy_index_out(operation):
+    q = Quantity(np.array([[3, 1, 4], [2, 7, 0]]), 'm')
+    storage = np.full((3, 2), -123, dtype=np.intp)
+    target = storage[:, 0]
+    assert operation(q, axis=0, out=target) is target
+    np.testing.assert_array_equal(target, operation(q.value, axis=0))
+    np.testing.assert_array_equal(storage[:, 1], -123)
+    kept = np.empty((1, 3), dtype=np.intp)
+    assert operation(q, axis=0, out=kept, keepdims=True) is kept
+    np.testing.assert_array_equal(kept, operation(q.value, axis=0, keepdims=True))
+
+
+def test_numpy_reduction_out_storage():
+    storage = np.arange(6.0).reshape(2, 3)
+    q = Quantity(storage, 'm')
+    target = Quantity(storage[0], 'cm')
+    assert np.sum(q, axis=0, out=target) is target
+    np.testing.assert_array_equal(storage, [[300, 500, 700], [3, 4, 5]])
+    assert np.cumsum(q, axis=1, out=q) is q
+    np.testing.assert_array_equal(storage, [[300, 800, 1500], [3, 7, 12]])
+    assert np.add.accumulate(q, axis=0, out=q) is q
+    np.testing.assert_array_equal(storage, [[300, 800, 1500], [303, 807, 1512]])
+    q.value.flags.writeable = False
+    separate = Quantity(np.empty(3), 'm')
+    assert np.sum(q, axis=0, out=separate) is separate
+    np.testing.assert_array_equal(separate.value, [603, 1607, 3012])
+
+
+def test_numpy_function_out_empty():
+    q = Quantity(np.empty((0, 3)), 'm')
+    target = Quantity(np.full(3, -123.0), 'cm')
+    assert np.sum(q, axis=0, out=target) is target
+    np.testing.assert_array_equal(target.value, 0)
+    empty = Quantity(np.empty((0, 3)), 'cm')
+    assert np.cumsum(q, axis=0, out=empty) is empty
+    assert np.add.accumulate(q, axis=0, out=empty) is empty
+    scalar = Quantity(np.array(2.0), 'km/m')
+    coherent = Quantity(np.array(-123.0), '')
+    assert np.sum(scalar, out=coherent) is coherent
+    assert coherent.value == 2000
+
+
+@pytest.mark.parametrize('operation', [np.sum, np.add.reduce, np.cumsum, np.add.accumulate])
+def test_numpy_function_out_invalid_dimension(operation):
+    q = Quantity(np.arange(3.0), 'm')
+    target = Quantity(np.full(np.shape(operation(q.value)), -123.0), 's')
+    with pytest.raises(DimensionError, match='out has an incompatible dimension'):
+        operation(q, out=target)
+    np.testing.assert_array_equal(target.value, -123)
+
+
+@pytest.mark.parametrize('shape', [(1,), (2, 3), (0,)])
+def test_numpy_reduction_out_invalid_shape(shape):
+    q = Quantity(np.arange(3.0), 'm')
+    for operation in (np.sum, np.add.reduce, np.argmax):
+        buffer = np.full(shape, -123, dtype=np.intp)
+        out = buffer if operation is np.argmax else Quantity(buffer, 'm')
+        with pytest.raises(ValueError, match='result shape'):
+            operation(q, out=out)
+        np.testing.assert_array_equal(buffer, -123)
+
+
+def test_numpy_function_out_invalid_buffer():
+    q = Quantity(np.arange(3.0), 'm')
+    for target in (np.array(-123.0), Quantity(1, 'm'), Quantity(np.float64(1), 'm')):
+        with pytest.raises(TypeError, match='plain numeric ndarray'):
+            np.sum(q, out=target)
+    target = Quantity(np.array(-123.0), 'm')
+    target.value.flags.writeable = False
+    with pytest.raises(ValueError, match='read-only'):
+        np.sum(q, out=target)
+    assert target.value == -123
+
+
+@pytest.mark.parametrize(
+    'target', [np.array(-123.0), np.array(False), Quantity(np.array(-123), '')]
+)
+def test_numpy_index_out_invalid_buffer(target):
+    q = Quantity(np.arange(3.0), 'm')
+    with pytest.raises(TypeError, match='Unitless out'):
+        np.argmax(q, out=target)
+    assert (target.value if isinstance(target, Quantity) else target) == (
+        False if isinstance(target, np.ndarray) and target.dtype.kind == 'b' else -123
+    )
+
+
+def test_numpy_function_out_invalid_cast():
+    q = Quantity(np.array([1.0, 2.5]), 'cm')
+    target = Quantity(np.array(-123), 'm')
+    for operation in (np.sum, np.mean, np.median, np.add.reduce):
+        with pytest.raises(TypeError):
+            operation(q, out=target)
+        assert target.value == -123
+    narrow = Quantity(np.array(-123, dtype=np.float32), 'm')
+    assert np.sum(q, dtype=np.float64, out=narrow) is narrow
+    assert narrow.value.dtype == np.dtype(np.float32)
+    np.testing.assert_allclose(narrow.value, 0.035)
+    with np.errstate(over='raise'):
+        with pytest.raises(FloatingPointError):
+            np.sum(Quantity(np.array([1e100]), 'm'), out=narrow)
+    np.testing.assert_allclose(narrow.value, 0.035)
+
+
+def test_numpy_join_out_invalid_options():
+    q = Quantity(np.array([1.0]), 'cm')
+    target = Quantity(np.full(2, -123), 'm')
+    with pytest.raises(TypeError):
+        np.concatenate((q, q), out=target)
+    np.testing.assert_array_equal(target.value, -123)
+    assert np.concatenate((q, q), out=target, casting='unsafe') is target
+    np.testing.assert_array_equal(target.value, 0)
+    for operation in (np.concatenate, np.stack):
+        with pytest.raises(TypeError, match='both dtype and out'):
+            operation((q, q), out=target, dtype=float)
+    with pytest.raises(DimensionError):
+        np.concatenate((q, Quantity(np.array([1.0]), 's')), out=target)
+    np.testing.assert_array_equal(target.value, 0)
+
+
+def test_numpy_function_out_invalid_kernel():
+    q = Quantity(np.array([np.inf, np.inf]), 'm')
+    target = Quantity(np.array(-123.0), 'm2')
+    with np.errstate(invalid='raise'):
+        with pytest.raises(FloatingPointError):
+            np.var(q, out=target)
+    assert target.value == -123
+    with pytest.raises(TypeError):
+        np.median(q, out=target, overwrite_input=True)
+    assert target.value == -123
+
+
+def test_numpy_reduction_out_protocol():
+    q = Quantity(np.arange(3.0), 'm')
+
+    class Foreign:
+        def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+            return 'foreign dispatched'
+
+        def __array_function__(self, func, types, args, kwargs):
+            return 'foreign dispatched'
+
+    assert np.add.reduce(q, out=Foreign()) == 'foreign dispatched'
+    assert np.sum(q, out=Foreign()) == 'foreign dispatched'
+    target = Quantity(np.array(-123.0), 'm')
+    for options in ({'where': True}, {'initial': 1}, {'casting': 'unsafe'}):
+        with pytest.raises(TypeError):
+            np.add.reduce(q, out=target, **options)
+    assert target.value == -123