bspy 4.1__py3-none-any.whl → 4.3__py3-none-any.whl

bspy/spline.py

@@ -2,6 +2,7 @@ import numpy as np
 from os import path
 import json
 from bspy.manifold import Manifold
+import bspy.spline_block
 import bspy._spline_domain
 import bspy._spline_evaluation
 import bspy._spline_intersection
@@ -78,7 +79,7 @@ class Spline(Manifold):
 
     def __repr__(self):
         return f"Spline({self.nInd}, {self.nDep}, {self.order}, " + \
-               f"{self.nCoef}, {self.knots} {self.coefs}, {self.metadata})"
+               f"{self.nCoef}, {self.knots}, {self.coefs}, {self.metadata})"
 
     def __add__(self, other):
         if isinstance(other, Spline):
@@ -124,6 +125,9 @@ class Spline(Manifold):
         else:
             return self.scale(other)
 
+    def __neg__(self):
+        return self.scale(-1.0)
+    
     def __sub__(self, other):
         if isinstance(other, Spline):
             return self.subtract(other, [(ix, ix) for ix in range(min(self.nInd, other.nInd))])
@@ -343,6 +347,42 @@ class Spline(Manifold):
         if slice.dimension != 1 and slice.dimension != 2: raise ValueError("Only works for nInd = 1 or 2")
         return bspy._spline_intersection.complete_slice(self, slice, solid)
 
+    @staticmethod
+    def composition(splines, tolerance = 1.0e-6):
+        """
+        Construct a spline approximation to a composition of splines sequence.
+
+        Parameters
+        ----------
+        splines : `array-like`
+            An array of splines.  The splines should have the property that the number
+            of independent variables of the ith spline should be the same as the number
+            of dependent variables of the (i+1)st spline.  The number of dependent
+            variables of the first spline is arbitrary, as is the number of independent
+            variables of the last one.  Moreover, the range of the ith spline should be
+            a subset of the domain of the (i-1)st spline.  The interpretation of the
+            sequence is s_0(s_1(... s_(n-1)(u)))).
+        
+        tolerance : `scalar`
+            The maximum 2-norm of the difference between the given function and the
+            spline fit.  Defaults to 1.0e-6.
+        
+        Returns
+        -------
+        spline : `Spline`
+            The spline which approximates the given composition.
+
+        Notes
+        -----
+        This currently defaults to a cubic spline.  Depending on user experience, this
+        may change in the future.
+
+        See also
+        --------
+        `fit` : Fit a given function to a specified tolerance.
+        """
+        return bspy._spline_fitting.composition(splines, tolerance)
+
     @staticmethod
     def cone(radius1, radius2, height, tolerance = None):
         """
@@ -409,6 +449,24 @@ class Spline(Manifold):
         """
         return bspy._spline_operations.confine(self, range_bounds)
 
+    def continuity(self):
+        """
+        Return the smoothness of the spline in each of its independent variables.
+
+        Returns
+        -------
+        `smoothness` : `iterable`
+            An array of length nInd containing the number of times the function is continuously
+            in each of the independent variables of the input spline.
+
+        Notes
+        -----
+        The value -1 is returned if the spline is discontinuous in that variable.  The degree of the spline
+        is returned if the spline contains no interior knots even though the spline is an analytic function
+        of that variable.
+        """
+        return bspy._spline_evaluation.continuity(self)
+
     @staticmethod
     def contour(F, knownXValues, dF = None, epsilon = None, metadata = {}):
         """
@@ -418,8 +476,8 @@ class Spline(Manifold):
 
         Parameters
         ----------
-        F : function or `Spline`
-            A function or spline that takes an array-like argument of length `n` and returns an 
+        F : function, `Spline`, or `SplineBlock`
+            A function, spline, or spline block that takes an array-like argument of length `n` and returns an 
             array-like result of length `n - 1`.
 
         knownXValues : `iterable` of array-like
@@ -428,11 +486,12 @@ class Spline(Manifold):
             All x values must be length `n` and be listed in the order they appear on the contour.  
             `F(x)` for all known x values must be a zero vector of length `n-1`.
 
-        dF : `iterable` or `None`, optional
-            An `iterable` of the `n` functions representing the `n` first derivatives of `F`. 
+        dF : function, `iterable`, or `None`, optional
+            A function that returns the Jacobian of F as an array with shape (n - 1, n). 
+            Can also be an `iterable` of `n` functions that return the `n` first derivatives of `F`. 
             If `dF` is `None` (the default), the first derivatives will be computed for you. 
-            If `F` is not a spline, computing the first derivatives involves multiple calls to `F` 
-            and can be numerically unstable. 
+            If `F` is not a spline or spline block, computing the first derivatives involves 
+            multiple calls to `F` and can be numerically unstable. 
 
         epsilon : `float`, optional
             Tolerance for contour precision. Evaluating `F` with contour values will be within epsilon 
@@ -455,7 +514,7 @@ class Spline(Manifold):
         Notes
         -----
         The returned spline has constant parametric speed (the length of its derivative is constant). 
-        If `F` is a `Spline`, then the range of the returned contour is confined to the domain of `F`. 
+        If `F` is a `Spline` or a `SplineBlock`, then the range of the returned contour is confined to the domain of `F`. 
         Implements the algorithm described in section 7 of Grandine, Thomas A. 
         "Applications of contouring." Siam Review 42, no. 2 (2000): 297-316.
         """
