unitx 0.8.4__tar.gz → 0.8.6__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. {unitx-0.8.4 → unitx-0.8.6}/CHANGELOG.md +33 -0
  2. {unitx-0.8.4 → unitx-0.8.6}/PKG-INFO +15 -15
  3. {unitx-0.8.4 → unitx-0.8.6}/README.md +14 -14
  4. {unitx-0.8.4 → unitx-0.8.6}/docs/numpy.md +154 -9
  5. {unitx-0.8.4 → unitx-0.8.6}/pyproject.toml +1 -1
  6. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numpy.py +218 -46
  7. {unitx-0.8.4 → unitx-0.8.6}/tests/numpy_typing/check_numpy.py +15 -0
  8. {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy.py +3 -4
  9. unitx-0.8.6/tests/test_numpy_differentiation.py +245 -0
  10. unitx-0.8.6/tests/test_numpy_multi_outputs.py +286 -0
  11. {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_outputs.py +4 -3
  12. unitx-0.8.6/tests/test_numpy_statistics.py +254 -0
  13. {unitx-0.8.4 → unitx-0.8.6}/.github/workflows/ci.yml +0 -0
  14. {unitx-0.8.4 → unitx-0.8.6}/.github/workflows/release.yml +0 -0
  15. {unitx-0.8.4 → unitx-0.8.6}/.gitignore +0 -0
  16. {unitx-0.8.4 → unitx-0.8.6}/LICENSE +0 -0
  17. {unitx-0.8.4 → unitx-0.8.6}/conftest.py +0 -0
  18. {unitx-0.8.4 → unitx-0.8.6}/docs/images/blackbody.png +0 -0
  19. {unitx-0.8.4 → unitx-0.8.6}/docs/migration.md +0 -0
  20. {unitx-0.8.4 → unitx-0.8.6}/docs/scalars.md +0 -0
  21. {unitx-0.8.4 → unitx-0.8.6}/docs/units.md +0 -0
  22. {unitx-0.8.4 → unitx-0.8.6}/examples/README.md +0 -0
  23. {unitx-0.8.4 → unitx-0.8.6}/examples/blackbody.ipynb +0 -0
  24. {unitx-0.8.4 → unitx-0.8.6}/examples/damped_oscillator.ipynb +0 -0
  25. {unitx-0.8.4 → unitx-0.8.6}/examples/gaussian_wavepacket.ipynb +0 -0
  26. {unitx-0.8.4 → unitx-0.8.6}/examples/optical_attenuation.ipynb +0 -0
  27. {unitx-0.8.4 → unitx-0.8.6}/examples/pendulum_uncertainty.ipynb +0 -0
  28. {unitx-0.8.4 → unitx-0.8.6}/pyrightconfig.json +0 -0
  29. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/__init__.py +0 -0
  30. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_constnamespace.py +0 -0
  31. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numerics.py +0 -0
  32. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numpy_typing.py +0 -0
  33. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_unicode.py +0 -0
  34. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/dimension.py +0 -0
  35. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/exceptions.py +0 -0
  36. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/factor.py +0 -0
  37. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/monomial.py +0 -0
  38. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/py.typed +0 -0
  39. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/quantity.py +0 -0
  40. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/__init__.py +0 -0
  41. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/bases.py +0 -0
  42. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/constants.py +0 -0
  43. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/units.py +0 -0
  44. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/singleunit.py +0 -0
  45. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unit.py +0 -0
  46. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unitparser.py +0 -0
  47. {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unitregistry.py +0 -0
  48. {unitx-0.8.4 → unitx-0.8.6}/tests/__init__.py +0 -0
  49. {unitx-0.8.4 → unitx-0.8.6}/tests/_notebooks.py +0 -0
  50. {unitx-0.8.4 → unitx-0.8.6}/tests/example_typing/check_blackbody.py +0 -0
  51. {unitx-0.8.4 → unitx-0.8.6}/tests/test_builtin_definitions.py +0 -0
  52. {unitx-0.8.4 → unitx-0.8.6}/tests/test_dimension.py +0 -0
  53. {unitx-0.8.4 → unitx-0.8.6}/tests/test_examples.py +0 -0
  54. {unitx-0.8.4 → unitx-0.8.6}/tests/test_factor.py +0 -0
  55. {unitx-0.8.4 → unitx-0.8.6}/tests/test_import.py +0 -0
  56. {unitx-0.8.4 → unitx-0.8.6}/tests/test_monomial.py +0 -0
  57. {unitx-0.8.4 → unitx-0.8.6}/tests/test_numeric.py +0 -0
  58. {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_integration.py +0 -0
  59. {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_products.py +0 -0
  60. {unitx-0.8.4 → unitx-0.8.6}/tests/test_quantity.py +0 -0
  61. {unitx-0.8.4 → unitx-0.8.6}/tests/test_si.py +0 -0
  62. {unitx-0.8.4 → unitx-0.8.6}/tests/test_singleunit.py +0 -0
  63. {unitx-0.8.4 → unitx-0.8.6}/tests/test_typing.py +0 -0
  64. {unitx-0.8.4 → unitx-0.8.6}/tests/test_unicode.py +0 -0
  65. {unitx-0.8.4 → unitx-0.8.6}/tests/test_unit.py +0 -0
  66. {unitx-0.8.4 → unitx-0.8.6}/tests/test_unit_definition.py +0 -0
  67. {unitx-0.8.4 → unitx-0.8.6}/tests/test_unitparser.py +0 -0
  68. {unitx-0.8.4 → unitx-0.8.6}/tests/test_unitregistry.py +0 -0
  69. {unitx-0.8.4 → unitx-0.8.6}/tests/test_warnings.py +0 -0
  70. {unitx-0.8.4 → unitx-0.8.6}/tests/typing/check_quantity.py +0 -0
  71. {unitx-0.8.4 → unitx-0.8.6}/tests/typing/check_si.py +0 -0
@@ -1,5 +1,38 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.8.6] - 2026-10-20
4
+
5
+ ### Added
6
+
7
+ - Support diff with compatible boundary values converted to the input unit,
8
+ and gradient with scalar spacing or coordinate arrays carrying units. Return
9
+ each gradient component in the ordinate unit divided by that axis's
10
+ coordinate unit, including mixed units across axes.
11
+ - Support input masks for sum, add.reduce, mean, std, and var, including staged
12
+ output writes. Preserve units, selected-sample statistics, and native NumPy
13
+ dtype, empty-sample warnings, and degrees-of-freedom behavior.
14
+ - Support scalar initial values for sum/add.reduce, converting compatible
15
+ Quantities to the input unit. Bare nonzero initial values remain dimensionless;
16
+ bare zero is an additive identity. Document accumulator casting and empty sums.
17
+
18
+ ## [0.8.5] - 2026-10-20
19
+
20
+ ### Added
21
+
22
+ - Support modf and frexp with units on both modf parts and the frexp mantissa;
23
+ return the binary exponent as a bare integer. Decompose stored coordinates
24
+ without implicitly normalizing scaled dimensionless units.
25
+ - Support both outputs, positional buffers, partial None outputs, and boolean
26
+ masks. Stage every output before writing, preserve target units and dtypes,
27
+ and reject overlapping outputs. Validate scalar, empty, strided, and shared
28
+ storage cases, and use ldexp to reconstruct extreme finite floating values.
29
+
30
+ ### Improved
31
+
32
+ - Consolidate Quantity-first NumPy function dispatch and reuse output staging
33
+ for single-output and multiple-output calls.
34
+ - Use absolute documentation and image links in the README for PyPI rendering.
35
+
3
36
  ## [0.8.4] - 2026-10-20
4
37
 
5
38
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: unitx
3
- Version: 0.8.4
3
+ Version: 0.8.6
4
4
  Summary: A modern, intuitive unit library, with exact unit algebra, expressive type hints, and NumPy integration.
5
5
  Project-URL: Homepage, https://github.com/DaitTHU/unitx
6
6
  Project-URL: Issues, https://github.com/DaitTHU/unitx/issues
@@ -26,7 +26,7 @@ Description-Content-Type: text/markdown
26
26
 
27
27
  [![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
28
28
  [![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
29
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
29
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/DaitTHU/unitx/blob/main/LICENSE)
30
30
 
31
31
  A modern, intuitive unit library for Python 3.12+.
32
32
  Exact unit algebra, expressive type hints, and NumPy integration.
@@ -129,7 +129,7 @@ plt.title('Blackbody radiation')
129
129
  plt.show()
130
130
  ```
131
131
 
132
- ![Blackbody spectral radiance](docs/images/blackbody.png)
132
+ ![Blackbody spectral radiance](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.png)
133
133
 
134
134
  One Quantity wraps the entire ndarray with one unit. NumPy handles broadcasting;
135
135
  unitx checks dimensions and combines units. `SI.h` and `SI.kB` retain Decimal
@@ -139,7 +139,7 @@ values in the catalogue and enter NumPy calculations as floats.
139
139
  `.value_in(unit)` also converts it to a chosen unit. Implicit unit removal with
140
140
  `np.asarray(quantity)` or `np.array(quantity)` raises TypeError.
141
141
 
142
- The [blackbody notebook](examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
142
+ The [blackbody notebook](https://github.com/DaitTHU/unitx/blob/main/examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
143
143
  without an explicit dtype. This automatic construction inference is checked
144
144
  with NumPy 2.5 stubs and Pyright; the example also runs on NumPy 2.1. Older
145
145
  NumPy stubs may still infer Any for this expression. NumPy's own stubs can
@@ -147,9 +147,9 @@ infer different types for `np.array` and `np.asarray`;
147
147
  `np.array([...]) * unit` can become Any. `unit * array` and
148
148
  `Quantity(array, unit)` provide alternative construction forms. Arbitrary
149
149
  shape/dtype inference and wrapped return types for every NumPy function are not
150
- promised. See the [supported operations, storage rules, and typing limits](docs/numpy.md).
150
+ promised. See the [supported operations, storage rules, and typing limits](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md).
151
151
 
152
- The [physics notebooks](examples/README.md) also cover damped motion, Gaussian
152
+ The [physics notebooks](https://github.com/DaitTHU/unitx/blob/main/examples/README.md) also cover damped motion, Gaussian
153
153
  wave-packet spreading, optical attenuation, and correlated measurement uncertainty.
154
154
  They include explanations and numerical checks; plots are generated when run,
155
155
  keeping saved notebooks small.
@@ -197,7 +197,7 @@ NumPy numerical operations instead follow the documented array conversion,
197
197
  promotion, rounding, and overflow rules. Array comparisons return boolean
198
198
  masks, and NumPy-backed quantities are unhashable.
199
199
 
200
- Read the [scalar numerical contract](docs/scalars.md) for Decimal conversion,
200
+ Read the [scalar numerical contract](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md) for Decimal conversion,
201
201
  exact comparisons, powers, tolerances, and optional SymPy factorization.
202
202
 
203
203
  ## Expressions and custom units
@@ -236,7 +236,7 @@ Definitions register spellings in the current process and return a new Unit.
236
236
  Use `Factor` or `SymbolicConstant` with a unit when an additional exact unit
237
237
  scale is intended; ordinary numbers construct quantities.
238
238
 
239
- See the [unit and quantity guide](docs/units.md) for ScaledUnit, dynamic
239
+ See the [unit and quantity guide](https://github.com/DaitTHU/unitx/blob/main/docs/units.md) for ScaledUnit, dynamic
240
240
  registration, spelling-specific prefix permissions, catalogue conventions,
241
241
  copying, and serialization.
242
242
 
@@ -264,11 +264,11 @@ with `_` are internal.
264
264
 
265
265
  ## Documentation and development
266
266
 
267
- - [Unit and quantity guide](docs/units.md)
268
- - [Scalar numerical behavior](docs/scalars.md)
269
- - [NumPy support matrix and typing](docs/numpy.md)
270
- - [Migration from 0.3.0](docs/migration.md)
271
- - [Changelog](CHANGELOG.md)
267
+ - [Unit and quantity guide](https://github.com/DaitTHU/unitx/blob/main/docs/units.md)
268
+ - [Scalar numerical behavior](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md)
269
+ - [NumPy support matrix and typing](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md)
270
+ - [Migration from 0.3.0](https://github.com/DaitTHU/unitx/blob/main/docs/migration.md)
271
+ - [Changelog](https://github.com/DaitTHU/unitx/blob/main/CHANGELOG.md)
272
272
 
273
273
  Run the checks from the repository root:
274
274
 
@@ -283,9 +283,9 @@ Pytest includes runtime tests, source doctests, and Pyright checks. CI covers
283
283
  Python 3.12–3.15, optional SymPy, and minimum/current NumPy versions. Strict
284
284
  scalar consumers are also checked without NumPy installed.
285
285
 
286
- Publishing a GitHub Release triggers the [release workflow](.github/workflows/release.yml)
286
+ Publishing a GitHub Release triggers the [release workflow](https://github.com/DaitTHU/unitx/blob/main/.github/workflows/release.yml)
287
287
  to validate and upload wheel/sdist distributions to PyPI. Manual workflow runs
288
288
  validate and store distributions without uploading them. Release tags must
289
289
  match the project version.
290
290
 
291
- Licensed under the [MIT License](LICENSE).
291
+ Licensed under the [MIT License](https://github.com/DaitTHU/unitx/blob/main/LICENSE).
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![PyPI version](https://img.shields.io/pypi/v/unitx)](https://pypi.org/project/unitx/)
4
4
  [![Python versions](https://img.shields.io/pypi/pyversions/unitx)](https://pypi.org/project/unitx/)
5
- [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
5
+ [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/DaitTHU/unitx/blob/main/LICENSE)
6
6
 
7
7
  A modern, intuitive unit library for Python 3.12+.
8
8
  Exact unit algebra, expressive type hints, and NumPy integration.
@@ -105,7 +105,7 @@ plt.title('Blackbody radiation')
105
105
  plt.show()
106
106
  ```
107
107
 
108
- ![Blackbody spectral radiance](docs/images/blackbody.png)
108
+ ![Blackbody spectral radiance](https://raw.githubusercontent.com/DaitTHU/unitx/main/docs/images/blackbody.png)
109
109
 
110
110
  One Quantity wraps the entire ndarray with one unit. NumPy handles broadcasting;
111
111
  unitx checks dimensions and combines units. `SI.h` and `SI.kB` retain Decimal
@@ -115,7 +115,7 @@ values in the catalogue and enter NumPy calculations as floats.
115
115
  `.value_in(unit)` also converts it to a chosen unit. Implicit unit removal with
116
116
  `np.asarray(quantity)` or `np.array(quantity)` raises TypeError.
117
117
 
118
- The [blackbody notebook](examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
118
+ The [blackbody notebook](https://github.com/DaitTHU/unitx/blob/main/examples/blackbody.ipynb) uses `np.asarray([...]) * unit`
119
119
  without an explicit dtype. This automatic construction inference is checked
120
120
  with NumPy 2.5 stubs and Pyright; the example also runs on NumPy 2.1. Older
121
121
  NumPy stubs may still infer Any for this expression. NumPy's own stubs can
@@ -123,9 +123,9 @@ infer different types for `np.array` and `np.asarray`;
123
123
  `np.array([...]) * unit` can become Any. `unit * array` and
124
124
  `Quantity(array, unit)` provide alternative construction forms. Arbitrary
125
125
  shape/dtype inference and wrapped return types for every NumPy function are not
126
- promised. See the [supported operations, storage rules, and typing limits](docs/numpy.md).
126
+ promised. See the [supported operations, storage rules, and typing limits](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md).
127
127
 
128
- The [physics notebooks](examples/README.md) also cover damped motion, Gaussian
128
+ The [physics notebooks](https://github.com/DaitTHU/unitx/blob/main/examples/README.md) also cover damped motion, Gaussian
129
129
  wave-packet spreading, optical attenuation, and correlated measurement uncertainty.
130
130
  They include explanations and numerical checks; plots are generated when run,
131
131
  keeping saved notebooks small.
@@ -173,7 +173,7 @@ NumPy numerical operations instead follow the documented array conversion,
173
173
  promotion, rounding, and overflow rules. Array comparisons return boolean
174
174
  masks, and NumPy-backed quantities are unhashable.
175
175
 
176
- Read the [scalar numerical contract](docs/scalars.md) for Decimal conversion,
176
+ Read the [scalar numerical contract](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md) for Decimal conversion,
177
177
  exact comparisons, powers, tolerances, and optional SymPy factorization.
178
178
 
179
179
  ## Expressions and custom units
@@ -212,7 +212,7 @@ Definitions register spellings in the current process and return a new Unit.
212
212
  Use `Factor` or `SymbolicConstant` with a unit when an additional exact unit
213
213
  scale is intended; ordinary numbers construct quantities.
214
214
 
215
- See the [unit and quantity guide](docs/units.md) for ScaledUnit, dynamic
215
+ See the [unit and quantity guide](https://github.com/DaitTHU/unitx/blob/main/docs/units.md) for ScaledUnit, dynamic
216
216
  registration, spelling-specific prefix permissions, catalogue conventions,
217
217
  copying, and serialization.
218
218
 
@@ -240,11 +240,11 @@ with `_` are internal.
240
240
 
241
241
  ## Documentation and development
242
242
 
243
- - [Unit and quantity guide](docs/units.md)
244
- - [Scalar numerical behavior](docs/scalars.md)
245
- - [NumPy support matrix and typing](docs/numpy.md)
246
- - [Migration from 0.3.0](docs/migration.md)
247
- - [Changelog](CHANGELOG.md)
243
+ - [Unit and quantity guide](https://github.com/DaitTHU/unitx/blob/main/docs/units.md)
244
+ - [Scalar numerical behavior](https://github.com/DaitTHU/unitx/blob/main/docs/scalars.md)
245
+ - [NumPy support matrix and typing](https://github.com/DaitTHU/unitx/blob/main/docs/numpy.md)
246
+ - [Migration from 0.3.0](https://github.com/DaitTHU/unitx/blob/main/docs/migration.md)
247
+ - [Changelog](https://github.com/DaitTHU/unitx/blob/main/CHANGELOG.md)
248
248
 
249
249
  Run the checks from the repository root:
250
250
 
@@ -259,9 +259,9 @@ Pytest includes runtime tests, source doctests, and Pyright checks. CI covers
259
259
  Python 3.12–3.15, optional SymPy, and minimum/current NumPy versions. Strict
260
260
  scalar consumers are also checked without NumPy installed.
261
261
 
262
- Publishing a GitHub Release triggers the [release workflow](.github/workflows/release.yml)
262
+ Publishing a GitHub Release triggers the [release workflow](https://github.com/DaitTHU/unitx/blob/main/.github/workflows/release.yml)
263
263
  to validate and upload wheel/sdist distributions to PyPI. Manual workflow runs
264
264
  validate and store distributions without uploading them. Release tags must
265
265
  match the project version.
266
266
 
267
- Licensed under the [MIT License](LICENSE).
267
+ Licensed under the [MIT License](https://github.com/DaitTHU/unitx/blob/main/LICENSE).
@@ -79,11 +79,13 @@ methods, mixed array types, and keywords fail explicitly.
79
79
  | power, float_power / `**` | Dimensional bases require a finite real scalar exponent; dimensionless bases/exponents normalize their scales |
80
80
  | sin, cos, tan, exp, expm1, log, log2, log10, log1p | Require coherent dimensionless values; return dimensionless Quantity |
81
81
  | isfinite, isnan, isinf, signbit | Bare boolean results |
82
- | add.reduce, add.accumulate | Preserve unit; accept axis, dtype, out, plus keepdims for reduce |
82
+ | modf | Fractional and integral parts in the input unit |
83
+ | frexp | Mantissa in the input unit; bare integer binary exponent |
84
+ | add.reduce, add.accumulate | Preserve unit; accept axis, dtype, out, plus keepdims, initial, where for reduce |
83
85
  | multiply.reduce | Product unit rules below; accepts axis, dtype, keepdims, initial, where, out |
84
86
 
85
87
  Ufunc `__call__` accepts `where`, `dtype`, `casting`, `order`, `subok`, and
86
- single-output `out` as described below. Each kernel validates its own options.
88
+ `out` as described below (two outputs for modf/frexp). Each kernel validates its own options.
87
89
  `where` is a bare boolean scalar
88
90
  or plain boolean ndarray; masked-out positions without an output buffer follow
89
91
  NumPy's uninitialized-result behavior. Numeric outputs must stay in the
@@ -97,21 +99,25 @@ functions, including exp/log. Python scalar numerical semantics remain native.
97
99
  | --- | --- | --- |
98
100
  | reshape, transpose | Preserve unit | shape/order/copy; axes |
99
101
  | concatenate, stack | Convert to first Quantity's unit; bare arrays remain dimensionless | axis, dtype, casting, out; dtype and out are mutually exclusive |
100
- | sum, mean | Preserve unit | axis, dtype, keepdims, out |
102
+ | sum | Preserve unit | axis, dtype, keepdims, initial, where, out |
103
+ | mean | Preserve unit | axis, dtype, keepdims, where, out |
101
104
  | prod | Product unit rules below | axis, dtype, keepdims, initial, where, out |
102
105
  | median | Preserve unit | axis, keepdims, out; overwrite_input=False |
103
- | std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims, out |
106
+ | std, var | Preserve unit / square unit | axis, dtype, ddof, keepdims, where, out |
104
107
  | cumsum | Preserve unit | axis, dtype, out |
105
108
  | argmin, argmax | Bare indices | axis, keepdims, out |
106
109
  | trapezoid | Multiply ordinate and coordinate units | x, scalar dx, axis; no out |
110
+ | diff | Preserve input unit | n, axis, prepend, append; no out |
111
+ | gradient | Divide input unit by each coordinate unit | scalar spacings or coordinate arrays, axis, edge_order; no out |
107
112
  | isclose, allclose | Bare mask / Python bool | rtol, atol, equal_nan |
108
113
 
109
114
  Supply the first magnitude argument positionally; concatenate/stack take a
110
115
  sequence. Options follow each supported signature, including positional out
111
116
  checks. Function and reduction outputs follow the rules below;
112
- overwrite_input=True is rejected. Reduction/statistical `where` and `initial`
113
- are supported only for prod/multiply.reduce. Unsupported mean, correction,
114
- and other keywords raise TypeError.
117
+ overwrite_input=True is rejected. Reduction/statistical `where` is supported
118
+ for sum, mean, std, var, add.reduce, prod, and multiply.reduce; `initial` is
119
+ supported only for sum/add.reduce and prod/multiply.reduce. Precomputed `mean`,
120
+ `correction`, and other unsupported keywords raise TypeError.
115
121
  There is no `__setitem__`; `q += other` creates a result and rebinds q.
116
122
 
117
123
  `np.trapezoid(y, x=x)` accepts a Quantity for y, x, or both and returns a
@@ -124,6 +130,99 @@ coordinate order (including reversed or nonmonotonic x), broadcasting, and
124
130
  empty intervals follow [NumPy trapezoid](https://numpy.org/doc/stable/reference/generated/numpy.trapezoid.html).
125
131
  No coordinate sorting, interpolation, dtype option, or output buffer is added.
126
132
 
133
+ ## Differences and gradients
134
+
135
+ `np.diff(q, n=1, axis=-1)` computes differences in q's stored coordinates and
136
+ retains its unit for every order n. `prepend` and `append` may be numeric
137
+ scalars/arrays or Quantities; their dimensions must match the input, and their
138
+ values convert to the input unit before differencing. Bare boundaries are
139
+ dimensionless, including bare zero. A bare input with a Quantity boundary is
140
+ also dimensionless. Scaled dimensionless boundaries therefore normalize to the
141
+ input's coordinates. Explicit list inputs/boundaries remain unsupported.
142
+
143
+ With `n=0`, diff returns its input object unchanged and ignores axis and
144
+ boundaries. Other orders follow [NumPy diff](https://numpy.org/doc/stable/reference/generated/numpy.diff.html)
145
+ for shapes, scalar-boundary expansion, dtype promotion, unsigned wraparound,
146
+ and empty results. A difference is not a derivative: its unit is not divided
147
+ by a coordinate unit or raised to n.
148
+
149
+ `np.gradient(f, *spacing, axis=None, edge_order=1)` accepts numeric or Quantity
150
+ input and spacings. Each spacing is a scalar step or one-dimensional coordinate
151
+ array; bare inputs and spacings are dimensionless. A single scalar step applies
152
+ to every selected axis. Otherwise supply one spacing per selected axis, in
153
+ the order given by axis. Each component has unit `f.unit / spacing.unit`,
154
+ including exact ScaledUnit factors. No spacing means dimensionless unit steps.
155
+ The kernels use stored numerical coordinates; no implicit SI conversion is
156
+ needed because each result retains the corresponding unit ratio.
157
+
158
+ One selected axis returns one Quantity; multiple axes return a tuple of
159
+ Quantities, which may have different dimensions. No selected axes returns an
160
+ empty tuple. Output shapes, nonuniform/decreasing coordinates, edge_order,
161
+ dtype, and numerical warnings follow
162
+ [NumPy gradient](https://numpy.org/doc/stable/reference/generated/numpy.gradient.html).
163
+ Coordinates are not sorted or interpolated. Neither function accepts out,
164
+ where, or dtype. These NumPy entry points require at least one Quantity among
165
+ their dispatched inputs; the existing NumPy stub limitations still apply.
166
+
167
+ ```python
168
+ time = Quantity(np.array([0.0, 1, 3, 6]), 's')
169
+ distance = Quantity(np.array([0.0, 2, 6, 12]), 'm')
170
+ increments = np.diff(distance)
171
+ assert increments.unit == Unit('m')
172
+ velocity = np.gradient(distance, time, edge_order=2)
173
+ assert velocity.unit == Unit('m/s')
174
+ np.testing.assert_allclose(velocity.value, 2)
175
+ assert np.trapezoid(velocity, time).isclose(distance[-1] - distance[0])
176
+ ```
177
+
178
+ ## Masked sums and statistics
179
+
180
+ `np.sum(q)` and `np.add.reduce(q)` preserve q's unit, including ScaledUnit and
181
+ scaled dimensionless units. Their default axes are all axes and axis 0,
182
+ respectively. Both accept `initial`, a numeric scalar or scalar Quantity,
183
+ including NumPy scalars and zero-dimensional arrays. A Quantity initial must
184
+ have the input's dimension and is converted to the input unit, then added once
185
+ to every result slice. Bare nonzero initial values are coherent dimensionless
186
+ values; they do not implicitly acquire the input unit. Bare zero is accepted
187
+ as the additive identity in any dimension, while a Quantity zero retains its
188
+ declared dimension. Empty or fully masked sums return zero in the input unit,
189
+ or the converted initial when supplied. Explicit `initial=None` uses NumPy's
190
+ first-element semantics and fails on empty reductions.
191
+
192
+ The input and explicit `dtype` select the accumulator; initial does not promote
193
+ it. NumPy casts the converted initial into that dtype before summation, so an
194
+ integer accumulator can truncate a fractional initial. Decimal/Fraction initial
195
+ values enter the NumPy floating domain. Complex initial values follow NumPy's
196
+ casting rules, even for complex zero. Unsupported initial arrays, bools, or
197
+ incompatible dimensions fail before writing an output.
198
+
199
+ `where` on sum, add.reduce, mean, std, and var is a bare boolean scalar or plain
200
+ boolean ndarray broadcast to the input shape. It selects **input elements**;
201
+ all result positions are written when `out` is supplied. Different slices may
202
+ have different selected counts. Mean and standard deviation retain the input
203
+ unit; variance has its square. Statistics use stored coordinates, including
204
+ for scaled dimensionless input. NumPy controls dtype, complex statistics, NaN/Inf,
205
+ empty-sample warnings, and degrees of freedom (N in `N - ddof` is the selected count).
206
+ Masks do not imply automatic NaN omission. These operations use the same staged
207
+ output rules as other reductions, including exact shape and unchanged targets
208
+ on computation, unit, shape, or casting errors. `add.accumulate`, cumsum, and
209
+ median do not gain `where` or `initial`.
210
+
211
+ ```python
212
+ samples = Quantity(np.array([[1.0, 2, 3], [4, 5, 6]]), 'm')
213
+ selected = np.array([[True, False, True], [False, True, True]])
214
+ totals = np.sum(samples, axis=1, where=selected, initial=Quantity(50, 'cm'))
215
+ assert totals.unit == samples.unit
216
+ np.testing.assert_allclose(totals.value, [4.5, 11.5])
217
+ means = np.mean(samples, axis=1, where=selected)
218
+ np.testing.assert_allclose(means.value, [2, 5.5])
219
+ ```
220
+
221
+ The numerical rules follow [NumPy sum](https://numpy.org/doc/stable/reference/generated/numpy.sum.html),
222
+ [mean](https://numpy.org/doc/stable/reference/generated/numpy.mean.html), and
223
+ [var](https://numpy.org/doc/stable/reference/generated/numpy.var.html), with the
224
+ unit and output constraints above.
225
+
127
226
  ## Product reductions
128
227
 
129
228
  `np.prod(q)` reduces all axes by default; `np.multiply.reduce(q)` defaults to
@@ -234,13 +333,59 @@ indices = np.empty(3, dtype=np.intp)
234
333
  assert np.argmax(q, axis=0, out=indices) is indices
235
334
  ```
236
335
 
237
- `out=None` and ufunc `out=(None,)` allocate ordinary results.
238
- Multiple-output ufuncs and product accumulations remain unsupported.
336
+ `out=None` and ufunc `out=(None,)` allocate ordinary single-output results.
337
+ The supported multiple-output calls are described below; other multiple-output
338
+ ufuncs and product accumulations remain unsupported.
239
339
  Output writes preserve the magnitude's type and dtype, so the covariant
240
340
  `Quantity[T]` contract remains valid; no setter or arbitrary replacement of T
241
341
  is introduced. NumPy's own stubs do not accept Quantity outputs or infer wrapped
242
342
  return types; these runtime calls may require a local type-checker suppression.
243
343
 
344
+ ## Multiple-output decompositions
345
+
346
+ `np.modf(q)` returns `(fractional, integral)`, both Quantities with q's unit.
347
+ `np.frexp(q)` returns `(mantissa, exponent)`, with q's unit on the mantissa and
348
+ a bare integer ndarray or NumPy scalar for the binary exponent. These functions
349
+ decompose **stored coordinates**, including for ScaledUnit and scaled
350
+ dimensionless inputs: convert q to the desired unit before decomposing it.
351
+ Changing the input unit can change both numerical outputs. There is no implicit
352
+ conversion to coherent dimensionless values. Thus `fractional + integral`
353
+ reconstructs q. For frexp, reconstruct with
354
+ `Quantity(np.ldexp(mantissa.value, exponent), mantissa.unit)`; separately
355
+ computing `np.exp2(exponent)` can overflow for large finite inputs. Dtype,
356
+ signed-zero, NaN/Inf, and real-input restrictions follow
357
+ [NumPy modf](https://numpy.org/doc/stable/reference/generated/numpy.modf.html) and
358
+ [frexp](https://numpy.org/doc/stable/reference/generated/numpy.frexp.html).
359
+ Only their ordinary `__call__` operation is supported.
360
+
361
+ Both accept `out=(first, second)` or positional output arguments. Each `None`
362
+ allocates that output; `(None, None)` allocates both. Every unit-bearing output
363
+ requires a Quantity with a writable plain numeric ndarray; frexp's exponent
364
+ requires a bare integer ndarray. The existing conversion, casting, and `where`
365
+ rules apply independently to each output. Supplied buffers must all have the
366
+ common broadcast shape of the inputs, mask, and outputs. An allocated output
367
+ also has that shape. False mask positions retain supplied values; without a
368
+ buffer those positions are unspecified.
369
+
370
+ ```python
371
+ parts = Quantity(np.array([1.25, -2.5]), 'm')
372
+ fractional = Quantity(np.empty(2), 'cm')
373
+ integral = Quantity(np.empty(2), 'm')
374
+ f, i = np.modf(parts, out=(fractional, integral))
375
+ assert f is fractional and i is integral
376
+ np.testing.assert_array_equal(f.value, [25, -50])
377
+ np.testing.assert_array_equal(i.value, [1, -2])
378
+ ```
379
+
380
+ All supplied outputs are converted and staged before any is written. A shape,
381
+ unit, casting, read-only, computation, or conversion failure leaves **all**
382
+ targets unchanged. Input/output overlap and masks sharing output storage are
383
+ supported. The two output buffers may share storage only when their elements
384
+ do not overlap; overlapping outputs raise ValueError before writing. This
385
+ avoids one result overwriting another. Final writes have the same concurrent
386
+ mutation and external-buffer limitations as single outputs, and require
387
+ temporary storage. The covariance and NumPy-stub limitations above still apply.
388
+
244
389
  ## Close comparisons and typing
245
390
 
246
391
  `q.isclose(other, rel_tol=1e-9, abs_tol=0)` uses the symmetric formula in
@@ -4,7 +4,7 @@ build-backend = 'hatchling.build'
4
4
 
5
5
  [project]
6
6
  name = 'unitx'
7
- version = '0.8.4'
7
+ version = '0.8.6'
8
8
  description = 'A modern, intuitive unit library, with exact unit algebra, expressive type hints, and NumPy integration.'
9
9
  readme = 'README.md'
10
10
  requires-python = '>=3.12'