Struct Curve 

pub struct Curve {
    pub points: BTreeSet<Point2D>,
    pub x_range: (Decimal, Decimal),
}

Represents a mathematical curve as a collection of 2D points.

Overview

The Curve struct is a fundamental representation of a curve, defined as a series of points in a two-dimensional Cartesian coordinate system. Each curve is associated with an x_range, specifying the inclusive domain of the curve in terms of its x-coordinates.

This structure supports precise mathematical and computational operations, including interpolation, analysis, transformations, and intersections. The use of Decimal for coordinates ensures high-precision calculations, making it particularly suitable for scientific, financial, or mathematical applications.

Usage

The Curve struct acts as the basis for high-level operations provided within the crate::curves module. These include (but are not limited to):

• Generating statistical analyses (CurveAnalysisResult)
• Performing curve interpolation
• Logical manipulations, such as merging curves (MergeOperation)
• Visualizing graphs or curve plots using libraries like plotters

Example Applications

The Curve type fits into mathematical or graphical operations such as:

• Modeling data over a range of x-values
• Comparing curves through transformations or intersections
• Calculating derivatives, integrals, and extrema along the curve

Constraints

• All points in the points vector must lie within the specified x_range.
• Methods working with Curve data will assume that the points vector is ordered by the x-coordinate. Non-ordered inputs may lead to undefined behavior in specific operations.

See Also

• Point2D: The fundamental data type for representing points in 2D space.
• MergeOperation: Enum for combining multiple curves.

Fields

points: BTreeSet<Point2D>

A ordered set of Point2D objects that defines the curve in terms of its x-y plane coordinates. Points are stored in a BTreeSet which automatically maintains them in sorted order by their x-coordinate.

x_range: (Decimal, Decimal)

A tuple (min_x, max_x) that specifies the minimum and maximum x-coordinate values for the curve. Operations performed on the curve should ensure they fall within this range. Both values are of type Decimal to ensure high precision in boundary calculations.

Implementations

impl Curve

pub fn new(points: BTreeSet<Point2D>) -> Self

Creates a new curve from a vector of points.

This constructor initializes a Curve instance using a list of 2D points provided as a BTreeSet<Point2D>. Additionally, the x-range of the curve is calculated and stored. The x-range is determined by evaluating the minimum and maximum x-coordinates among the provided points.

Parameters

• points (BTreeSet<Point2D>): A vector of points that define the curve in a two-dimensional Cartesian coordinate plane.

Returns

• Curve: A newly instantiated curve containing the provided points and the computed x-range.

Behavior

• Calculates the x-range of the points using calculate_range().
• Stores the provided points for later use in curve-related calculations.

See Also

• Point2D: The type of points used to define the curve.
• crate::curves::Curve::calculate_range: Computes the x-range of a set of points.

Trait Implementations

impl Arithmetic<Curve> for Curve

Implements the CurveArithmetic trait for the Curve type, providing functionality for merging multiple curves using a specified mathematical operation and performing arithmetic operations between two curves.

fn merge( curves: &[&Curve], operation: MergeOperation, ) -> Result<Curve, CurveError>

Merges a collection of curves into a single curve based on the specified mathematical operation.

Parameters

• curves (&[&Curve]): A slice of references to the curves to be merged. Each curve must have defined x-ranges and interpolation capabilities.
• operation (MergeOperation): The arithmetic operation to perform on the interpolated y-values for the provided curves. Operations include addition, subtraction, multiplication, division, and aggregation (e.g., max, min).

Returns

• Ok(Curve): Returns a new curve resulting from the merging operation.
• Err(CurvesError): If input parameters are invalid or the merge operation encounters an error (e.g., incompatible x-ranges or interpolation failure), an error is returned.

Behavior

1. Parameter Validation:

• Verifies that at least one curve is provided in the curves parameter.
• Returns an error if no curves are included or if x-ranges are incompatible.

2. Cloning Single Curve:

• If only one curve is provided, its clone is returned as the result without performing any further calculations.

3. Range Computation:

• Computes the intersection of x-ranges across the curves by finding the maximum lower bound (min_x) and minimum upper bound (max_x).
• If the x-range intersection is invalid (i.e., min_x >= max_x), an error is returned.

