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

bspy/spline.py

@@ -1,13 +1,15 @@
 import numpy as np
 from os import path
 import json
+from bspy.manifold import Manifold
 import bspy._spline_domain
 import bspy._spline_evaluation
 import bspy._spline_intersection
 import bspy._spline_fitting
 import bspy._spline_operations
 
-class Spline:
+@Manifold.register
+class Spline(Manifold):
     """
     A class to model, represent, and process piecewise polynomial tensor product
     functions (splines) as linear combinations of B-splines. 
@@ -178,31 +180,6 @@ class Spline:
             indMap = [(mapping, mapping) if np.isscalar(mapping) else mapping for mapping in indMap]
         return bspy._spline_operations.add(self, other, indMap)
 
-    def blossom(self, uvw):
-        """
-        Compute the blossom of the spline at given parameter values.
-
-        Parameters
-        ----------
-        uvwValues : `iterable`
-            An iterable of length `nInd` that specifies the degree-sized vectors of blossom parameters for each independent variable.
-
-        Returns
-        -------
-        value : `numpy.array`
-            The value of the spline's blossom at the given blossom parameters.
-
-        See Also
-        --------
-        `evaluate` : Compute the value of the spline at a given parameter value.
-
-        Notes
-        -----
-        Evaluates the blossom based on blossoming algorithm 1 found in Goldman, Ronald N. "Blossoming and knot insertion algorithms for B-spline curves." 
-        Computer Aided Geometric Design 7, no. 1-4 (1990): 69-81.
-        """
-        return bspy._spline_evaluation.blossom(self, uvw)
-
     @staticmethod
     def bspline_values(knot, knots, splineOrder, u, derivativeOrder = 0, taylorCoefs = False):
         """
@@ -211,7 +188,8 @@ class Spline:
         Parameters
         ----------
         knot : `int`
-            The rightmost knot in the bspline segment.
+            The rightmost knot in the bspline segment.  If knot is None, then this value is
+            determined by binary search
 
         knots : array-like
             The array of knots for the bspline.
@@ -231,6 +209,10 @@ class Spline:
 
         Returns
         -------
+        knot : `int`
+            The rightmost knot in the bspline segment.  If this is specified on input, then this
+            valued is returned.  Otherwise, it is computed and then returned.
+
         value : `numpy.array`
             The value of the bspline or its derivative at the given parameter.
 
@@ -332,6 +314,35 @@ class Spline:
         """
         return bspy._spline_domain.common_basis(splines, indMap)
 
+    def complete_slice(self, slice, solid):
+        """
+        Add any missing inherent (implicit) boundaries of this spline's domain to the given slice of the 
+        given solid that are needed to make the slice valid and complete.
+
+        Parameters
+        ----------
+        slice : `solid.Solid`
+            The slice of the given solid formed by the spline. The slice may be incomplete, missing some of the 
+            spline's inherent domain boundaries. Its dimension must match `self.domain_dimension()`.
+
+        solid : `solid.Solid`
+            The solid being sliced by the manifold. Its dimension must match `self.range_dimension()`.
+
+        See Also
+        --------
+        `solid.Solid.slice` : slice the solid by a manifold.
+        `domain` : Return the domain of a spline.
+
+        Notes
+        -----
+        A spline's inherent domain is determined by its knot array for each dimension. This method only works for 
+        nInd of 1 or 2.
+        """
+        if self.domain_dimension() != slice.dimension: raise ValueError("Spline domain dimension must match slice dimension")
+        if self.range_dimension() != solid.dimension: raise ValueError("Spline range dimension must match solid dimension")
+        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 cone(radius1, radius2, height, tolerance = None):
         """
@@ -537,21 +548,16 @@ class Spline:
             indMap = [(mapping, mapping, True) if np.isscalar(mapping) else (*mapping, True) for mapping in indMap]
         return bspy._spline_operations.multiplyAndConvolve(self, other, indMap, productType)
 
-    def copy(self, metadata={}):
+    def copy(self):
         """
         Create a copy of a spline.
-
-        Parameters
-        ----------
-        metadata : `dict`, optional
-            A dictionary of ancillary data to store with the spline. Default is {}.
         
         Returns
         -------
         spline : `Spline`
             The spline copy.
         """
