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.
- {unitx-0.8.4 → unitx-0.8.6}/CHANGELOG.md +33 -0
- {unitx-0.8.4 → unitx-0.8.6}/PKG-INFO +15 -15
- {unitx-0.8.4 → unitx-0.8.6}/README.md +14 -14
- {unitx-0.8.4 → unitx-0.8.6}/docs/numpy.md +154 -9
- {unitx-0.8.4 → unitx-0.8.6}/pyproject.toml +1 -1
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numpy.py +218 -46
- {unitx-0.8.4 → unitx-0.8.6}/tests/numpy_typing/check_numpy.py +15 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy.py +3 -4
- unitx-0.8.6/tests/test_numpy_differentiation.py +245 -0
- unitx-0.8.6/tests/test_numpy_multi_outputs.py +286 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_outputs.py +4 -3
- unitx-0.8.6/tests/test_numpy_statistics.py +254 -0
- {unitx-0.8.4 → unitx-0.8.6}/.github/workflows/ci.yml +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/.github/workflows/release.yml +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/.gitignore +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/LICENSE +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/conftest.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/docs/images/blackbody.png +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/docs/migration.md +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/docs/scalars.md +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/docs/units.md +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/README.md +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/blackbody.ipynb +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/damped_oscillator.ipynb +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/gaussian_wavepacket.ipynb +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/optical_attenuation.ipynb +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/examples/pendulum_uncertainty.ipynb +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/pyrightconfig.json +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/__init__.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_constnamespace.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numerics.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_numpy_typing.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/_unicode.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/dimension.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/exceptions.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/factor.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/monomial.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/py.typed +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/quantity.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/__init__.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/bases.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/constants.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/si/units.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/singleunit.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unit.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unitparser.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/src/unitx/unitregistry.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/__init__.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/_notebooks.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/example_typing/check_blackbody.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_builtin_definitions.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_dimension.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_examples.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_factor.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_import.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_monomial.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_numeric.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_integration.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_numpy_products.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_quantity.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_si.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_singleunit.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_typing.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_unicode.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_unit.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_unit_definition.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_unitparser.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_unitregistry.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/test_warnings.py +0 -0
- {unitx-0.8.4 → unitx-0.8.6}/tests/typing/check_quantity.py +0 -0
- {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.
|
|
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
|
[](https://pypi.org/project/unitx/)
|
|
28
28
|
[](https://pypi.org/project/unitx/)
|
|
29
|
-
[](LICENSE)
|
|
29
|
+
[](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
|
-

|
|
132
|
+

|
|
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
|
[](https://pypi.org/project/unitx/)
|
|
4
4
|
[](https://pypi.org/project/unitx/)
|
|
5
|
-
[](LICENSE)
|
|
5
|
+
[](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
|
-

|
|
108
|
+

|
|
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
|
-
|
|
|
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
|
-
|
|
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
|
|
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`
|
|
113
|
-
|
|
114
|
-
|
|
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
|
-
|
|
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.
|
|
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'
|