4. Interpolation and Arithmetic:

• Divides the x-range into steps equally spaced intervals (default: 100).
• Interpolates the y-values for all curves at each x-value in the range.
• Applies the specified operation to the aggregated y-values at each x-point.

5. Parallel Processing:

• Uses parallel iteration to perform interpolation and value combination efficiently, leveraging the Rayon library.

6. Error Handling:

• Any errors during interpolation or arithmetic operations are propagated back to the caller.

Errors

• Invalid Parameter (CurvesError): Returned when no curves are provided or x-ranges are incompatible.
• Interpolation Failure (CurvesError): Raised if interpolation fails for a specific curve or x-value.

Example Use Case

This function enables combining multiple curves for tasks such as:

• Summing y-values across different curves to compute a composite curve.
• Finding the maximum/minimum y-value at each x-point for a collection of curves.

fn merge_with( &self, other: &Curve, operation: MergeOperation, ) -> Result<Curve, CurveError>

Combines the current Curve instance with another curve using a mathematical operation, resulting in a new curve.

Parameters

• self (&Self): A reference to the current curve instance.
• other (&Curve): A reference to the second curve for the arithmetic operation.
• operation (MergeOperation): The operation to apply when merging the curves.

Returns

• Ok(Curve): Returns a new curve that represents the result of the operation.
• Err(CurvesError): If the merge operation fails (e.g., incompatible x-ranges or interpolation errors), an error is returned.

Behavior

This function is a convenience wrapper around merge_curves that operates specifically on two curves. It passes self and other as an array to merge_curves and applies the desired operation.

Errors

• Inherits all errors returned by the merge_curves method, including parameter validation and interpolation errors.

Examples

Use this method to easily perform arithmetic operations between two curves, such as summing their y-values or finding their pointwise maximum.

type Error = CurveError

The error type returned when merging operations fail

impl AxisOperations<Point2D, Decimal> for Curve

type Error = CurveError

The type of error that can occur during point operations

fn contains_point(&self, x: &Decimal) -> bool

Checks if a coordinate value exists in the structure.

fn get_index_values(&self) -> Vec<Decimal>

Returns a vector of references to all index values in the structure.

fn get_values(&self, x: Decimal) -> Vec<&Decimal>

Returns a vector of references to dependent values for a given coordinate.

fn get_closest_point(&self, x: &Decimal) -> Result<&Point2D, Self::Error>

Finds the closest point to the given coordinate value.

fn get_point(&self, x: &Decimal) -> Option<&Point2D>

Finds the closest point to the given coordinate value.

fn merge_indexes(&self, axis: Vec<Input>) -> Vec<Input>

Merges the index values from the current structure with an additional set of indices. This combines self.get_index_values() with the provided axis vector to create a single vector of unique indices.

impl BiLinearInterpolation<Point2D, Decimal> for Curve

Implementation of the BiLinearInterpolation trait for the Curve struct.

This function performs bilinear interpolation, which is used to estimate the value of a function at a given point x within a grid defined by at least 4 points. Bilinear interpolation combines two linear interpolations: one along the x-axis and another along the y-axis, within the bounds defined by the four surrounding points.

Parameters

• x: The x-coordinate value for which the interpolation will be performed. Must fall within the range of the x-coordinates of the curve’s points.

Returns

• Ok(Point2D): A Point2D instance representing the interpolated point at the given x-coordinate, with both x and y provided as Decimal values.
• Err(CurvesError): An error if the interpolation cannot be performed due to one of the following reasons:
  • There are fewer than 4 points in the curve.
  • The x-coordinate does not fall within a valid range of points.
  • The bracketing points for the given x-coordinate cannot be determined.

Function Details

1. Input Validation:

   • Ensures the curve has at least 4 points, as required for bilinear interpolation.
   • Returns an error if the condition is not met.

2. Exact Match Check:

   • If the x-coordinate matches exactly with one of the points in the curve, the corresponding Point2D is returned directly.

3. Bracket Point Search:

   • Determines the bracketing points (i and j) for the given x-coordinate using the find_bracket_points method.

4. Grid Point Selection:

   • Extracts four points from the curve:
     • p11: Bottom-left point.
     • p12: Bottom-right point.
     • p21: Top-left point.
     • p22: Top-right point.

