math.f90 Source File


This file depends on

sourcefile~~math.f90~~EfferentGraph sourcefile~math.f90 math.f90 sourcefile~auxiliar.f90~2 auxiliar.f90 sourcefile~math.f90->sourcefile~auxiliar.f90~2 sourcefile~constants.f90 constants.f90 sourcefile~math.f90->sourcefile~constants.f90 sourcefile~continuation.f90 continuation.f90 sourcefile~math.f90->sourcefile~continuation.f90 sourcefile~linalg.f90 linalg.f90 sourcefile~math.f90->sourcefile~linalg.f90 sourcefile~auxiliar.f90~2->sourcefile~constants.f90 sourcefile~continuation.f90->sourcefile~auxiliar.f90~2 sourcefile~continuation.f90->sourcefile~constants.f90 sourcefile~continuation.f90->sourcefile~linalg.f90 sourcefile~linalg.f90->sourcefile~auxiliar.f90~2 sourcefile~linalg.f90->sourcefile~constants.f90

Files dependent on this one

sourcefile~~math.f90~~AfferentGraph sourcefile~math.f90 math.f90 sourcefile~ar_models.f90 ar_models.f90 sourcefile~ar_models.f90->sourcefile~math.f90 sourcefile~auxiliar.f90 auxiliar.f90 sourcefile~auxiliar.f90->sourcefile~math.f90 sourcefile~binaries.f90 binaries.f90 sourcefile~binaries.f90->sourcefile~math.f90 sourcefile~binaries.f90->sourcefile~ar_models.f90 sourcefile~critical.f90 critical.f90 sourcefile~critical.f90->sourcefile~math.f90 sourcefile~critical.f90->sourcefile~ar_models.f90 sourcefile~stability.f90 stability.f90 sourcefile~critical.f90->sourcefile~stability.f90 sourcefile~flash_mp.f90 flash_mp.f90 sourcefile~flash_mp.f90->sourcefile~math.f90 sourcefile~flash_mp.f90->sourcefile~ar_models.f90 sourcefile~flash_mp.f90->sourcefile~stability.f90 sourcefile~generalized_isoline.f90 generalized_isoline.f90 sourcefile~generalized_isoline.f90->sourcefile~math.f90 sourcefile~generalized_isoline.f90->sourcefile~ar_models.f90 sourcefile~generalized_isoline.f90->sourcefile~stability.f90 sourcefile~gerg2008.f90 gerg2008.f90 sourcefile~gerg2008.f90->sourcefile~math.f90 sourcefile~armodel_adiff_api.f90 armodel_adiff_api.f90 sourcefile~gerg2008.f90->sourcefile~armodel_adiff_api.f90 sourcefile~generic_cubic.f90 generic_cubic.f90 sourcefile~gerg2008.f90->sourcefile~generic_cubic.f90 sourcefile~implementations.f90~2 implementations.f90 sourcefile~gerg2008.f90->sourcefile~implementations.f90~2 sourcefile~nonlineal.f90 nonlineal.f90 sourcefile~nonlineal.f90->sourcefile~math.f90 sourcefile~phase_envelopes_pt_3ph.f90 phase_envelopes_pt_3ph.f90 sourcefile~phase_envelopes_pt_3ph.f90->sourcefile~math.f90 sourcefile~phase_envelopes_pt_3ph.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_pt_mp.f90 phase_envelopes_pt_mp.f90 sourcefile~phase_envelopes_pt_mp.f90->sourcefile~math.f90 sourcefile~phase_envelopes_pt_mp.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_pt_mp.f90->sourcefile~auxiliar.f90 sourcefile~phase_envelopes_px_3ph.f90 phase_envelopes_px_3ph.f90 sourcefile~phase_envelopes_px_3ph.f90->sourcefile~math.f90 sourcefile~phase_envelopes_px_3ph.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_px_3ph.f90->sourcefile~auxiliar.f90 sourcefile~phase_envelopes_px_mp.f90 phase_envelopes_px_mp.f90 sourcefile~phase_envelopes_px_mp.f90->sourcefile~math.f90 sourcefile~phase_envelopes_px_mp.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_px_mp.f90->sourcefile~auxiliar.f90 sourcefile~phase_envelopes_tx_mp.f90 phase_envelopes_tx_mp.f90 sourcefile~phase_envelopes_tx_mp.f90->sourcefile~math.f90 sourcefile~phase_envelopes_tx_mp.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_tx_mp.f90->sourcefile~auxiliar.f90 sourcefile~saturation_point.f90 saturation_point.f90 sourcefile~saturation_point.f90->sourcefile~math.f90 sourcefile~saturation_point.f90->sourcefile~ar_models.f90 sourcefile~saturation_point.f90->sourcefile~nonlineal.f90 sourcefile~uniquac.f90 uniquac.f90 sourcefile~uniquac.f90->sourcefile~math.f90 sourcefile~armodel_adiff_api.f90->sourcefile~ar_models.f90 sourcefile~auxiliar.f90~3 auxiliar.f90 sourcefile~auxiliar.f90~3->sourcefile~ar_models.f90 sourcefile~consistency_armodel.f90 consistency_armodel.f90 sourcefile~consistency_armodel.f90->sourcefile~ar_models.f90 sourcefile~equilibria.f90 equilibria.f90 sourcefile~equilibria.f90->sourcefile~binaries.f90 sourcefile~equilibria.f90->sourcefile~critical.f90 sourcefile~equilibria.f90->sourcefile~flash_mp.f90 sourcefile~equilibria.f90->sourcefile~generalized_isoline.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_pt_3ph.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_pt_mp.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_px_3ph.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_px_mp.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_tx_mp.f90 sourcefile~equilibria.f90->sourcefile~auxiliar.f90~3 sourcefile~flash.f90 flash.f90 sourcefile~equilibria.f90->sourcefile~flash.f90 sourcefile~flash_second_order.f90 flash_second_order.f90 sourcefile~equilibria.f90->sourcefile~flash_second_order.f90 sourcefile~phase_envelopes_pt.f90 phase_envelopes_pt.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_pt.f90 sourcefile~phase_envelopes_px.f90 phase_envelopes_px.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_px.f90 sourcefile~phase_envelopes_tx.f90 phase_envelopes_tx.f90 sourcefile~equilibria.f90->sourcefile~phase_envelopes_tx.f90 sourcefile~pure_saturation.f90 pure_saturation.f90 sourcefile~equilibria.f90->sourcefile~pure_saturation.f90 sourcefile~saturations_points.f90 saturations_points.f90 sourcefile~equilibria.f90->sourcefile~saturations_points.f90 sourcefile~equilibria.f90->sourcefile~stability.f90 sourcefile~flash.f90->sourcefile~ar_models.f90 sourcefile~flash.f90->sourcefile~auxiliar.f90~3 sourcefile~pressure_equality.f90 pressure_equality.f90 sourcefile~flash.f90->sourcefile~pressure_equality.f90 sourcefile~flash_second_order.f90->sourcefile~ar_models.f90 sourcefile~flash_second_order.f90->sourcefile~auxiliar.f90~3 sourcefile~flash_second_order.f90->sourcefile~stability.f90 sourcefile~generic_cubic.f90->sourcefile~ar_models.f90 sourcefile~volume.f90 volume.f90 sourcefile~generic_cubic.f90->sourcefile~volume.f90 sourcefile~implementations.f90 implementations.f90 sourcefile~implementations.f90->sourcefile~uniquac.f90 sourcefile~nrtl_hv.f90 nrtl_hv.f90 sourcefile~implementations.f90->sourcefile~nrtl_hv.f90 sourcefile~models.f90 models.f90 sourcefile~models.f90->sourcefile~ar_models.f90 sourcefile~models.f90->sourcefile~gerg2008.f90 sourcefile~models.f90->sourcefile~generic_cubic.f90 sourcefile~models.f90->sourcefile~implementations.f90 sourcefile~pc_saft.f90 pc_saft.f90 sourcefile~models.f90->sourcefile~pc_saft.f90 sourcefile~alphas.f90 alphas.f90 sourcefile~models.f90->sourcefile~alphas.f90 sourcefile~cubic_mixing.f90 cubic_mixing.f90 sourcefile~models.f90->sourcefile~cubic_mixing.f90 sourcefile~huron_vidal.f90 huron_vidal.f90 sourcefile~models.f90->sourcefile~huron_vidal.f90 sourcefile~models.f90->sourcefile~implementations.f90~2 sourcefile~quadratic_mixing.f90 quadratic_mixing.f90 sourcefile~models.f90->sourcefile~quadratic_mixing.f90 sourcefile~sddlc.f90 sddlc.f90 sourcefile~models.f90->sourcefile~sddlc.f90 sourcefile~pc_saft.f90->sourcefile~critical.f90 sourcefile~pure_critical_solver.f90 pure_critical_solver.f90 sourcefile~pc_saft.f90->sourcefile~pure_critical_solver.f90 sourcefile~tapenade_ar_api.f90 tapenade_ar_api.f90 sourcefile~pc_saft.f90->sourcefile~tapenade_ar_api.f90 sourcefile~pc_saft.f90->sourcefile~volume.f90 sourcefile~phase_envelopes_pt.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_pt.f90->sourcefile~critical.f90 sourcefile~phase_envelopes_pt.f90->sourcefile~phase_envelopes_pt_mp.f90 sourcefile~phase_envelopes_pt.f90->sourcefile~auxiliar.f90~3 sourcefile~phase_envelopes_px.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_px.f90->sourcefile~auxiliar.f90 sourcefile~phase_envelopes_tx.f90->sourcefile~ar_models.f90 sourcefile~phase_envelopes_tx.f90->sourcefile~auxiliar.f90 sourcefile~pressure_equality.f90->sourcefile~ar_models.f90 sourcefile~pure_critical_solver.f90->sourcefile~ar_models.f90 sourcefile~pure_critical_solver.f90->sourcefile~pure_saturation.f90 sourcefile~pure_saturation.f90->sourcefile~ar_models.f90 sourcefile~saturations_points.f90->sourcefile~ar_models.f90 sourcefile~saturations_points.f90->sourcefile~saturation_point.f90 sourcefile~saturations_points.f90->sourcefile~auxiliar.f90~3 sourcefile~stability.f90->sourcefile~ar_models.f90 sourcefile~tapenade_ar_api.f90->sourcefile~ar_models.f90 sourcefile~volume.f90->sourcefile~ar_models.f90 sourcefile~alphas.f90->sourcefile~generic_cubic.f90 sourcefile~autodiff.f90 autodiff.f90 sourcefile~autodiff.f90->sourcefile~armodel_adiff_api.f90 sourcefile~consistency.f90 consistency.f90 sourcefile~consistency.f90->sourcefile~consistency_armodel.f90 sourcefile~cubic_mixing.f90->sourcefile~generic_cubic.f90 sourcefile~fluids.f90 fluids.f90 sourcefile~fluids.f90->sourcefile~models.f90 sourcefile~huron_vidal.f90->sourcefile~generic_cubic.f90 sourcefile~huron_vidal.f90->sourcefile~quadratic_mixing.f90 sourcefile~huron_vidal.f90->sourcefile~nrtl_hv.f90 sourcefile~implementations.f90~2->sourcefile~generic_cubic.f90 sourcefile~implementations.f90~2->sourcefile~implementations.f90 sourcefile~implementations.f90~2->sourcefile~pure_saturation.f90 sourcefile~implementations.f90~2->sourcefile~alphas.f90 sourcefile~implementations.f90~2->sourcefile~huron_vidal.f90 sourcefile~implementations.f90~2->sourcefile~quadratic_mixing.f90 sourcefile~quadratic_mixing.f90->sourcefile~generic_cubic.f90 sourcefile~yaeos.f90 yaeos.f90 sourcefile~yaeos.f90->sourcefile~equilibria.f90 sourcefile~yaeos.f90->sourcefile~models.f90 sourcefile~yaeos.f90->sourcefile~consistency.f90 sourcefile~nrtl_hv.f90->sourcefile~autodiff.f90 sourcefile~sddlc.f90->sourcefile~quadratic_mixing.f90