-        return type(self)(self.nInd, self.nDep, self.order, self.nCoef, self.knots, self.coefs, metadata)
+        return type(self)(self.nInd, self.nDep, self.order, self.nCoef, self.knots, self.coefs, self.metadata)
 
     def cross(self, vector):
         """
@@ -712,7 +718,7 @@ class Spline:
         Returns
         -------
         bounds : `numpy.array`
-            nInd x 2 array of the upper and lower bounds on each of the independent variables.
+            nInd x 2 array of the lower and upper bounds on each of the independent variables.
 
         See Also
         --------
@@ -721,6 +727,17 @@ class Spline:
         """
         return bspy._spline_evaluation.domain(self)
 
+    def domain_dimension(self):
+        """
+        Return the domain dimension of a spline (nInd).
+
+        Returns
+        -------
+        dimension : `int`
+            The dimension of the spline's domain (nInd)
+        """
+        return self.nInd
+
     def dot(self, vector):
         """
         Dot product a spline by the given vector.
@@ -858,7 +875,7 @@ class Spline:
         Parameters
         ----------
         newDomain : array-like
-            nInd x 2 array of the new upper and lower bounds on each of the independent variables (same form as 
+            nInd x 2 array of the new lower and upper bounds on each of the independent variables (same form as 
             returned from `domain`). If a bound is None or nan then the original bound (and knots) are left unchanged.
 
         continuityOrder : `int`
@@ -878,6 +895,23 @@ class Spline:
         """
         return bspy._spline_domain.extrapolate(self, newDomain, continuityOrder)
 
+    def flip_normal(self):
+        """
+        Flip the direction of the normal.
+
+        Returns
+        -------
+        spline : `Spline`
+            The spline with flipped normal. The spline retains the same tangent space.
+
+        See Also
+        --------
+        `solid.Solid.complement` : Return the complement of the solid: whatever was inside is outside and vice-versa.
+        """
+        spline = self.copy()
+        spline.metadata["flipNormal"] = not self.metadata.get("flipNormal", False)
+        return spline
+
     def fold(self, foldedInd):
         """
         Fold the coefficients of a spline's indicated independent variables into the coefficients of the remaining independent variables, retaining the 
@@ -956,13 +990,82 @@ class Spline:
         """
         return bspy._spline_fitting.four_sided_patch(bottom, right, top, left, surfParam)
 
+    @staticmethod
+    def from_dict(dictionary):
+        """
+        Create a `Spline` from a data in a `dict`.
+
+        Parameters
+        ----------
+        dictionary : `dict`
+            The `dict` containing `Spline` data.
+
+        Returns
+        -------
+        spline : `Spline`
+
+        See Also
+        --------
+        `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"])
+
+    def full_domain(self):
+        """
+        Return a solid that represents the full domain of the spline.
+
+        Returns
+        -------
+        domain : `Solid`
+            The full (untrimmed) domain of the spline.
+
+        See Also
+        --------
+        `Boundary` : A portion of the boundary of a solid.
+        """
+        return bspy._spline_intersection.full_domain(self)
+    
+    def geodesic(self, uvStart, uvEnd, tolerance = 1.0e-6):
+        """
+        Determine a geodesic between two points on a surface
+
+        Parameters
+        ----------
+        uvStart : `array-like`
+            The parameter values for the surface at one end of the desired geodesic.
+        
+        uvEnd : `array-like`
+            The parameter values for the surface at the other end of the desired geodesic.
+        
+        tolerance : scalar
+            The maximum error in parameter space to which the geodesic should get computed.
+            Defaults to 1.0e-6.
+
+        Returns
+        -------
+        geodesic : `Spline`
+            A spline curve whose range is in the domain of the given surface.  The range of the
+            curve is the locus of points whose image under the surface map form the curve of
+            minimum distance between the two given points.
+        
+        See Also
+        --------
+        `solve_ode` : Solve an ordinary differential equation using spline collocation.
+
+        Notes
+        -----
+        Solves the second order ODE which are the geodesic equations over the surface.
+        """
+        return bspy._spline_fitting.geodesic(self, uvStart, uvEnd, tolerance)
+    
     def graph(self):
         """
         Generate the spline which is the graph of the given spline.
         
         Returns
         -------
-        spline: `Spline`
+        spline : `Spline`
             A spline with nInd independent variables and nInd + nDep dependent variables, the first nInd of
             which are just the independent variables themselves. For example, given a scalar
             valued function f of two variables u and v, returns the spline of two independent variables whose
@@ -998,7 +1101,7 @@ class Spline:
         The Greville abscissae always satisfy the interlacing conditions, so can be used as
         valid collocation points, interpolation points, or quadrature points.
         """
-        return bspy._spline_operations.greville(self, ind)
+        return bspy._spline_evaluation.greville(self, ind)
         
     def insert_knots(self, newKnots):
         """