5. x-Normalization:

   • Computes a normalized x value (dx in the range [0,1]), used to perform interpolation along the x-axis within the defined grid.

6. Linear Interpolation:

   • First performs interpolation along the x-axis for the bottom and top edges of the grid, resulting in partial y-values bottom and top.
   • Then, interpolates along the y-axis between the bottom and top edge values, resulting in the final interpolated y-coordinate.

7. Output:

   • Returns the interpolated Point2D with the input x-coordinate and the computed y-coordinate.

Errors

• Insufficient Points: If the curve contains fewer than 4 points, a CurvesError with a relevant message is returned.
• Out-of-Range x: If the x-coordinate cannot be bracketed by points in the curve, a CurvesError is returned with an appropriate message.

Related Traits

• BiLinearInterpolation: The trait defining this method.
• Interpolate: Ensures compatibility of the curve with multiple interpolation methods.

See Also

• Curve: The overarching structure that represents the curve.
• Point2D: The data type used to represent individual points on the curve.
• find_bracket_points: A helper method used to locate the two points that bracket the given x-coordinate.

fn bilinear_interpolate( &self, x: Decimal, ) -> Result<Point2D, InterpolationError>

Performs bilinear interpolation to find the value of the curve at a given x coordinate.

Parameters

• x: The x-coordinate at which the interpolation is to be performed. This should be a Decimal value within the range of the curve’s known points.

Returns

• On success, returns a Point2D instance representing the interpolated point at the given x value.
• On failure, returns a CurvesError:
  • CurvesError::InterpolationError: If there are fewer than four points available for interpolation or if the required conditions for interpolation are not met.

Function Description

• The function retrieves the set of points defining the curve using self.get_points().
• If fewer than four points exist, the function immediately fails with an InterpolationError.
• If the exact x value is found in the point set, its corresponding Point2D is returned directly.
• Otherwise, it determines the bracketing points (two pairs of points forming a square grid) necessary for bilinear interpolation using self.find_bracket_points().
• From the bracketing points, it computes:
  • dx: A normalized value representing the relative position of x between its bracketing x-coordinates in the [0,1] interval.
  • bottom: The interpolated y-value along the bottom edge of the grid.
  • top: The interpolated y-value along the top edge of the grid.
  • y: The final interpolated value along the y-dimension from bottom to top.
• Returns the final interpolated point as Point2D(x, y).

Errors

• Returns an error if the curve has fewer than four points, as bilinear interpolation requires at least four.
• Returns an error from self.find_bracket_points() if x cannot be bracketed.

Notes

• The input x should be within the bounds of the curve for interpolation to succeed, as specified by the bracketing function.
• This function assumes that the points provided by get_points are sorted by ascending x-coordinate.

Example Use Case

This method is useful for calculating intermediate values on a 2D grid when exact measurements are unavailable. Bilinear interpolation is particularly applicable for approximating smoother values in a tabular dataset or a regularly sampled grid.

impl Clone for Curve

fn clone(&self) -> Curve

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CubicInterpolation<Point2D, Decimal> for Curve

Implements the CubicInterpolation trait for the Curve struct, providing an algorithm for cubic interpolation utilizing a Catmull-Rom spline.

Method: cubic_interpolate

Parameters

• x: The x-value at which the interpolation is performed. This value must be within the range of x-values in the curve’s defined points, and it is passed as a Decimal to allow for high-precision computation.

Returns

• Ok(Point2D): Returns a Point2D representing the interpolated x and y values.
• Err(CurvesError): Returns an error if:
  • There are fewer than 4 points available for interpolation.
  • The x-value is outside the curve’s range, or interpolation fails for any other reason.

Behavior

1. Point Validation: Ensures at least four points exist for cubic interpolation, as this is a fundamental requirement for computing the Catmull-Rom spline.
2. Exact Match Check: If the x-value matches an existing point in the curve, the method directly returns the corresponding Point2D without further computation.
3. Bracket Points: Determines the bracketing points (4 points total) around the provided x-value. Depending on the position of the x-value in the curve, the method dynamically adjusts the selected points to ensure they form a proper bracket:
   • If near the start of the curve, uses the first four points.
   • If near the end, uses the last four points.
   • Else, selects points before and after x to define the bracket.
