status module¶

Status
¶ This enum contains all status codes that can be returned from procedures that can fail for some inputs.

SUCCESS
¶ (
0
) Procedure exited with no error.

BAD_MULTIPLICITY
¶ (
1
) An iterative method (e.g. Newton’s method) failed to converge because it encountered a solution with an unsupported multiplicity (i.e. it was a triple root or higher). The multiplicity is detected by the observed rate of convergence.

NO_CONVERGE
¶ (
2
) An iterative method failed to converge in the maximum allowed number of iterations.

INSUFFICIENT_SPACE
¶ (
3
) All allocation must be done by the caller, hence any variablesize output must be already allocated. This will be used when the caller has not allocated enough space for the output values.

SAME_CURVATURE
¶ (
4
) Classification of a curvecurve intersection failed due to two curves having identical curvature at a tangent intersection.

BAD_INTERIOR
¶ (
5
) Caused by a failure during the process of triangletriangle intersection. Occurs when the corners and edgeedge intersections can’t be converted into the curved polygon(s) that make up the intersection of the two triangles.

EDGE_END
¶ (
6
) A triangletriangle intersection point occurs at the end of an edge (only intersections at the beginning of an edge should be used).

SINGULAR
¶ (
7
) Signifies that an attempt was made to solve a linear system that was singular.

UNKNOWN
¶ (
999
) Signifies a block of code reached an “impossible” state. Either the code has violated some mathematical invariant or the author of that block of code has misunderstood the possible states of the system.
Example:
Consider curves which intersect at the point \(B_1\left(\frac{3}{2}\right) = B_2(2)\):
\[\begin{split}\begin{align*} B_1(s) &= \left[\begin{array}{c} 0 \\ 0 \end{array}\right] (1  s)^2 + \left[\begin{array}{c} 2 \\ 4 \end{array}\right] 2s(1  s) + \left[\begin{array}{c} 4 \\ 0 \end{array}\right] s^2 = \left[\begin{array}{c} 4s \\ 8s(1  s) \end{array}\right] \\ B_2(t) &= \left[\begin{array}{c} 2 \\ 0 \end{array}\right] (1  t) + \left[\begin{array}{c} 0 \\ 3 \end{array}\right] t = \left[\begin{array}{c} 2(1  t) \\ 3t \end{array}\right] \end{align*}\end{split}\]When trying to use Newton’s method to find the root of
\[F(s, t) = B_1(s)  B_2(t)\]nearest to \(s = \frac{7}{8}, t = 2\):
// Inputs. int num_nodes1 = 3; double nodes1[6] = { 0.0, 0.0, 6.0, 4.0, 12.0, 0.0 }; double s = 7.0 / 8.0; int num_nodes2 = 2; double nodes2[4] = { 6.0, 0.0, 0.0, 3.0 }; double t = 2.0; // Outputs. double new_s, new_t; Status status; BEZ_newton_refine_curve_intersect(&s, &num_nodes1, nodes1, &t, &num_nodes2, nodes2, &new_s, &new_t, &status); if (status == SINGULAR) { printf("Jacobian is singular.\n"); }
the method fails with the status
SINGULAR
because the Jacobian\[\begin{split}DF\left(\frac{7}{8}, 2\right) = \left[\begin{array}{c c} 4 & 2 \\ 6 & 3 \end{array}\right]\end{split}\]is singular to numerical precision:
>>> bezier_include '.../sitepackages/bezier/include' >>> bezier_lib '.../sitepackages/bezier/lib' >>> invoke_shell(f""" ... gcc \ ... o example \ ... example_status.c \ ... I {bezier_include} \ ... L {bezier_lib} \ ... L {gfortran_lib} \ ... lbezier \ ... lm lgfortran ... """) >>> invoke_shell("./example") Jacobian is singular.
