saturation_point.f90 Source File


This file depends on

sourcefile~~saturation_point.f90~~EfferentGraph sourcefile~saturation_point.f90 saturation_point.f90 sourcefile~ar_models.f90 ar_models.f90 sourcefile~saturation_point.f90->sourcefile~ar_models.f90 sourcefile~constants.f90 constants.f90 sourcefile~saturation_point.f90->sourcefile~constants.f90 sourcefile~linalg.f90 linalg.f90 sourcefile~saturation_point.f90->sourcefile~linalg.f90 sourcefile~math.f90 math.f90 sourcefile~saturation_point.f90->sourcefile~math.f90 sourcefile~nonlineal.f90 nonlineal.f90 sourcefile~saturation_point.f90->sourcefile~nonlineal.f90 sourcefile~ar_models.f90->sourcefile~constants.f90 sourcefile~ar_models.f90->sourcefile~math.f90 sourcefile~base.f90 base.f90 sourcefile~ar_models.f90->sourcefile~base.f90 sourcefile~linalg.f90->sourcefile~constants.f90 sourcefile~auxiliar.f90~2 auxiliar.f90 sourcefile~linalg.f90->sourcefile~auxiliar.f90~2 sourcefile~math.f90->sourcefile~constants.f90 sourcefile~math.f90->sourcefile~linalg.f90 sourcefile~math.f90->sourcefile~auxiliar.f90~2 sourcefile~continuation.f90 continuation.f90 sourcefile~math.f90->sourcefile~continuation.f90 sourcefile~nonlineal.f90->sourcefile~constants.f90 sourcefile~nonlineal.f90->sourcefile~linalg.f90 sourcefile~nonlineal.f90->sourcefile~math.f90 sourcefile~auxiliar.f90~2->sourcefile~constants.f90 sourcefile~substance.f90 substance.f90 sourcefile~base.f90->sourcefile~substance.f90 sourcefile~continuation.f90->sourcefile~constants.f90 sourcefile~continuation.f90->sourcefile~linalg.f90 sourcefile~continuation.f90->sourcefile~auxiliar.f90~2 sourcefile~substance.f90->sourcefile~constants.f90

Files dependent on this one

sourcefile~~saturation_point.f90~~AfferentGraph sourcefile~saturation_point.f90 saturation_point.f90 sourcefile~saturations_points.f90 saturations_points.f90 sourcefile~saturations_points.f90->sourcefile~saturation_point.f90 sourcefile~equilibria.f90 equilibria.f90 sourcefile~equilibria.f90->sourcefile~saturations_points.f90 sourcefile~yaeos.f90 yaeos.f90 sourcefile~yaeos.f90->sourcefile~equilibria.f90

Source Code

module nonlinear_solvers
   !! # Damped Newton solver
   !! Solve small nonlinear systems using Newton steps and Armijo backtracking.
   !!
   !! # Description
   !! `newton_solve` accepts a callback returning residuals and a dense Jacobian,
   !! updates the initial guess in place, and reports a convergence code. It is
   !! imported by `solve_TP` in this source file, although that routine
   !! currently calls `newton` from `yaeos__math_nonlinearsolvers` instead.
   !!
   !! # Examples
   !! ```fortran
   !! call newton_solve(fun, x, tol, max_iter, its, info)
   !! ```
   use yaeos__constants, only: dp => pr
   use yaeos__math_linalg, only: solve_system
   implicit none