4. Parameter Calculation: Computes a normalized parameter t that represents the relative position of the target x-value between p1 and p2.
5. Catmull-Rom Spline: Performs cubic interpolation using a Catmull-Rom spline, a widely used, smooth spline algorithm. The coefficients are calculated based on the relative x position and the y-values of the four surrounding points.
6. Interpolation: Calculates the interpolated y-value using the cubic formula:

   y(t) = 0.5 * (
       2 * p1.y + (-p0.y + p2.y) * t
       + (2 * p0.y - 5 * p1.y + 4 * p2.y - p3.y) * t^2
       + (-p0.y + 3 * p1.y - 3 * p2.y + p3.y) * t^3
   )

   Here, t is the normalized x position, and p0, p1, p2, p3 are the four bracketed points.

Errors

• Returns an error of type CurvesError::InterpolationError if any issues are encountered, such as insufficient points or the inability to locate bracket points.

Example

This method is part of the Curve struct, which defines a set of points and supports interpolation. It is often used in applications requiring smooth manifolds or animations.

Notes

• The computed y-value ensures smooth transitions and continuity between interpolated segments.
• Catmull-Rom splines are particularly effective for creating visually smooth transitions, making this method suitable for curves, animations, and numerical analysis.

See Also

• CubicInterpolation: The trait defining this method.
• Point2D: Represents the points used for interpolation.
• find_bracket_points: Determines the bracketing points required for interpolation.

fn cubic_interpolate(&self, x: Decimal) -> Result<Point2D, InterpolationError>

Performs cubic interpolation on a set of points to estimate the y-coordinate for a given x value using a Catmull-Rom spline.

Parameters

• x: The x-coordinate for which the interpolation is performed. This value should lie within the range of the points on the curve.

Returns

• Ok(Point2D): A Point2D instance representing the interpolated position (x, y), where y is estimated using cubic interpolation.
• Err(CurvesError): An error indicating issues with the interpolation process, such as insufficient points or an out-of-range x value.

Requirements

• The number of points in the curve must be at least 4, as cubic interpolation requires four points for accurate calculations.
• The specified x value should be inside the range defined by the curve’s points.
• If the specified x matches an existing point on the curve, the interpolated result directly returns that exact point.

Functionality

This method performs cubic interpolation using the general properties of the Catmull-Rom spline, which is well-suited for smooth curve fitting. It operates as follows:

1. Exact Point Check: If the x value matches an existing point, the method returns that point without further processing.

2. Bracketing Points Selection:

   • Searches for two points that bracket the given x value (using find_bracket_points from the Interpolate trait). The method ensures that there are always enough points before and after the target x value to perform cubic interpolation.

3. Point Selection for Interpolation:

   • Depending on the position of the target x value, four points (p0, p1, p2, p3) are selected:
     • When x is near the start of the points, select the first four.
     • When x is near the end, select the last four.
     • Otherwise, select the two points just before and after the x value and include an additional adjacent point on either side.

4. Parameter Calculation:

   • The t parameter is derived, representing the normalized position of x between p1 and p2.

5. Cubic Interpolation:

   • The interpolated y-coordinate is computed using the Catmull-Rom spline formula, leveraging the t-value and the y-coordinates of the four selected points.

Error Handling

This method returns an error in the following circumstances:

• If fewer than 4 points are available, it returns a CurvesError::InterpolationError with a corresponding message.
• If the bracketing points cannot be identified (e.g., when x is outside the range of points), the appropriate interpolation error is propagated.

Example

• Interpolating smoothly along a curve defined by a set of points, avoiding sharp transitions between segments.

• Provides a high degree of precision due to the use of the Decimal type for x and y calculations.

impl Debug for Curve

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Curve

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Curve

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Curve

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl From<Curve> for GraphData

fn from(curve: Curve) -> Self

Converts to this type from the input type.

impl GeometricObject<Point2D, Decimal> for Curve

type Error = CurveError

Type alias for any errors that might occur during the construction of the geometric object.

fn get_points(&self) -> BTreeSet<&Point2D>

