optionstratlib_math/geometrics/operations/
transformations.rs

1use rust_decimal::Decimal;
2/// # Geometric Transformations
3///
4/// A trait that defines common geometric transformations and operations for geometric objects
5/// in any number of dimensions. This trait provides methods for manipulating objects in space
6/// and analyzing their properties.
7///
8/// ## Type Parameters
9///
10/// * `Point` - The point type used to represent positions in the geometric space.
11///
12pub trait GeometricTransformations<Point> {
13    /// The error type that can be returned by geometric operations.
14    type Error;
15
16    /// Translates the geometric object by specified amounts along each dimension.
17    ///
18    /// # Arguments
19    ///
20    /// * `deltas` - A vector of decimal values representing the translation distance
21    ///   along each dimension. The length of this vector should match the dimensionality
22    ///   of the geometric object.
23    ///
24    /// # Returns
25    ///
26    /// A new instance of the geometric object after translation, or an error if
27    /// the transformation could not be applied.
28    ///
29    /// # Errors
30    ///
31    /// Returns the implementation's `Self::Error` when `deltas`
32    /// length does not match the geometry's dimension, or when the
33    /// coordinate shift overflows the backing `Decimal` range.
34    fn translate(&self, deltas: Vec<&Decimal>) -> Result<Self, Self::Error>
35    where
36        Self: Sized;
37
38    /// Scales the geometric object by specified factors along each dimension.
39    ///
40    /// # Arguments
41    ///
42    /// * `factors` - A vector of decimal values representing the scaling factor
43    ///   for each dimension. The length of this vector should match the dimensionality
44    ///   of the geometric object.
45    ///
46    /// # Returns
47    ///
48    /// A new instance of the geometric object after scaling, or an error if
49    /// the transformation could not be applied.
50    ///
51    /// # Errors
52    ///
53    /// Returns the implementation's `Self::Error` when `factors`
54    /// length does not match the geometry's dimension, when a factor
55    /// is zero on a required axis, or when the rescaled coordinate
56    /// overflows the backing `Decimal` range.
57    fn scale(&self, factors: Vec<&Decimal>) -> Result<Self, Self::Error>
58    where
59        Self: Sized;
60
61    /// Finds all intersection points between this geometric object and another.
62    ///
63    /// # Arguments
64    ///
65    /// * `other` - The other geometric object to find intersections with.
66    ///
67    /// # Returns
68    ///
69    /// A vector of intersection points, or an error if the intersections
70    /// could not be determined.
71    ///
72    /// # Errors
73    ///
74    /// Returns the implementation's `Self::Error` when the two
75    /// geometries live on incompatible domains or when the
76    /// intersection solver fails to converge.
77    fn intersect_with(&self, other: &Self) -> Result<Vec<Point>, Self::Error>;
78
79    /// Calculates the derivative at a specific point on the geometric object.
80    ///
81    /// For curves, this represents the tangent. For surfaces, this can represent
82    /// partial derivatives.
83    ///
84    /// # Arguments
85    ///
86    /// * `point` - The point at which to calculate the derivative.
87    ///
88    /// # Returns
89    ///
90    /// A vector containing the derivative values along each dimension, or an error
91    /// if the derivative could not be calculated.
92    ///
93    /// # Errors
94    ///
95    /// Returns the implementation's `Self::Error` when `point`
96    /// falls outside the geometry's domain, or when the
97    /// finite-difference / analytical derivative is undefined at
98    /// that point (e.g. discontinuity).
99    fn derivative_at(&self, point: &Point) -> Result<Vec<Decimal>, Self::Error>;
100
101    /// Finds the extrema (minimum and maximum points) of the geometric object.
102    ///
103    /// # Returns
104    ///
105    /// A tuple containing the minimum and maximum points of the geometric object,
106    /// or an error if the extrema could not be determined.
107    ///
108    /// # Errors
109    ///
110    /// Returns the implementation's `Self::Error` when the geometry
111    /// is empty or when the extremum search cannot decide between
112    /// several tied candidates.
113    fn extrema(&self) -> Result<(Point, Point), Self::Error>;
114
115    /// Calculates the area or volume under the geometric object relative to a base value.
116    ///
117    /// For curves, this calculates the area. For higher-dimensional objects,
118    /// this calculates volume.
119    ///
120    /// # Arguments
121    ///
122    /// * `base_value` - The reference value to measure from.
123    ///
124    /// # Returns
125    ///
126    /// The calculated area or volume, or an error if the calculation failed.
127    ///
128    /// # Errors
129    ///
130    /// Returns the implementation's `Self::Error` when the
131    /// integration domain is empty, when the trapezoid / Simpson
132    /// kernel encounters a degenerate sub-interval, or when the
133    /// accumulator overflows the backing `Decimal` range.
134    fn measure_under(&self, base_value: &Decimal) -> Result<Decimal, Self::Error>;
135}
optionstratlib_math/geometrics/operations/transformations.rs

optionstratlib_math/geometrics/operations/
transformations.rs