contains

   !============================================================
   !  Damped Newton solver with Armijo backtracking
   !  Single callback: fun(x, f, J)
   !============================================================
   subroutine newton_solve(fun, x, tol, max_iter, its, info)
      !! # newton_solve
      !! Solve a nonlinear system by damped Newton iteration.
      !!
      !! # Description
      !! Forms the Newton direction from \(J\,dx=-F\), then applies
      !! backtracking to reduce the squared-residual merit function. `info=0`
      !! indicates residual convergence (max-norm below `tol`); `info=1`
      !! indicates the iteration limit.
      !!
      !! # Examples
      !! See the module-level callback example.
      implicit none

      ! ------ Interface to user-supplied function ------
      interface
         subroutine fun(x, f, J)
            import dp
            real(dp), intent(in)  :: x(:) !! Current unknown vector.
            real(dp), intent(out) :: f(:) !! Residual vector.
            real(dp), intent(out) :: J(:,:) !! Residual Jacobian.
         end subroutine fun
      end interface

      ! ------ Arguments ------
      real(dp), intent(inout) :: x(:) !! Initial guess; last iterate on return.
      real(dp), intent(in)    :: tol !! Absolute residual convergence tolerance.
      integer, intent(in)     :: max_iter !! Maximum Newton iterations.
      integer, intent(out)    :: its !! Iteration count at termination.
      integer, intent(out)    :: info !! 0 = converged (max-norm of residuals below `tol`), 1 = iteration limit reached

      ! ------ Local variables ------
      integer :: n !! Number of unknowns
      integer :: k !! Loop/index or term index.
      real(dp) :: f_norm
      real(dp) :: phi_x
      real(dp) :: phi_trial
      real(dp) :: grad_phi_p
      real(dp) :: alpha !! Backtracking step length
      real(dp) :: f(size(X)) !! Residual or scalar equation value.
      real(dp) :: J(size(X),size(X)) !! Jacobian matrix
      real(dp) :: dx(size(X))
      real(dp) :: xtrial(size(X))
      real(dp) :: ftrial(size(X))
      real(dp) :: Jp(size(X))

      n = size(x)

      ! Assume failure until success
      info = 1

      ! ---------- Main Newton iteration ----------
      do its = 1, max_iter

         ! Evaluate f and J at current point
         call fun(x, f, J)
         f_norm = maxval(abs(f))

         if (f_norm < tol) then
            info = 0
            return
         end if

         ! Solve: J dx = -f   (replace with your solver)
         dx = solve_system(J, -f)

         ! Merit function φ = 1/2 ||f||^2
         phi_x = 0.5_dp * dot_product(f, f)

         ! Directional derivative φ' = fᵀ (J dx)
         Jp = matmul(J, dx)
         grad_phi_p = dot_product(f, Jp)

         ! If not descent, flip direction
         if (grad_phi_p > 0._dp) then
            dx = -dx
            Jp = -Jp
            grad_phi_p = -grad_phi_p
         end if

         ! ------------ Armijo backtracking ------------
         alpha = 1.0_dp

         do
            xtrial = x + alpha * dx
            call fun(xtrial, ftrial, J) ! J not needed but required by interface

            phi_trial = 0.5_dp * dot_product(ftrial, ftrial)

            if (phi_trial <= phi_x + 1e-4_dp * alpha * grad_phi_p) exit

            alpha = alpha * 0.5_dp
            if (alpha < 1e-8_dp) exit
         end do

         ! Update
         x = x + alpha * dx
      end do
   end subroutine newton_solve
end module nonlinear_solvers

module yaeos__m_s_sp
   !! # Saturation-point nonlinear systems
   !! Residual equations, Jacobians, and point solvers for bubble, dew, and liquid-liquid states.
   !!
   !! # Description
   !! The routines in this module encode saturation unknowns in logarithmic
   !! coordinates and enforce isofugacity, material-balance, and specification
   !! equations. They are implementation-level solvers used by the public
   !! `saturation_pressure` and `saturation_temperature` routines.
   !!
   !! # Examples
   !! Application code should call the public saturation-point functions rather
   !! than these solver helpers.
   use yaeos__constants, only: pr
   use yaeos__models_ar, only: ArModel, size
   implicit none