Returns a BTreeSet containing references to the points that constitute the geometric object. The BTreeSet ensures that the points are ordered and unique.

fn from_vector<T>(points: Vec<T>) -> Self

where T: Into<Point2D> + Clone,

Creates a new geometric object from a Vec of points.

fn construct<T>(method: T) -> Result<Self, Self::Error>

where Self: Sized, T: Into<ConstructionMethod<Point2D, Decimal>>,

Constructs a geometric object using a specific construction method.

fn vector(&self) -> Vec<&Point>

Returns a Vec containing references to the points that constitute the geometric object. This method simply converts the BTreeSet from get_points into a Vec.

fn to_vector(&self) -> Vec<&Point>

Returns the points of the geometric object as a Vec of references. Equivalent to calling the vector() method.

fn calculate_range<I>(iter: I) -> (Decimal, Decimal)

where I: Iterator<Item = Decimal>,

Calculates the minimum and maximum decimal values from an iterator of decimals.

impl GeometricTransformations<Point2D> for Curve

type Error = CurveError

The error type that can be returned by geometric operations.

fn translate(&self, deltas: Vec<&Decimal>) -> Result<Self, Self::Error>

Translates the geometric object by specified amounts along each dimension.

fn scale(&self, factors: Vec<&Decimal>) -> Result<Self, Self::Error>

Scales the geometric object by specified factors along each dimension.

fn intersect_with(&self, other: &Self) -> Result<Vec<Point2D>, Self::Error>

Finds all intersection points between this geometric object and another.

fn derivative_at(&self, point: &Point2D) -> Result<Vec<Decimal>, Self::Error>

Calculates the derivative at a specific point on the geometric object.

fn extrema(&self) -> Result<(Point2D, Point2D), Self::Error>

Finds the extrema (minimum and maximum points) of the geometric object.

fn measure_under(&self, base_value: &Decimal) -> Result<Decimal, Self::Error>

Calculates the area or volume under the geometric object relative to a base value.

impl Graph for Curve

fn graph_data(&self) -> GraphData

Return the raw data ready for plotting.

fn graph_config(&self) -> GraphConfig

Optional per‑object configuration overrides.

impl Index<usize> for Curve

Allows indexed access to the points in a Curve using usize indices.

Overview

This implementation provides intuitive, array-like access to the points within a Curve. By using the Index<usize> trait, users can directly reference specific points by their index within the internal points collection without manually iterating or managing indices themselves.

Behavior

• The index method fetches the Point2D at the specified position in the order of the curve’s points (sorted by the Point2D ordering, typically based on the x values).
• If the specified index exceeds the range of available points, it triggers a panic with the message "Index out of bounds".

Constraints

• The index must be a valid value between 0 and self.points.len() - 1.
• The Curve’s points are internally stored as a BTreeSet<Point2D>, so indexing reflects the natural order of the set, which is determined by the Ord trait implementation for Point2D.

Fields Accessed

• points: A BTreeSet of Point2D structs representing the curve’s 2D points.

Panics

This implementation will panic if:

• The index provided is out of bounds (less than 0 or greater than/equal to the number of points in the curve).

Use Cases

• Quickly accessing specific points on a curve during visualization, interpolation, or analysis operations.
• Performing operations that require stepwise access to points, such as slicing or filtering points along the curve.

Example

Suppose you have a Curve instance curve with multiple points:

let point = curve[0]; // Access the first point

Important Notes

• This indexing implementation provides read-only access (&Self::Output).
• Modifying the points collection or its contents directly is not allowed through this implementation, ensuring immutability when using indexed access.

Type Associations

• Input:
  • The input type for the Index operation is usize, the standard for indexing.
• Output:
  • The output type for the Index operation is a reference to Point2D, specifically &Point2D.

Key Implementations

• Index<usize>: Provides indexing-based access to curve points.

fn index(&self, index: usize) -> &Self::Output

Fetches the Point2D at the specified index.

Panics if the index is invalid.

type Output = Point2D

The returned type after indexing.

impl Interpolate<Point2D, Decimal> for Curve

Implementation of the Interpolate trait for the Curve struct.

