Struct Surface 

pub struct Surface {
    pub points: BTreeSet<Point3D>,
    pub x_range: (Decimal, Decimal),
    pub y_range: (Decimal, Decimal),
}

Represents a mathematical surface in 3D space.

Overview

The Surface struct defines a three-dimensional surface composed of a collection of 3D points. It tracks the range of coordinates in the X and Y dimensions to establish the boundaries of the surface.

Fields

• points: A sorted collection of Point3D objects that define the surface geometry. BTreeSet keeps them ordered and rejects an exact duplicate of the full (x, y, z) triple; it does not stop two heights from sitting above one xy-coordinate. See Surface::new for the one-height-per-cell rule and for why it is a convention rather than an invariant.
• x_range: A tuple containing the minimum and maximum x-coordinates of the surface as Decimal values, representing the surface’s width boundaries.
• y_range: A tuple containing the minimum and maximum y-coordinates of the surface as Decimal values, representing the surface’s depth boundaries.

Examples

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

// Create some 3D points
let mut points = BTreeSet::new();
points.insert(Point3D { x: dec!(0.0), y: dec!(0.0), z: dec!(1.0) });
points.insert(Point3D { x: dec!(1.0), y: dec!(0.0), z: dec!(2.0) });
points.insert(Point3D { x: dec!(0.0), y: dec!(1.0), z: dec!(1.5) });
points.insert(Point3D { x: dec!(1.0), y: dec!(1.0), z: dec!(2.5) });

// Create a surface with these points
let surface = Surface {
    points,
    x_range: (dec!(0.0), dec!(1.0)),
    y_range: (dec!(0.0), dec!(1.0)),
};

Usage

Surface is primarily used for mathematical modeling, data visualization, and numerical analysis. It can represent various 3D structures such as option pricing surfaces, terrain models, or any other data that can be plotted in three dimensions.

Fields

points: BTreeSet<Point3D>

Collection of 3D points defining the surface.

Public, so a struct literal can populate it without passing through Surface::new. No constructor can therefore guarantee one height per xy-coordinate.

x_range: (Decimal, Decimal)

The minimum and maximum x-coordinates of the surface (min_x, max_x)

y_range: (Decimal, Decimal)

The minimum and maximum y-coordinates of the surface (min_y, max_y)

Implementations

impl Surface

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

Creates a new instance from a set of 3D points.

Parameters

• points: A sorted set of Point3D objects that will form this geometric object.

Returns

A new instance of the implementing structure with computed x and y ranges.

Details

This constructor initializes a geometric object by:

1. Computing the minimum and maximum x-coordinate values
2. Computing the minimum and maximum y-coordinate values
3. Storing the provided points and calculated ranges

The ranges are calculated using the calculate_range utility method defined in the GeometricObject trait.

Examples

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

let mut points = BTreeSet::new();
points.insert(Point3D { x: dec!(1.0), y: dec!(2.0), z: dec!(3.0) });
points.insert(Point3D { x: dec!(4.0), y: dec!(5.0), z: dec!(6.0) });

let object = Surface::new(points);

One height per xy-coordinate

A Surface is a function of its (x, y) coordinate: at most one z above each cell. Every consumer reads it that way. get_point and contains_point answer from the first point matching (x, y), and merge_axis_interpolate resamples both surfaces onto one shared xy-grid with one z per cell.

Nothing enforces the rule. Point3D orders on the full (x, y, z) triple, so points may hold several heights above one xy-coordinate and new stores them all; a surface built that way is outside the contract, and get_point then silently returns the lowest z of the stack, the first in (x, y, z) order, while contains_point reports only that something is there. Use get_values to see every z above a cell.

Normalizing here would not help: points is a pub field, so a struct literal reaches the same state without going through any constructor. Rejecting or collapsing a duplicate can only ever be a convenience on this path, never an invariant of the type.

The one projection that is genuinely multi-valued, Surface::project_onto, returns a Vec<Point2D> for that reason and never a Curve.

pub fn project_onto(&self, axis: Axis) -> Vec<Point2D>

Projects the surface onto a 2D plane by dropping one coordinate.

The projection is perpendicular to axis: the coordinate naming the axis is omitted and the remaining two become the abscissa and the ordinate of a Point2D.

Parameters

• &self: Reference to the Surface instance
• axis (Axis): The axis perpendicular to the projection plane:
  • Axis::X: Projects onto the YZ plane (x-coordinate is omitted)
  • Axis::Y: Projects onto the XZ plane (y-coordinate is omitted)
  • Axis::Z: Projects onto the XY plane (z-coordinate is omitted)

Returns

• Vec<Point2D>: exactly one projected point per surface point, sorted ascending by the projected (x, y) pair.

Behavior

• For Axis::X, the returned points carry (y, z) coordinates
• For Axis::Y, the returned points carry (x, z) coordinates
• For Axis::Z, the returned points carry (x, y) coordinates

