Struct Point2D 

pub struct Point2D {
    pub x: Decimal,
    pub y: Decimal,
}

Represents a point in two-dimensional space with x and y coordinates.

Overview

The Point2D struct is used to define a point in a 2D Cartesian coordinate system. Both coordinates are stored as Decimal values to provide high precision, making it suitable for applications requiring accurate numerical calculations.

Usage

This structure serves as a fundamental data type in various geometric operations:

• Defining positions in curve plotting and interpolation
• Representing intersections between curves
• Serving as input/output for mathematical transformations
• Supporting coordinate-based algorithms in the library

Examples

use rust_decimal_macros::dec;
use optionstratlib_math::curves::Point2D;

// Create a point at coordinates (3.5, -2.25)
let point = Point2D {
    x: dec!(3.5),
    y: dec!(-2.25)
};

Derivable Traits

• Debug: Enables formatted debugging output
• Clone and Copy: Allow efficient duplication of point values
• Serialize and Deserialize: Support for serialization frameworks

This struct is primarily used in conjunction with the Curve and Curvable types to represent mathematical curves and perform geometric operations.

Fields

x: Decimal

The x-coordinate in the Cartesian plane, represented as a high-precision Decimal value to ensure accuracy in mathematical operations.

y: Decimal

The y-coordinate in the Cartesian plane, represented as a high-precision Decimal value to ensure accuracy in mathematical operations.

Implementations

impl Point2D

pub fn new<T: Into<Decimal>, U: Into<Decimal>>(x: T, y: U) -> Self

Creates a new instance of Point2D using the specified x and y coordinates.

Parameters

• x: The x-coordinate of the point, which implements Into<Decimal>.
• y: The y-coordinate of the point, which implements Into<Decimal>.

Returns

A Point2D instance with the provided x and y coordinates, converted into Decimal.

Usage

This function is used when creating a Point2D object from any type that can be converted into Decimal, allowing flexibility in input types (e.g., f64, i32, etc.).

pub fn to_tuple<T: TryFrom<Decimal> + 'static, U: TryFrom<Decimal> + 'static>( &self, ) -> Result<(T, U), CurveError>

Converts the Point2D instance into a tuple (T, U).

Parameters

• T: The type for the x-coordinate, which must implement From<Decimal> and have a ’static lifetime.
• U: The type for the y-coordinate, which must implement From<Decimal> and have a ’static lifetime.

Returns

• Ok: A tuple (T, U) containing the converted x and y values.
• Err: A CurvesError if conversion constraints are violated:
  • x must be positive if T is the Positive type.
  • y must be positive if U is the Positive type.

Errors

This function returns an error if the positivity constraints are violated or if conversions fail due to invalid type requirements.

pub fn from_tuple<T: Into<Decimal>, U: Into<Decimal>>( x: T, y: U, ) -> Result<Self, CurveError>

Creates a new Point2D instance from a tuple containing x and y values.

Parameters

• x: The x-coordinate, which implements Into<Decimal>.
• y: The y-coordinate, which implements Into<Decimal>.

Returns

• Ok: A new Point2D instance with the given x and y coordinates.
• Err: A CurvesError if coordinate creation fails.

Usage

This function allows constructing a Point2D directly from a tuple representation.

Errors

Currently infallible for the blanket Into<Decimal> bounds; the Result signature is retained so future implementations that can reject non-finite or out-of-range conversions (e.g. via TryFrom<f64>) can surface CurveError::ConstructionError without a breaking change.

pub fn to_f64_tuple(&self) -> Result<(f64, f64), CurveError>

Converts the Point2D instance into a tuple of (f64, f64).

Returns

• Ok: A tuple (f64, f64) containing the x and y values.
• Err: A CurvesError if either x or y cannot be converted from Decimal to f64 (e.g., out-of-range value).

Errors

Returns a CurvesError::Point2DError with a reason explaining the failure.

pub fn from_f64_tuple(x: f64, y: f64) -> Result<Self, CurveError>

Creates a new Point2D instance from a tuple of (f64, f64) values.

Parameters

• x: The x-coordinate of the point as a f64.
• y: The y-coordinate of the point as a f64.

Returns

• Ok: A new Point2D instance if both x and y values can be successfully converted from f64 to Decimal.
• Err: A CurvesError if the conversion fails (e.g., invalid precision).

