unitx 0.17.2__tar.gz → 0.17.4__tar.gz

{unitx-0.17.2 → unitx-0.17.4}/.github/consumers/arrays.py

@@ -6,10 +6,11 @@ import numpy as np
 from numpy.typing import NDArray
 
 from unitx import AffineQuantity, LogQuantity, LogUnit, Quantity, Unit
+from unitx import math as unitx_math
 from unitx._numerics import Array
 from unitx._numerics.numpy_typing import NumpyValue
 from unitx.cgs import emu, esu, gaussian, hl
-from unitx.exceptions import DimensionError
+from unitx.exceptions import DimensionError, ImplicitConversionError, UnitOperationError
 from unitx.si import si
 
 type ArrayQuantity = Quantity[Array] | AffineQuantity[Array] | LogQuantity[Array]
@@ -29,13 +30,13 @@ def check_components(signal: Quantity[NDArray[np.complex128]]) -> None:
 
 def check_arrays(values: NDArray[np.float64]) -> None:
     ratio = Quantity(values, si.percent)
-    assert_type(ratio.n, NumpyValue)
+    assert_type(ratio.n, NDArray[np.float64] | np.float64)
     np.testing.assert_allclose(ratio.n, values / 100)
     assert_type(ratio.as_pair(), tuple[NDArray[np.float64], Unit])
     assert ratio.as_pair()[0] is values
-    assert_type(ratio.to_base(), Quantity[NumpyValue])
-    assert_type(ratio.simplify(), Quantity[NumpyValue])
-    assert_type(Quantity(values, si.m).compact(), Quantity[NumpyValue])
+    assert_type(ratio.to_base(), Quantity[NDArray[np.float64] | np.float64])
+    assert_type(ratio.simplify(), Quantity[NDArray[np.float64] | np.float64])
+    assert_type(Quantity(values, si.m).compact(), Quantity[NDArray[np.float64] | np.float64])
     assert Quantity(values, si.cm * si.m).simplify().unit == si.m**2
     signal = Quantity(np.asarray([3 + 4j], dtype=np.complex128), si.V)
     check_components(signal)
@@ -555,7 +556,7 @@ def check_array_methods(target: NDArray[np.float64]) -> None:
     assert_type(columns, Quantity[NDArray[np.float32]])
     assert_type(columns.ravel(), Quantity[NDArray[np.float32]])
     assert_type(columns.copy(), Quantity[NDArray[np.float32]])
-    assert_type(columns.mean(axis=0), Quantity[NumpyValue])
+    assert_type(columns.mean(axis=0), Quantity[NDArray[np.float32] | np.float32])
     assert np.shares_memory(columns.value, values)
     assert not np.shares_memory(columns.copy().value, values)
     out = Quantity(target, si.cm)
@@ -578,3 +579,96 @@ def check_array_methods(target: NDArray[np.float64]) -> None:
 
 
 check_array_methods(np.zeros(2, dtype=np.float64))
