Add least_squares, reset_knots, keep_knots across all fitter types

- Add least_squares(smoothing, reset_knots) to all 9 fitter types
  (was missing from fitpack_parametric_curve). When reset_knots=.true.,
  a smoothing pre-fit determines sparser knots before the LS pass.
- Add interpolate(reset_knots) to all 9 types (default .true.).
  When .false., FITPACK continues from current knots.
- Add keep_knots parameter to fit() to bypass the iopt guard.
- Extend test_umbrella_api with parametric curve interpolate/LS tests.
- Mark PR A (Public API Cleanup) as done in refactoring plan.

Author: perazz

docs/refactoring/04_oop_interface_analysis.md

@@ -223,7 +223,7 @@ that serializes all allocatable components).
 
 # PR Plans
 
-## PR A: Public API Cleanup & Umbrella Module
+## PR A: Public API Cleanup & Umbrella Module (DONE)
 
 **Goal**: Make the `fitpack` umbrella module self-sufficient — users should never need
 `use fitpack_core` directly.
@@ -270,9 +270,9 @@ A user writing `curve%bc = OUTSIDE_EXTRAPOLATE` must also `use fitpack_core`. Si
 
 ---
 
-## PR B: Abstract Base Type
+## PR B: Abstract Base Type (DONE — PR #41)
 
-**Goal**: Extract shared state and logic into an abstract `fitpack_spline` base type that
+**Goal**: Extract shared state and logic into an abstract `fitpack_fitter` base type that
 all 9 concrete types extend.
 
 ### Design

project/fitpack.cbp

@@ -90,6 +90,7 @@
 		<Unit filename="../src/fitpack_constrained_c.f90">
 			<Option weight="0" />
 		</Unit>
+		<Unit filename="../src/fitpack_core.F90" />
 		<Unit filename="../src/fitpack_core.f90">
 			<Option weight="0" />
 		</Unit>
@@ -102,6 +103,7 @@
 		<Unit filename="../src/fitpack_curves_c.f90">
 			<Option weight="0" />
 		</Unit>
+		<Unit filename="../src/fitpack_fitters.f90" />
 		<Unit filename="../src/fitpack_grid_surfaces.f90">
 			<Option weight="0" />
 		</Unit>

src/fitpack_curves.f90

@@ -331,39 +331,57 @@ pure function curve_eval_many_pure(this,x) result(y)
     end function curve_eval_many_pure
 
     ! Interpolating curve
-    integer(FP_FLAG) function interpolating_curve(this,order) result(ierr)
+    integer(FP_FLAG) function interpolating_curve(this,order,reset_knots) result(ierr)
         class(fitpack_curve), intent(inout) :: this
         integer(FP_SIZE), optional, intent(in) :: order
+        logical, optional, intent(in) :: reset_knots
 
-        ! Set zero smoothing
-        this%iopt = IOPT_NEW_SMOOTHING
-        
-        ! Update order if necessary
-        ierr = curve_fit_automatic_knots(this,smoothing=zero,order=order)
+        logical :: do_reset
+
+        do_reset = .true.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) this%iopt = IOPT_NEW_SMOOTHING
+
+        ierr = curve_fit_automatic_knots(this,smoothing=zero,order=order,keep_knots=.not.do_reset)
 
     end function interpolating_curve
 
     ! Least-squares curve fit with current knots
-    integer(FP_FLAG) function curve_fit_least_squares(this) result(ierr)
+    integer(FP_FLAG) function curve_fit_least_squares(this,smoothing,reset_knots) result(ierr)
         class(fitpack_curve), intent(inout) :: this
+        real(FP_REAL), optional, intent(in) :: smoothing
+        logical, optional, intent(in) :: reset_knots
+
+        logical :: do_reset
+
+        ! Optionally recompute knots via a smoothing fit first
+        do_reset = .false.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) then
+            this%iopt = IOPT_NEW_SMOOTHING
+            ierr = this%fit(smoothing)
+            if (.not.FITPACK_SUCCESS(ierr)) return
+        end if
+
         this%iopt = IOPT_NEW_LEASTSQUARES
         ierr = this%fit()
     end function curve_fit_least_squares
 
     ! Curve fitting driver: automatic number of knots
