nf_solver_initialize Function

   type(hompack_status) function nf_solver_initialize( &
      self, problem_type, callbacks, n, dima, config) result(status)
   !! This function initializes a [[nf_solver]] object for a specified problem type,
   !! user-supplied callbacks, and configuration parameters.
   !! It validates the inputs, allocates necessary state variables (deallocation included),
   !! and binds the callbacks to the solver object.

      class(nf_solver), intent(inout) :: self
         !! Solver object.
      integer, intent(in) :: problem_type
         !! Problem type. Must be one of the following:
         !! * `fix_point` : solve \( F(x) = x \).
         !! * `zero_find` : solve \( F(x) = 0 \).
         !! * `curve_track` : track a zero curve of \( \rho(a,\lambda,x) = 0 \).
      type(hompack_f_callbacks), intent(in) :: callbacks
         !! User-supplied function and Jacobian evaluation subroutines. Required callbacks
         !! depend on `problem_type` as follows:
         !! * For `problem_type = fix_point` or `zero_find`, callbacks `f` and `fjac` must be
         !!   provided.
         !! * For `problem_type = curve_track`, callbacks `rho` and `rhojac` must be provided.
      integer, intent(in) :: n
         !! Problem dimension, i.e., the dimension of the independent variable \(x\).
      integer, intent(in), optional :: dima
         !! Dimension of the parameter vector \(a\) for curve-tracking problems. Required if
         !! `problem_type` is `curve_track`.
      type(nf_config), intent(in), optional :: config
         !! Configuration parameters. If not provided, default values are used.

      integer :: dima_, ierr

      ! Validate 'problem_type'
      if (problem_type /= problem_fix_point .and. problem_type /= problem_zero_find .and. &
          problem_type /= problem_curve_track) then
         status%message = "Illegal input: `prob_type` must be `fix_point`, `zero_find`, or `curve_track`."
         status%code = fixpnf_input_error
         return
      end if

      ! Validate 'n'
      if (n <= 0) then
         status%message = "Illegal input: `n` must be greater or equal than one."
         status%code = fixpnf_input_error
         return
      end if

      ! Validate callbacks and parameter vector 'a'
      if (problem_type == problem_fix_point .or. problem_type == problem_zero_find) then
         if (.not. associated(callbacks%f)) then
            status%message = "Illegal input: callback `f` must be provided for fixed-point and zero-finding problems."
            status%code = fixpnf_input_error
            return
         end if
         if (.not. associated(callbacks%fjac)) then
            status%message = "Illegal input: callback `fjac` must be provided for fixed-point and zero-finding problems."
            status%code = fixpnf_input_error
            return
         end if
         dima_ = n
      else if (problem_type == problem_curve_track) then
         if (.not. associated(callbacks%rho)) then
            status%message = "Illegal input: callback `rho` must be provided for curve-tracking problems."
            status%code = fixpnf_input_error
            return
         end if
         if (.not. associated(callbacks%rhojac)) then
            status%message = "Illegal input: callback `rhojac` must be provided for curve-tracking problems."
            status%code = fixpnf_input_error
            return
         end if
         if (.not. present(dima)) then
            status%message = "Illegal input: parameter vector dimension `dima` must be provided for curve-tracking problems."
            status%code = fixpnf_input_error
            return
         end if
         if (dima <= 0) then
            status%message = "Illegal input: parameter vector dimension `dima` must be greater than zero."
            status%code = fixpnf_input_error
            return
         end if
         dima_ = dima
      end if

      ! Validate configuration parameters
      if (present(config)) then
         if (config%max_steps < 1) then
            status%message = "Illegal input: `config.max_steps` must be greater than zero."
            status%code = fixpnf_input_error
            return
         end if
         if (config%ansre <= zero) then
            status%message = "Illegal input: `config.ansre` must be greater than zero."
            status%code = fixpnf_input_error
            return
         end if
         if (config%ansae < zero) then
            status%message = "Illegal input: `config.ansae` must be greater or equal than zero."
            status%code = fixpnf_input_error
            return
         end if
      end if

      ! Allocate state variables
      call self%state%alloc(n, dima_, stat=ierr)
      if (ierr /= 0) then
         status%message = "Memory allocation failure during initialization."
         status%code = fixpnf_memory_error
         return
      end if

      ! Update object fields now that initialization is successful
      self%problem_type = problem_type
      self%callbacks = callbacks ! copy is intentional
      if (present(config)) self%config = config
      self%initialized = .true.

      ! Finalize
      status%message = "Initialization successful."
      status%code = fixpnf_success

   end function nf_solver_initialize