+
+
+def check_calculus_types(values: NDArray[np.float64]) -> None:
+    coordinate = Quantity(values, si.s)
+    signal = 2 * Quantity(values, si.A)
+    assert_type(coordinate.to(si.ms), Quantity[NDArray[np.float64] | np.float64])
+    assert_type(signal * coordinate, Quantity[NDArray[np.float64] | np.float64])
+    weights = cast(Quantity[Array], np.gradient(coordinate, axis=0))
+    weights[[0, -1]] /= 2
+    integral = cast(Quantity[Array], np.trapezoid(signal, coordinate))
+    assert np.sum(signal * weights).isclose(integral)
+    points = AffineQuantity(values, si.degC)
+    increments = cast(Quantity[Array], np.diff(points))
+    assert increments.unit == si.degC.delta_unit
+    assert np.diff(points, n=0) is points
+    rate = cast(Quantity[Array], np.gradient(points, coordinate, axis=0))
+    np.testing.assert_allclose(rate.value, 1)
+    levels = LogQuantity(values, si.dBm)
+    differences = cast(Quantity[Array], np.diff(levels))
+    assert differences.unit == si.dBm.delta_unit
+    try:
+        np.asarray(coordinate)
+    except ImplicitConversionError as error:
+        assert isinstance(error, TypeError)
+    else:
+        error_message = 'Array coercion must preserve the explicit numerical boundary.'
+        raise AssertionError(error_message)
+    try:
+        np.add(points, points)
+    except UnitOperationError as error:
+        assert isinstance(error, TypeError)
+    else:
+        error_message = 'Adding two points must fail.'
+        raise AssertionError(error_message)
+
+
+check_calculus_types(np.array([0.0, 1, 3, 6]))
+
+
+def check_scientific_inference(values: NDArray[np.float64]) -> None:
+    spectrum = Quantity(values.reshape(2, 2, 2), si.J)
+    mask = np.array([True, False])
+    selected = spectrum[mask, 0, 0]
+    assert_type(selected, Quantity[NDArray[np.float64]])
+    assert_type(spectrum[:, 0, 0], Quantity[NDArray[np.float64]])
+    phase = 1j * selected
+    assert_type(phase, Quantity[NDArray[np.complex128] | np.complex128])
+    assert_type(spectrum.sum(), Quantity[np.float64])
+    assert_type(spectrum.sum().value_in(si.J), np.float64)
+    assert_type(selected.astype(float), Quantity[NDArray[np.float64]])
+    assert_type(Quantity(np.float32(2), si.percent).n, np.float32)
+    np.testing.assert_array_equal(selected.value, [values[0]])
+    np.testing.assert_array_equal(phase.value, 1j * selected.value)
+    assert spectrum.sum().value_in(si.J) == np.sum(values)
+
+
+check_scientific_inference(np.arange(8, dtype=np.float64))
+
+
+def check_complex_field(values: NDArray[np.float64]) -> None:
+    z = values * si.m
+    gouy = unitx_math.atan(z / (0.5 * si.m))
+    geometry = unitx_math.hypot(1, z / (0.5 * si.m))
+    field = unitx_math.conj(unitx_math.exp(1j * gouy) / geometry)
+    assert_type(field, Quantity[NDArray[np.complex128] | np.complex128])
+    for _ in range(3):
+        field *= unitx_math.exp(-1j * gouy)
+        assert_type(field, Quantity[NDArray[np.complex128] | np.complex128])
+    angle = np.arctan(np.linspace(-1, 1, 5) / 0.5)
+    expected = np.exp(-4j * angle) / np.hypot(1, np.linspace(-1, 1, 5) / 0.5)
+    np.testing.assert_allclose(field.n, expected, rtol=1e-14)
+
+
+check_complex_field(np.linspace(-1, 1, 5))
+
+
+def check_shape_axes(values: NDArray[np.float64]) -> None:
+    q = Quantity(values.reshape(2, 1, 4), si.m)
+    permuted = q.transpose(2, 0, 1).squeeze(-1)
+    assert_type(permuted, Quantity[NDArray[np.float64]])
+    assert np.shares_memory(permuted.value, values)
+    np.testing.assert_array_equal(permuted.value, values.reshape(2, 4).T)
+    assert_type(Quantity(np.float32(2), si.m).squeeze(), Quantity[np.float32])
+    for point in (
+        AffineQuantity(values.reshape(2, 1, 4), si.degC),
+        LogQuantity(values.reshape(2, 1, 4), si.dBm),
+    ):
+        transformed = point.transpose((2, 0, 1)).squeeze(axis=-1)
+        assert type(transformed) is type(point) and transformed.unit is point.unit
+        np.testing.assert_array_equal(transformed.value, values.reshape(2, 4).T)
+
+
+check_shape_axes(np.arange(8.0))

{unitx-0.17.2 → unitx-0.17.4}/.github/consumers/scalars.py

@@ -26,6 +26,7 @@ from unitx import (
     time,
 )
 from unitx.cgs import cgs, emu, esu, gaussian, hl