Multi-valued projections

Dropping a coordinate from a grid is multi-valued: every row of the grid contributes a different height above the same projected abscissa. A projection of an n-by-m grid therefore yields n * m points, several of which share an abscissa, and two rows that agree on the two surviving coordinates project onto the very same point.

That is why this returns a Vec and not a Curve. A curve is a function of its abscissa (see Curve::new) and it stores its points in a BTreeSet, which drops every projected point equal to one already collected. The vector keeps all of them: result.len() == self.points.len(), always.

Callers that need a function of the projected abscissa must aggregate the ordinates sharing one themselves. This method does not choose an aggregation for them, and building a Curve from the result without aggregating first is exactly the loss the return type exists to prevent.

pub fn get_f64_points(&self) -> Result<Vec<(f64, f64, f64)>, SurfaceError>

Converts the surface points from Decimal to f64 format, with swapped y and z coordinates.

Returns

A vector of tuples containing the coordinates of each point in the surface as (x, z, y) where each coordinate is converted to an f64 value.

Details

• This function is only available on non-WebAssembly targets.
• The coordinates are returned as (x, z, y) tuples, with y and z swapped.
• If the conversion from Decimal to f64 fails for any coordinate, that value will be replaced with 0.0.

Example

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

let mut points = BTreeSet::new();
points.insert(Point3D { x: dec!(1.5), y: dec!(3.0), z: dec!(2.0) });
points.insert(Point3D { x: dec!(2.5), y: dec!(4.0), z: dec!(3.0) });

let surface = Surface {
    points,
    x_range: (dec!(1.0), dec!(3.0)),
    y_range: (dec!(3.0), dec!(4.0)),
};

// Will produce: [(1.5, 2.0, 3.0), (2.5, 3.0, 4.0)]
let points = surface.get_f64_points();

Errors

SurfaceError::Point3DError when a coordinate has no f64 conversion (decimal_to_f64, #828). It used to read as 0.0.

Trait Implementations

impl Arithmetic<Surface> for Surface

fn merge( surfaces: &[&Surface], operation: MergeOperation, ) -> Result<Surface, Self::Error>

Merges a collection of surfaces into one, resampled onto a 51 x 51 grid over the intersection of their ranges.

Each cell of the grid interpolates every operand and combines the heights with operation. An empty slice is an error; a single surface is returned as a clone.

Determinism

The same operands in the same order give the same result, digit for digit. Within a cell the heights are accumulated in the order they were passed in, never in an order chosen by the thread pool: Decimal multiplication rounds once a product needs more than 28 decimal digits and is therefore not associative, so a parallel reducer would take its bracketing from rayon’s chunking and could return different last digits on consecutive runs of one binary over one input.

Max and Min still reduce in parallel; they select a height rather than accumulating one, so no rounding enters, and the same caveat about ties between equal Decimal values at different scales applies as it does to Curve::merge.

Errors

• SurfaceError::OperationError when no surfaces are supplied or their ranges do not intersect.
• The interpolation error of the operand that failed, and any checked-arithmetic failure raised while combining the heights.

type Error = SurfaceError

The error type returned when merging operations fail

fn merge_with( &self, other: &Surface, operation: MergeOperation, ) -> Result<Surface, Self::Error>

Merges the current curve with another curve using the specified merge operation.

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<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 Surface

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 Surface

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

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 Surface

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

Formats the value using the given formatter.

impl Default for Surface

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Surface

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

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<Point3D> for Surface

type Error = SurfaceError

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<Point3D>, Self::Error>

Finds all intersection points between this geometric object and another.

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

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

fn extrema(&self) -> Result<(Point3D, Point3D), 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 Index<usize> for Surface

Implementation of the Index trait for Surface, allowing direct indexing access to surface points.

Overview

This implementation allows you to access individual points in a Surface using array-like indexing notation (e.g., surface[0], surface[1]). Points are retrieved in the order they appear in the underlying BTreeSet.

Panics

Panics if index >= self.points.len(). This matches the documented contract of std::ops::Index and of Vec. Index has no error channel; for a lookup that reports a missing index, use get_points().into_iter().nth(index).

Performance

Note that this implementation uses iter().nth(index) which has O(n) time complexity for BTreeSet. For frequent access to points by index, consider using a data structure with O(1) indexing performance.

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

Retrieves a reference to a point on the surface at the specified index.

This implementation allows using indexing syntax (e.g., surface[i]) to access individual points that make up the surface.

Panics

Panics if index >= self.points.len().

type Output = Point3D

The returned type after indexing.

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 Len for Surface

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<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<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 MetricsExtractor for Surface

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 Serialize for Surface

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

where __S: Serializer,

Serialize this value into the given Serde serializer.

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 Surface

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.