Source Code

module yaeos__math
   !! # Mathematical methods for `yaeos`
   !!
   !! # Description
   !! This module provides all the relevant mathematical functions used in this
   !! library. Most important ones are:
   !!
   !! - newton: Newton solving method
   !! - solve_system: Solving linear system Ax = b
   !! - continuation: Continuation method for line tracing
   !!
   !! # Examples
   !!
   !! ## Squared error calculation
   !! ```fortran
   !!  use yaeos__constants, only: pr
   !!  use yaeos__math, only: sq_error
   !!  print *, sq_error(2.5_pr, 3.0_pr)
   !! ```
   !!
   !! ```fortran
   !!  use yaeos__constants, only: pr
   !!  use yaeos__math, only: sq_error
   !!  real(pr) :: x(2) = [2.5_pr, 5.0_pr], y(2) = [3.0_pr, 4.5_pr]
   !!  ! It also works with arrays
   !!  print *, sq_error(x, y)
   !! ```

   use yaeos__math_continuation, only: continuation
   use yaeos__math_linalg, only: solve_system, cubic_roots
   use yaeos__constants, only: pr

   implicit none

   type :: Point
      !! # Point
      !! Represents the single point of a line segment.
      !!
      !! # Description
      !! Representation of a point in the 2D space with its coordinates. It is
      !! used to represent either the intersection of two lines segments or the
      !! self-intersection of a single line. In the first case the `i` and `j`
      !! attributes represent the indices of the line segments that intersected.
      !! In the second case both represent the index of the line segment that
      !! self-intersected.
      !!
      !! # Examples
      !!
      !! ```fortran
      !! ```
      real(pr) :: x !! X coordinate
      real(pr) :: y !! Y coordinate
      integer :: i !! Index of the first line segment
      integer :: j !! Index of the second line segment
   end type Point

   abstract interface
      subroutine f_1d(x, f, df)
         !! Callback interface for a scalar residual and its derivative.
         import pr
         real(pr), intent(in) :: x !! Current scalar iterate.
         real(pr), intent(out) :: f !! Residual value \(f(x)\).
         real(pr), intent(out) :: df !! Derivative \(df/dx\).
      end subroutine f_1d
   end interface

   interface newton
      module procedure :: newton_1d
   end interface newton