@@ -483,7 +542,7 @@ class Spline(Manifold):
         The algorithm used to to find all intersection curves is from Grandine, Thomas A., and Frederick W. Klein IV. 
         "A new approach to the surface intersection problem." Computer Aided Geometric Design 14, no. 2 (1997): 111-134.
         """
-        return bspy._spline_intersection.contours(self)
+        return bspy._spline_intersection.contours(bspy.spline_block.SplineBlock(self))
 
     def contract(self, uvw):
         """
@@ -581,7 +640,7 @@ class Spline(Manifold):
 
     def curvature(self, uvw):
         """
-        Compute the curvature of a univariate spline.
+        Compute the curvature of a univariate or bivariate spline.
 
         Parameters
         ----------
@@ -591,7 +650,8 @@ class Spline(Manifold):
         Returns
         -------
         value : scalar
-            The value of the curvature at the given point on the curve.
+            The value of the curvature at the given point on the curve or surface.  If called on a surface,
+            the value will represent the Gaussian curvature of the surface at the given point.
         
         Notes
         -----
@@ -895,6 +955,49 @@ class Spline(Manifold):
         """
         return bspy._spline_domain.extrapolate(self, newDomain, continuityOrder)
 
+    @staticmethod
+    def fit(domain, f, order = None, knots = None, tolerance = 1.0e-4):
+        """
+        Fit the function f with a spline to a given tolerance.
+
+        Parameters
+        ----------
+        domain - `array-like`
+            An nInd x 2 array which specifies the rectangular domain (in nInd dimensions)
+            over which the function f is defined.  The approximating spline which is the
+            output will be defined over the same rectangular domain
+        
+        f : Python function
+            The function to approximate.  It is a vector-valued function of nDep
+            components in nInd variables.  Alternatively, it can return a spline of any
+            number independent variables and nDep dependent variables.  In this case, the
+            resulting spline function will have nInd + number of independent variables
+            in the splines returned independent variables and nDep dependent variables.
+        
+        order : `array-like`
+            An optional integer array of length nInd which specifies the polynomial
+            order to use in each of the independent variables.  It will default to order
+            4 (degree 3) if None is specified (the default)
+        
+        knots : `array-like`
+            The initial knot sequence to use, if given
+        
+        tolerance : `scalar`
+            The maximum 2-norm of the difference between the given function and the
+            spline fit.  Defaults to 1.0e-4.
+        
+        Returns
+        -------
+        spline : `Spline`
+            A spline which approximates the given function to within the specified
+            tolerance.
+        
+        See Also
+        --------
+        `least_squares` : Fit a least squares approximation to given data.
+        """
+        return bspy._spline_fitting.fit(domain, f, order, knots, tolerance)
+    
     def flip_normal(self):
         """
         Flip the direction of the normal.
@@ -993,7 +1096,7 @@ class Spline(Manifold):
     @staticmethod
     def from_dict(dictionary):
         """
-        Create a `Spline` from a data in a `dict`.
+        Create a `Spline` from data in a `dict`.
 
         Parameters
         ----------
@@ -1009,7 +1112,7 @@ class Spline(Manifold):
         `to_dict` : Return a `dict` with `Spline` data.
         """
         return Spline(dictionary["nInd"], dictionary["nDep"], dictionary["order"], dictionary["nCoef"],
-                [np.array(knots) for knots in dictionary["knots"]], np.array(dictionary["coefs"]), dictionary["metadata"])
+                [np.array(knots) for knots in dictionary["knots"]], np.array(dictionary["coefs"]), dictionary.get("metadata", {}))
 
     def full_domain(self):
         """