+from unitx.exceptions import ImplicitConversionError, UnitOperationError, UnitxError
 from unitx.factor import Factor
 from unitx.imperial import imperial
 from unitx.quantity import quantity as decimal_quantity
@@ -120,6 +121,9 @@ assert_type(root, Quantity[float])
 assert root == 3 * si.m
 assert math.sin(90 * si.deg).value == 1.0
 assert math.hypot(3 * si.m, 400 * si.cm) == 5 * si.m
+assert_type(math.exp(1j), Quantity[complex])
+assert_type(math.conj(2 + 3j), Quantity[complex])
+assert math.conj(Quantity(2 + 3j, si.m)).value == 2 - 3j
 
 stamp = time.time()
 start = time.perf_counter()
@@ -185,3 +189,14 @@ assert 'matplotlib' not in sys.modules
 # The sibling stub must retain the module-level Decimal factory.
 assert_type(decimal_quantity(1.25, si.m), Quantity[Decimal])
 assert decimal_quantity(1.25, si.m).value == Decimal('1.25')
+
+assert issubclass(UnitOperationError, TypeError)
+assert issubclass(UnitOperationError, UnitxError)
+assert issubclass(ImplicitConversionError, UnitOperationError)
+try:
+    _ = (20 @ si.degC) * 2
+except UnitOperationError as error:
+    assert isinstance(error, TypeError)
+else:
+    error_message = 'Multiplying a coordinate point must fail.'
+    raise AssertionError(error_message)

{unitx-0.17.2 → unitx-0.17.4}/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [0.17.4] - 2026-10-28
+
+### Added
+
+- Add typed `transpose` and `squeeze` methods for Quantity, AffineQuantity and
+  LogQuantity, preserving full units, coordinate families and NumPy views.
+- Add `unitx.math.conj` and complex inputs to `unitx.math.exp` for typed complex
+  phases, preserving complete units and the existing NumPy dispatch rules.
+
+### Changed
+
+- Expose `n` as an ordinary read-only property and retain float inference for
+  scientific scalar formulas, with exact runtime conversion rules unchanged.
+- Preserve known NumPy dtypes through the supported `unitx.math` phase functions,
+  mixed real/complex algebra, absolute values and same-dtype augmented products.
+- Retain ndarray results and numeric dtypes for slices, boolean indices,
+  ellipses, new axes and tuples starting with one of these indices.
+- Infer complex64/complex128 for float32/float64 multiplication and division
+  with Python complex scalars, including reflected operations.
+- Infer concrete NumPy dtype and container types for explicit `astype` calls,
+  and NumPy scalar types for complete sum/mean reductions and their numerical
+  exits, reducing the need for consumer casts and numerical conversions.
+
+## [0.17.3] - 2026-10-27
+
+### Added
+
+- Support `diff` and `gradient` on affine/logarithmic point arrays, returning
+  differences and using coordinate difference units for derivatives. Align
+  point boundaries explicitly; retain the original object for `diff(n=0)`.
+- Document reusable trapezoidal weights using `np.gradient` and an endpoint
+  correction.
+- Add `UnitOperationError` for point/difference semantic violations and its
+  `ImplicitConversionError` subclass for silent array unit removal. Both remain
+  catchable as TypeError and UnitxError; native numerical errors stay native.
+
+### Changed
+
+- Delegate direct array methods through a private lazy decorator, retaining
+  explicit signatures, method defaults and the existing NumPy unit/output rules.
+- Retain known floating/complex NumPy dtypes in linear conversions, supported
+  arithmetic and default sum/mean results, including possible NumPy scalars.
+  Preserve numeric dtypes in indexing/iteration; narrow exact Fraction
+  arithmetic and complex scalar result domains.
+
+### Fixed
+
+- Update the generator annotation on registry definition scopes to avoid the
+  deprecated Iterator overload of `contextmanager` in current type stubs.
+
 ## [0.17.2] - 2026-10-27
 
 ### Added

