@itwin/core-geometry 4.3.0-dev.11 → 4.3.0-dev.12

package/lib/esm/numerics/Newton.d.ts

@@ -1,186 +1,241 @@
 import { Plane3dByOriginAndVectors } from "../geometry3d/Plane3dByOriginAndVectors";
-/** base class for Newton iterations in various dimensions.
- * Dimension-specific classes carry all dimension-related data and answer generalized queries
- * from this base class.
+/**
+ * Base class for Newton iterations in various dimensions.
+ * Dimension-specific classes carry all dimension-related data and answer generalized queries from this base class.
  * @internal
  */
 export declare abstract class AbstractNewtonIterator {
-    /** Compute a step.  The current x and function values must be retained for use in later method calls */
+    /** Compute a step. The current x and function values must be retained for use in later method calls. */
     abstract computeStep(): boolean;
-    /** return the current step size, scaled for use in tolerance tests.
-     * * This is a single number, typically the max of various per-dimension `dx / (1+x)` for the x and dx of that dimension.
+    /**
+     * Return the current step size, scaled for use in tolerance tests.
+     * * This is a single number, typically the max of various per-dimension `dx/(1+x)` for the x and dx of that dimension.
      */
     abstract currentStepSize(): number;
     /**
-     * Apply the current step (in all dimensions)
+     * Apply the current step (in all dimensions).
      * @param isFinalStep true if this is a final step.
      */
     abstract applyCurrentStep(isFinalStep: boolean): boolean;
     /**
+     * The constructor.
      * @param stepSizeTarget tolerance to consider a single step converged.
-     * This number should be "moderately" strict.   Because 2 successive convergences are required,
+     * This number should be "moderately" strict. Because 2 successive convergences are required,
      * it is expected that a first "accept" for (say) 10 to 14 digit step will be followed by another
-     * iteration.   A well behaved newton would then hypothetically double the number of digits to
-     * 20 to 28.  Since the IEEE double only carries 16 digits, this second-convergence step will
+     * iteration. A well behaved newton would then hypothetically double the number of digits to
+     * 20 to 28. Since the IEEE double only carries 16 digits, this second-convergence step will
      * typically achieve full precision.
      * @param successiveConvergenceTarget number of successive convergences required for acceptance.
-     * @param maxIterations max number of iterations.   A typical newton step converges in 3 to 6 iterations.
-     *     Allow 15 to 20 to catch difficult cases.
+     * @param maxIterations max number of iterations. A typical newton step converges in 3 to 6 iterations.
+     * Allow 15 to 20 to catch difficult cases.
      */
     protected constructor(stepSizeTolerance?: number, successiveConvergenceTarget?: number, maxIterations?: number);
-    /** Number of consecutive steps which passed convergence condition */
+    /** Number of consecutive steps which passed convergence condition. */
     protected _numAccepted: number;
-    /** Target number of successive convergences */
+    /** Target number of successive convergences. */
     protected _successiveConvergenceTarget: number;
-    /** convergence target (the implementation-specific currentStepSize is compared to this) */
+    /** Convergence target (the implementation-specific currentStepSize is compared to this). */
     protected _stepSizeTolerance: number;
-    /** Max iterations allowed */
+    /** Max iterations allowed. */
     protected _maxIterations: number;
-    /** number of iterations (incremented at each step) */
+    /** Number of iterations (incremented at each step). */
     numIterations: number;
     /**
      * Test if a step is converged.
-     * * Convergence is accepted with enough (_successiveConvergenceTarget) small steps (according to _stepSizeTolerance) occur in succession.
-     * @param delta step size as reported by currentStepSize
+     * * Convergence is accepted with enough (_successiveConvergenceTarget) small steps (according to _stepSizeTolerance)
+     * occur in succession.
+     * @param delta step size as reported by currentStepSize.
      */
     testConvergence(delta: number): boolean;
     /**
      * Run iterations, calling various methods from base and derived classes:
      * * computeStep -- typically evaluate derivatives and solve linear system.
-     * * currentStepSize -- return numeric measure of the step just computed by computeStep
+     * * currentStepSize -- return numeric measure of the step just computed by computeStep.
      * * testConvergence -- test if the step from currentStepSize (along with recent steps) is converged.
-     * * applyCurrentStep -- apply the step to the independent variables
+     * * applyCurrentStep -- apply the step to the independent variables.
      */
     runIterations(): boolean;
 }
