pub struct AnyScalar { /* private fields */ }Expand description
Dynamic scalar compatibility wrapper for tensor4all-core.
This owns a rank-0 IdxTensor so that scalar values can participate in
the same eager autodiff graph as tensors while preserving the existing
dynamic scalar API shape. The infallible scalar constructors retain a
tensor-initialization failure for later fallible tensor or AD operations.
Infallible arithmetic also retains typed backend diagnostics and the
tracked-state marker when an eager operation fails.
Implementations§
Source§impl AnyScalar
impl AnyScalar
Sourcepub fn is_in_single_precision_range(&self) -> bool
pub fn is_in_single_precision_range(&self) -> bool
Returns whether every nonzero component converts to a normal f32, so
that converting the scalar to single precision only rounds it to 24
significant bits.
Use it on the factors of reciprocal_factors
before applying them to single-precision entries: a factor outside
this range would become zero or infinite, or lose a component.
§Examples
use tensor4all_core::AnyScalar;
assert!(AnyScalar::new_real(0.25).is_in_single_precision_range());
assert!(AnyScalar::new_complex(3.0, 0.0).is_in_single_precision_range());
assert!(!AnyScalar::new_real(2.0_f64.powi(-199)).is_in_single_precision_range());
assert!(!AnyScalar::new_complex(1.0, 1e300).is_in_single_precision_range());
assert!(!AnyScalar::new_real(f64::NAN).is_in_single_precision_range());Sourcepub fn reciprocal_factors(&self) -> Result<Vec<AnyScalar>, AnyScalarError>
pub fn reciprocal_factors(&self) -> Result<Vec<AnyScalar>, AnyScalarError>
Returns scalar factors whose product is 1 / self, ordered so that
multiplying a value by each in turn divides it by self with every
intermediate before the last product finite when the quotient
components are, and without forming a component of 1 / self that
could underflow. The last product multiplies by a rounded factor, so a
quotient component within a few units in the last place of f64::MAX
can round to infinity.
Use this instead of multiplying by 1 / self when self may be tiny or
huge: for self = 3 * 2^-1070, 1 / self overflows although
2^-1000 / self is finite. Apply the factors in order.
- A real divisor whose magnitude is in
[2^-500, 2^500]gives the single factor1 / self. - Another real divisor gives exact powers of two
2^jfollowed by1 / (self * 2^j), where|self * 2^j|is in[1/4, 1/2)for a small divisor and in[2^64, 2^65)for a large one. Each component of the result is thenfl(x * fl(1 / self)), with the reciprocal rounded as if the exponent range were unbounded, also when the product is subnormal. - An untracked purely imaginary divisor
b igives-i, which is exact, followed by the factors of the realb, so the real-divisor guarantees apply to each component. - Another complex divisor gives a real factor last, built from
1 / |self * 2^j|^2with|self * 2^j|in[1/4, 1/2)up to|self| = 2^201and in[2^64, 2^65)above. Whenj >= 0,2^jandconj(self * 2^j)come first. Whenj < 0and|self|is below2^201, the factors areconj(self * 2^j)and2^j / |self * 2^j|^2if scalingselfdown is exact; if it would flush a component,conj(self)is applied unscaled instead, as2^j,conj(self),2^j / |self * 2^j|^2. Above2^201,conj(self)comes between two powers of two whose product is2^(2j), followed by1 / |self * 2^j|^2. No component of1 / selfor of a scaled-downselfis formed on its own, and no intermediate component exceeds the largest component of the value or of the quotient, so none overflows unless a quotient component does. The error of each component is a few units in the last place of|quotient|. For a real value with a subnormal quotient, the intermediate before the last factor is rounded at subnormal granularity and the last factor can amplify that rounding, so the absolute error is several units of2^-1074, and a component that small can round to zero. No worst-case constant is derived; on the tests’ sample of complex divisors and subnormal quotients the largest errors are8 * 2^-1074when|self| < 1/2and4 * 2^-1074otherwise, and the tests check that both are attained.
The guarantees are for f64 and Complex64 arithmetic. Entries stored
in single precision convert each factor to f32, which keeps the
guarantees only when every factor passes
is_in_single_precision_range.
A gradient-tracked divisor yields tracked factors.
§Returns
One to five factors, to be applied in order.
§Errors
Returns AnyScalarError when self is zero or has a NaN or infinite
component.
§Examples
use tensor4all_core::AnyScalar;
let divide = |value: AnyScalar, divisor: &AnyScalar| {
divisor
.reciprocal_factors()
.unwrap()
.into_iter()
.fold(value, |acc, factor| acc * factor)
};
// 3 * 2^-1070 is subnormal and its reciprocal overflows.
let tiny = AnyScalar::new_real(f64::from_bits(48));
assert!((1.0 / tiny.real()).is_infinite());
let quotient = divide(AnyScalar::new_real(2.0_f64.powi(-1000)), &tiny);
assert_eq!(quotient.real(), 2.0_f64.powi(70) / 3.0);
// (2^600 + 2^-420 i): the imaginary part of the reciprocal is below
// the smallest subnormal, but that of 2^600 / divisor is -2^-1020.
let divisor = AnyScalar::new_complex(2.0_f64.powi(600), 2.0_f64.powi(-420));
let quotient = divide(AnyScalar::new_real(2.0_f64.powi(600)), &divisor);
assert_eq!(quotient.real(), 1.0);
assert_eq!(quotient.imag(), -2.0_f64.powi(-1020));
assert!(AnyScalar::new_real(0.0).reciprocal_factors().is_err());Source§impl AnyScalar
impl AnyScalar
Sourcepub fn from_value<T: ScalarTensorElement>(value: T) -> Self
pub fn from_value<T: ScalarTensorElement>(value: T) -> Self
Creates an AnyScalar from a tensor element.
Use this when you already have a scalar value that implements
[TensorElement] and want to lift it into the dynamic scalar wrapper.
§Arguments
value- The scalar value to wrap.
§Returns
A rank-0 AnyScalar containing value. The supported scalar types are
f32, f64, Complex32, and Complex64; the dtype is retained without
promotion.
Tensor initialization is attempted eagerly. Because this constructor is
infallible, an initialization failure is retained and returned by later
tensor- or AD-dependent operations such as AnyScalar::enable_grad.
Value-only accessors and non-AD arithmetic remain available.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::from_value(3.0f64);
assert_eq!(scalar.real(), 3.0);
assert!(scalar.is_real());Sourcepub fn from_real(x: f64) -> Self
pub fn from_real(x: f64) -> Self
Creates a real-valued AnyScalar.
This is a convenience wrapper around AnyScalar::from_value.
§Arguments
x- The real scalar value to wrap.
§Returns
A rank-0 AnyScalar with real dtype.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::from_real(1.25);
assert_eq!(scalar.as_f64(), Some(1.25));
assert!(scalar.is_real());Sourcepub fn from_complex(re: f64, im: f64) -> Self
pub fn from_complex(re: f64, im: f64) -> Self
Creates a complex-valued AnyScalar.
This is a convenience wrapper around AnyScalar::from_value.
§Arguments
re- The real part of the complex value.im- The imaginary part of the complex value.
§Returns
A rank-0 AnyScalar containing the requested complex number.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::from_complex(1.0, -2.0);
assert_eq!(scalar.as_c64().map(|z| (z.re, z.im)), Some((1.0, -2.0)));
assert!(scalar.is_complex());Sourcepub fn new_real(x: f64) -> Self
pub fn new_real(x: f64) -> Self
Creates a real-valued AnyScalar.
This is an alias for AnyScalar::from_real.
§Arguments
x- The real scalar value to wrap.
§Returns
A rank-0 AnyScalar with real dtype.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::new_real(2.5);
assert_eq!(scalar.real(), 2.5);
assert!(scalar.is_real());Sourcepub fn new_complex(re: f64, im: f64) -> Self
pub fn new_complex(re: f64, im: f64) -> Self
Creates a complex-valued AnyScalar.
This is an alias for AnyScalar::from_complex.
§Arguments
re- The real part of the complex value.im- The imaginary part of the complex value.
§Returns
A rank-0 AnyScalar containing the requested complex number.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::new_complex(2.0, 3.0);
assert_eq!(scalar.as_c64().map(|z| (z.re, z.im)), Some((2.0, 3.0)));
assert!(scalar.is_complex());Sourcepub fn primal(&self) -> Result<Self, AnyScalarError>
pub fn primal(&self) -> Result<Self, AnyScalarError>
Returns the detached primal value of this scalar.
This is an alias for AnyScalar::detach.
§Returns
A scalar with the same value and no gradient tracking.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, or when the AD backend cannot detach it.
§Examples
use tensor4all_core::AnyScalar;
let primal = AnyScalar::new_real(5.0).enable_grad().unwrap().primal().unwrap();
assert_eq!(primal.real(), 5.0);
assert!(!primal.tracks_grad());Sourcepub fn enable_grad(self) -> Result<Self, AnyScalarError>
pub fn enable_grad(self) -> Result<Self, AnyScalarError>
Enables gradient tracking for this scalar.
§Returns
A new scalar that shares the same value but participates in autodiff.
§Errors
Returns the original tensor-initialization diagnostic if this scalar’s eager backend tensor could not be created, or propagates an AD runtime failure while enabling gradients.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::new_real(2.0).enable_grad().unwrap();
assert!(scalar.tracks_grad());Sourcepub fn tracks_grad(&self) -> bool
pub fn tracks_grad(&self) -> bool
Sourcepub fn grad(&self) -> Result<Option<Self>, AnyScalarError>
pub fn grad(&self) -> Result<Option<Self>, AnyScalarError>
Returns the stored gradient, if any.
§Returns
Ok(Some(_)) when a gradient is available, Ok(None) when no gradient
has been recorded, or an error if the backend cannot read it.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, or when the AD backend cannot read the stored
gradient. A scalar with no recorded gradient returns Ok(None) rather
than an error.
§Examples
use tensor4all_core::AnyScalar;
let x = AnyScalar::new_real(2.0).enable_grad().unwrap();
let y = &x * &x;
y.backward().unwrap();
let grad = x.grad().unwrap().unwrap();
assert_eq!(grad.real(), 4.0);Sourcepub fn clear_grad(&self) -> Result<(), AnyScalarError>
pub fn clear_grad(&self) -> Result<(), AnyScalarError>
Clears the stored gradient for this scalar.
§Returns
Ok(()) when the gradient buffer was cleared successfully.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, or when the AD backend cannot clear the stored
gradient.
§Examples
use tensor4all_core::AnyScalar;
let x = AnyScalar::new_real(2.0).enable_grad().unwrap();
let y = &x * &x;
y.backward().unwrap();
assert!(x.grad().unwrap().is_some());
x.clear_grad().unwrap();
assert!(x.grad().unwrap().is_none());Sourcepub fn backward(&self) -> Result<(), AnyScalarError>
pub fn backward(&self) -> Result<(), AnyScalarError>
Runs reverse-mode autodiff starting from this scalar.
§Returns
Ok(()) when gradients were accumulated successfully.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, when it is not a scalar-valued tracked leaf, or
when the reverse pass fails.
§Examples
use tensor4all_core::AnyScalar;
let x = AnyScalar::new_real(2.0).enable_grad().unwrap();
let y = &x * &x;
y.backward().unwrap();
let grad = x.grad().unwrap().unwrap();
assert_eq!(grad.real(), 4.0);Sourcepub fn detach(&self) -> Result<Self, AnyScalarError>
pub fn detach(&self) -> Result<Self, AnyScalarError>
Returns a detached copy of this scalar.
§Returns
A scalar with the same value but without gradient tracking.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, or when the AD backend cannot detach it.
§Examples
use tensor4all_core::AnyScalar;
let detached = AnyScalar::new_real(7.0)
.enable_grad()
.unwrap()
.detach()
.unwrap();
assert_eq!(detached.real(), 7.0);
assert!(!detached.tracks_grad());Sourcepub fn is_complex(&self) -> bool
pub fn is_complex(&self) -> bool
Sourcepub fn as_c64(&self) -> Option<Complex64>
pub fn as_c64(&self) -> Option<Complex64>
Returns this scalar as a Complex64 when it is complex-valued.
§Returns
Some(value) for complex scalars or None for real and integer
scalars.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::new_complex(2.5, 1.0);
assert_eq!(scalar.as_c64().map(|z| (z.re, z.im)), Some((2.5, 1.0)));
assert_eq!(AnyScalar::new_real(2.5).as_c64(), None);Sourcepub fn try_conj(&self) -> Result<Self, AnyScalarError>
pub fn try_conj(&self) -> Result<Self, AnyScalarError>
Returns the complex conjugate of this scalar.
§Returns
The conjugated scalar. Real-valued inputs are returned unchanged.
§Errors
Returns an AnyScalarError when this scalar’s eager backend tensor
could not be created, or when the AD backend’s conjugation fails (for
example for a dtype it cannot track). Real-valued scalars are returned
unchanged.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::new_complex(3.0, -4.0).conj();
assert_eq!(scalar.as_c64().map(|z| (z.re, z.im)), Some((3.0, 4.0)));Sourcepub fn compose_complex(real: Self, imag: Self) -> Result<Self, AnyScalarError>
pub fn compose_complex(real: Self, imag: Self) -> Result<Self, AnyScalarError>
Combines two real-valued scalars into a complex scalar.
§Arguments
real- The real component.imag- The imaginary component.
§Returns
A complex AnyScalar whose real and imaginary parts come from the
inputs.
§Errors
Returns an AnyScalarError when either input is not real-valued, or
when the multiplication by the imaginary unit or the addition fails in
the eager backend.
§Examples
use tensor4all_core::AnyScalar;
let scalar = AnyScalar::compose_complex(
AnyScalar::new_real(3.0),
AnyScalar::new_real(-4.0),
)
.unwrap();
assert_eq!(scalar.as_c64().map(|z| (z.re, z.im)), Some((3.0, -4.0)));Sourcepub fn powi(&self, exponent: i32) -> Self
pub fn powi(&self, exponent: i32) -> Self
Raises this scalar to an integer power.
§Arguments
-
exponent- The integer exponent to apply. Negative exponents returnthe reciprocal power.
§Returns
The value of self^exponent. Zero exponents return 1.
§Examples
use tensor4all_core::AnyScalar;
assert_eq!(AnyScalar::new_real(2.0).powi(3).real(), 8.0);
assert_eq!(AnyScalar::new_real(2.0).powi(-1).real(), 0.5);Trait Implementations§
Source§impl PartialOrd for AnyScalar
impl PartialOrd for AnyScalar
Source§impl SumFromStorage for AnyScalar
impl SumFromStorage for AnyScalar
Source§fn sum_from_storage(storage: &Storage) -> Self
fn sum_from_storage(storage: &Storage) -> Self
Auto Trait Implementations§
impl !RefUnwindSafe for AnyScalar
impl !UnwindSafe for AnyScalar
impl Freeze for AnyScalar
impl Send for AnyScalar
impl Sync for AnyScalar
impl Unpin for AnyScalar
impl UnsafeUnpin for AnyScalar
Blanket Implementations§
§impl<Rhs, Lhs, Output> AddByRef<Rhs> for Lhs
impl<Rhs, Lhs, Output> AddByRef<Rhs> for Lhs
type Output = Output
fn add_by_ref(&self, rhs: &Rhs) -> <Lhs as AddByRef<Rhs>>::Output
§impl<U> As for U
impl<U> As for U
§fn as_<T>(self) -> Twhere
T: CastFrom<U>,
U: Sized,
fn as_<T>(self) -> Twhere
T: CastFrom<U>,
U: Sized,
self to type T. The semantics of numeric casting with the as operator are followed, so <T as As>::as_::<U> can be used in the same way as T as U for numeric conversions. Read moreSource§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
impl<ST, DT> CastableFrom<ST, Initialized, Initialized> for DT
impl<ST, DT> CastableFrom<ST, Uninit, Uninit> for DT
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
§impl<Rhs, Lhs, Output> DivByRef<Rhs> for Lhs
impl<Rhs, Lhs, Output> DivByRef<Rhs> for Lhs
type Output = Output
fn div_by_ref(&self, rhs: &Rhs) -> <Lhs as DivByRef<Rhs>>::Output
impl<T, U> Imply<T> for U
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more