This implementation integrates the get_points method for the Curve structure, providing access to its internal points. The Interpolate trait ensures compatibility with various interpolation methods such as Linear, BiLinear, Cubic, and Spline interpolations. By implementing this trait, Curve gains the ability to perform interpolation operations and access bracketing points.

Traits Involved

The Interpolate trait is an aggregation of multiple interpolation-related traits:

• LinearInterpolation
• BiLinearInterpolation
• CubicInterpolation
• SplineInterpolation

These underlying traits implement specific interpolation algorithms, enabling Curve to support a robust set of interpolation options through the associated methods. Depending on the use case and provided parameters (e.g., interpolation type and target x-coordinate), the appropriate algorithm is invoked.

See Also

• Curve: The underlying mathematical structure being interpolated.
• Point2D: The fundamental data type for the curve’s points.
• Interpolate: The trait defining interpolation operations.

fn interpolate( &self, x: Input, interpolation_type: InterpolationType, ) -> Result<Point, InterpolationError>

Interpolates a value at the given x-coordinate using the specified interpolation method.

fn find_bracket_points( &self, x: Input, ) -> Result<(usize, usize), InterpolationError>

Finds the indices of points that bracket the given x-coordinate.

impl Len for Curve

fn len(&self) -> usize

Returns the number of elements in the collection or the size of the object.

fn is_empty(&self) -> bool

Returns true if the collection contains no elements or the object has zero size.

impl LinearInterpolation<Point2D, Decimal> for Curve

Implements the LinearInterpolation trait for the Curve struct.

This implementation provides linear interpolation functionality for a given set of points on a curve. The interpolation computes the y value corresponding to a given x value using the linear interpolation formula. The method ensures that the input x is within the range of the curve’s defined points.

y = p1.y + (x - p1.x) * (p2.y - p1.y) / (p2.x - p1.x)

Parameters

• x: A Decimal representing the x-coordinate for which the corresponding interpolated y value is to be computed.

Returns

• Ok(Point2D): A Point2D instance containing the input x value and the interpolated y value.
• Err(CurvesError): Returns an error of type CurvesError::InterpolationError in any of the following cases:
  • The curve does not have enough points for interpolation.
  • The provided x value is outside the range of the curve’s points.
  • Bracketing points for x cannot be found.

Working Mechanism

1. The method calls find_bracket_points (implemented in the Interpolate trait) to locate the index pair (i, j) of two points that bracket the x value.
2. From the located points p1 and p2, the method calculates the interpolated y value using the linear interpolation formula.
3. Finally, a Point2D is created and returned with the provided x and the computed y value.

Implementation Details

• The function leverages Decimal arithmetic for high precision in calculations.
• It assumes that the provided points on the curve are sorted in ascending order based on their x values.

Errors

This method returns a CurvesError in the following cases:

• Insufficient Points: When the curve has fewer than two points.
• Out-of-Range x: When the input x value lies outside the range of the defined points.
• No Bracketing Points Found: When the method fails to find two points that bracket the given x.

Example (How it works internally)

Suppose the curve is defined by the following points:

• p1 = (2.0, 4.0)
• p2 = (5.0, 10.0)

Given x = 3.0, the method computes:

y = 4.0 + (3.0 - 2.0) * (10.0 - 4.0) / (5.0 - 2.0)
  = 4 + 1 * 6 / 3
  = 4 + 2
  = 6.0

It will return Point2D { x: 3.0, y: 6.0 }.

See Also

• find_bracket_points: Finds two points that bracket a value.
• Point2D: Represents points in 2D space.
• CurvesError: Represents errors related to curve operations.

fn linear_interpolate(&self, x: Decimal) -> Result<Point2D, InterpolationError>

Method

linear_interpolate

Performs linear interpolation for a given x value by finding two consecutive points on the curve (p1 and p2) that bracket the provided x. The y value is then calculated using the linear interpolation formula:

impl MergeAxisInterpolate<Point2D, Decimal> for Curve

where Self: Sized,

fn merge_axis_interpolate( &self, other: &Self, interpolation: InterpolationType, ) -> Result<(Self, Self), Self::Error>

Interpolates both structures to align them on a common set of index values.

fn merge_axis_index<'a>(&'a self, other: &'a Self) -> Vec<Input>

Merges the index values from two structures into a single ordered vector.