-    integer(FP_FLAG) function curve_fit_automatic_knots(this,smoothing,order) result(ierr)
+    integer(FP_FLAG) function curve_fit_automatic_knots(this,smoothing,order,keep_knots) result(ierr)
         class(fitpack_curve), intent(inout) :: this
         real(FP_REAL), optional, intent(in) :: smoothing
         integer(FP_SIZE), optional, intent(in) :: order
+        logical, optional, intent(in) :: keep_knots
 
         integer(FP_SIZE) :: loop,nit
         real(FP_REAL) :: smooth_now(3)
+        logical :: do_guard
 
         !> Get smoothing trajectory
         call get_smoothing(this%smoothing,smoothing,nit,smooth_now)
 
-        !> Ensure we start with new knots
-        if (this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
+        !> Ensure we start with new knots (unless caller wants to keep them)
+        do_guard = .true.; if (present(keep_knots)) do_guard = .not.keep_knots
+        if (do_guard .and. this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
 
         !> Set/update order
         if (present(order)) this%order = order

src/fitpack_grid_surfaces.f90

@@ -94,37 +94,56 @@ module fitpack_grid_surfaces
     contains
 
     ! Fit a surface to least squares of the current knots
-    integer function surface_fit_least_squares(this) result(ierr)
+    integer function surface_fit_least_squares(this,smoothing,reset_knots) result(ierr)
        class(fitpack_grid_surface), intent(inout) :: this
+       real(FP_REAL), optional, intent(in) :: smoothing
+       logical, optional, intent(in) :: reset_knots
+
+       logical :: do_reset
+
+       ! Optionally recompute knots via a smoothing fit first
+       do_reset = .false.; if (present(reset_knots)) do_reset = reset_knots
+       if (do_reset) then
+           this%iopt = IOPT_NEW_SMOOTHING
+           ierr = this%fit(smoothing)
+           if (.not.FITPACK_SUCCESS(ierr)) return
+       end if
 
        this%iopt = IOPT_NEW_LEASTSQUARES
        ierr = this%fit()
 
     end function surface_fit_least_squares
 
     ! Find interpolating surface
-    integer function surface_fit_interpolating(this) result(ierr)
+    integer function surface_fit_interpolating(this,reset_knots) result(ierr)
         class(fitpack_grid_surface), intent(inout) :: this
+        logical, optional, intent(in) :: reset_knots
+
+        logical :: do_reset
 
-        ! Set zero smoothing
-        ierr = surface_fit_automatic_knots(this,smoothing=zero)
+        do_reset = .true.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) this%iopt = IOPT_NEW_SMOOTHING
+        ierr = surface_fit_automatic_knots(this,smoothing=zero,keep_knots=.not.do_reset)
 
     end function surface_fit_interpolating
 
 
     ! Fit a surface z = s(x,y) defined on a meshgrid: x[1:n], y[1:m]
-    integer(FP_FLAG) function surface_fit_automatic_knots(this,smoothing,order) result(ierr)
+    integer(FP_FLAG) function surface_fit_automatic_knots(this,smoothing,order,keep_knots) result(ierr)
         class(fitpack_grid_surface), intent(inout) :: this
         real(FP_REAL), optional, intent(in) :: smoothing
         integer, optional, intent(in) :: order
+        logical, optional, intent(in) :: keep_knots
 
         integer(FP_SIZE) :: loop,nit
         real(FP_REAL) :: smooth_now(3)
+        logical :: do_guard
 
         call get_smoothing(this%smoothing,smoothing,nit,smooth_now)
 
-        !> Ensure we start with new knots
-        if (this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
+        !> Ensure we start with new knots (unless caller wants to keep them)
+        do_guard = .true.; if (present(keep_knots)) do_guard = .not.keep_knots
+        if (do_guard .and. this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
 
         ! User may want to change the order for both x and y
         if (present(order)) this%order = order

src/fitpack_gridded_polar.f90

@@ -106,36 +106,55 @@ module fitpack_gridded_polar
     contains
 
     ! Fit a surface to least squares of the current knots
-    integer function polr_fit_least_squares(this) result(ierr)
+    integer function polr_fit_least_squares(this,smoothing,reset_knots) result(ierr)
        class(fitpack_grid_polar), intent(inout) :: this
+       real(FP_REAL), optional, intent(in) :: smoothing
+       logical, optional, intent(in) :: reset_knots
+
+       logical :: do_reset
+
+       ! Optionally recompute knots via a smoothing fit first
+       do_reset = .false.; if (present(reset_knots)) do_reset = reset_knots
+       if (do_reset) then
+           this%iopt = IOPT_NEW_SMOOTHING
+           ierr = this%fit(smoothing)
+           if (.not.FITPACK_SUCCESS(ierr)) return
+       end if
 
        this%iopt = IOPT_NEW_LEASTSQUARES
        ierr = this%fit()
 
     end function polr_fit_least_squares
 
     ! Find interpolating surface
-    integer function polr_fit_interpolating(this) result(ierr)
+    integer function polr_fit_interpolating(this,reset_knots) result(ierr)
         class(fitpack_grid_polar), intent(inout) :: this
+        logical, optional, intent(in) :: reset_knots
+
+        logical :: do_reset
 
-        ! Set zero smoothing
-        ierr = polr_fit_automatic_knots(this,smoothing=zero)
+        do_reset = .true.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) this%iopt = IOPT_NEW_SMOOTHING
+        ierr = polr_fit_automatic_knots(this,smoothing=zero,keep_knots=.not.do_reset)
 
     end function polr_fit_interpolating
 
 
     ! Fit a surface z = s(x,y) defined on a meshgrid: x[1:n], y[1:m]
-    integer function polr_fit_automatic_knots(this,smoothing) result(ierr)
+    integer function polr_fit_automatic_knots(this,smoothing,keep_knots) result(ierr)
         class(fitpack_grid_polar), intent(inout) :: this
         real(FP_REAL), optional, intent(in) :: smoothing
+        logical, optional, intent(in) :: keep_knots
 
         integer :: loop,nit,iopt(3),ider(2)
         real(FP_REAL) :: smooth_now(3)
+        logical :: do_guard
 
         call get_smoothing(this%smoothing,smoothing,nit,smooth_now)
 
-        !> Ensure we start with new knots
-        if (this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
+        !> Ensure we start with new knots (unless caller wants to keep them)
+        do_guard = .true.; if (present(keep_knots)) do_guard = .not.keep_knots
+        if (do_guard .and. this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
 
         do loop=1,nit
 

src/fitpack_gridded_sphere.f90

@@ -99,36 +99,55 @@ module fitpack_gridded_sphere
     contains
 
     ! Fit a surface to least squares of the current knots
-    integer function spgrid_fit_least_squares(this) result(ierr)
+    integer function spgrid_fit_least_squares(this,smoothing,reset_knots) result(ierr)
        class(fitpack_grid_sphere), intent(inout) :: this
+       real(FP_REAL), optional, intent(in) :: smoothing
+       logical, optional, intent(in) :: reset_knots
+
+       logical :: do_reset
+
+       ! Optionally recompute knots via a smoothing fit first
+       do_reset = .false.; if (present(reset_knots)) do_reset = reset_knots
+       if (do_reset) then
+           this%iopt = IOPT_NEW_SMOOTHING
+           ierr = this%fit(smoothing)
+           if (.not.FITPACK_SUCCESS(ierr)) return
+       end if
 
        this%iopt = IOPT_NEW_LEASTSQUARES
        ierr = this%fit()
 
     end function spgrid_fit_least_squares
 
     ! Find interpolating surface
-    integer function spgrid_fit_interpolating(this) result(ierr)
+    integer function spgrid_fit_interpolating(this,reset_knots) result(ierr)
         class(fitpack_grid_sphere), intent(inout) :: this
+        logical, optional, intent(in) :: reset_knots
+
+        logical :: do_reset
 
-        ! Set zero smoothing
-        ierr = spgrid_fit_automatic_knots(this,smoothing=zero)
+        do_reset = .true.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) this%iopt = IOPT_NEW_SMOOTHING
+        ierr = spgrid_fit_automatic_knots(this,smoothing=zero,keep_knots=.not.do_reset)
 
     end function spgrid_fit_interpolating
 
 
     ! Fit a surface z = s(x,y) defined on a meshgrid: x[1:n], y[1:m]
-    integer function spgrid_fit_automatic_knots(this,smoothing) result(ierr)
+    integer function spgrid_fit_automatic_knots(this,smoothing,keep_knots) result(ierr)
         class(fitpack_grid_sphere), intent(inout) :: this
         real(FP_REAL), optional, intent(in) :: smoothing
+        logical, optional, intent(in) :: keep_knots
 
         integer :: loop,nit,iopt(3),ider(4)
         real(FP_REAL) :: smooth_now(3)
+        logical :: do_guard
 
         call get_smoothing(this%smoothing,smoothing,nit,smooth_now)
 
-        !> Ensure we start with new knots
-        if (this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
+        !> Ensure we start with new knots (unless caller wants to keep them)
+        do_guard = .true.; if (present(keep_knots)) do_guard = .not.keep_knots
+        if (do_guard .and. this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
 
         do loop=1,nit
 

src/fitpack_parametric.f90

@@ -82,7 +82,8 @@ module fitpack_parametric_curves
 
            !> Generate/update fitting curve, with optional smoothing
            procedure :: fit         => curve_fit_automatic_knots
-           procedure :: interpolate => interpolating_curve
+           procedure :: interpolate   => interpolating_curve
+           procedure :: least_squares => parcur_fit_least_squares
 
            !> Evaluate curve at given coordinates
            procedure :: eval_one  => curve_eval_one
@@ -427,31 +428,56 @@ function curve_eval_many(this,u,ierr) result(x)
     end function curve_eval_many
 
     ! Interpolating curve
-    integer function interpolating_curve(this,order) result(ierr)
+    integer function interpolating_curve(this,order,reset_knots) result(ierr)
         class(fitpack_parametric_curve), intent(inout) :: this
         integer(FP_SIZE), optional, intent(in) :: order
+        logical, optional, intent(in) :: reset_knots
 
-        ! Set zero smoothing
-        this%iopt = IOPT_NEW_SMOOTHING
+        logical :: do_reset
+
+        do_reset = .true.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) this%iopt = IOPT_NEW_SMOOTHING
 
-        ! Set zero smoothing
-        ierr = curve_fit_automatic_knots(this,smoothing=zero,order=order)
+        ierr = curve_fit_automatic_knots(this,smoothing=zero,order=order,keep_knots=.not.do_reset)
 
     end function interpolating_curve
 
+    ! Least-squares curve fit with current knots
+    integer function parcur_fit_least_squares(this,smoothing,reset_knots) result(ierr)
+        class(fitpack_parametric_curve), intent(inout) :: this
+        real(FP_REAL), optional, intent(in) :: smoothing
+        logical, optional, intent(in) :: reset_knots
+
+        logical :: do_reset
+
+        ! Optionally recompute knots via a smoothing fit first
+        do_reset = .false.; if (present(reset_knots)) do_reset = reset_knots
+        if (do_reset) then
+            this%iopt = IOPT_NEW_SMOOTHING
+            ierr = this%fit(smoothing)
+            if (.not.FITPACK_SUCCESS(ierr)) return
+        end if
+
+        this%iopt = IOPT_NEW_LEASTSQUARES
+        ierr = this%fit()
+    end function parcur_fit_least_squares
+
     ! Curve fitting driver: automatic number of knots
-    integer function curve_fit_automatic_knots(this,smoothing,order) result(ierr)
+    integer function curve_fit_automatic_knots(this,smoothing,order,keep_knots) result(ierr)
         class(fitpack_parametric_curve), intent(inout) :: this
         real(FP_REAL), optional, intent(in) :: smoothing
         integer(FP_SIZE), optional, intent(in) :: order
+        logical, optional, intent(in) :: keep_knots
 
         integer :: loop,nit
         real(FP_REAL) :: smooth_now(3)
+        logical :: do_guard
 
         call get_smoothing(this%smoothing,smoothing,nit,smooth_now)
 
-        !> Ensure we start with new knots
-        if (this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
+        !> Ensure we start with new knots (unless caller wants to keep them)
+        do_guard = .true.; if (present(keep_knots)) do_guard = .not.keep_knots
+        if (do_guard .and. this%iopt==IOPT_OLD_FIT) this%iopt = IOPT_NEW_SMOOTHING
 
         ! Set order
         if (present(order)) this%order = order