@@ -1111,7 +1214,12 @@ class Spline(Manifold):
         ----------
         newKnots : `iterable` of length `nInd`
             An iterable that specifies the knots to be added to each independent variable's knots. 
-            len(newKnots[ind]) == 0 if no knots are to be added for the `ind` independent variable.
+            len(newKnots[ind]) == 0 if no knots are to be added for the `ind` independent variable. 
+            
+            Each knot may be specified as its knot value or a tuple indicating the knot value and its multiplicity. 
+            For example, spline.insert_knots([[0.1, (0.3, 2)], [(.5, 3), .2, .5]]) will insert 0.1 once and 0.3 twice into 
+            the knots of the first independent variable, and will insert 0.2 once and 0.5 four times into the knots of the 
+            second independent variable. Knots do not need to be sorted.
 
         Returns
         -------
@@ -1128,48 +1236,46 @@ class Spline(Manifold):
         """
         return bspy._spline_domain.insert_knots(self, newKnots)
 
-    def integral(self, with_respect_to, uvw1, uvw2, returnSpline = False):
+    def integral(self, integrand = None, domain = None):
         """
-        Compute the derivative of the spline at given parameter values.
+        Compute the integral of a function composed with a spline.  In particular, compute the
+        nInd-dimensional integral over the specified domain of the quantity f(x_0, x_1, ..., x_{nDep - 1})dA,
+        where x_i is the (i+1)-th dependent variable, and dA is the multivariate measure of the spline mapping.
 
         Parameters
         ----------
-        with_respect_to : `iterable`
-            An iterable of length `nInd` that specifies the integer order of integral for each independent variable.
-            A zero-order integral just evaluates the spline normally.
-        
-        uvw1 : `iterable`
-            An iterable of length `nInd` that specifies the lower limit of each independent variable (the parameter values).
+        integrand : Python function, optional
+            A Python function which takes an array-like object of length nDep as input and returns a
+            scalar.  If None is specified for integrand, then the function which returns a constant value
+            of one is used.  This computes the volume measure of the spline itself (arc length, surface area,
+            volume, etc.) depending on the dimensionality of the spline itself.
+    
+        domain : array-like
+            nInd x 2 array of the lower and upper limits of integration for the spline on each of the
+            independent variables.  If domain is None, then the actual domain of the spline is used.
         
-        uvw2 : `iterable`
-            An iterable of length `nInd` that specifies the upper limit of each independent variable (the parameter values).
-
-        returnSpline : `boolean`, optional
-            A boolean flag that if true returns the integrated spline along with the value of its integral. Default is false.
- 
         Returns
         -------
-        value : `numpy.ndarray`
-            The value of the integral of the spline at the given parameter limits.
-
-        spline : `Spline`
-            The integrated spline, which is only returned if `returnSpline` is `True`.
-
+        integral_value : `float`
+            The computed value of the specified integral
+        
         See Also
         --------
-        `integrate` : Integrate a spline with respect to one of its independent variables, returning the resulting spline.
-        `evaluate` : Compute the value of the spline at a given parameter value.
-        `differentiate` : Differentiate a spline with respect to one of its independent variables, returning the resulting spline.
-        `derivative` : Compute the derivative of the spline at a given parameter value.
+        `integrate` : Integrate a spline with respect to one of its independent variables, returning
+                      the resulting spline.
 
         Notes
         -----
-        The integral method uses the integrate method to integrate the spline `with_respect_to` times for each independent variable.
-        Then the method returns that integrated spline's value at `uw2` minus its value at `uw1` (optionally along with the spline).
-        The method doesn't calculate the integral directly because the number of operations required is nearly the same as constructing
-        the integrated spline.
+        This function is very useful for computing mass properties of splines.  If the integrand function
+        returns one, then the volume measure of the spline itself is computed (arc length, surface area,
+        volume, etc.).  If the integrand function returns one of the dependent variable values, then the
+        integral will be the first moment of the spline with respect to that variable, making it possible
+        to compute centroids and center of mass.  The integrand function should be smooth, but is otherwise
+        unrestricted.
+
+        Attempts to compute the integral to two digits less than machine precision.
         """
-        return bspy._spline_evaluation.integral(self, with_respect_to, uvw1, uvw2, returnSpline)
+        return bspy._spline_evaluation.composed_integral(self, integrand, domain)
 
     def integrate(self, with_respect_to = 0):
         """
@@ -1178,7 +1284,7 @@ class Spline(Manifold):
         Parameters
         ----------
         with_respect_to : integer, optional
-            The number of the independent variable to integrate. Default is zero.
+            The index of the independent variable to integrate. Default is zero.
 
         Returns
         -------