impl MetricsExtractor for Curve

A default implementation for the Curve type using a provided default strategy.

This implementation provides a basic approach to computing curve metrics by using interpolation and statistical methods available in the standard curve analysis library.

Note

This is a minimal implementation that may need to be customized or enhanced based on specific requirements or domain-specific analysis needs.

fn compute_basic_metrics(&self) -> Result<BasicMetrics, MetricsError>

Computes basic statistical metrics for the curve.

fn compute_shape_metrics(&self) -> Result<ShapeMetrics, MetricsError>

Computes shape-related metrics for the curve.

fn compute_range_metrics(&self) -> Result<RangeMetrics, MetricsError>

Computes range-related metrics for the curve.

fn compute_trend_metrics(&self) -> Result<TrendMetrics, MetricsError>

Computes trend-related metrics for the curve.

fn compute_risk_metrics(&self) -> Result<RiskMetrics, MetricsError>

Computes risk-related metrics for the curve.

fn compute_curve_metrics(&self) -> Result<Metrics, MetricsError>

Computes and aggregates all curve metrics into a comprehensive CurveMetrics struct.

fn compute_surface_metrics(&self) -> Result<Metrics, MetricsError>

Computes comprehensive metrics for a surface representation.

impl Plottable for Curve

Plottable implementation for single Curve

type Error = CurveError

The error type returned by plotting operations.

fn plot(&self) -> PlotBuilder<Self>

where Self: Sized,

Creates a plot builder for configuring and generating visualizations.

impl Serialize for Curve

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl SplineInterpolation<Point2D, Decimal> for Curve

Implements the SplineInterpolation trait for the Curve struct, providing functionality to perform cubic spline interpolation.

Overview

This method calculates the interpolated y value for a given x value by using cubic spline interpolation on the points in the Curve. The method ensures a smooth transition between points by computing second derivatives of the curve at each point, and uses those derivatives in the spline interpolation formula.

Parameters

• x: The x-coordinate at which the curve should be interpolated. This value is passed as a Decimal for precise calculations.

Returns

• On success, returns a Point2D instance representing the interpolated point.
• On error, returns a CurvesError indicating the reason for failure (e.g., insufficient points or an out-of-range x-coordinate).

Errors

• Returns CurvesError::InterpolationError with an appropriate error message in the following cases:
  • If the curve contains fewer than three points, as spline interpolation requires at least three points.
  • If the given x value lies outside the range of x-coordinates spanned by the points in the curve.
  • If a valid segment for interpolation cannot be located.

Details

1. Validation:
   • Ensures that there are at least three points in the curve for spline interpolation.
   • Validates that the provided x value is within the range of x values of the curve.
2. Exact Match: If the x value matches the x-coordinate of an existing point, the corresponding Point2D is returned immediately.
3. Second Derivative Calculation:
   • Uses a tridiagonal matrix to compute the second derivatives at each point. This step involves setting up the system of equations based on the boundary conditions (natural spline) and solving it using the Thomas algorithm.
4. Segment Identification:
   • Determines the segment (interval between two consecutive points) in which the provided x value lies.
5. Interpolation:
   • Computes the interpolated y-coordinate using the cubic spline formula, which is based on the second derivatives and the positions of the surrounding points.

Implementation Notes

• This implementation uses Decimal from the rust_decimal crate to ensure high precision in calculations, making it suitable for scientific and financial applications.
• The Thomas algorithm is employed to solve the tridiagonal matrix system efficiently.
• The method assumes natural spline boundary conditions, where the second derivatives at the endpoints are set to zero, ensuring a smooth and continuous curve shape.

Example Usage

Refer to the documentation for how to use the SplineInterpolation trait, as examples are not provided inline with this implementation.

See Also

• SplineInterpolation: The trait definition for spline interpolation.
• Point2D: Represents a point in 2D space.
• Curve: Represents a mathematical curve made up of points for interpolation.
• CurveError: Enumerates possible errors during curve operations.

fn spline_interpolate(&self, x: Decimal) -> Result<Point2D, InterpolationError>

Performs cubic spline interpolation for a given x-coordinate and returns the interpolated Point2D value. This function computes the second derivatives of the curve points, solves a tridiagonal system to derive the interpolation parameters, and evaluates the spline function for the provided x value.

