unitx 0.16.2__tar.gz → 0.16.3__tar.gz

{unitx-0.16.2 → unitx-0.16.3}/.github/consumers/arrays.py

@@ -5,12 +5,14 @@ from typing import assert_type, cast
 import numpy as np
 from numpy.typing import NDArray
 
-from unitx import LogQuantity, LogUnit, Quantity, Unit
+from unitx import AffineQuantity, LogQuantity, LogUnit, Quantity, Unit
 from unitx._numerics import Array
 from unitx.cgs import emu, esu, gaussian, hl
 from unitx.exceptions import DimensionError
 from unitx.si import si
 
+type ArrayQuantity = Quantity[Array] | AffineQuantity[Array] | LogQuantity[Array]
+
 
 def check_arrays(values: NDArray[np.float64]) -> None:
     charge = gaussian.convert(Quantity(values, si.C), gaussian.statC)
@@ -47,6 +49,24 @@ def check_arrays(values: NDArray[np.float64]) -> None:
 
     # NumPy's stubs lose the wrapper on these returns. State the supported
     # array result domain explicitly and verify the wrapper at runtime.
+    for sample in (distance, AffineQuantity(values, si.degC), level):
+        expanded = cast(ArrayQuantity, np.expand_dims(sample, (0, -1)))
+        # moveaxis/rollaxis stubs require ndarray input despite runtime dispatch.
+        moved = cast(
+            ArrayQuantity,
+            expanded.__array_function__(np.moveaxis, (type(expanded),), (expanded, 0, -1), {}),
+        )
+        swapped = cast(ArrayQuantity, np.swapaxes(moved, 0, 1))
+        rolled = cast(
+            ArrayQuantity,
+            swapped.__array_function__(np.rollaxis, (type(swapped),), (swapped, 2, 0), {}),
+        )
+        squeezed = np.squeeze(rolled)
+        result = cast(ArrayQuantity, np.ravel(squeezed))
+        assert type(result) is type(sample) and result.unit == sample.unit
+        np.testing.assert_array_equal(result.value, values)
+        assert np.shares_memory(result.value, sample.value)
+
     bounded = cast(Quantity[Array], np.clip(distance, Quantity(500, si.cm), Quantity(25, si.m)))
     assert isinstance(bounded, Quantity) and bounded.unit == si.m
     np.testing.assert_allclose(bounded.value, [5, 20, 25])

{unitx-0.16.2 → unitx-0.16.3}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## [Unreleased]
 
+## [0.16.3] - 2026-10-25
+
+### Added
+
+- Support NumPy `squeeze`, `expand_dims`, `moveaxis`, `swapaxes`, `rollaxis`
+  and `ravel`, preserving complete units or point coordinates. Retain NumPy's
+  axis rules, dtype, shared views, read-only storage and necessary copies.
+
 ## [0.16.2] - 2026-10-25
 
 ### Added