-/** object to evaluate a newton function.  The object must retain most-recent function and derivative
+/**
+ * Object to evaluate a newton function. The object must retain most-recent function and derivative
  * values for immediate query.
  * @internal
  */
 export declare abstract class NewtonEvaluatorRtoRD {
-    /** evaluate the function and its derivative at x. */
+    /** Evaluate the function and its derivative at x. */
     abstract evaluate(x: number): boolean;
-    /** most recent function value */
+    /** Most recent function value, i.e., f(x_n). */
     currentF: number;
-    /** most recent evaluated derivative */
+    /** Most recent evaluated derivative, i.e., f'(x_n). */
     currentdFdX: number;
 }
 /**
  * Newton iterator for use when both function and derivative can be evaluated.
+ * To solve `f(x) = 0`, the Newton iteration is `x_{n+1} = x_n - dx = x_n - f(x_n)/f'(x_n)`.
+ * To solve `f(x) = target` which is equivalent to solving  `g(x) = f(x) - target = 0`, the Newton iteration is
+ * `x_{n+1} = x_n - dx = x_n - g(x_n)/g'(x_n) = x_n - (f(x_n)-target)/f'(x_n)`.
  * @internal
  */
 export declare class Newton1dUnbounded extends AbstractNewtonIterator {
     private _func;
+    /** Current step is dx. */
     private _currentStep;
+    /** Current X is x_n. */
     private _currentX;
+    /** The target */
     private _target;
     /**
-     * Constructor for 1D newton iteration with approximate derivatives.
-     * @param func function that returns both function and derivative.
+     * Constructor for 1D newton iteration with derivatives.
+     * @param func function that returns both function value and derivative.
      */
     constructor(func: NewtonEvaluatorRtoRD);
-    /** Set the independent variable */
+    /** Set the independent variable, i.e., x_n. */
     setX(x: number): boolean;
-    /** Get the independent variable */
+    /** Get the independent variable, i.e., x_n. */
     getX(): number;
-    /** Set the target function value */
+    /** Set the target function value. */
     setTarget(y: number): void;
-    /** move the current X by the just-computed step */
+    /** Move the current X by the just-computed step, i.e., `x_n - dx`. */
     applyCurrentStep(): boolean;
     /** Compute the univariate newton step. */
     computeStep(): boolean;
-    /** Return the current step size as a relative number. */
+    /** Return the current step size as a relative number, i.e., `|dx / (1 + |x_n|)|`. */
     currentStepSize(): number;
 }
-/** object to evaluate a newton function (without derivative).  The object must retain most-recent function value.
+/**
+ * Object to evaluate a newton function (without derivative). The object must retain most-recent function value.
  * @internal
  */
 export declare abstract class NewtonEvaluatorRtoR {
     /** Evaluate function value into member currentF */
     abstract evaluate(x: number): boolean;
-    /** Most recent function evaluation. */
+    /** Most recent function evaluation, i.e., f(x_n). */
     currentF: number;
 }
-/** Newton iteration for a univariate function, using approximate derivatives.
+/**
+ * Newton iteration for a univariate function, using approximate derivatives.
+ * To approximate the derivatives we use a small step `h`, i.e., `f'(x_n) = (f(x_n + h) - f(x_n)) / h`.
+ * Therefore, to solve `f(x) = 0`, the iteration is
+ * `x_{n+1} = x_n - dx = x_n - f(x_n)/f'(x_n) = x_n - f(x_n) * h / (f(x_n + h) - f(x_n))`.
  * @internal
  */
 export declare class Newton1dUnboundedApproximateDerivative extends AbstractNewtonIterator {
     private _func;
+    /** Current step is dx. */
     private _currentStep;
+    /** Current X is x_n. */
     private _currentX;
-    /** Step size for iteration.
+    /**
+     * Step size for approximate derivative for the iteration.
      * * Initialized to 1e-8, which is appropriate for iteration in fraction space.
      * * Should be larger for iteration with real distance as x.
      */
     derivativeH: number;
     /**
      * Constructor for 1D newton iteration with approximate derivatives.
-     * @param func function that returns both function and derivative.
+     * @param func function that only returns function value (and not derivative).
      */
     constructor(func: NewtonEvaluatorRtoR);
-    /** Set the x (independent, iterated) value */
+    /** Set the independent variable, i.e., x_n. */
     setX(x: number): boolean;
-    /** Get the independent variable */
+    /** Get the independent variable, i.e., x_n. */
     getX(): number;
-    /** move the current X by the just-computed step */
+    /** Move the current X by the just-computed step, i.e., `x_n - dx`. */
     applyCurrentStep(): boolean;
-    /** Univariate newton step computed with APPROXIMATE derivative. */
+    /** Univariate newton step computed with approximate derivative. */
     computeStep(): boolean;
-    /** Return the current step size as a relative number. */
+    /** Return the current step size as a relative number, i.e., `|dx / (1 + |x_n|)|`. */
     currentStepSize(): number;
 }