Parameters

• x:
  • The x-coordinate at which the interpolation is to be performed.
  • Must be of type Decimal.

Returns

• Ok(Point2D):

  • The Point2D instance representing the interpolated point at the given x value.
  • The interpolated y value is calculated based on the cubic spline interpolation algorithm.

• Err(CurvesError):

  • Returned when an error occurs during the interpolation process, such as:
    • Insufficient points provided (less than 3 points).
    • The given x is outside the valid range of the points.
    • Unable to determine the correct segment for interpolation.

Errors

• CurvesError::InterpolationError:
  • Occurs under the following conditions:
    • “Need at least three points for spline interpolation”: Requires at least 3 points to perform cubic spline interpolation.
    • “x is outside the range of points”: The provided x value lies outside the domain of the curve points.
    • “Could not find valid segment for interpolation”: Spline interpolation fails due to an invalid segment determination.

Pre-conditions

• The curve must contain at least three points for cubic spline interpolation.
• The x value must fall within the range of the curve’s x-coordinates.

Implementation Details

• Inputs:
  • Uses the get_points method of the curve to retrieve the list of Point2D instances that define the interpolation curve.
  • Computes the second derivatives (m) for each point using the Thomas algorithm to solve a tridiagonal system.
• Boundary Conditions:
  • Natural spline boundary conditions are used, with the second derivatives on the boundary set to zero.
• Interpolation:
  • Determines the segment [x_i, x_{i+1}] to which the input x belongs.
  • Uses the cubic spline equation to calculate the interpolated y value.

Mathematical Formulation

Let x_i, x_{i+1}, y_i, y_{i+1} refer to the points of the segment where x lies. The cubic spline function at x is computed as follows:

S(x) = m_i * (x_{i+1} - x)^3 / (6 * h)
     + m_{i+1} * (x - x_i)^3 / (6 * h)
     + (y_i / h - h * m_i / 6) * (x_{i+1} - x)
     + (y_{i+1} / h - h * m_{i+1} / 6) * (x - x_i)

Where:

• m_i, m_{i+1} are the second derivatives at x_i and x_{i+1}.
• h = x_{i+1} - x_i is the distance between the two points.
• (x_{i+1} - x) and (x - x_i) are the relative distances within the segment.

Example Usages (Non-code)

This method is typically used for high-precision curve fitting or graphical rendering where smooth transitions between points are essential. Common applications include:

• Signal processing.
• Data interpolation for missing values.
• Smooth graphical representations of mathematical functions.

Related Types

• Point2D: Represents a 2D point and is used as input/output for this function.
• CurveError Represents any error encountered during interpolation.

Performance

• The function operates with O(n) complexity, where n is the number of points. The tridiagonal system is solved efficiently using the Thomas algorithm.

Notes

• Natural spline interpolation may introduce minor deviations beyond the range of existing data points due to its boundary conditions. For strictly constrained results, consider alternative interpolation methods, such as linear or cubic Hermite interpolation.

impl StatisticalCurve for Curve

fn get_x_values(&self) -> Vec<Decimal>

Retrieves the x-axis values for the statistical curve.

fn generate_statistical_curve( &self, basic_metrics: &BasicMetrics, shape_metrics: &ShapeMetrics, range_metrics: &RangeMetrics, trend_metrics: &TrendMetrics, num_points: usize, seed: Option<u64>, ) -> Result<Curve, CurveError>

Generates a statistical curve with properties that match the provided metrics.

fn generate_refined_statistical_curve( &self, basic_metrics: &BasicMetrics, shape_metrics: &ShapeMetrics, range_metrics: &RangeMetrics, trend_metrics: &TrendMetrics, num_points: usize, max_attempts: usize, tolerance: Decimal, seed: Option<u64>, ) -> Result<Curve, CurveError>

Generates a refined statistical curve that iteratively adjusts to better match the target metrics.

fn verify_curve_metrics( &self, curve: &Curve, target_metrics: &BasicMetrics, tolerance: Decimal, ) -> Result<bool, CurveError>

Verifies if the metrics of the generated curve match the target metrics within the specified tolerance.