{unitx-0.17.2 → unitx-0.17.4}/CONTRIBUTING.md

@@ -112,10 +112,13 @@ python -m build
 python -m twine check --strict dist/*
 ```
 
-Check wheel/sdist contents, version metadata, `py.typed`, and an installed
-consumer outside the checkout. Source-tree success alone does not verify
-packaging. Use a clean export of the intended commit when separating several
-changes into independently reviewable commits.
+Build release artifacts from a clean checkout or Git export of the intended
+commit. Git's local `.git/info/exclude` is not a distribution manifest:
+building a shared working tree can include locally ignored notes in an sdist.
+Check wheel/sdist contents, version metadata, `py.typed`, and installed
+consumers outside the checkout. Source-tree success alone does not verify
+packaging. When separating changes, also validate the actual committed
+snapshots rather than only the final working tree.
 
 The [release workflow](.github/workflows/release.yml) validates distributions
 and uploads them to PyPI after a published GitHub Release. The tag must match

{unitx-0.17.2 → unitx-0.17.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unitx
-Version: 0.17.2
+Version: 0.17.4
 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.17.2 → unitx-0.17.4}/docs/architecture.md

@@ -165,6 +165,12 @@ enumerate their own reference/difference dependencies. Display, NumPy and
 serialization remain explicit integration boundaries. Numeric caches, parser
 state and reconstruction indexes remain separate from mathematical identity.
 
+Direct array methods declare their public signatures explicitly. A private
+decorator in `_numerics/methods.py` binds their defaults and lazily delegates to
+the same NumPy dispatch used by function calls. It adds no dynamic method lookup
+or separate unit rules; coordinate and linear result construction stays in the
+existing handlers. Reshape keeps its explicit positional-shape normalization.
+
 The point marker's type parameter describes the result of adding a difference,
 not the original magnitude type. This prevents the open scalar protocol from
 claiming point operands and preserves concrete result types without naming the

{unitx-0.17.2 → unitx-0.17.4}/docs/numpy/calculus.md

@@ -69,13 +69,18 @@ No coordinate sorting, interpolation, dtype option, or output buffer is added.
 
 ## Differences and gradients
 
-`np.diff(q, n=1, axis=-1)` computes differences in q's stored coordinates and
-retains its unit for every order n. `prepend` and `append` may be numeric
+`np.diff(q, n=1, axis=-1)` computes differences in q's stored coordinates.
+Linear quantities retain their unit; AffineQuantity and LogQuantity points
+return ordinary Quantities in their complete difference unit for every positive
+order n. Logarithmic differences describe changes in readings, without an
+implicit conversion to physical power or amplitude. `prepend` and `append` may be numeric
 scalars/arrays or Quantities; their dimensions must match the input, and their
 values convert to the input unit before differencing. Bare boundaries are
 dimensionless, including bare zero. A bare input with a Quantity boundary is
 also dimensionless. Scaled dimensionless boundaries therefore normalize to the
 input's coordinates. Explicit list inputs/boundaries remain unsupported.
+For points, boundaries must be compatible points and convert to the input
+coordinate first; a difference or bare zero cannot stand in for a point.
 
 With `n=0`, diff returns its input object unchanged and ignores axis and
 boundaries. Other orders follow [NumPy diff](https://numpy.org/doc/stable/reference/generated/numpy.diff.html)
@@ -83,12 +88,15 @@ for shapes, scalar-boundary expansion, dtype promotion, unsigned wraparound,
 and empty results. A difference is not a derivative: its unit is not divided
 by a coordinate unit or raised to n.
 
-`np.gradient(f, *spacing, axis=None, edge_order=1)` accepts numeric or Quantity
-input and spacings. Each spacing is a scalar step or one-dimensional coordinate
+`np.gradient(f, *spacing, axis=None, edge_order=1)` accepts numeric values,
+Quantities and coordinate points. Each spacing is a scalar difference step or one-dimensional coordinate
 array; bare inputs and spacings are dimensionless. A single scalar step applies
 to every selected axis. Otherwise supply one spacing per selected axis, in
 the order given by axis. Each component has unit `f.unit / spacing.unit`,
 including exact Unit factors. No spacing means dimensionless unit steps.
+For point-valued f, use its difference unit in the numerator. A point coordinate
+array contributes its difference unit in the denominator; a scalar point is
+not a step. Changing a coordinate origin does not change the derivative.
 The kernels use stored numerical coordinates; no implicit SI conversion is
 needed because each result retains the corresponding unit ratio.
 
@@ -112,4 +120,31 @@ np.testing.assert_allclose(velocity.value, 2)
 assert np.trapezoid(velocity, time).isclose(distance[-1] - distance[0])
 ```
 
+## Reusable trapezoidal weights
+
+For repeated weighted sums or contractions on a real one-dimensional grid of
+at least two samples, compute weights with gradient and halve the endpoints:
+
+```python
+time = Quantity(np.array([0.0, 1, 3, 6]), 's')
+current = Quantity(np.array([0.0, 2, 6, 12]), 'A')
+weights = np.gradient(time, axis=0)
+weights[[0, -1]] /= 2
+np.testing.assert_allclose(weights.value, [0.5, 1.5, 2.5, 1.5])
+assert np.sum(current * weights).isclose(np.trapezoid(current, time))
+```
+
+With no spacing argument and the default `edge_order=1`, interior gradient
+entries are `(x[i+1] - x[i-1]) / 2`, half the sum of adjacent intervals.
+Endpoints are full one-sided intervals, so their halving is essential.
+This is mathematically equivalent to trapezoidal weights; floating-point
+rounding order can differ from interval-by-interval integration.
+Decreasing and nonmonotonic coordinates retain their interval signs.
+Gradient needs at least two samples; handle empty/singleton grids locally
+only when the calculation requires them. Point coordinates return difference
+weights; logarithmic readings are not implicitly mapped to physical values.
+
+For a single integral, use `np.trapezoid`, following the linear integration
+contract above. NumPy function stubs retain the [documented typing limits](../typing.md#numpy-magnitude-types).
+
 [NumPy overview and support matrix](../numpy.md) · [Documentation index](../README.md)

{unitx-0.17.2 → unitx-0.17.4}/docs/numpy/methods.md

@@ -1,7 +1,7 @@
 # Direct array methods
 
-For NumPy magnitudes, Quantity provides `reshape`, `ravel`, `copy`, `sum`,
-`mean` and `std`. AffineQuantity and LogQuantity provide the same methods
+For NumPy magnitudes, Quantity provides `reshape`, `ravel`, `copy`, `transpose`,
+`squeeze`, `sum`, `mean` and `std`. AffineQuantity and LogQuantity provide the same methods
 except `sum`. Mean preserves a point's coordinate; standard deviation returns
 its difference unit. Logarithmic statistics operate on readings; convert to
 physical values explicitly before averaging power or amplitude.
@@ -15,6 +15,14 @@ ndarray storage, including for a NumPy scalar. Its C default follows
 can remain a NumPy scalar; ndarray input remains ndarray with the same dtype.
 Python scalar magnitudes require the scalar APIs or explicit array construction.
 
+`transpose()` reverses the axes; `transpose((2, 0, 1))` and
+`transpose(2, 0, 1)` select a permutation. Axis inputs are positional.
+`squeeze(axis=None)` removes all length-one axes, or only the selected integer
+or tuple of axes. Both retain the complete unit, coordinate family and dtype,
+and share storage for ndarray inputs. A fully squeezed ndarray remains a
+zero-dimensional ndarray; a NumPy scalar remains a NumPy scalar. Invalid
+axes raise native NumPy errors without changing the input.
+
 Reductions accept `axis`, `dtype`, `out`, `keepdims` and `where`. Sum also
 accepts a compatible `initial` (bare zero is the additive identity); std
 supports `ddof`, `correction` and a compatible precomputed `mean`. These use
@@ -34,6 +42,8 @@ np.testing.assert_allclose(samples.mean(axis=1).value, [1, 4])
 assert samples.sum(initial=Quantity(100, 'cm')) == Quantity(16, 'm')
 assert np.shares_memory(samples.ravel().value, samples.value)
 assert not np.shares_memory(samples.copy().value, samples.value)
+channels = samples.reshape(2, 1, 3).transpose(2, 0, 1).squeeze(-1)
+np.testing.assert_array_equal(channels.value, samples.value.T)
 assert np.trapezoid(np.array([1.0, 2, 3]), dx=Quantity(2, 's')) == Quantity(8, 's')
 ```
 

{unitx-0.17.2 → unitx-0.17.4}/docs/numpy.md

@@ -33,7 +33,8 @@ differences, and point sums/products are rejected.
 ## Values, storage, and precision
 
 `.value`, `.value_in(unit)`, and `.to(unit).value` are explicit numerical exits.
-`np.asarray(q)` and `np.array(q)` raise TypeError even for dimensionless q;
+`np.asarray(q)` and `np.array(q)` raise `ImplicitConversionError` (a TypeError)
+even for dimensionless q;
 use `np.asarray(q.value_in(target_unit))`.
 
 Construction, unit-only multiplication/division, and an identity conversion
@@ -71,7 +72,7 @@ produce unhashable Quantities. `bool(q)` delegates to `bool(q.value)`.
 
 ## Direct array methods
 
-Quantity provides `reshape`, `ravel`, `copy`, `sum`, `mean` and `std` for NumPy
+Quantity provides `reshape`, `ravel`, `copy`, `transpose`, `squeeze`, `sum`, `mean` and `std` for NumPy
 magnitudes. Two coordinate families provide the same methods except `sum`;
 mean preserves a point and std returns a difference. These methods preserve
 the wrapper in static types. See [array methods](numpy/methods.md) for shape,
@@ -212,8 +213,8 @@ functions, including exp/log. Python scalar arithmetic follows the separate [sca
 | argmin/nanargmin, argmax/nanargmax | Bare indices | axis, keepdims, out |
 | interp | Align x to xp's unit; retain fp's unit | finite strictly increasing 1-D xp; scalar left/right, period=None; no out |
 | trapezoid | Multiply ordinate and coordinate units | x, scalar dx, axis; no out |
-| diff | Preserve input unit | n, axis, prepend, append; no out |
-| gradient | Divide input unit by each coordinate unit | scalar spacings or coordinate arrays, axis, edge_order; no out |
+| diff | Preserve linear unit; point inputs return differences for n > 0 | n, axis, compatible point/value prepend and append; no out |
+| gradient | Divide input difference unit by each coordinate difference unit | scalar difference spacings or coordinate arrays, axis, edge_order; no out |
 | isclose, allclose | Bare mask / Python bool | rtol, atol, equal_nan |
 
 Supply the first magnitude argument positionally; concatenate/stack take a
@@ -235,8 +236,8 @@ behavior for augmented arithmetic.
 `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.
+Quantity, AffineQuantity, or LogQuantity. Ravel also has a direct method;
+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

{unitx-0.17.2 → unitx-0.17.4}/docs/stdlib.md

@@ -1,6 +1,6 @@
 # Standard-library enhancements
 
-`unitx.math` provides a finite set of unit-aware real functions. `unitx.time`
+`unitx.math` provides a finite set of unit-aware functions. `unitx.time`
 provides integer nanosecond clock readings and explicit duration adapters.
 `unitx.statistics` provides scalar means, dispersion and paired statistics.
 These modules work without NumPy installed.
@@ -9,7 +9,7 @@ These modules work without NumPy installed.
 
 | Module | Use |
 | --- | --- |
-| `unitx.math` | Unit-aware real mathematical functions with scalar and optional NumPy backends |
+| `unitx.math` | Unit-aware mathematical functions with scalar and optional NumPy backends |
 | `unitx.time` | Integer ns clocks, scalar sleep, timedelta and aware datetime conversion |
 | `unitx.statistics` | [Scalar means, dispersion, covariance and correlation](statistics.md) |
 
@@ -46,6 +46,7 @@ identities or arbitrary-precision evaluation.
 | `sin(x)`, `cos(x)`, `tan(x)` | Dimensionless input, including deg/rad; coherent dimensionless result |
 | `asin(x)`, `acos(x)`, `atan(x)` | Dimensionless input; result in rad |
 | `exp(x)`, `expm1(x)` | Dimensionless input; coherent dimensionless result |
+| `conj(x)` | Complex conjugate in the complete input unit |
 | `log(x)`, `log1p(x)`, `log2(x)`, `log10(x)` | Dimensionless input; coherent dimensionless result |
 | `hypot(*coordinates)` | Compatible input dimensions; first coordinate's unit |
 | `atan2(y, x)` | Compatible input dimensions; result in rad |
@@ -58,11 +59,15 @@ Use `log(x) / log(base)` for a different base. `hypot()` returns dimensionless
 zero; `hypot(x)` returns the absolute value in x's unit. For a bare first
 coordinate, the result unit is coherent dimensionless.
 
-Python int, float, Fraction and Decimal inputs use the standard-library math
+Real transcendental calls on Python int, float, Fraction and Decimal use the standard-library math
 backend, returning `Quantity[float]`. Decimal/Fraction input does not imply
 arbitrary-precision output. Standard math domain, overflow, NaN and infinity
 behavior applies. In particular, negative `sqrt` raises ValueError; negative
-`cbrt` returns a real cube root. Complex inputs, bools, custom scalar backends,
+`cbrt` returns a real cube root. `exp` also accepts complex inputs: Python
+complex values use `cmath.exp`, and NumPy complex magnitudes use `np.exp`.
+`conj` preserves the native scalar type or delegates to NumPy conjugation;
+it preserves the complete input unit. Other functions retain their real domain.
+Bools, custom scalar backends,
 implicit list/tuple arrays, affine points and logarithmic units are unsupported.
 Explicitly convert a logarithmic quantity to a physical ratio first.
 
@@ -74,13 +79,35 @@ may differ from the standard library's multi-coordinate implementation.
 The wrappers accept positional inputs only, without `out` or `where`.
 Use the supported NumPy ufuncs directly for those options.
 
-Array overloads return `Quantity[Array]`, using the NumPy-independent magnitude
-protocol so strict scalar users have complete annotations without NumPy.
+The `sqrt`, `sin`, `cos`, `atan` and `exp` overloads retain known NumPy floating
+dtypes; `exp` and `conj` also retain known complex dtypes. Two-coordinate
+float64 `hypot` calls with float64 or Python real inputs retain float64.
+The result includes a possible NumPy scalar, since zero-dimensional array
+operations can remove the array container. Other array overloads return
+`Quantity[Array]`, using the NumPy-independent magnitude protocol.
+Strict scalar users have complete annotations without NumPy.
 At runtime, magnitudes are native NumPy arrays/scalars. The protocol exposes
 shape/ndim/size/dtype and explicit array conversion, without promising a
 particular result shape or dtype. For additional native array methods in
 static analysis, use `np.asarray(result.value)`.
 
+For a typed complex phase, use this existing mathematical entry point directly:
+
+```python
+import numpy as np
+from unitx import math
+from unitx.si import si
+
+z = np.linspace(-1, 1, 5) * si.m
+gouy = math.atan(z / (0.5 * si.m))
+field = math.conj(math.exp(1j * gouy) / math.hypot(1, z / (0.5 * si.m)))
+field *= math.exp(-1j * gouy)
+```
+
+The phase formula needs no dtype argument or cast. Ordinary `np.exp(q)` and
+`np.conj(q)` still work at runtime, but their NumPy function signatures may
+infer a bare ndarray or an incomplete dtype. unitx does not alter those stubs.
+
 ## Clock readings
 
 ```python