@@ -1546,7 +1652,7 @@ class Spline(Manifold):
         dependent variables (instead of one less, as is typical). In that case, the normal represents the null space of 
         the matrix formed by the tangents of the spline. If the null space is greater than one dimension, the normal will be zero.
         """
-        return bspy._spline_operations.normal_spline(self, indices)
+        return bspy._spline_operations.normal_spline(bspy.spline_block.SplineBlock(self), indices)
 
     @staticmethod
     def point(point):
@@ -1943,6 +2049,35 @@ class Spline(Manifold):
         `multiply` : Multiply two splines together.
         """
         return bspy._spline_fitting.sphere(radius, tolerance)
+
+    def split(self, minContinuity = 0, breaks = None):
+        """
+        Split a spline into separate spline pieces.
+
+        Parameters
+        ----------
+        minContinuity : `int`, optional
+            The minimum expected continuity of each spline piece. The default is zero, for C0 continuity.
+
+        breaks : `iterable` of length `nInd` or `None`, optional
+            An iterable that specifies the breaks at which to separate the spline. 
+            len(breaks[ind]) == 0 if there the spline isn't separated for the `ind` independent variable. 
+            If breaks is `None` (the default), the spline will only be separated at discontinuities.
+
+        Returns
+        -------
+        splineArray : array of `Spline`
+            A array of splines with nInd dimensions containing the spline pieces. 
+
+        See Also
+        --------
+        `join` : Join a list of splines together into a single spline.
+        """
+        splineArray = bspy.spline_block.SplineBlock(self).split(minContinuity, breaks)
+        splines = splineArray.ravel()
+        for i, block in enumerate(splines):
+            splines[i] = block.block[0][0][1]
+        return splines.reshape(splineArray.shape)
     
     def subtract(self, other, indMap = None):
         """
@@ -1985,7 +2120,7 @@ class Spline(Manifold):
 
     def tangent_space(self, uvw):
         """
-        Return the tangent space of the spline.
+        Return the tangent space of the spline. (Same as Jacobian.)
 
         Parameters
         ----------
@@ -1997,7 +2132,7 @@ class Spline(Manifold):
         tangentSpace : `numpy.array`
             The nDep x nInd matrix of tangent vectors (tangents are the columns).
         """
-        return bspy._spline_evaluation.tangent_space(self, uvw)
+        return bspy._spline_evaluation.jacobian(self, uvw)
 
     def to_dict(self):
         """
@@ -2164,9 +2299,11 @@ class Spline(Manifold):
 
         Returns
         -------
-        trimmedSpline, rangeBounds : `Spline`, `np.array`
-            A spline trimmed to the given domain bounds, and the range of the trimmed spline given as 
-            lower and upper bounds on each dependent variable.
+        trimmedSpline : `Spline`
+            A spline trimmed to the given domain bounds.
+        
+        rangeBounds : `np.array`
+            The range of the trimmed spline given as lower and upper bounds on each dependent variable.
 
         See Also
         --------
@@ -2213,7 +2350,7 @@ class Spline(Manifold):
         """
         return bspy._spline_domain.unfold(self, foldedInd, coefficientlessSpline)
 
-    def zeros(self, epsilon=None):
+    def zeros(self, epsilon=None, initialScale=None):
         """
         Find the roots of a spline (nInd must match nDep).
 
@@ -2223,6 +2360,10 @@ class Spline(Manifold):
             Tolerance for root precision. The root will be within epsilon of the actual root. 
             The default is the machine epsilon.
 
+        initialScale : array-like, optional
+            The initial scale of each dependent variable (as opposed to the current scale of 
+            the spline, which may have been normalized). The default is an array of ones (size nDep).
+
         Returns
         -------
         roots : `iterable`
@@ -2233,7 +2374,7 @@ class Spline(Manifold):
         See Also
         --------
         `intersect` : Intersect two splines.
-        `contour` : Fit a spline to the contour defined by `F(x) = 0`.
+        `contours` : Find all the contour curves of a spline whose `nInd` is one larger than its `nDep`.
 
         Notes
         -----
@@ -2246,4 +2387,5 @@ class Spline(Manifold):
         if self.nInd <= 1:
             return bspy._spline_intersection.zeros_using_interval_newton(self)
         else:
-            return bspy._spline_intersection.zeros_using_projected_polyhedron(self, epsilon)
+            return bspy._spline_intersection.zeros_using_projected_polyhedron(bspy.spline_block.SplineBlock(self), epsilon, initialScale)
+