@@ -1092,39 +1195,45 @@ class Spline:
 
     def intersect(self, other):
         """
-        Intersect two splines.
+        Intersect a spline or hyperplane.
 
         Parameters
         ----------
-        other : `Spline`
-            The spline to intersect with self (`other.nDep` match match `self.nDep`).
+        other : `Spline` or `Hyperplane`
+            The `Manifold` to intersect with self (must have same range dimension as self).
 
         Returns
         -------
-        intersection : `iterable` or `NotImplemented`
-            If `self.nInd + other.nInd - self.nDep` is 0, returns an iterable of intersection points in the 
-            parameter space of the two splines (a vector of size `self.nInd + other.nInd`).
-            If `self.nInd + other.nInd - self.nDep` is 1, returns an iterable of `Spline` curves, each of whose domain is [0, 1] 
-            and each of whose range is in the parameter space of the two splines (a vector of size `self.nInd + other.nInd`).
-            If `self.nInd + other.nInd - self.nDep` is < 0 or > 1, `NotImplemented` is returned.
+        intersections : `iterable` (or `NotImplemented` if other is an unknown type of Manifold)
+            A list of intersections between the two manifolds. 
+            Each intersection records either a crossing or a coincident region.
+
+            For a crossing, intersection is a `Manifold.Crossing`: (left, right)
+            * left : `Manifold` in the manifold's domain where the manifold and the other cross.
+            * right : `Manifold` in the other's domain where the manifold and the other cross.
+            * Both intersection manifolds have the same domain and range (the crossing between the manifold and the other).
+
+            For a coincident region, intersection is a `Manifold.Coincidence`: (left, right, alignment, transform, inverse, translation)
+            * left : `Solid` in the manifold's domain within which the manifold and the other are coincident.
+            * right : `Solid` in the other's domain within which the manifold and the other are coincident.
+            * alignment : scalar value holding the normal alignment between the manifold and the other (the dot product of their unit normals).
+            * transform : `numpy.array` holding the transform matrix from the manifold's domain to the other's domain.
+            * inverse : `numpy.array` holding the inverse transform matrix from the other's domain to the boundary's domain.
+            * translation : `numpy.array` holding the translation vector from the manifold's domain to the other's domain.
+            * Together transform, inverse, and translation form the mapping from the manifold's domain to the other's domain and vice-versa.
         
         See Also
         --------
         `zeros` : Find the roots of a spline (nInd must match nDep).
         `contours` : Find all the contour curves of a spline.
+        `solid.Solid.slice` : slice the solid by a manifold.
 
         Notes
         -----
         Uses `zeros` to find all intersection points and `contours` to find all the intersection curves.
         """
-        if not(self.nDep == other.nDep): raise ValueError("The number of dependent variables for both splines much match.")
-        freeParameters = self.nInd + other.nInd - self.nDep
-        if freeParameters == 0:
-            return self.subtract(other).zeros()
-        elif freeParameters == 1:
-            return self.subtract(other).contours()
-        else:
-            return NotImplemented
+        if not(self.range_dimension() == other.range_dimension()): raise ValueError("The number of dependent variables for both splines much match.")
+        return bspy._spline_intersection.intersect(self, other)
 
     def jacobian(self, uvw):
         """
@@ -1324,9 +1433,8 @@ class Spline:
         if isinstance(splineData, dict):
             splineData = [splineData]
         for splineDict in splineData:
-            splines.append(Spline(splineDict["nInd"], splineDict["nDep"], splineDict["order"], splineDict["nCoef"],
-                [np.array(knots) for knots in splineDict["knots"]], np.array(splineDict["coefs"]), splineDict["metadata"]))
-        return splines        
+            splines.append(Spline.from_dict(splineDict))
+        return splines
 
     def multiply(self, other, indMap = None, productType = 'S'):
         """
@@ -1468,18 +1576,39 @@ class Spline:
     def range_bounds(self):
         """
         Return the range of a spline as lower and upper bounds on each of the
-        dependent variables
+        dependent variables.
         """
         return bspy._spline_evaluation.range_bounds(self)
 
