Skip to content
Specular Differentiation
GitHub

specular.calculation.scaled_mean 

scaled_mean(alpha, beta, sigma=1.0)

Evaluate the scaled angular mean elementwise. Also available as specular.scaled_mean.

Parameters

Name Description
alpha, beta Real scalars or broadcast-compatible arrays of slopes.
sigma Concrete, finite, positive real scalar. Default: 1.0.

Returns

A scalar or array with the broadcast shape of alpha and beta. NumPy and Numba return a Python float for scalar results and a NumPy array otherwise; JAX returns a JAX array. Arithmetic uses the selected backend's calculation dtype.

Notes

The scale parameter defines

\[ \mathcal C_\sigma(\alpha,\beta) =\sigma\mathcal C(\alpha/\sigma,\beta/\sigma). \]

Inputs are promoted before arithmetic. Scale-safe formulas recover representable results when direct rescaling would overflow or underflow. The exact identities

\[ \mathcal C_\sigma(\alpha,\alpha)=\alpha, \qquad \mathcal C_\sigma(\alpha,-\alpha)=0 \]

are preserved for finite slopes even in those regimes. Other results remain subject to the backend dtype's representable range and device treatment of subnormal values. Under JAX transformations, alpha and beta may be traced, but sigma must remain static.

See the calculation guide for background.

Examples

from specular.calculation import scaled_mean

print(scaled_mean(1.0, -0.5, sigma=2.0))
print(scaled_mean([1.0, 2.0], [-1.0, 2.0]))  # [0. 2.]
Source code in specular/calculation.py 
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def scaled_mean(
    alpha: Any,
    beta: Any,
    sigma: Any = 1.0,
) -> Any:
    r"""Evaluate the scaled angular mean elementwise.

    This is
    :math:`\mathcal C_\sigma(\alpha,\beta)
    =\sigma\mathcal C(\alpha/\sigma,\beta/\sigma)` for a concrete,
    finite, positive scalar ``sigma``. Inputs are promoted to the selected
    backend's calculation dtype before arithmetic. Scale-safe formulas
    recover representable results when direct rescaling would overflow or
    underflow. The exact identities
    :math:`\mathcal C_\sigma(\alpha,\alpha)=\alpha` and
    :math:`\mathcal C_\sigma(\alpha,-\alpha)=0` are preserved even when
    forming ``alpha / sigma`` would underflow or overflow. Other results
    remain subject to the selected backend dtype's representable range.
    """

    scale = _positive_scalar(sigma, name="sigma")
    return _get_selected_backend()._scaled_mean(alpha, beta, scale)