Errors

Returns a CurvesError::Point2DError with a reason if either x or y could not be converted from f64.

Trait Implementations

impl AxisOperations<Point2D, Decimal> for Curve

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

Reports whether the curve has a point at the abscissa x.

Answers on x alone, so it says nothing about how many ordinates sit there. On a curve honouring the one-point-per-abscissa rule of Curve::new there is at most one.

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

Returns the abscissa of every point, in (x, y) order.

A curve holding several ordinates at one abscissa yields that abscissa once per ordinate; the duplicates are visible here rather than dropped.

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

Returns every ordinate at the abscissa x, in ascending order.

This is the multi-valued reader: unlike Self::get_point, it never picks a survivor. A curve honouring the one-point-per-abscissa rule of Curve::new returns at most one value; anything longer says the curve is not a function of its abscissa.

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

Returns the point at the abscissa x, if there is one.

Assumes the one-point-per-abscissa rule of Curve::new. If the curve breaks it, this returns the first match in (x, y) order, which is the lowest ordinate of the stack, and the rest are invisible to the caller. Use Self::get_values to see all of them.

type Error = CurveError

The type of error that can occur during point operations

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

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 AxisOperations<Point3D, Point2D> for Surface

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

Reports whether any point sits above the xy-coordinate x.

Answers on the (x, y) pair alone, so it says nothing about how many heights are stacked there. On a surface honouring the one-height-per-cell rule of Surface::new there is at most one.

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

Returns the xy-coordinate of every point, in (x, y, z) order.

A surface holding several heights above one cell yields that cell once per height; the duplicates are visible here rather than dropped.

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

Returns every z above the xy-coordinate x, in ascending order.

This is the multi-valued reader: unlike Self::get_point, it never picks a survivor. A surface honouring the one-height-per-cell rule of Surface::new returns at most one value; anything longer says the surface is not a function of its xy-coordinate.

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

Returns the point above the xy-coordinate x, if there is one.

Assumes the one-height-per-cell rule of Surface::new. If the surface breaks it, this returns the first match in (x, y, z) order, which is the lowest z of the stack, and the rest are invisible to the caller. Use Self::get_values to see all of them.

type Error = SurfaceError

The type of error that can occur during point operations

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

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.

What it computes

Bilinear interpolation is defined on a cell of a two-dimensional grid: the answer is the mean of four corner samples, weighted by the query’s fractional position along each axis. A curve has one axis, so the cell is built out of two of its segments and the second fraction is fixed at one half:

• the near edge is the segment that brackets x, from sample i to sample i + 1;
• the far edge is the segment two positions further along, from sample f to sample f + 1;
• the answer is the mean of the two edges read at the same fraction.

t    = (x - x[i]) / (x[i+1] - x[i])
near = y[i] + t * (y[i+1] - y[i])
far  = y[f] + t * (y[f+1] - y[f])
y    = (near + far) / 2

Behaviour near the upper boundary

The far edge is f = i + 2 while such a segment exists. Over the last two segments of the curve it does not, and f is clamped to len - 2, the curve’s last segment. Two consequences a caller can act on:

• on the final segment the two edges coincide, near equals far, and the answer is the linear interpolant there. Not always to the last digit: this method normalises x before scaling by the rise and LinearInterpolation::linear_interpolate scales first, so where the fraction along the segment has no finite decimal expansion the two round at scale 28 on different quantities and can part company in the 28th place;
• on the second-to-last segment the far edge is the segment immediately after the near one instead of the one after that.

Why not clamp the window start

The obvious repair, and the one CubicInterpolation::cubic_interpolate applies at its own boundary, is to slide the whole window back to the last four samples. Do not reach for it here. The window start is also the denominator of t, so moving it back off the segment holding x pushes t past 1. Written out, the answer weights the four ordinates it reads by

y = (1 - t)/2 * y[i] + t/2 * y[i+1] + (1 - t)/2 * y[f] + t/2 * y[f+1]