-    def remove_knot(self, iKnot):
+    def range_dimension(self):
+        """
+        Return the range dimension of a spline (nDep).
+
+        Returns
+        -------
+        dimension : `int`
+            The dimension of the spline's range (nDep)
+        """
+        return self.nDep
+
+    def remove_knot(self, iKnot, nLeft = 0, nRight = 0):
         """
         Remove a single knot from a univariate spline.
         
         Parameters
         ----------
         iKnot : integer
-            index of the knot to remove from the spline
+            Index of the knot to remove from the spline
+        
+        nLeft : integer
+            Number of continuity conditions to enforce on the left end.  For example, if nLeft = 2,
+            then remove_knot will leave the function value and first derivative unchanged on the
+            left end of the domain.
+        
+        nRight : integer
+            Number of continuity conditions to enforce on the right end.  For example, if
+            nRight = 3, then remove_knot will leave the function value and first and second
+            derivative values unchanged on the right end of the domain.
         
         Returns
         -------
@@ -1496,9 +1625,9 @@ class Spline:
         -----
         Solves a simple least squares problem
         """
-        return bspy._spline_domain.remove_knot(self, iKnot)
+        return bspy._spline_domain.remove_knot(self, iKnot, nLeft, nRight)
     
-    def remove_knots(self, tolerance = 1.0e-14):
+    def remove_knots(self, tolerance = 1.0e-14, nLeft = 0, nRight = 0):
         """
         Remove interior knots from a spline.
 
@@ -1509,6 +1638,17 @@ class Spline:
             removed until removal of the next knot would put the pointwise error above the threshold.
             The default is 1.0e-14 which is relative to the size of each of the dependent variables.
 
+        nLeft : integer
+            Number of continuity conditions to enforce on the left end.  For example, if nLeft = 2,
+            then remove_knot will leave the function value and first derivative unchanged on the
+            left end of the domain.
+        
+        nRight : integer
+            Number of continuity conditions to enforce on the right end.  For example, if
+            nRight = 3, then remove_knot will leave the function value and first and second
+            derivative values unchanged on the right end of the domain.
+        
+
         Returns
         -------
         spline : `Spline`
@@ -1524,7 +1664,7 @@ class Spline:
         -----
         Calls `remove_knot` repeatedly until no longer possible.
         """
-        return bspy._spline_domain.remove_knots(self, tolerance)
+        return bspy._spline_domain.remove_knots(self, tolerance, nLeft, nRight)
     
     def reparametrize(self, newDomain):
         """
@@ -1533,7 +1673,7 @@ class Spline:
         Parameters
         ----------
         newDomain : array-like
-            nInd x 2 array of the new upper and lower bounds on each of the independent variables (same form as 
+            nInd x 2 array of the new lower and upper bounds on each of the independent variables (same form as 
             returned from `domain`). If a bound pair is `None` then the original bound (and knots) are left unchanged. 
             For example, `[[0.0, 1.0], None]` will reparametrize the first independent variable and leave the second unchanged)
 
@@ -1570,7 +1710,7 @@ class Spline:
 
     def revolve(self, angle):
         """