-/** object to evaluate a 2-parameter newton function (with derivatives!!).
+/**
+ * Object to evaluate a 2-parameter newton function with derivatives.
  * @internal
  */
 export declare abstract class NewtonEvaluatorRRtoRRD {
-    /** Iteration controller calls this to ask for evaluation of the function and its two partial derivatives.
+    /**
+     * Iteration controller calls this to ask for evaluation of the function and its two partial derivatives.
      * * The implementation returns true, it must set the currentF object.
      */
     abstract evaluate(x: number, y: number): boolean;
-    /** most recent function evaluation as xy parts of the plane */
+    /**
+     * Most recent function evaluation as parts of the plane.
+     * * See doc of [[Newton2dUnboundedWithDerivative]] class for info on 2d newton method.
+     * * For current value (u,v) of the independent variable, and `F(u,v) := (x(u,v), y(u,v)), the returned plane has:
+     * * `origin.x` = x(u,v)
+     * * `origin.y` = y(u,v)
+     * * `vectorU.x` = dx/du
+     * * `vectorU.y` = dy/du
+     * * `vectorV.x` = dx/dv
+     * * `vectorV.y` = dy/dv
+     * * In other words, the plane stores the columns of the Jacobian matrix J of F: `vectorU` stores the partials
+     * of F with respect to u (the first column of J), and `vectorV` stores the partials of F with respect to v
+     * (the second column of J):
+     *
+     * `[vectorU.x   vectorV.x]`
+     *
+     * `[vectorU.y   vectorV.y]`
+     */
     currentF: Plane3dByOriginAndVectors;
     /**
-     * constructor.
+     * Constructor.
      * * This creates a currentF object to (repeatedly) receive function and derivatives.
      */
     constructor();
 }
 /**
  * Implement evaluation steps for newton iteration in 2 dimensions, using caller supplied NewtonEvaluatorRRtoRRD object.
+ * * Suppose we want to find the roots of `F(u,v) := (x(u,v), y(u,v))`. Writing `X := (u,v)` and `F(X)` as column vectors,
+ *  the 2D Newton's iteration to find a root of `F` is given by:
+ * `X_{n+1} = X_n - dX = X_n - JInv(X_n)F(X_n)`, where `JInv` is the inverse of the Jacobian matrix `J`, and `J` is
+ * defined as:
+ *
+ * `[dx/du   dx/dv]`
+ *
+ * `[dy/du   dy/dv]`
  * @internal
  */
 export declare class Newton2dUnboundedWithDerivative extends AbstractNewtonIterator {
     private _func;
+    /** Current step, or dX = (du, dv). */
     private _currentStep;
+    /** Current uv parameters, or X_n = (u_n, v_n). */
     private _currentUV;
+    /**
+     * Constructor for 2D newton iteration with derivatives.
+     * @param func function that returns both function value and derivative.
+     */
     constructor(func: NewtonEvaluatorRRtoRRD);
-    /** Set the current uv coordinates for current iteration */
-    setUV(x: number, y: number): boolean;
-    /** Get the current u coordinate */
+    /** Set the current uv parameters, i.e., `X_n = (u_n, v_n)`. */
+    setUV(u: number, v: number): boolean;
+    /** Get the current u parameter of X_n, i.e., u_n. */
     getU(): number;
-    /** Get the current v coordinate */
+    /** Get the current v parameter of X_n, i.e., v_n. */
     getV(): number;
-    /** Move the currentUV coordinate by currentStep. */
+    /** Update the current uv parameter by currentStep, i.e., compute `X_{n+1} := X_n - dX = (u_n - du, v_n - dv)`. */
     applyCurrentStep(): boolean;
-    /** Evaluate the functions and derivatives at this._currentUV
-     * Invert the jacobian and compute the this._currentStep.
+    /**
+     * Evaluate the functions and derivatives at `X_n = (u_n, v_n)`, and solve the Jacobian matrix equation to
+     * compute `dX = (du, dv)`.
      */
     computeStep(): boolean;
     /**
-     * Return the largest relative step of the x,y, components of the current step.
+     * Return the current relative step size, i.e., the larger absolute component of `dX / (1 + |X_n|)`
      */
     currentStepSize(): number;
 }
 /**
- * SimpleNewton has static methods for newton methods with evaluated functions presented as immediate arguments (not function object)
+ * SimpleNewton has static methods for newton methods with evaluated functions presented as immediate arguments
+ * (not function object).
  * @internal
  */
 export declare class SimpleNewton {
-    /** Run a one-dimensional newton iteration with separate functions for function and derivative.
-     * * completion is at 2 (TWO) successive passes at (absoluteTolerance + relTol * abs (x)), where relTol is chosen internally.
-     * * absoluteTolerance is usually aggressively tight -- should come into play only for x near zero.
-     * * The relTol is fluffy (for instance around 1e-11) but in properly converging cases the extra pass after first success
-     *    normally moves to full machine precision.
+    /**
+     * Run a one-dimensional newton iteration with separate functions for function and derivative.
+     * * Completion is at 2 (TWO) successive passes at `absoluteTolerance + relTol * abs(x)`, where relTol is
+     * chosen internally.
+     * * `absoluteTolerance` is usually aggressively tight -- should come into play only for x near zero.
+     * * The `relTol` is fluffy (for instance around 1e-11) but in properly converging cases the extra pass after
+     * first success normally moves to full machine precision.
      * * This is an open-loop newton -- it just runs, and returns undefined if anything bad happens.
      */
     static runNewton1D(x: number, func: (x: number) => number | undefined, derivative: (x: number) => number | undefined, absoluteTolerance?: number): number | undefined;

package/lib/esm/numerics/Newton.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Newton.d.ts","sourceRoot":"","sources":["../../../src/numerics/Newton.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Newton.d.ts","sourceRoot":"","sources":["../../../src/numerics/Newton.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AAMpF;;;;GAIG;AACH,8BAAsB,sBAAsB;IAC1C,wGAAwG;aACxF,WAAW,IAAI,OAAO;IACtC;;;OAGG;aACa,eAAe,IAAI,MAAM;IACzC;;;OAGG;aACa,gBAAgB,CAAC,WAAW,EAAE,OAAO,GAAG,OAAO;IAC/D;;;;;;;;;;;OAWG;IACH,SAAS,aACP,iBAAiB,GAAE,MAAgB,EACnC,2BAA2B,GAAE,MAAU,EACvC,aAAa,GAAE,MAAW;IAM5B,sEAAsE;IACtE,SAAS,CAAC,YAAY,EAAE,MAAM,CAAK;IACnC,gDAAgD;IAChD,SAAS,CAAC,4BAA4B,EAAE,MAAM,CAAC;IAC/C,4FAA4F;IAC5F,SAAS,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACrC,8BAA8B;IAC9B,SAAS,CAAC,cAAc,EAAE,MAAM,CAAC;IACjC,uDAAuD;IAChD,aAAa,EAAE,MAAM,CAAK;IACjC;;;;;OAKG;IACI,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAQ9C;;;;;;OAMG;IACI,aAAa,IAAI,OAAO;CAWhC;AACD;;;;GAIG;AACH,8BAAsB,oBAAoB;IACxC,qDAAqD;aACrC,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAC5C,gDAAgD;IACzC,QAAQ,EAAG,MAAM,CAAC;IACzB,uDAAuD;IAChD,WAAW,EAAG,MAAM,CAAC;CAC7B;AACD;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,sBAAsB;IAC3D,OAAO,CAAC,KAAK,CAAuB;IACpC,0BAA0B;IAC1B,OAAO,CAAC,YAAY,CAAU;IAC9B,wBAAwB;IACxB,OAAO,CAAC,SAAS,CAAU;IAC3B,iBAAiB;IACjB,OAAO,CAAC,OAAO,CAAU;IACzB;;;OAGG;gBACgB,IAAI,EAAE,oBAAoB;IAK7C,+CAA+C;IACxC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAI/B,+CAA+C;IACxC,IAAI,IAAI,MAAM;IAGrB,qCAAqC;IAC9B,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI;IAGjC,sEAAsE;IAC/D,gBAAgB,IAAI,OAAO;IAIlC,0CAA0C;IACnC,WAAW,IAAI,OAAO;IAU7B,qFAAqF;IAC9E,eAAe,IAAI,MAAM;CAGjC;AAED;;;GAGG;AACH,8BAAsB,mBAAmB;IACvC,mDAAmD;aACnC,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAC5C,qDAAqD;IAC9C,QAAQ,EAAG,MAAM,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,qBAAa,sCAAuC,SAAQ,sBAAsB;IAChF,OAAO,CAAC,KAAK,CAAsB;IACnC,0BAA0B;IAC1B,OAAO,CAAC,YAAY,CAAU;IAC9B,wBAAwB;IACxB,OAAO,CAAC,SAAS,CAAU;IAC3B;;;;OAIG;IACI,WAAW,EAAE,MAAM,CAAC;IAE3B;;;OAGG;gBACgB,IAAI,EAAE,mBAAmB;IAK5C,+CAA+C;IACxC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;IAI/B,+CAA+C;IACxC,IAAI,IAAI,MAAM;IAGrB,sEAAsE;IAC/D,gBAAgB,IAAI,OAAO;IAIlC,mEAAmE;IAC5D,WAAW,IAAI,OAAO;IAc7B,qFAAqF;IAC9E,eAAe,IAAI,MAAM;CAGjC;AAED;;;GAGG;AACH,8BAAsB,sBAAsB;IAC1C;;;OAGG;aACa,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IACvD;;;;;;;;;;;;;;;;;OAiBG;IACI,QAAQ,EAAG,yBAAyB,CAAC;IAC5C;;;OAGG;;CAIJ;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,+BAAgC,SAAQ,sBAAsB;IACzE,OAAO,CAAC,KAAK,CAAyB;IACtC,sCAAsC;IACtC,OAAO,CAAC,YAAY,CAAW;IAC/B,kDAAkD;IAClD,OAAO,CAAC,UAAU,CAAU;IAC5B;;;OAGG;gBACgB,IAAI,EAAE,sBAAsB;IAM/C,+DAA+D;IACxD,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAI3C,qDAAqD;IAC9C,IAAI,IAAI,MAAM;IAGrB,qDAAqD;IAC9C,IAAI,IAAI,MAAM;IAGrB,kHAAkH;IAC3G,gBAAgB,IAAI,OAAO;IAKlC;;;OAGG;IACI,WAAW,IAAI,OAAO;IAe7B;;OAEG;IACI,eAAe,IAAI,MAAM;CAMjC;AACD;;;;GAIG;AACH,qBAAa,YAAY;IACvB;;;;;;;;OAQG;WACW,WAAW,CACvB,CAAC,EAAE,MAAM,EACT,IAAI,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EACvC,UAAU,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAC7C,iBAAiB,GAAE,MAAoC,GACtD,MAAM,GAAG,SAAS;CAyBtB"}

package/lib/esm/numerics/Newton.js

@@ -10,27 +10,28 @@ import { Plane3dByOriginAndVectors } from "../geometry3d/Plane3dByOriginAndVecto
 import { Point2d, Vector2d } from "../geometry3d/Point2dVector2d";
 import { SmallSystem } from "./Polynomials";
 // cspell:word currentdFdX
-/** base class for Newton iterations in various dimensions.
- * Dimension-specific classes carry all dimension-related data and answer generalized queries
- * from this base class.
+/**
+ * Base class for Newton iterations in various dimensions.
+ * Dimension-specific classes carry all dimension-related data and answer generalized queries from this base class.
  * @internal
  */
 export class AbstractNewtonIterator {
     /**
+     * The constructor.
      * @param stepSizeTarget tolerance to consider a single step converged.
-     * This number should be "moderately" strict.   Because 2 successive convergences are required,
+     * This number should be "moderately" strict. Because 2 successive convergences are required,
      * it is expected that a first "accept" for (say) 10 to 14 digit step will be followed by another
-     * iteration.   A well behaved newton would then hypothetically double the number of digits to
-     * 20 to 28.  Since the IEEE double only carries 16 digits, this second-convergence step will
+     * iteration. A well behaved newton would then hypothetically double the number of digits to
+     * 20 to 28. Since the IEEE double only carries 16 digits, this second-convergence step will
      * typically achieve full precision.
      * @param successiveConvergenceTarget number of successive convergences required for acceptance.
-     * @param maxIterations max number of iterations.   A typical newton step converges in 3 to 6 iterations.
-     *     Allow 15 to 20 to catch difficult cases.
+     * @param maxIterations max number of iterations. A typical newton step converges in 3 to 6 iterations.
+     * Allow 15 to 20 to catch difficult cases.
      */
     constructor(stepSizeTolerance = 1.0e-11, successiveConvergenceTarget = 2, maxIterations = 15) {
-        /** Number of consecutive steps which passed convergence condition */
+        /** Number of consecutive steps which passed convergence condition. */
         this._numAccepted = 0;
-        /** number of iterations (incremented at each step) */
+        /** Number of iterations (incremented at each step). */
         this.numIterations = 0;
         this._stepSizeTolerance = stepSizeTolerance;
         this._successiveConvergenceTarget = successiveConvergenceTarget;
@@ -38,8 +39,9 @@ export class AbstractNewtonIterator {
     }
     /**
      * Test if a step is converged.
-     * * Convergence is accepted with enough (_successiveConvergenceTarget) small steps (according to _stepSizeTolerance) occur in succession.
-     * @param delta step size as reported by currentStepSize
+     * * Convergence is accepted with enough (_successiveConvergenceTarget) small steps (according to _stepSizeTolerance)
+     * occur in succession.
+     * @param delta step size as reported by currentStepSize.
      */
     testConvergence(delta) {
         if (Math.abs(delta) < this._stepSizeTolerance) {
@@ -52,16 +54,15 @@ export class AbstractNewtonIterator {
     /**
      * Run iterations, calling various methods from base and derived classes:
      * * computeStep -- typically evaluate derivatives and solve linear system.
-     * * currentStepSize -- return numeric measure of the step just computed by computeStep
+     * * currentStepSize -- return numeric measure of the step just computed by computeStep.
      * * testConvergence -- test if the step from currentStepSize (along with recent steps) is converged.
-     * * applyCurrentStep -- apply the step to the independent variables
+     * * applyCurrentStep -- apply the step to the independent variables.
      */
     runIterations() {
         this._numAccepted = 0;
         this.numIterations = 0;
         while (this.numIterations++ < this._maxIterations && this.computeStep()) {
-            if (this.testConvergence(this.currentStepSize())
-                && this.applyCurrentStep(true)) {
+            if (this.testConvergence(this.currentStepSize()) && this.applyCurrentStep(true)) {
                 return true;
             }
             this.applyCurrentStep(false);
@@ -69,7 +70,8 @@ export class AbstractNewtonIterator {
         return false;
     }
 }
-/** object to evaluate a newton function.  The object must retain most-recent function and derivative
+/**
+ * Object to evaluate a newton function. The object must retain most-recent function and derivative
  * values for immediate query.
  * @internal
  */
@@ -77,26 +79,39 @@ export class NewtonEvaluatorRtoRD {
 }
 /**
  * Newton iterator for use when both function and derivative can be evaluated.
+ * To solve `f(x) = 0`, the Newton iteration is `x_{n+1} = x_n - dx = x_n - f(x_n)/f'(x_n)`.
+ * To solve `f(x) = target` which is equivalent to solving  `g(x) = f(x) - target = 0`, the Newton iteration is
+ * `x_{n+1} = x_n - dx = x_n - g(x_n)/g'(x_n) = x_n - (f(x_n)-target)/f'(x_n)`.
  * @internal
  */
 export class Newton1dUnbounded extends AbstractNewtonIterator {
     /**
-     * Constructor for 1D newton iteration with approximate derivatives.
-     * @param func function that returns both function and derivative.
+     * Constructor for 1D newton iteration with derivatives.
+     * @param func function that returns both function value and derivative.
      */
     constructor(func) {
         super();
         this._func = func;
         this.setTarget(0);
     }
-    /** Set the independent variable */
-    setX(x) { this._currentX = x; return true; }
-    /** Get the independent variable */
-    getX() { return this._currentX; }
-    /** Set the target function value */
-    setTarget(y) { this._target = y; }
-    /** move the current X by the just-computed step */
-    applyCurrentStep() { return this.setX(this._currentX - this._currentStep); }
+    /** Set the independent variable, i.e., x_n. */
+    setX(x) {
+        this._currentX = x;
+        return true;
+    }
+    /** Get the independent variable, i.e., x_n. */
+    getX() {
+        return this._currentX;
+    }
+    /** Set the target function value. */
+    setTarget(y) {
+        this._target = y;
+    }
+    /** Move the current X by the just-computed step, i.e., `x_n - dx`. */
+    applyCurrentStep() {
+        // console.log(this._currentX - this._currentStep); // print approximations for debug
+        return this.setX(this._currentX - this._currentStep);
+    }
     /** Compute the univariate newton step. */
     computeStep() {
         if (this._func.evaluate(this._currentX)) {
@@ -108,41 +123,54 @@ export class Newton1dUnbounded extends AbstractNewtonIterator {
         }
         return false;
     }
-    /** Return the current step size as a relative number. */
+    /** Return the current step size as a relative number, i.e., `|dx / (1 + |x_n|)|`. */
     currentStepSize() {
         return Math.abs(this._currentStep / (1.0 + Math.abs(this._currentX)));
     }
 }
-/** object to evaluate a newton function (without derivative).  The object must retain most-recent function value.
+/**
+ * Object to evaluate a newton function (without derivative). The object must retain most-recent function value.
  * @internal
  */
 export class NewtonEvaluatorRtoR {
 }
-/** Newton iteration for a univariate function, using approximate derivatives.
+/**
+ * Newton iteration for a univariate function, using approximate derivatives.
+ * To approximate the derivatives we use a small step `h`, i.e., `f'(x_n) = (f(x_n + h) - f(x_n)) / h`.
+ * Therefore, to solve `f(x) = 0`, the iteration is
+ * `x_{n+1} = x_n - dx = x_n - f(x_n)/f'(x_n) = x_n - f(x_n) * h / (f(x_n + h) - f(x_n))`.
  * @internal
  */
 export class Newton1dUnboundedApproximateDerivative extends AbstractNewtonIterator {
     /**
      * Constructor for 1D newton iteration with approximate derivatives.
-     * @param func function that returns both function and derivative.
+     * @param func function that only returns function value (and not derivative).
      */
     constructor(func) {
         super();
         this._func = func;
         this.derivativeH = 1.0e-8;
     }
-    /** Set the x (independent, iterated) value */
-    setX(x) { this._currentX = x; return true; }
-    /** Get the independent variable */
-    getX() { return this._currentX; }
-    /** move the current X by the just-computed step */
-    applyCurrentStep() { return this.setX(this._currentX - this._currentStep); }
-    /** Univariate newton step computed with APPROXIMATE derivative. */
+    /** Set the independent variable, i.e., x_n. */
+    setX(x) {
+        this._currentX = x;
+        return true;
+    }
+    /** Get the independent variable, i.e., x_n. */
+    getX() {
+        return this._currentX;
+    }
+    /** Move the current X by the just-computed step, i.e., `x_n - dx`. */
+    applyCurrentStep() {
+        // console.log(this._currentX - this._currentStep); // print approximations for debug
+        return this.setX(this._currentX - this._currentStep);
+    }
+    /** Univariate newton step computed with approximate derivative. */
     computeStep() {
         if (this._func.evaluate(this._currentX)) {
-            const fA = this._func.currentF;
+            const fA = this._func.currentF; // f(x_n)
             if (this._func.evaluate(this._currentX + this.derivativeH)) {
-                const fB = this._func.currentF;
+                const fB = this._func.currentF; // f(x_n + h)
                 const dx = Geometry.conditionalDivideFraction(fA, (fB - fA) / this.derivativeH);
                 if (dx !== undefined) {
                     this._currentStep = dx;
@@ -152,17 +180,18 @@ export class Newton1dUnboundedApproximateDerivative extends AbstractNewtonIterat
         }
         return false;
     }
-    /** Return the current step size as a relative number. */
+    /** Return the current step size as a relative number, i.e., `|dx / (1 + |x_n|)|`. */
     currentStepSize() {
         return Math.abs(this._currentStep / (1.0 + Math.abs(this._currentX)));
     }
 }
-/** object to evaluate a 2-parameter newton function (with derivatives!!).
+/**
+ * Object to evaluate a 2-parameter newton function with derivatives.
  * @internal
  */
 export class NewtonEvaluatorRRtoRRD {
     /**
-     * constructor.
+     * Constructor.
      * * This creates a currentF object to (repeatedly) receive function and derivatives.
      */
     constructor() {
@@ -171,25 +200,49 @@ export class NewtonEvaluatorRRtoRRD {
 }
 /**
  * Implement evaluation steps for newton iteration in 2 dimensions, using caller supplied NewtonEvaluatorRRtoRRD object.
+ * * Suppose we want to find the roots of `F(u,v) := (x(u,v), y(u,v))`. Writing `X := (u,v)` and `F(X)` as column vectors,
+ *  the 2D Newton's iteration to find a root of `F` is given by:
+ * `X_{n+1} = X_n - dX = X_n - JInv(X_n)F(X_n)`, where `JInv` is the inverse of the Jacobian matrix `J`, and `J` is
+ * defined as:
+ *
+ * `[dx/du   dx/dv]`
+ *
+ * `[dy/du   dy/dv]`
  * @internal
  */
 export class Newton2dUnboundedWithDerivative extends AbstractNewtonIterator {
+    /**
+     * Constructor for 2D newton iteration with derivatives.
+     * @param func function that returns both function value and derivative.
+     */
     constructor(func) {
         super();
         this._func = func;
         this._currentStep = Vector2d.createZero();
         this._currentUV = Point2d.createZero();
     }
-    /** Set the current uv coordinates for current iteration */
-    setUV(x, y) { this._currentUV.set(x, y); return true; }
-    /** Get the current u coordinate */
-    getU() { return this._currentUV.x; }
-    /** Get the current v coordinate */
-    getV() { return this._currentUV.y; }
-    /** Move the currentUV coordinate by currentStep. */
-    applyCurrentStep() { return this.setUV(this._currentUV.x - this._currentStep.x, this._currentUV.y - this._currentStep.y); }
-    /** Evaluate the functions and derivatives at this._currentUV
-     * Invert the jacobian and compute the this._currentStep.
+    /** Set the current uv parameters, i.e., `X_n = (u_n, v_n)`. */
+    setUV(u, v) {
+        this._currentUV.set(u, v);
+        return true;
+    }
+    /** Get the current u parameter of X_n, i.e., u_n. */
+    getU() {
+        return this._currentUV.x;
+    }
+    /** Get the current v parameter of X_n, i.e., v_n. */
+    getV() {
+        return this._currentUV.y;
+    }
+    /** Update the current uv parameter by currentStep, i.e., compute `X_{n+1} := X_n - dX = (u_n - du, v_n - dv)`. */
+    applyCurrentStep() {
+        // print approximations for debug
+        // console.log("(" + (this._currentUV.x - this._currentStep.x) + "," + (this._currentUV.y - this._currentStep.y) + ")");
+        return this.setUV(this._currentUV.x - this._currentStep.x, this._currentUV.y - this._currentStep.y);
+    }
+    /**
+     * Evaluate the functions and derivatives at `X_n = (u_n, v_n)`, and solve the Jacobian matrix equation to
+     * compute `dX = (du, dv)`.
      */
     computeStep() {
         if (this._func.evaluate(this._currentUV.x, this._currentUV.y)) {
@@ -200,22 +253,25 @@ export class Newton2dUnboundedWithDerivative extends AbstractNewtonIterator {
         return false;
     }
     /**
-     * Return the largest relative step of the x,y, components of the current step.
+     * Return the current relative step size, i.e., the larger absolute component of `dX / (1 + |X_n|)`
      */
     currentStepSize() {
         return Geometry.maxAbsXY(this._currentStep.x / (1.0 + Math.abs(this._currentUV.x)), this._currentStep.y / (1.0 + Math.abs(this._currentUV.y)));
     }
 }
 /**
- * SimpleNewton has static methods for newton methods with evaluated functions presented as immediate arguments (not function object)
+ * SimpleNewton has static methods for newton methods with evaluated functions presented as immediate arguments
+ * (not function object).
  * @internal
  */
 export class SimpleNewton {
-    /** Run a one-dimensional newton iteration with separate functions for function and derivative.
-     * * completion is at 2 (TWO) successive passes at (absoluteTolerance + relTol * abs (x)), where relTol is chosen internally.
-     * * absoluteTolerance is usually aggressively tight -- should come into play only for x near zero.
-     * * The relTol is fluffy (for instance around 1e-11) but in properly converging cases the extra pass after first success
-     *    normally moves to full machine precision.
+    /**
+     * Run a one-dimensional newton iteration with separate functions for function and derivative.
+     * * Completion is at 2 (TWO) successive passes at `absoluteTolerance + relTol * abs(x)`, where relTol is
+     * chosen internally.
+     * * `absoluteTolerance` is usually aggressively tight -- should come into play only for x near zero.
+     * * The `relTol` is fluffy (for instance around 1e-11) but in properly converging cases the extra pass after
+     * first success normally moves to full machine precision.
      * * This is an open-loop newton -- it just runs, and returns undefined if anything bad happens.
      */
     static runNewton1D(x, func, derivative, absoluteTolerance = Geometry.smallFloatingPoint) {
@@ -230,10 +286,11 @@ export class SimpleNewton {
                 if (dx === undefined)
                     return undefined;
                 x -= dx;
+                // console.log(x); // print approximations for debug
                 tolerance = absoluteTolerance + Math.abs(x) * relTol;
                 if (Math.abs(dx) < tolerance) {
                     numConverged++;
-                    if (dx === 0.0 || numConverged > 1) // bypass convergence count on true 0 dx !
+                    if (dx === 0.0 || numConverged > 1) // bypass convergence count on true 0 dx
                         return x;
                 }
                 else {