which sums to one for any t, but has every weight non-negative only while t is in [0, 1]. Past 1 the two (1 - t)/2 weights go negative, the answer stops being a convex combination of the cell’s corners, and what is left is an extrapolation of a cell that does not contain x: on (0,0), (1,1), (2,4), (3,9) the window-start clamp returns 9.5 at x = 2.5, above every ordinate the curve has. Being a convex combination of its cell’s corners is what makes bilinear interpolation bilinear interpolation, so it is the near edge that has to stay put and the far edge that gives way. That is why the two boundary rules differ.

Before this rule existed the last two segments returned InterpolationError::Bilinear because the window ran off the end.

What this is not

The far edge sits elsewhere on the curve, so the result does not follow the samples between knots and this is not an interpolant through them: on (0,0), (1,1), (2,4), (3,9) the value at x = 0.5 is 3.5, not the 0.5 a straight reading of the bracketing segment gives.

An x landing exactly on a sample returns that sample, which neither one-sided limit approaching it matches, so the result jumps at every sample. That jump is as old as the method and owes nothing to the boundary rule above: on (0,0), (1,1), (2,4), (3,9), (4,16) both limits at x = 1 are 5 against a sample of 1, and both segments meeting there are far from the clamp. What the clamp does add is that at the last two samples before the end of the curve the two limits no longer agree with each other either, because the segments on either side get different far edges.

Reach for LinearInterpolation or SplineInterpolation when a curve through the samples is what is wanted.

Parameters

• x: The x-coordinate to interpolate at. Must lie within the range of the curve’s x-coordinates.

Returns

• Ok(Point2D): The interpolated point at x, both coordinates as Decimal.
• Err(InterpolationError): See the error list below.

Errors

• InterpolationError::Bilinear: the curve holds fewer than four samples, or a checked-arithmetic step left the representable Decimal range.
• InterpolationError::OutOfRange: x falls outside the curve’s x-range.
• InterpolationError::DegenerateInterval: several samples share the abscissa x, so the curve has no value there.

One point per abscissa

A curve is a function of its abscissa; see Curve::new. Asking for a repeated abscissa returns InterpolationError::DegenerateInterval, as it does for the three sibling algorithms; no ordinate of the stack is chosen. A stack elsewhere on the curve does not stop this method answering: only the near edge’s width is divided by, and a stack sitting on the far edge is read for its two ordinates alone.

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>

Reads the curve at x as the mean of the bracketing segment and the segment two positions further along, both at the same fraction.

The far segment is clamped to the curve’s last one where it would run off the end, which makes the final segment a plain linear interpolation. The impl-level documentation states the rule and its consequences in full.

Errors

• InterpolationError::Bilinear when the curve holds fewer than four samples, or when a checked-arithmetic step leaves the representable Decimal range.
• InterpolationError::OutOfRange when x is outside the curve’s x-range.
• InterpolationError::DegenerateInterval when several samples share the abscissa x.

impl BiLinearInterpolation<Point3D, Point2D> for Surface

fn bilinear_interpolate( &self, xy: Point2D, ) -> Result<Point3D, InterpolationError>

Performs bilinear interpolation to compute a value for the given input.

impl Clone for Point2D

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ComposeSchema for Point2D

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Copy for Point2D

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.
• If the curve is not a function of its abscissa at the point it is asked about, it returns InterpolationError::DegenerateInterval: several points at x leave the exact-match branch with no single value to return, and two consecutive points sharing an abscissa leave the interpolation bracket with zero width. Neither case picks an ordinate. See Curve::new for the rule.

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 CubicInterpolation<Point3D, Point2D> for Surface

fn cubic_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Interpolates a new point on the curve for a given x input value using cubic interpolation.

impl Debug for Point2D

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Point2D

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Point2D

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

Formats the value using the given formatter.

impl Eq for Point2D

impl From<&Point2D> for Point2D

fn from(point: &Point2D) -> Self

Converts to this type from the input type.

impl GeometricObject<Point2D, Decimal> for Curve

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

where T: Into<Point2D> + Clone,

Builds a curve from a vector of convertible points.

One point per abscissa

Same rule and same non-enforcement as Curve::new: a curve is a function of its abscissa, and this constructor does not check it. points is collected into a BTreeSet, which drops an exact duplicate of an (x, y) pair but keeps two ordinates that merely share an x. Aggregate before calling if the input can carry several ordinates per abscissa, as the projection returned by crate::surfaces::Surface::project_onto does.

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 construct<T>(method: T) -> Result<Self, Self::Error>

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

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 GeometricObject<Point3D, Point2D> for Surface