contains
   elemental real(pr) function sq_error(exp, pred)
      !! # Squared error between two values.
      !!
      !! # Description
      !! Returns the squared relative error \(((exp-pred)/exp)^2\). `exp`
      !! must be nonzero; the result is dimensionless and elementally
      !! applicable to scalar or array values.
      !!
      !! # Examples
      !!
      !! ```fortran
      !!  error = sq_error(true_value, model_value)
      !! ```
      use yaeos__constants, only: pr
      real(pr), intent(in) :: exp !! Reference or expected value; must be nonzero.
      real(pr), intent(in) :: pred !! Predicted value being compared with `exp`.
      sq_error = ((exp - pred)/exp)**2
   end function sq_error

   function central_numdiff(f, x, eps) result(df)
      !! Approximate the Jacobian of a vector function by centered differences.
      !! Column `i` is evaluated using a perturbation \(dx_i=x_i\,eps\); thus
      !! this routine requires nonzero entries in `x` for finite differences.
      interface
         function f(x)
            !! Vector-valued function differentiated by `central_numdiff`.
            import pr
            real(pr), intent(in) :: x(:) !! Function input vector.
            real(pr) :: f(size(x)) !! Function output vector.
         end function f
      end interface
      real(pr), intent(in) :: x(:) !! Evaluation point.
      real(pr), intent(in) :: eps !! Relative finite-difference step multiplier.
      real(pr) :: df(size(x), size(x)) !! Approximate Jacobian matrix.

      integer :: i !! Loop/index variable.
      real(pr) :: f1(size(x))
      real(pr) :: f2(size(x))
      real(pr) :: dx(size(x))

      do i=1,size(x)
         dx = 0
         dx(i) = x(i) * eps
         df(:, i) = (f(x + dx) - f(x - dx))/(2*dx(i))
      end do
   end function central_numdiff

   function dx_to_dn(x, dx) result(dn)
      !! # dx_to_dn
      !!
      !! # Description
      !! Convert the mole fraction derivatives of a quantity (calculated
      !! so they do not sum to 1) to mole number derivatives (where the mole
      !! fractions do sum to one). Requires the derivatives and the mole fractions
      !! of the mixture.
      !! From [Chemicals (Python)](https://chemicals.readthedocs.io/chemicals.utils.html?highlight=dxs_to_dns#chemicals.utils.dxs_to_dns)
      use yaeos__constants, only: pr
      real(pr), intent(in) :: x(:) !! Mole-fraction vector.
      real(pr), intent(in) :: dx(:) !! Derivative of the property with respect to mole fractions.
      real(pr) :: dn(size(x))

      real(pr) :: sum_xdx

      dn = 0

      sum_xdx = sum(x * dx)

      dn = dx - sum_xdx
   end function dx_to_dn

   function derivative_dxk_dni(n) result(dxk_dni)
      !! # derivative_dxk_dni
      !!
      !! # Description
      !! Calculate the mole fraction first derivatives respect to mole numbers
      !!
      real(pr), intent(in) :: n(:) !! Component mole amounts.
      real(pr) :: dxk_dni(size(n), size(n)) !! \(\partial x_k/\partial n_i\), indexed `(k,i)`.

      real(pr) :: n_tot !! Total number of moles.
      integer :: nc !! Number of components.
      integer :: k
      integer :: i !! Loop/index variable.

      n_tot = sum(n)
      nc = size(n)

      dxk_dni = 0.0_pr
      do concurrent(k=1:nc, i=1:nc)
         if (k == i) then
            dxk_dni(k,i) = (n_tot - n(i)) / n_tot**2
         else
            dxk_dni(k,i) = -n(k) / n_tot**2
         end if
      end do
   end function derivative_dxk_dni

   function derivative_d2xk_dnidnj(n) result(d2xk_dnidnj)
      !! # derivative_d2xk_dnidnj
      !!
      !! # Description
      !! Calculate the mole fraction second derivatives respect to mole numbers
      !!
      real(pr), intent(in) :: n(:) !! Component mole amounts.
      real(pr) :: d2xk_dnidnj(size(n), size(n), size(n)) !! \(\partial^2x_k/\partial n_i\partial n_j\), indexed `(k,i,j)`.

      real(pr) :: n_tot !! Total number of moles.
      integer :: nc !! Number of components.
      integer :: k !! Loop index `k`.
      integer :: i !! Loop index `i`.
      integer :: j !! Loop index `j`.

      n_tot = sum(n)
      nc = size(n)

      d2xk_dnidnj = 0.0_pr
      do concurrent (k=1:nc, i=1:nc, j=1:nc)
         if (i==k .and. j==k) then
            d2xk_dnidnj(k,i,j) = -2 * (n_tot - n(i)) / n_tot**3
         else if (i==k) then
            d2xk_dnidnj(k,i,j) = (2 * n(i) - n_tot) / n_tot**3
         else if (j==k) then
            d2xk_dnidnj(k,i,j) = (2 * n(j) - n_tot) / n_tot**3
         else
            d2xk_dnidnj(k,i,j) = 2 * n(k) / n_tot**3
         end if
      end do
   end function derivative_d2xk_dnidnj

   subroutine newton_1d(f, x, tol, max_iters, failed)
      !! # newton_1d
      !!
      !! # Description
      !! Find a root of a scalar function by damped Newton iteration.
      !! Each step is halved until its magnitude is at most half the current
      !! iterate's magnitude. This is a step-size safeguard, not a residual
      !! line search.
      procedure(f_1d) :: f !! Function and derivative callback.
      real(pr), intent(in out) :: x !! Initial guess, replaced by the root estimate.
      real(pr), intent(in) :: tol !! Absolute tolerance for residual and step size.
      integer, intent(in) :: max_iters !! Maximum Newton iterations.
      logical, intent(out) :: failed !! True when the iteration limit is exhausted.

      integer :: i !! Loop/index variable.
      real(pr) :: fval
      real(pr) :: df
      real(pr) :: step


      fval = 10
      step = 10

      do i=1, max_iters
         if (abs(fval) < tol .or. abs(step) < tol)  exit
         call f(x, fval, df)


         step = fval/df
         do while (abs(step) > 0.5 * abs(x))
            step = step/2
         end do

         x = x - step

         failed = i >= max_iters
      end do

   end subroutine newton_1d

   elemental function interpol(x1, x2, y1, y2, x_obj) result(y)
      !! # interpol
      !!
      !! # Description
      !! Linear interpolation.
      !!
      !! Calculates the linear interpolation between two points at a desired
      !! x value with the equation:
      !! \[
      !!    y = \frac{y_2 - y_1}{x_2 - x_1} \cdot (x_{obj})  - x_1 + y_1
      !! \]
      !!
      !! Since this function is defined as `elemental` it will also interpolate
      !! a set of vectors.
      !!
      !! Examples of usage:
      !!
      !! ```fortran
      !! x1 = 2
      !! x2 = 5
      !! y1 = 2
      !! y2 = 9
      !! y = interpol(x1, x2, y1, y2, 2.3)
      !! ```
      !!
      !! ```fortran
      !! x1 = 2
      !! x2 = 5
      !! y1 = [2, 6]
      !! y2 = [9, 15]
      !! y = interpol(x1, x2, y1, y2, 2.3)
      !! ```
      real(pr), intent(in) :: x1 !! First point x value
      real(pr), intent(in) :: x2 !! Second point x value
      real(pr), intent(in) :: y1 !! First point y value
      real(pr), intent(in) :: y2 !! Second point y value
      real(pr), intent(in) :: x_obj !! Desired x value to interpolate
      real(pr) :: y !! y value at `x_obj`
      y = (y2 - y1)/(x2 - x1)*(x_obj - x1) + y1
   end function interpol

   function intersect_one_line(lx, ly) result(intersections)
      !! # intersect_one_line
      !! Find the intersections of a single line with itself.
      !!
      !! # Description
      !! This function finds the self-intersections in a line. This is
      !! determined by checking all possible pairs of lines segments.
      !! The iteration starts from the first segment of the line and compares
      !! it with all subsequent segments to find intersections. Then it goes
      !! to the next segment and repeats the process. The intersections are
      !! stored in an array of `point` type, which contains the coordinates
      !! of the intersection points.
      !!
      !! # Examples
      !!
      !! ```fortran
      !! ```
      !!
      !! # References
      !!
      real(pr), intent(in) :: lx(:) !! X coordinates of the polyline vertices.
      real(pr), intent(in) :: ly(:) !! Y coordinates of the polyline vertices.
      type(point), allocatable :: intersections(:) !! Detected non-adjacent segment intersections.

      real(pr) :: s
      real(pr) :: t
      integer :: i !! Loop index `i`.
      integer :: j !! Loop index `j`.

      real(pr) :: x
      real(pr) :: y
      real(pr) :: xold
      real(pr) :: yold

      xold = 9999
      yold = 9999

      allocate (intersections(0))
      line1: do i = 2, size(lx) - 1
         line2: do j = i + 2, size(lx)
            associate ( &
               x1 => lx(i - 1), x2 => lx(i), &
               x3 => lx(j), x4 => lx(j - 1), &
               y1 => ly(i - 1), y2 => ly(i), &
               y3 => ly(j), y4 => ly(j - 1))

               call intersects(x1, x2, x3, x4, y1, y2, y3, y4, s, t)
               if (0 <= s .and. s <= 1 .and. 0 <= t .and. t <= 1) then
                  x = s*(x2 - x1) + x1
                  y = s*(y2 - y1) + y1
                  if (abs(x - xold) > 1 .or. abs(y - yold) > 1) then
                     xold = x
                     yold = y
                     ! Use earliest point for the "other" line
                     intersections = [intersections, point(x, y, i, j - 1)]
                  end if
               end if
            end associate
         end do line2
      end do line1
      if (size(intersections) > 3) then
         deallocate(intersections)
         allocate(intersections(0))
      end if
   end function intersect_one_line

   subroutine intersects(x1, x2, x3, x4, y1, y2, y3, y4, s, t)
      !! # intersects
      !! Calculate the intersection between two line segments.
      !!
      !! # Description
      !! This subroutine calculates the intersection point of two line segments
      !! defined by their endpoints (x1, y1) to (x2, y2) and (x3, y3) to (x4, y4).
      !! If the segments intersect, the parameters s and t will contain the
      !! normalized distances along each segment to the intersection point.
      !! The intersection point can be calculated as:
      !! \[
      !!    x = s \cdot (x2 - x1) + x1
      !!    y = s \cdot (y2 - y1) + y1
      !! \]
      !! If the segments do not intersect, s and t will be outside
      !! the range [0, 1].
      !!
      !! # Examples
      !!
      !! ```fortran
      !! ```
      !!
      !! # References
      !!
      real(pr), intent(in) :: x1 !! X coordinate of the first endpoint of segment 1.
      real(pr), intent(in) :: x2 !! X coordinate of the second endpoint of segment 1.
      real(pr), intent(in) :: x3 !! X coordinate of the first endpoint of segment 2.
      real(pr), intent(in) :: x4 !! X coordinate of the second endpoint of segment 2.
      real(pr), intent(in) :: y1 !! Y coordinate of the first endpoint of segment 1.
      real(pr), intent(in) :: y2 !! Y coordinate of the second endpoint of segment 1.
      real(pr), intent(in) :: y3 !! Y coordinate of the first endpoint of segment 2.
      real(pr), intent(in) :: y4 !! Y coordinate of the second endpoint of segment 2.
      real(pr), intent(out) :: s !! Normalized position along segment 1; `s` and `t` both in [0,1] iff the segments intersect.
      real(pr), intent(out) :: t !! Normalized position along segment 2.

      real(pr) :: A(2, 2)
      real(pr) :: b(2)
      real(pr) :: tmp !! Temporary intermediate value.

      A(1, :) = [x2 - x1, x3 - x4]
      A(2, :) = [y2 - y1, y3 - y4]
      b = [x3 - x1, y3 - y1]

      b = solve_system(a, b)
      s = b(1)
      t = b(2)
   end subroutine intersects

   subroutine levenberg_marquardt(&
      fun, tol, X, F, info &
      )
      !! Solve a nonlinear least-squares system with MINPACK's `lmdif1`.
      !! The routine updates `X` and returns residuals and MINPACK status.
      use minpack_module, only: lmdif1, lmdif
      use yaeos__auxiliar, only: optval
      use yaeos__math_linalg, only: solve_system

      interface
         subroutine fun(m, n, x, fvec, iflag)
            !! # fun
            !!
            !! # Description
            !! MINPACK residual callback for rectangular least-squares systems.
            import pr
            integer, intent(in) :: m !! Number of residual equations.
            integer, intent(in) :: n !! Number of unknowns.
            real(pr), intent(in) :: x(n) !! Current unknown vector.
            real(pr), intent(out) :: fvec(m) !! Residual vector.
            integer, intent(in out) :: iflag !! MINPACK callback control/status flag.
         end subroutine fun
      end interface

      real(pr), intent(in) :: tol !! Convergence tolerance passed to MINPACK.
      real(pr), intent(in out) :: X(:) !! Variables vector
      real(pr), intent(out) :: F(:) !! Function values at solved point
      integer, intent(in out) :: info !! MINPACK termination code.

      integer :: m
      integer :: n
      integer :: iwa(size(x))
      integer :: lwa
      real(pr) :: wa(size(F) * size(x) + 5*size(x) + size(f))

      m = size(F)
      n = size(X)
      lwa = size(F) * size(X) + 5 * size(X) + size(F) + 10
      call lmdif1(fun, m, n, X, F, tol, Info, Iwa, Wa, Lwa)
      ! call lmdif(fun, m, n, x, F, tol, tol, Gtol, 1000, Epsfcn=1e-5_pr, Diag, Mode, Factor, Nprint, Info, Nfev, Fjac, Ldfjac, Ipvt, Qtf, Wa1, Wa2, Wa3, Wa4)

   end subroutine levenberg_marquardt

   subroutine powel_hybrid(&
      fun, tol, X, F, info &
      )
      !! # powel_hybrid
      !!
      !! # Description
      !! Solve a square nonlinear system with MINPACK's Powell hybrid method.
      use minpack_module, only: hybrd1
      use yaeos__auxiliar, only: optval
      use yaeos__math_linalg, only: solve_system

      interface
         subroutine fun(n, x, fvec, iflag)
            !! # fun
            !!
            !! # Description
            !! MINPACK residual callback for a square nonlinear system.
            import pr
            integer, intent(in) :: n !! Number of unknowns and residuals.
            real(pr), intent(in) :: x(n) !! Current unknown vector.
            real(pr), intent(out) :: fvec(n) !! Residual vector.
            integer, intent(in out) :: iflag !! MINPACK callback control/status flag.
         end subroutine fun
      end interface

      real(pr), intent(in) :: tol !! Convergence tolerance passed to MINPACK.
      real(pr), intent(in out) :: X(:) !! Variables vector
      real(pr), intent(out) :: F(:) !! Function values at solved point
      integer, intent(out) :: info !! MINPACK termination code.

      integer :: m
      integer :: n
      integer :: iwa(size(x))
      integer :: lwa
      real(pr) :: wa((size(X)*(3*size(X)+13))/2 + 5)

      m = size(F)
      n = size(X)
      lwa = (n*(3*n+13))/2 + 5
      call hybrd1(fun, n, x, F, tol, info, Wa, Lwa)
   end subroutine powel_hybrid

end module yaeos__math