contains

   subroutine saturation_F(model, z, X, ns, S, F, dF, dPdVz, dPdVy)
      !! # saturation_F
      !! Evaluate the saturation residual system in log-volume coordinates.
      !!
      !! # Description
      !! With \(X = [\ln K_i, \ln V_z, \ln V_y, \ln T, \ln P]\) and
      !! \(y = K z\), the residuals are
      !! \(\ln f_i(y, V_y, T) - \ln f_i(z, V_z, T)\) (isofugacity),
      !! \(\sum_i (y_i - z_i)\), \(P_y - P_z\), \(\ln P - \ln P_y\), and
      !! \(X_{ns} - S\). The Jacobian is returned when `dF` is present.
      class(ArModel), intent(in) :: model !! EOS used to evaluate phase fugacities.
      real(pr), intent(in) :: X(:) !! Unknowns \([\ln K_i, \ln V_z, \ln V_y, \ln T, \ln P]\)
      integer, intent(in) :: ns !! Index of the specified unknown.
      real(pr), intent(in) :: S !! Value imposed on unknown `ns`.
      real(pr), intent(out) :: F(:) !! Saturation residual vector.
      real(pr), optional, intent(out) :: dF(:, :) !! Residual Jacobian.
      real(pr), intent(out) :: dPdVz !! Pressure derivative with respect to the feed-phase volume.
      real(pr), intent(out) :: dPdVy !! Pressure derivative with respect to the incipient-phase volume.

      ! Variables
      real(pr) :: T
      real(pr) :: Vz
      real(pr) :: Vy
      real(pr) :: z(size(model)) !! Feed composition

      ! Main phase variables
      real(pr) :: lnfug_z(size(model)) !! Logarithmic thermodynamic quantity or intermediate.
      real(pr) :: dlnfug_dn_z(size(model), size(model))
      real(pr) :: dlnfug_dT_z(size(model))
      real(pr) :: dlnfug_dV_z(size(model))
      real(pr) :: dlnfug_dP_z(size(model))
      real(pr) :: Pz
      real(pr) :: dPdTz
      real(pr) :: dPdn_z(size(z))

      ! incipient phase variables
      real(pr) :: y(size(z)) !! Incipient/second phase composition.
      real(pr) :: lnfug_y(size(model)) !! Logarithmic thermodynamic quantity or intermediate.
      real(pr) :: dlnfug_dn_y(size(model), size(model))
      real(pr) :: dlnfug_dT_y(size(model))
      real(pr) :: dlnfug_dV_y(size(model))
      real(pr) :: dlnfug_dP_y(size(model))
      real(pr) :: Py
      real(pr) :: dPdTy
      real(pr) :: dPdn_y(size(z))

      real(pr) :: lnPspec !! Logarithmic thermodynamic quantity or intermediate.

      integer :: j !! Loop/index variable.
      integer :: nc !! Number of components.

      nc = size(z)

      y  = z * exp(X(:nc))
      Vz = exp(X(nc+1))
      Vy = exp(X(nc+2))
      T  = exp(X(nc+3))
      lnPspec = X(nc+4)

      if (present(df)) then
         call model%lnfug_vt(&
            n=z, V=Vz, T=T, P=Pz, dPdT=dPdTz, dPdV=dPdVz, dPdn=dPdn_z, &
            lnf=lnfug_z, &
            dlnfdV=dlnfug_dV_z, dlnfdT=dlnfug_dT_z, dlnfdn=dlnfug_dn_z &
            )

         call model%lnfug_vt(&
            n=y, V=Vy, T=T, P=Py, dPdT=dPdTy, dPdV=dPdVy, dPdn=dPdn_y, &
            lnf=lnfug_y, &
            dlnfdV=dlnfug_dV_y, dlnfdT=dlnfug_dT_y, dlnfdn=dlnfug_dn_y &
            )
      else
         call model%lnfug_vt(n=z, V=Vz, T=T, P=Pz, lnf=lnfug_z)
         call model%lnfug_vt(n=y, V=Vy, T=T, P=Py, lnf=lnfug_y)
      end if

      F = 0

      F(:nc) = lnfug_y - lnfug_z
      F(nc + 1) = sum(y - z)
      F(nc + 2) = Py - Pz
      F(nc + 3) = lnPspec - log(Py)
      F(nc + 4) = X(ns) - S

      if (present(dF)) then
         dF = 0

         ! isofugacity
         do j=1,nc
            df(:nc, j) = y(j) * dlnfug_dn_y(:, j)
         end do

         dF(:nc, nc+1) = -dlnfug_dV_z * Vz
         dF(:nc, nc+2) =  dlnfug_dV_y * Vy
         dF(:nc, nc+3) =  T * (dlnfug_dT_y - dlnfug_dT_z)

         ! mass balance
         df(nc+1, :nc) = y

         ! pressure equality
         df(nc+2, :nc)  = y * dPdn_y
         df(nc+2, nc+1) = -dPdVz * Vz
         df(nc+2, nc+2) = dPdVy * Vy
         df(nc+2, nc+3) = T*(dPdTy - dPdTz)

         df(nc+3, :nc) = -y * dPdn_y/Py
         df(nc+3, nc+1) = 0
         df(nc+3, nc+2) = -dPdVy * Vy / Py
         df(nc+3, nc+3) = -dPdTy * T / Py
         df(nc+3, nc+4) = 1

         df(nc+4, ns) = 1
      end if
   end subroutine saturation_F

   subroutine saturation_TP(model, kind, z, X, ns, S, F, dF, dFdS)
      !! # saturation_TP
      !! Evaluate a saturation residual system at fixed pressure or temperature.
      !!
      !! # Description
      !! Reconstructs phase compositions from logarithmic K-factors, evaluates
      !! fugacity coefficients with root selections determined by `kind`, and
      !! returns isofugacity, material-balance, and specification residuals:
      !! \(\ln K_i + \ln\phi_i(y) - \ln\phi_i(z)\), \(\sum_i (y_i - z_i)\),
      !! and \(X_{ns} - S\).
      class(ArModel), intent(in) :: model !! EOS used for phase properties.
      character(len=*), intent(in) :: kind !! `"bubble"`, `"dew"`, or `"liquid-liquid"`; any other value uses stable roots.
      real(pr), intent(in) :: z(size(model)) !! Feed composition.

      real(pr), intent(in) :: X(:) !! Unknowns \([\ln K_i, \ln T, \ln P]\)
      integer, intent(in) :: ns !! Index of the specified unknown.
      real(pr), intent(in) :: S !! Value imposed on unknown `ns`.

      real(pr), intent(out) :: F(:) !! Residual vector.
      real(pr), intent(out) :: dF(:, :) !! Jacobian with respect to the unknown vector.
      real(pr), intent(out) :: dFdS(:) !! Residual derivative with respect to the specification.

      character(len=14) :: kind_z
      character(len=14) :: kind_y

      real(pr) :: y(size(X)-2) !! Incipient/second phase composition.
      real(pr) :: Vz
      real(pr) :: Vy
      real(pr) :: lnPhi_z(size(X)-2) !! Logarithmic thermodynamic quantity or intermediate.
      real(pr) :: lnPhi_y(size(X)-2) !! Logarithmic thermodynamic quantity or intermediate.
      real(pr) :: dlnphi_dt_z(size(X)-2)
      real(pr) :: dlnphi_dt_y(size(X)-2)
      real(pr) :: dlnphi_dp_z(size(X)-2)
      real(pr) :: dlnphi_dp_y(size(X)-2)
      real(pr) :: dlnphi_dn_z(size(X)-2, size(X)-2)
      real(pr) :: dlnphi_dn_y(size(X)-2, size(X)-2)

      real(pr) :: T
      real(pr) :: P
      real(pr) :: K(size(X)-2) !! Equilibrium K-factors

      integer :: i !! Loop index `i`.
      integer :: j !! Loop index `j`.
      integer :: nc !! Number of components.

      nc = size(X)-2

      F = 0
      dF = 0

      K = exp(X(:nc))
      T = exp(X(nc+1))
      P = exp(X(nc+2))

      y = K*z

      select case(kind)
       case ("bubble")
         kind_z = "liquid"
         kind_y = "vapor"
       case ("dew")
         kind_z = "vapor"
         kind_y = "liquid"
       case ("liquid-liquid")
         kind_z = "liquid"
         kind_y = "liquid"
       case default
         kind_z = "stable"
         kind_y = "stable"
      end select

      call model%lnphi_pt(&
         z, P, T, V=Vz, root_type=kind_z, &
         lnPhi=lnphi_z, dlnPhidt=dlnphi_dt_z, &
         dlnPhidp=dlnphi_dp_z, dlnphidn=dlnphi_dn_z &
         )
      call model%lnphi_pt(&
         y, P, T, V=Vy, root_type=kind_y, &
         lnPhi=lnphi_y, dlnPhidt=dlnphi_dt_y, &
         dlnPhidp=dlnphi_dp_y, dlnphidn=dlnphi_dn_y &
         )

      F(:nc) = X(:nc) + lnPhi_y - lnPhi_z
      F(nc + 1) = sum(y - z)
      F(nc + 2) = X(ns) - S

      ! Jacobian Matrix
      do j=1,nc
         df(:nc, j) = dlnphi_dn_y(:, j) * y(j)
         df(j, j) = dF(j, j) + 1
      end do

      df(:nc, nc + 1) = T * (dlnphi_dt_y - dlnphi_dt_z)
      df(:nc, nc + 2) = P * (dlnphi_dp_y - dlnphi_dp_z)

      df(nc + 1, :nc) = y

      df(nc + 2, :) = 0
      df(nc + 2, ns) = 1

      dFdS = 0
      dFdS(nc+2) = -1
   end subroutine saturation_TP

   subroutine solve_TP(model, kind, z, X, ns, S, tol, max_iterations, its)
      !! # solve_TP
      !! Correct a fixed-pressure or fixed-temperature saturation point.
      !!
      !! # Description
      !! Applies `newton` from `yaeos__math_nonlinearsolvers` to the residual
      !! system assembled by `saturation_TP` and updates the packed unknown
      !! vector in place.
      use nonlinear_solvers, only: newton_solve
      use yaeos__math, only: solve_system
      use yaeos__math_nonlinearsolvers, only: newton, homotopy
      class(ArModel), intent(in) :: model !! EOS used for phase fugacities.
      character(len=*), intent(in) :: kind !! `"bubble"`, `"dew"`, or `"liquid-liquid"`; any other value uses stable roots.
      real(pr), intent(in) :: z(:) !! Feed composition.
      real(pr), intent(inout) :: X(:) !! Initial packed unknowns; corrected state on return.
      integer, intent(in) :: ns !! Index of the specified variable.
      real(pr), intent(in) :: S !! Specified value of `X(ns)` (log coordinates)
      real(pr), intent(in) :: tol !! Residual tolerance.
      integer, intent(in) :: max_iterations !! Maximum corrector iterations.
      integer, intent(out) :: its !! Iterations used.

      integer :: nc !! Number of components.

      real(pr) :: F(size(X)) !! Residual or scalar equation value.
      real(pr) :: dF(size(X), size(X))
      real(pr) :: dFdS(size(X))
      real(pr) :: dx(size(X))

      real(pr) :: t
      real(pr) :: G(size(X))
      real(pr) :: dG(size(X), size(X))
      real(pr) :: H(size(X))
      real(pr) :: dH(size(X), size(X))
      real(pr) :: X0(size(X))

      real(pr) :: alpha !! Step length (unused)
      real(pr) :: phi_x
      real(pr) :: phi_ax
      real(pr) :: grad_phi_p
      real(pr) :: Jp(size(X))
      real(pr) :: Xnew(size(X))
      integer :: info !! Solver status code.

      nc = size(X) - 2

      ! call homotopy(sub=wrap, x=X, tol=tol, max_its=max_iterations, its=its)
      call newton(sub=wrap, x=X, tol=tol, max_its=max_iterations, its=its)

      ! call newton_solve(fun=wrap, x=X, tol=1e-7_pr, max_iter=20, its=its, info=info)
      call wrap(X, F, dF)
      ! print *, F
      ! print *, its, maxval(abs(F))
   contains
      subroutine wrap(X, F, J)
         real(pr), intent(in) :: X(:) !! Unknowns \([\ln K_i, \ln T, \ln P]\)
         real(pr), intent(out) :: F(:) !! Residual vector
         real(pr), intent(out) :: J(:, :) !! Jacobian matrix
         call saturation_TP(model, kind, z, X, ns, S=S, F=F, dF=J, dFdS=dFdS)
      end subroutine
   end subroutine solve_TP

   subroutine solve_VxVyT(model, z, X, ns, S, tol, max_iterations, its)
      !! # solve_VxVyT
      !! Solve saturation equations using log phase volumes and temperature.
      !!
      !! # Description
      !! Undamped Newton correction of the `saturation_F` system, with unknowns
      !! \([\ln K_i, \ln V_z, \ln V_y, \ln T, \ln P]\). Pressure is an unknown
      !! tied to the incipient-phase pressure, and phase pressure equality is
      !! one of the residuals.
      use yaeos__math, only: solve_system
      class(ArModel), intent(in) :: model !! EOS used for phase properties.
      real(pr), intent(in) :: z(:) !! Feed composition.
      real(pr), intent(inout) :: X(:) !! Initial unknown vector; corrected state on return.
      integer, intent(in) :: ns !! Index of the specified variable.
      real(pr), intent(in) :: S !! Specification value in solver coordinates.
      real(pr), intent(in) :: tol !! Residual tolerance.
      integer, intent(in) :: max_iterations !! Maximum Newton iterations.
      integer, intent(out) :: its !! Iterations used.

      real(pr) :: dPdVz !! Pressure derivative with respect to the feed-phase volume.
      real(pr) :: dPdVy !! Pressure derivative with respect to the incipient-phase volume.

      integer :: nc !! Number of components.
      real(pr) :: F(size(X)) !! Residual or scalar equation value.
      real(pr) :: dF(size(X), size(X))
      real(pr) :: dFdS(size(X))
      real(pr) :: Xold(size(X))
      real(pr) :: dx(size(X))
      real(pr) :: dx_old(size(x))

      nc = size(X) - 4

      its = 0
      do while (its < max_iterations)
         call saturation_F(model, z, X, ns, S, F, dF, dPdVz, dPdVy)
         if (all(abs(F) < tol)) exit

         dX = solve_system(dF, -F)

         X = X + dX

         its = its + 1
      end do
   end subroutine solve_VxVyT
end module yaeos__m_s_sp