Implementation of the GeometricObject trait for the Surface struct.

This implementation provides functionality to create and manipulate 3D surfaces using points in three-dimensional space. It supports construction from explicit point collections or through parametric functions.

Type Parameters

• Uses Point3D as the points that form the surface
• Uses Point2D as the parametric input for surface generation

Methods

• get_points(): Retrieves all points in the surface
• from_vector(): Constructs a surface from a vector of points
• construct(): Creates a surface using different construction methods

Error Handling

Uses SurfaceError for various error conditions, including:

• Empty point collections
• Invalid construction parameters
• Errors during parametric function evaluation

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

Returns a borrowed reference to all points in the surface as an ordered set

Returns

• BTreeSet<&Point3D> - A sorted set containing references to all points that define the surface, maintaining the natural ordering of points

Example

use optionstratlib_math::surfaces::{Surface, Point3D};
use std::collections::BTreeSet;
use rust_decimal_macros::dec;
use optionstratlib_math::geometrics::GeometricObject;

// Create a surface with some points
let mut surface = Surface {
    points: BTreeSet::new(),
    x_range: (dec!(0), dec!(10)),
    y_range: (dec!(0), dec!(10)),
};

// Add points to the surface
surface.points.insert(Point3D { x: dec!(1.0), y: dec!(2.0), z: dec!(3.0) });
surface.points.insert(Point3D { x: dec!(4.0), y: dec!(5.0), z: dec!(6.0) });

// Get references to all points in the surface
let points = surface.get_points();
assert_eq!(points.len(), 2);

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

where T: Into<Point3D> + Clone,

Creates a new Surface from a vector of points that can be converted into Point3D objects.

This method constructs a Surface by converting each point in the input vector to a Point3D and collecting them into an ordered set. It also calculates the x and y coordinate ranges of the points to define the surface’s boundaries.

Type Parameters

• T: A type that can be converted into Point3D via the Into trait and can be cloned.

Parameters

• points: A vector of objects that can be converted to Point3D.

Returns

A new Surface instance containing the converted points and their coordinate ranges.

Example

use optionstratlib_math::surfaces::{Surface, Point3D};
use optionstratlib_math::geometrics::GeometricObject;
use rust_decimal_macros::dec;

// Create points data
let points = vec![
    Point3D { x: dec!(1.0), y: dec!(2.0), z: dec!(3.0) },
    Point3D { x: dec!(4.0), y: dec!(5.0), z: dec!(6.0) }
];

// Create a surface from the points
let surface = Surface::from_vector(points);

// The surface will contain both points and have x_range and y_range calculated automatically
assert_eq!(surface.points.len(), 2);
assert_eq!(surface.x_range, (dec!(1.0), dec!(4.0)));
assert_eq!(surface.y_range, (dec!(2.0), dec!(5.0)));

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

where Self: Sized, T: Into<ConstructionMethod<Point3D, Point2D, SurfaceError>>,

Constructs a Surface from a given construction method.

This function creates a Surface object from either a set of 3D points or a parametric function.

Parameters

• method - A construction method that can be converted into a ConstructionMethod<Point3D, Point2D, SurfaceError>

Type Parameters

• T - Type that can be converted into a ConstructionMethod<Point3D, Point2D, SurfaceError>

Returns

• Result<Self, Self::Error> - Either a successfully constructed Surface or an error

Errors

• SurfaceError::Point3DError - If an empty points array is provided
• SurfaceError::ConstructionError - If invalid parameters are provided or the parametric function fails

Examples

Creating from existing points

use std::collections::BTreeSet;
use optionstratlib_math::geometrics::{ConstructionMethod, GeometricObject};
use optionstratlib_math::surfaces::{Point3D, Surface};
let points = BTreeSet::from_iter(vec![
    Point3D::new(0, 0, 0),
    Point3D::new(1, 0, 1),
    Point3D::new(0, 1, 1),
]);
let surface = Surface::construct(ConstructionMethod::FromData { points })?;

Creating from a parametric function

