Clarify type stability issues

[TheBB]

I have been working on automatic type checking in Splipy. This is quite challenging, because Splipy has been written to be extremely lenient in terms of types, and many functions return one of several different types based on input parameters. For example, SplineObject.split is a particularly egregious offender: it returns either a list of objects or (if the original object is periodic) only a single object. Since there's no way to encode whether an object is periodic or not in the type system, it's impossible for a type checker to know whether .split returns a list of objects or a single object in any particular case (even though the programmer does!).

I propose to phase out those functions and replace them with more stable alternatives. We can potentially leave behind the incriminating function to prevent destroying existing code, but I don't want to use them in Splipy if at all possible.

In this issue I will list out each relevant case as I find them.

• BSplineBasis.evaluate returns either a sparse array or a dense array. The sparse code path is more general.
  • Resolved with overload.
• BSPlineBasis.continuity returns either an int or a float. It is convenient to pretend it's always an int. What to do?
  • Resolved by adding knot_continuity and min_continuity which are both type-stable.
• SplineObject.section sometimes returns an array, sometimes a spline object.
  • Resolved by using the unwrap_points=False keyword parameter.
• SplineObject.split sometimes returns a list, sometimes only one object.
• SplineObject.tangent, when called without a direction, returns a tuple of arrays (one for each direction) - except for Curves.
• Curve.curvature returns a float when there's only a single input parameter - most other such functions return a float only when there's a single input parameter that is not in a list.
• Curve.torsion: same problem.

[VikingScientist]

This will break downstream applications and as such come with a major version bump.

BSplineBasis.evaluate

The dense version was mostly for verification during early stages. I see little to no benefit in keeping it around. Converting from sparse to dense can always be done outside if it useful to have the dense representation

BSPlineBasis.continuity returns either an int or a float. It is convenient to pretend it's always an int. What to do?

The only float that should ever be returned here is np.inf. Don't know if anyone actually have the need for this, but it is mathematically the most correct solution. Returning -1 or 0 is not acceptable as these are well-defined continuity at knots that are being used. It also seems Numpy only has a float infinity and not an integer infinity. If it is important to typecheck this, then I guess we have to throw errors instead when input is of an non-knot value.

SplineObject.section sometimes returns an array, sometimes a spline object.

This could always be an array.

SplineObject.split sometimes returns a list, sometimes only one object.

This could always be an array

SplineObject.tangent, when called without a direction, returns a tuple of arrays (one for each direction) - except for Curves.

This one has to have a special implementation for Curves. I don't want to always be picking out element number 0 when I know that it only contains a single element.

Curve.curvature returns a float when there's only a single input parameter - most other such functions return a float only when there's a single input parameter that is not in a list.

I want this to behave in the same manner as `np.cos´ does. With a float input you get a float output. With array input you get array output. Don't know how to make this work with typechecking, but if numpy can make it work, then we can make it work

Curve.torsion: same problem

Same solution

[TheBB]

SplineObject.section sometimes returns an array, sometimes a spline object.

This could always be an array.

No... it could always be a SplineObject, but it can't always be an array. The question is whether we return a degenerate array for a zero-dimensional object or not.

Currently there's a flag that, if enabled, wraps points as zero-dimensional spline objects. If not enabled, it's not possible type-wise to predict whether you're getting a spline object or an array back.

To be honest, everywhere in our code where we use that function we either use the flag or should use the flag, so it was a mistake to implement that function with the default the other way. But so long as we use it, this is not a problem.

SplineObject.split sometimes returns a list, sometimes only one object.

This could always be an array

Agree.

SplineObject.tangent, when called without a direction, returns a tuple of arrays (one for each direction) - except for Curves.

This one has to have a special implementation for Curves. I don't want to always be picking out element number 0 when I know that it only contains a single element.

Respectfully disagree. This makes it very inconvenient to use SplineObject.tangent in code that is generic over pardim.

Prior art.

Curve.curvature returns a float when there's only a single input parameter - most other such functions return a float only when there's a single input parameter that is not in a list.

I want this to behave in the same manner as `np.cos´ does. With a float input you get a float output. With array input you get array output. Don't know how to make this work with typechecking, but if numpy can make it work, then we can make it work

Agree. You're describing the behavior it does currently not have and which most other functions in Splipy do have (and which we have successfully typed already).