-        Rotate the spline to create a surface of revolution (nDep must equal 2, 
+        Revolve the spline to create a surface of revolution (nDep must equal 2, 
         first dimension provides the radius for x and y, second dimension provides the z).
 
         Parameters
@@ -1658,15 +1798,7 @@ class Spline:
                 if isinstance(obj, np.ndarray):
                     return obj.tolist()
                 if isinstance(obj, Spline):
-                    return {
-                        "nInd" : obj.nInd,
-                        "nDep" : obj.nDep,
-                        "order" : obj.order,
-                        "nCoef" : obj.nCoef,
-                        "knots" : obj.knots,
-                        "coefs" : obj.coefs,
-                        "metadata" : obj.metadata
-                    }
+                    return obj.to_dict()
                 return super().default(obj)
 
         with open(fileName, 'w', encoding='utf-8') as file:
@@ -1733,6 +1865,50 @@ class Spline:
         """
         return bspy._spline_fitting.section(xytk)
     
+    def solve_ode(self, nLeft, nRight, FAndF_u, tolerance = 1.0e-6, args = ()):
+        """
+        Numerically solve an ordinary differential equation with boundary conditions.
+
+        Parameters
+        ==========
+        self : `Spline`
+            The initial guess for the solution to the spline.  All of the spline parameters, e.g.
+            order, boundary conditions, domain, etc. are all established by the initial guess.  The
+            ODE itself must be of the form u^(nOrder)(t) = F(t, u, u', ... , u^(nOrder-1)).  self.nDep should
+            be the same as the number of state variables in the ODE.
+        
+        nLeft : integer
+            The number of boundary conditions to be imposed on the left side of the domain.  The
+            order of the differential equation is assumed to be the sum of nLeft and nRight.
+        
+        nRight : integer
+            The number of boundary conditions to be imposed on the right sie of the domain.  The
+            order of the differential equation is assumed to be the sum of nLeft and nRight.
+        
+        FAndF_u : Python function
+            FAndF_u must have exactly this calling sequence:  FAndF_u(t, uData, *args).  t is a scalar set
+            to the desired value of the independent variable of the ODE.  uData will be a numpy matrix of shape
+            (self.nDep, nOrder) whose columns are (u, ... , u^(nOrder - 1).  It must return a numpy
+            vector of length self.nDep and a numpy array whose shape is (self.nDep, self.nDep, nOrder).
+            The first output vector is the value of the forcing function F at (t, uData).  The numpy
+            array is the array of partial derivatives with respect to all the numbers in uData.  Thus, if
+            this array is called jacobian, then jacobian[:, i, j] is the gradient of the forcing function with
+            respect to uData[i, j].
+        
+        tolerance : scalar
+            The relative error to which the ODE should get solved.
+        
+        args : tuple
+            Additional arguments to pass to the user-defined function FAndF_u.  For example, if FAndF_u has the
+            FAndF_u(t, uData, a, b, c), then args must be a tuple of length 3.
+
+        Notes
+        =====
+        This method uses B-splines as finite elements.  The ODE itself is discretized using
+        collocation.
+        """
+        return bspy._spline_fitting.solve_ode(self, nLeft, nRight, FAndF_u, tolerance, args)
+
     @staticmethod
     def sphere(radius, tolerance = None):
         """
@@ -1807,6 +1983,37 @@ class Spline:
             indMap = [(mapping, mapping) if np.isscalar(mapping) else mapping for mapping in indMap]
         return self.add(other.scale(-1.0), indMap)
 
+    def tangent_space(self, uvw):
+        """
+        Return the tangent space of the spline.
+
+        Parameters
+        ----------
+        uvw : array-like
+            The value at which to evaluate the tangent space.
+
+        Returns
+        -------
+        tangentSpace : `numpy.array`
+            The nDep x nInd matrix of tangent vectors (tangents are the columns).
+        """
+        return bspy._spline_evaluation.tangent_space(self, uvw)
+
+    def to_dict(self):
+        """
+        Return a `dict` with `Spline` data.
+
+        Returns
+        -------
+        dictionary : `dict`
+
+        See Also
+        --------
+        `from_dict` : Create a `Spline` from a data in a `dict`.
+        """
+        return {"type" : "Spline", "nInd" : self.nInd, "nDep" : self.nDep, "order" : self.order, "nCoef" : self.nCoef,
+            "knots" : self.knots, "coefs" : self.coefs, "metadata" : self.metadata}
+
     @staticmethod
     def torus(innerRadius, outerRadius, tolerance = None):
         """
@@ -1845,7 +2052,7 @@ class Spline:
         """
         return bspy._spline_fitting.torus(innerRadius, outerRadius, tolerance)
     
-    def transform(self, matrix):
+    def transform(self, matrix, matrixInverseTranspose = None):
         """
         Transform a spline by the given matrix.
 
@@ -1854,6 +2061,9 @@ class Spline:
         matrix : array-like
             An array of size `newNDep`x`nDep` that specifies the transform matrix.
 
+        matrixInverseTranspose : `numpy.array`, optional
+            The inverse transpose of matrix (not used for splines).
+
         Returns
         -------
         spline : `Spline`
@@ -1928,7 +2138,7 @@ class Spline:
         Parameters
         ----------
         newDomain : array-like
-            nInd x 2 array of the new upper and lower bounds on each of the independent variables (same form as 
+            nInd x 2 array of the new lower and upper bounds on each of the independent variables (same form as 
             returned from `domain`). If a bound is None or nan then the original bound (and knots) are left unchanged.
 
         Returns
@@ -1943,6 +2153,29 @@ class Spline:
         """
         return bspy._spline_domain.trim(self, newDomain)
 
+    def trimmed_range_bounds(self, domainBounds):
+        """
+        Return the trimmed range bounds for the spline.
+
+        Parameters
+        ----------
+        domainBounds : array-like
+            An array with shape (nInd, 2) of lower and upper and lower bounds on each independent variable.
+
+        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.
+
+        See Also
+        --------
+        `trim` : Trim the domain of a spline.
+        `range_bounds` : Return the range of a spline as lower and upper bounds on each of the
+            dependent variables.
+        """
+        return bspy._spline_domain.trimmed_range_bounds(self, domainBounds)
+
     def unfold(self, foldedInd, coefficientlessSpline):
         """
         Unfold the coefficients of an original spline's indicated independent variables back into the spline, using the