{unitx-0.16.2 → unitx-0.16.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.16.2
+Version: 0.16.3
 Summary: Physical units, quantities, and unit conversion with exact unit algebra, type hints, and NumPy integration.
 Project-URL: Homepage, https://github.com/DaitTHU/unitx
 Project-URL: Documentation, https://daitthu.github.io/unitx/

{unitx-0.16.2 → unitx-0.16.3}/docs/numpy.md

@@ -38,8 +38,8 @@ use `np.asarray(q.value_in(target_unit))`.
 
 Construction, unit-only multiplication/division, and an identity conversion
 preserve the magnitude object. Factor/SymbolicConstant operands change the
-exact unit scale. Indexing, iteration, `.T`, reshape, and transpose follow
-NumPy's scalar/view/copy rules; `.flatten(order='C')` copies. Zero-dimensional
+exact unit scale. Indexing, iteration, `.T`, and the supported shape transformations
+follow NumPy's scalar/view/copy rules; `.flatten(order='C')` copies. Zero-dimensional
 arrays cannot be iterated. `.shape`, `.ndim`, `.dtype`, and `.size` are available
 for NumPy magnitudes. Python scalars do not acquire array attributes. Exposed
 values and views may share writable storage.
@@ -115,6 +115,9 @@ 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 |
+| squeeze, expand_dims | Preserve unit or point coordinate | axis |
+| moveaxis, swapaxes, rollaxis | Preserve unit or point coordinate | source/destination; axis1/axis2; axis/start |
+| ravel | Preserve unit or point coordinate | order: C, F, A, K |
 | concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting, out; dtype and out are mutually exclusive |
 | sum, nansum | Preserve unit | axis, dtype, keepdims, initial, where, out |
 | mean, nanmean | Preserve unit or point coordinate | axis, dtype, keepdims, where, out |
@@ -146,6 +149,35 @@ Indexed assignment and augmented arithmetic on ndarrays follow the fixed-target
 rules below. Python and NumPy scalar magnitudes retain ordinary result/rebinding
 behavior for augmented arithmetic.
 
+## Shape transformations
+
+`squeeze`, `expand_dims`, `moveaxis`, `swapaxes`, `rollaxis`, and `ravel`
+operate on magnitudes without conversion. Like reshape and transpose, they
+retain the complete unit or point coordinate and return the same family:
+Quantity, AffineQuantity, or LogQuantity. Only the NumPy function forms are
+supported; these functions have no `out` option.
+
+Axis rules and errors follow NumPy, including negative and tuple axes where
+supported. Squeezing an ndarray whose axes all have length one produces a
+zero-dimensional ndarray magnitude. Views share storage and its writeability
+with the input.
+`ravel` returns a contiguous one-dimensional magnitude, copying only when needed;
+it can copy a noncontiguous input even when reshape could return a view.
+Its C/F/A/K orders follow NumPy. Prefer `moveaxis` for new code; `rollaxis` is
+also supported for compatibility with existing NumPy code.
+
+```python
+import numpy as np
+from unitx import Quantity
+
+samples = Quantity(np.arange(6).reshape(1, 2, 3), 'cm')
+matrix = np.squeeze(samples, axis=0)
+assert matrix.shape == (2, 3)
+assert np.moveaxis(matrix, 0, -1).shape == (3, 2)
+assert matrix.unit == samples.unit
+assert np.shares_memory(matrix.value, samples.value)
+```
+
 ## Selection and clipping
 
 See [selection and clipping](numpy/selection.md) for `where`, `clip`,

{unitx-0.16.2 → unitx-0.16.3}/docs/typing.md

@@ -94,11 +94,16 @@ ufunc stubs preserve the wrapper at every intermediate call. For an explicit
 numerical boundary, use `np.expm1(np.asarray(q.value_in(si.one)))` after
 checking dimensions and normalizing the scale.
 
-The same NumPy stub limitation applies to `where`, `clip`,
+The same NumPy stub limitation applies to the supported shape transformations,
+`where`, `clip`,
 `minimum/maximum`, `average`, `quantile`, `percentile`, the supported `nan*`
 statistics, and `interp`: runtime results
 preserve the documented Quantity/point wrappers, but NumPy may annotate them
 as ndarrays or Any. NumPy's `out` annotations also accept only ndarrays.
+The `moveaxis` and `rollaxis` input annotations likewise require ndarrays
+and can reject a Quantity/point argument during static checking, despite
+working at runtime. Their installed type consumers check the dispatch protocol
+directly; runtime tests use ordinary NumPy calls.
 Runtime support and installed-consumer checks cover
 these calls; unitx does not replace NumPy's stubs.
 

{unitx-0.16.2 → unitx-0.16.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = 'hatchling.build'
 
 [project]
 name = 'unitx'
-version = '0.16.2'
+version = '0.16.3'
 description = 'Physical units, quantities, and unit conversion with exact unit algebra, type hints, and NumPy integration.'
 readme = 'README.md'
 requires-python = '>=3.12'

{unitx-0.16.2 → unitx-0.16.3}/src/unitx/_numerics/numpy.py

@@ -604,6 +604,12 @@ def dispatch_function(
             np.allclose,
             np.reshape,
             np.transpose,
+            np.squeeze,
+            np.expand_dims,
+            np.moveaxis,
+            np.swapaxes,
+            np.rollaxis,
+            np.ravel,
             np.argmin,
             np.argmax,
             np.nanargmin,
@@ -754,6 +760,30 @@ def _transpose(q: Any, axes: Any = None) -> Any:
     return _wrap(np.transpose(q.value, axes), q.unit)
 
 
+def _squeeze(q: Any, axis: Any = None) -> Any:
+    return _wrap(np.squeeze(q.value, axis=axis), q.unit)
+
+
+def _expand_dims(q: Any, axis: Any) -> Any:
+    return _wrap(np.expand_dims(q.value, axis), q.unit)
+
+
+def _moveaxis(q: Any, source: Any, destination: Any) -> Any:
+    return _wrap(np.moveaxis(q.value, source, destination), q.unit)
+
+
+def _swapaxes(q: Any, axis1: Any, axis2: Any) -> Any:
+    return _wrap(np.swapaxes(q.value, axis1, axis2), q.unit)
+
+
+def _rollaxis(q: Any, axis: Any, start: Any = 0) -> Any:
+    return _wrap(np.rollaxis(q.value, axis, start), q.unit)
+
+
+def _ravel(q: Any, order: Literal['C', 'F', 'A', 'K'] = 'C') -> Any:
+    return _wrap(np.ravel(q.value, order=order), q.unit)
+
+
 def _interp(
     x: Any, xp: Any, fp: Any, left: Any = None, right: Any = None, period: Any = None
 ) -> Any:
@@ -1216,6 +1246,12 @@ def _extremum(
 _QUANTITY_FUNCTIONS = {
     np.reshape: _reshape,
     np.transpose: _transpose,
+    np.squeeze: _squeeze,
+    np.expand_dims: _expand_dims,
+    np.moveaxis: _moveaxis,
+    np.swapaxes: _swapaxes,
+    np.rollaxis: _rollaxis,
+    np.ravel: _ravel,
     np.argmin: partial(_argmin_max, np.argmin),
     np.argmax: partial(_argmin_max, np.argmax),
     np.nanargmin: partial(_argmin_max, np.nanargmin),

unitx-0.16.3/tests/test_numpy_shapes.py

@@ -0,0 +1,217 @@
+"""Shape transformations retain units, coordinates and NumPy storage behavior."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+from unitx import AffineQuantity, LogQuantity, Quantity, Unit
+from unitx._numerics import Array
+from unitx.factor import Factor, pi
+
+np = pytest.importorskip('numpy')
+
+ArrayQuantity = Quantity[Array] | AffineQuantity[Array] | LogQuantity[Array]
+
+_TRANSFORMS = [
+    pytest.param(np.squeeze, (), {}, id='squeeze'),
+    pytest.param(np.squeeze, (), {'axis': (0, -2)}, id='squeeze-tuple'),
+    pytest.param(np.expand_dims, (0,), {}, id='expand-dims'),
+    pytest.param(np.expand_dims, (), {'axis': (0, -1)}, id='expand-dims-tuple'),
+    pytest.param(np.moveaxis, (0, -1), {}, id='moveaxis'),
+    pytest.param(np.moveaxis, (), {'source': (0, 3), 'destination': (3, 0)}, id='moveaxis-tuple'),
+    pytest.param(np.swapaxes, (), {'axis1': 1, 'axis2': -1}, id='swapaxes'),
+    pytest.param(np.rollaxis, (3,), {}, id='rollaxis'),
+    pytest.param(np.rollaxis, (), {'axis': 0, 'start': 4}, id='rollaxis-end'),
+    pytest.param(np.rollaxis, (3, -3), {}, id='rollaxis-negative-start'),
+    pytest.param(np.ravel, (), {}, id='ravel'),
+]
+
+
+@pytest.fixture(params=['linear', 'affine', 'logarithmic'])
+def sample(request: pytest.FixtureRequest) -> ArrayQuantity:
+    values = np.arange(24, dtype=np.int16).reshape(1, 2, 1, 12)[..., ::4]
+    if request.param == 'linear':
+        return Quantity(values, Factor(2) * pi * Unit('cm'))
+    if request.param == 'affine':
+        return AffineQuantity(values, 'degC')
+    return LogQuantity(values, 'dBm')
+
+
+@pytest.mark.parametrize('operation,args,kwargs', _TRANSFORMS)
+@pytest.mark.parametrize('readonly', [False, True])
+def test_numpy_shape_transform_storage(
+    sample: ArrayQuantity,
+    operation: Callable[..., Any],
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+    readonly: bool,
+) -> None:
+    sample.value.flags.writeable = not readonly
+    before = sample.value.copy()
+    expected = operation(sample.value, *args, **kwargs)
+    result = operation(sample, *args, **kwargs)
+    assert type(result) is type(sample)
+    assert result.unit == sample.unit
+    assert type(result.value) is type(expected)
+    assert result.value.dtype == expected.dtype
+    assert result.value.shape == expected.shape
+    assert result.value.strides == expected.strides
+    assert result.value.flags.writeable == expected.flags.writeable
+    assert np.shares_memory(result.value, sample.value) == np.shares_memory(expected, sample.value)
+    np.testing.assert_array_equal(result.value, expected)
+    np.testing.assert_array_equal(sample.value, before)
+
+
+@pytest.mark.parametrize('operation,args,kwargs', _TRANSFORMS)
+def test_numpy_shape_transform_empty(
+    sample: ArrayQuantity,
+    operation: Callable[..., Any],
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> None:
+    q = type(sample)(np.empty((1, 0, 1, 3), dtype=np.float32), sample.unit)
+    expected = operation(q.value, *args, **kwargs)
+    result = operation(q, *args, **kwargs)
+    assert type(result) is type(q) and result.unit == q.unit
+    assert result.value.shape == expected.shape
+    assert result.value.dtype == expected.dtype
+
+
+@pytest.mark.parametrize(
+    'operation,args',
+    [(np.squeeze, ()), (np.expand_dims, (-1,)), (np.moveaxis, ((), ())), (np.ravel, ())],
+)
+@pytest.mark.parametrize('value', [2, np.float32(2), np.array(2, dtype=np.int16)])
+def test_numpy_shape_transform_scalar(
+    sample: ArrayQuantity, operation: Callable[..., Any], args: tuple[object, ...], value: Any
+) -> None:
+    q = type(sample)(value, sample.unit)
+    expected = operation(value, *args)
+    result = operation(q, *args)
+    assert type(result) is type(q) and result.unit == q.unit
+    assert type(result.value) is type(expected)
+    assert result.value.shape == expected.shape
+    assert result.value.dtype == expected.dtype
+    np.testing.assert_array_equal(result.value, expected)
+
+
+def test_numpy_squeeze_zero_dimensional_result(sample: ArrayQuantity) -> None:
+    q = type(sample)(np.array([[2]], dtype=np.int16), sample.unit)
+    result = np.squeeze(q)
+    assert type(result) is type(q) and result.unit == q.unit
+    assert type(result.value) is np.ndarray and result.value.shape == ()
+    assert result.value.item() == 2
+    assert np.shares_memory(result.value, q.value)
+
+
+@pytest.mark.parametrize('operation,args,kwargs', _TRANSFORMS)
+def test_numpy_shape_transform_shared_write(
+    sample: ArrayQuantity,
+    operation: Callable[..., Any],
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> None:
+    q = type(sample)(np.arange(6.0).reshape(1, 2, 1, 3), sample.unit)
+    result = operation(q, *args, **kwargs)
+    assert np.shares_memory(result.value, q.value)
+    result.value.flat[0] = 42
+    assert q.value.flat[0] == 42
+    assert q.unit == sample.unit
+
+
+@pytest.mark.parametrize('order', ['C', 'F', 'A', 'K'])
+@pytest.mark.parametrize('layout', ['C', 'F', 'transpose', 'strided', 'negative'])
+def test_numpy_ravel_order(sample: ArrayQuantity, order: str, layout: str) -> None:
+    values = np.arange(12, dtype=np.int16).reshape(3, 4)
+    if layout == 'F':
+        values = np.asfortranarray(values)
+    elif layout == 'transpose':
+        values = values.T
+    elif layout == 'strided':
+        values = values[:, ::2]
+    elif layout == 'negative':
+        values = values[:, ::-1]
+    q = type(sample)(values, sample.unit)
+    before = values.copy()
+    expected = np.ravel(values, order)
+    result = np.ravel(q, order)
+    assert type(result) is type(q) and result.unit == q.unit
+    assert result.value.ndim == 1 and result.value.flags.c_contiguous
+    assert np.shares_memory(result.value, values) == np.shares_memory(expected, values)
+    np.testing.assert_array_equal(result.value, expected)
+    if not np.shares_memory(result.value, values):
+        result.value[0] = -1
+        np.testing.assert_array_equal(values, before)
+
+
+@pytest.mark.parametrize(
+    'operation,args',
+    [
+        (np.squeeze, (4,)),
+        (np.expand_dims, (-6,)),
+        (np.moveaxis, (4, 0)),
+        (np.swapaxes, (0, -5)),
+        (np.rollaxis, (0, 5)),
+    ],
+)
+def test_numpy_shape_transform_invalid_axis(
+    sample: ArrayQuantity, operation: Callable[..., Any], args: tuple[object, ...]
+) -> None:
+    before = sample.value.copy()
+    with pytest.raises(np.exceptions.AxisError):
+        operation(sample, *args)
+    np.testing.assert_array_equal(sample.value, before)
+
+
+def test_numpy_squeeze_invalid_axis_size(sample: ArrayQuantity) -> None:
+    with pytest.raises(ValueError, match='size not equal to one'):
+        np.squeeze(sample, axis=1)
+
+
+def test_numpy_squeeze_invalid_repeated_axis(sample: ArrayQuantity) -> None:
+    with pytest.raises(ValueError, match='duplicate value'):
+        np.squeeze(sample, axis=(0, 0))
+
+
+@pytest.mark.parametrize(
+    'operation,args',
+    [
+        (np.expand_dims, ((0, 0),)),
+        (np.moveaxis, ((0, 0), (1, 2))),
+        (np.moveaxis, ((0, 1), (2, 2))),
+    ],
+)
+def test_numpy_shape_transform_invalid_repeated_axis(
+    sample: ArrayQuantity, operation: Callable[..., Any], args: tuple[object, ...]
+) -> None:
+    with pytest.raises(ValueError, match='repeated axis'):
+        operation(sample, *args)
+
+
+def test_numpy_moveaxis_invalid_axis_count(sample: ArrayQuantity) -> None:
+    with pytest.raises(ValueError, match='same number of elements'):
+        np.moveaxis(sample, (0, 1), (2,))
+
+
+@pytest.mark.parametrize('operation,args,kwargs', _TRANSFORMS)
+def test_numpy_shape_transform_invalid_keyword(
+    sample: ArrayQuantity,
+    operation: Callable[..., Any],
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> None:
+    with pytest.raises(TypeError, match='unexpected keyword'):
+        operation(sample, *args, **kwargs, out=sample)
+
+
+def test_numpy_ravel_invalid_order(sample: ArrayQuantity) -> None:
+    with pytest.raises(ValueError, match='order'):
+        np.ravel(sample, order='invalid')
+
+
+def test_numpy_ravel_invalid_copy(sample: ArrayQuantity) -> None:
+    with pytest.raises(TypeError, match='unexpected keyword'):
+        np.ravel(sample, copy=True)