use rust_decimal_macros::dec;
use optionstratlib_math::curves::Point2D;
use optionstratlib_math::error::SurfaceError;
use optionstratlib_math::geometrics::{ConstructionMethod, ConstructionParams, GeometricObject};
use optionstratlib_math::surfaces::{Point3D, Surface};
let params = ConstructionParams::D3 {
    x_start: dec!(-1.0),
    x_end: dec!(1.0),
    y_start: dec!(-1.0),
    y_end: dec!(1.0),
    x_steps: 20,
    y_steps: 20,
};

// Parametric function defining a paraboloid: z = x² + y²
let f = Box::new(|p: Point2D| -> Result<Point3D, SurfaceError> {
    Ok(Point3D {
        x: p.x,
        y: p.y,
        z: p.x * p.x + p.y * p.y,
    })
});

let surface = Surface::construct(ConstructionMethod::Parametric { f, params })?;

type Error = SurfaceError

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

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

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

Reports the samples the two curves share.

What it computes

Every pair of samples (p1, p2), p1 from self and p2 from other, whose abscissas differ by less than 1e-6 and whose ordinates differ by less than 1e-6, contributes p1 to the result. The result is in (p1, p2) order: by self’s (x, y) order, then by other’s for one p1.

What it does not compute

Only coinciding samples are compared, never the segments between them. Two curves that cross between their samples are not reported, so (0, 0), (2, 2) and (0, 2), (2, 0), which cross at (1, 1), return nothing. A sample of self that coincides with several samples of other appears once per match. Whether a segment-crossing variant should exist is an open owner decision (#858); this method documents the current behaviour.

Cost

Both point sets are sorted by abscissa, so the samples of other within 1e-6 of p1 form a window that only slides forward as p1 advances. The walk is O(n + m) plus one step per matching pair, with no allocation beyond the result (#858). It visits the pairs the all-pairs comparison tested on ordinates, in the same order, so the result and any error are the same. When some abscissa difference could overflow, the all-pairs comparison runs instead, so the error names the same pair.

Errors

CurveError::AnalysisError when a coordinate difference leaves the Decimal range.

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 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 HasX for Point2D

fn get_x(&self) -> Decimal

Returns the X-coordinate value of this object.

impl Hash for Point2D

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

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 find_bracket_points( &self, x: Decimal, ) -> Result<(usize, usize), InterpolationError>

Same contract and same indices as the trait’s default, including the degenerate window over a repeated abscissa, without collecting the points into a Vec first: the pair is found in O(log n) and its index by counting the points before it (#858).

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

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

impl Interpolate<Point3D, Point2D> for Surface

Implementation of the Interpolate trait for the Surface type, enabling interpolation from 3D surface points to 2D points.

Overview

This implementation allows a Surface object to perform various types of interpolation (linear, bilinear, cubic, and spline) by projecting 3D points from the surface to 2D points.

Functionality

By implementing the Interpolate trait, Surface gains the following capabilities:

• Interpolating between 3D surface points to produce 2D projections
• Finding bracket points for interpolation operations
• Supporting multiple interpolation algorithms through the trait’s methods

Usage Example

use rust_decimal_macros::dec;
use optionstratlib_math::surfaces::{Surface, Point3D};
use optionstratlib_math::curves::Point2D;
use optionstratlib_math::geometrics::{Interpolate, InterpolationType};

let surface = Surface::new(Default::default());

// Interpolate a 2D point at a specific position using linear interpolation
let input_point = Point2D { x: dec!(1.5), y: dec!(2.0) };
let result = surface.interpolate(input_point, InterpolationType::Linear);

Related Traits

This implementation relies on the surface also implementing:

• LinearInterpolation<Point3D, Point2D>
• BiLinearInterpolation<Point3D, Point2D>
• CubicInterpolation<Point3D, Point2D>
• SplineInterpolation<Point3D, Point2D>
• GeometricObject<Point3D, Point2D>

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 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.
• Degenerate Bracket: When several points share the requested abscissa. The curve has no value there and the bracket around it has zero width, so the method reports InterpolationError::DegenerateInterval instead of picking one of the ordinates stacked there.

One point per abscissa

A curve is a function of its abscissa; see Curve::new. Asking for a repeated abscissa returns InterpolationError::DegenerateInterval; no ordinate of the stack is chosen.

Away from the stack the method still answers, reading the stack as a vertical jump: an x strictly inside an interval bounded by a repeated abscissa brackets against the point on its own side, the highest ordinate when the stack bounds the interval on the left and the lowest when it bounds it on the right.

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 LinearInterpolation<Point3D, Point2D> for Surface

Linear Interpolation for Surfaces

Implementation of the LinearInterpolation trait for Surface structures, enabling interpolation from 2D points to 3D points using barycentric coordinates.

Overview

This implementation allows calculating the height (z-coordinate) of any point within the surface’s x-y range by using linear interpolation based on the three nearest points in the surface. The method employs barycentric coordinate interpolation with triangulation of the nearest points.

Algorithm

The interpolation process follows these steps:

1. Validate that the input point is within the surface’s range
2. Check for degenerate cases (all points at same location)
3. Check for exact matches with existing points
4. Find the three nearest points to the query point
5. Calculate barycentric coordinates for the triangle formed by these points
6. Interpolate the z-value using the barycentric weights

fn linear_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Parameters

• xy - A Point2D representing the x and y coordinates where interpolation is needed

Returns

• Result<Point3D, InterpolationError> - The interpolated 3D point if successful, or an appropriate error if interpolation cannot be performed

Errors

Returns InterpolationError::Linear in the following cases:

• When the surface contains only coincident points forming a degenerate triangle
• When the query point is outside the surface’s x-y range

impl MergeAxisInterpolate<Point2D, Decimal> for Curve

where Self: Sized,

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

Resamples both curves onto the shared x-grid of their merged indices.

Each result holds one point per abscissa of that grid, so it is a function of its abscissa whatever the inputs were: where a curve already has a point at an abscissa, the one kept is the first match in (x, y) order, so a stack of ordinates collapses to its lowest, and elsewhere the point is interpolated. Aggregate such a curve before merging if a different ordinate is wanted.

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 MergeAxisInterpolate<Point3D, Point2D> for Surface

where Self: Sized,

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

Resamples both surfaces onto the shared xy-grid of their merged indices.

Each result holds one z per cell of that grid, so it is a function of its xy-coordinate whatever the inputs were: where a surface already covers a cell, the point kept is the first match in (x, y, z) order, so a stack of heights above one cell collapses to its lowest. Aggregate such a surface before merging if a different height is wanted.

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 Ord for Point2D

Orders on (x, y), lexicographically: the same pair PartialEq reads, so cmp returns Ordering::Equal exactly when the points are equal.

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

fn clamp_to<R>(self, range: R) -> Self

where Self: Sized, R: ClampBounds<Self>,

🔬This is a nightly-only experimental API. (clamp_to)

Restrict a value to a certain range.

impl PartialEq for Point2D

Two points are equal when both coordinates are equal.

PartialEq, Ord and Hash all read the full (x, y) pair, so a == b holds exactly when a.cmp(&b) is Ordering::Equal, and equal points hash alike. Ord requires that agreement.

Comparing on x alone would also break Point2D in its second role: it is the index type of a surface (AxisOperations<Point3D, Point2D>), where it names a coordinate in the xy-plane and z is the dependent value. An x-only Eq/Hash collapses every column of a surface grid onto one cell whenever those indices pass through a HashSet.

The “one ordinate per abscissa” rule is a property of a curve, not of a point, and it is a container-level invariant that nothing enforces: crate::curves::Curve::new stores a repeated abscissa unchanged, and points is a pub field, so no constructor could. The rule and what each consumer does when it is broken are documented on crate::curves::Curve::new. A genuinely multi-valued projection is not a curve at all: crate::surfaces::Surface::project_onto returns a Vec<Point2D>.

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl PartialOrd for Point2D

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Serialize for Point2D

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.
• Every call solves the system again. To read one curve at many abscissas, solve it once with CurveSpline, which returns the same answers.

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.
• The knots must be a function of their abscissa. Several points at the requested x leave the exact-match branch with no single value to return, and any repeated abscissa collapses a knot interval, so both return InterpolationError::DegenerateInterval rather than picking an ordinate. See Curve::new for the rule.

impl SplineInterpolation<Point3D, Point2D> for Surface

fn spline_interpolate(&self, xy: Point2D) -> Result<Point3D, InterpolationError>

Interpolates a y-value for the provided x-coordinate using spline interpolation.

impl ToSchema for Point2D

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.