Debian Codegraph @

mex/sources/heterogeneity/utils/fischer_burmeister.f08

raw
1 ! Copyright © 2025-2026 Dynare Team
2 !
3 ! This file is part of Dynare.
4 !
5 ! Dynare is free software: you can redistribute it and/or modify it under the terms of the
6 ! GNU General Public License as published by the Free Software Foundation, either version 3 of
7 ! the License, or (at your option) any later version.
8 !
9 ! Dynare is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without
10 ! even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 ! GNU General Public License for more details.
12 !
13 ! You should have received a copy of the GNU General Public License along with Dynare. If not,
14 ! see <https://www.gnu.org/licenses/>.
15 !
16 ! Original author: Normann Rion <[email protected]>
17 !
18 ! Fischer-Burmeister reformulation for complementarity problems
19 !
20 ! For a complementarity problem F(x) = 0 ⟂ lb ≤ x ≤ ub, the FB function transforms
21 ! the problem into an unconstrained system Φ(x) = 0 where:
22 ! - φ(a,b) = a + b - sqrt(a² + b² + ε) satisfies φ(a,b) = 0 ⟺ a ≥ 0, b ≥ 0, ab = 0
23 ! - Lower bound only: Φ = φ(x-lb, F) (standard MCP: F ≥ 0 at lower-bound binding)
24 ! - Upper bound only: Φ = φ(ub-x, -F) (standard MCP: F ≤ 0 at upper-bound binding)
25 ! - Double bounds: Φ = φ(x-lb, φ(ub-x, -F)) (nested formulation from LMMCP)
26
27 module fischer_burmeister
28 use iso_fortran_env, only: real64, int32
29 use calibration_types, only: BOUND_NONE, BOUND_LOWER, BOUND_UPPER, BOUND_BOTH
30 implicit none (type, external)
31
32 private
33 public :: FB_EPS, fb_phi, fb_phi_derivative, fb_transform, fb_transform_jacobian
34
35 ! Regularization parameter to avoid division by zero
36 real(real64), parameter :: FB_EPS = 1.0e-14_real64
37
38 contains
39
40 !---------------------------------------------------------------------------
41 ! Core Fischer-Burmeister function
42 ! φ(a,b) = a + b - sqrt(a² + b² + ε)
43 ! Property: φ(a,b) = 0 ⟺ a ≥ 0, b ≥ 0, ab = 0
44 !---------------------------------------------------------------------------
45 pure elemental function fb_phi(a, b) result(phi)
46 real(real64), intent(in) :: a, b
47 real(real64) :: phi
48 real(real64) :: r
49
50 r = sqrt(a*a + b*b + FB_EPS)
51 phi = a + b - r
52 end function fb_phi
53
54 !---------------------------------------------------------------------------
55 ! Derivatives of the Fischer-Burmeister function
56 ! ∂φ/∂a = 1 - a/r
57 ! ∂φ/∂b = 1 - b/r
58 ! where r = sqrt(a² + b² + ε)
59 !---------------------------------------------------------------------------
60 pure subroutine fb_phi_derivative(a, b, dphi_da, dphi_db)
61 real(real64), intent(in) :: a, b
62 real(real64), intent(out) :: dphi_da, dphi_db
63 real(real64) :: r
64
65 r = sqrt(a*a + b*b + FB_EPS)
66 dphi_da = 1.0_real64 - a / r
67 dphi_db = 1.0_real64 - b / r
68 end subroutine fb_phi_derivative
69
70 !---------------------------------------------------------------------------
71 ! Transform residuals F(x) → Φ(x) using Fischer-Burmeister
72 !
73 ! For each component i:
74 ! BOUND_NONE: Φ_i = -F_i (just negate, no bounds)
75 ! BOUND_LOWER: Φ_i = φ(x_i - lb_i, F_i)
76 ! BOUND_UPPER: Φ_i = φ(ub_i - x_i, -F_i)
77 ! BOUND_BOTH: Φ_i = φ(x_i - lb_i, φ(ub_i - x_i, -F_i)) (nested)
78 !---------------------------------------------------------------------------
79 pure subroutine fb_transform(n, x, fvec, lb, ub, bound_type, phi_vec)
80 integer(int32), intent(in) :: n
81 real(real64), intent(in) :: x(:)
82 real(real64), intent(in) :: fvec(:)
83 real(real64), intent(in) :: lb(:)
84 real(real64), intent(in) :: ub(:)
85 integer(int32), intent(in) :: bound_type(:)
86 real(real64), intent(out) :: phi_vec(:)
87
88 integer(int32) :: i
89 real(real64) :: phi_inner
90
91 do i = 1, n
92 select case (bound_type(i))
93 case (BOUND_NONE)
94 ! Unconstrained: just negate
95 phi_vec(i) = -fvec(i)
96
97 case (BOUND_LOWER)
98 ! Lower bound only: φ(x-lb, F)
99 phi_vec(i) = fb_phi(x(i) - lb(i), fvec(i))
100
101 case (BOUND_UPPER)
102 ! Upper bound only: φ(ub-x, -F)
103 phi_vec(i) = fb_phi(ub(i) - x(i), -fvec(i))
104
105 case (BOUND_BOTH)
106 ! Double bounds (nested): φ(x-lb, φ(ub-x, -F))
107 phi_inner = fb_phi(ub(i) - x(i), -fvec(i))
108 phi_vec(i) = fb_phi(x(i) - lb(i), phi_inner)
109 end select
110 end do
111 end subroutine fb_transform
112
113 !---------------------------------------------------------------------------
114 ! Transform Jacobian using FB chain rule
115 !
116 ! For Φ_i = φ(a_i, b_i), the chain rule gives:
117 ! ∂Φ_i/∂x_j = (∂φ/∂a)·(∂a_i/∂x_j) + (∂φ/∂b)·(∂b_i/∂x_j)
118 !
119 ! For different bound types:
120 ! BOUND_NONE: ∂Φ_i/∂x_j = -∂F_i/∂x_j
121 ! BOUND_LOWER: a=x-lb, b=F → ∂Φ_i/∂x_j = (∂φ/∂a)·δ_ij + (∂φ/∂b)·(∂F_i/∂x_j)
122 ! BOUND_UPPER: a=ub-x, b=-F → ∂Φ_i/∂x_j = (∂φ/∂a)·(-δ_ij) + (∂φ/∂b)·(-∂F_i/∂x_j)
123 ! BOUND_BOTH: nested chain rule (see implementation)
124 !---------------------------------------------------------------------------
125 pure subroutine fb_transform_jacobian(n, x, fvec, fjac, lb, ub, bound_type, phi_jac)
126 integer(int32), intent(in) :: n
127 real(real64), intent(in) :: x(:)
128 real(real64), intent(in) :: fvec(:)
129 real(real64), intent(in) :: fjac(:,:) ! [n × n]
130 real(real64), intent(in) :: lb(:)
131 real(real64), intent(in) :: ub(:)
132 integer(int32), intent(in) :: bound_type(:)
133 real(real64), intent(out) :: phi_jac(:,:) ! [n × n]
134
135 integer(int32) :: i, j
136 real(real64) :: a, b, dphi_da, dphi_db
137 real(real64) :: a_inner, b_inner, dphi_inner_da, dphi_inner_db
138 real(real64) :: phi_inner, dphi_outer_da, dphi_outer_db
139 real(real64) :: dphiinner_dxj
140
141 do i = 1, n
142 select case (bound_type(i))
143 case (BOUND_NONE)
144 ! Unconstrained: ∂Φ_i/∂x_j = -∂F_i/∂x_j
145 do j = 1, n
146 phi_jac(i, j) = -fjac(i, j)
147 end do
148
149 case (BOUND_LOWER)
150 ! Lower bound only: Φ = φ(x-lb, F)
151 a = x(i) - lb(i)
152 b = fvec(i)
153 call fb_phi_derivative(a, b, dphi_da, dphi_db)
154
155 do j = 1, n
156 if (i == j) then
157 ! ∂a/∂x_i = 1, ∂b/∂x_j = ∂F_i/∂x_j
158 phi_jac(i, j) = dphi_da + dphi_db * fjac(i, j)
159 else
160 ! ∂a/∂x_j = 0
161 phi_jac(i, j) = dphi_db * fjac(i, j)
162 end if
163 end do
164
165 case (BOUND_UPPER)
166 ! Upper bound only: Φ = φ(ub-x, -F)
167 a = ub(i) - x(i)
168 b = -fvec(i)
169 call fb_phi_derivative(a, b, dphi_da, dphi_db)
170
171 do j = 1, n
172 if (i == j) then
173 ! ∂a/∂x_i = -1, ∂b/∂x_j = -∂F_i/∂x_j
174 phi_jac(i, j) = dphi_da * (-1.0_real64) + dphi_db * (-fjac(i, j))
175 else
176 ! ∂a/∂x_j = 0
177 phi_jac(i, j) = dphi_db * (-fjac(i, j))
178 end if
179 end do
180
181 case (BOUND_BOTH)
182 ! Double bounds (nested): Φ = φ_outer(x-lb, φ_inner(ub-x, -F))
183 ! Inner: φ_inner = φ(ub-x, -F)
184 a_inner = ub(i) - x(i)
185 b_inner = -fvec(i)
186 phi_inner = fb_phi(a_inner, b_inner)
187 call fb_phi_derivative(a_inner, b_inner, dphi_inner_da, dphi_inner_db)
188
189 ! Outer: Φ = φ(x-lb, φ_inner)
190 a = x(i) - lb(i)
191 b = phi_inner
192 call fb_phi_derivative(a, b, dphi_outer_da, dphi_outer_db)
193
194 do j = 1, n
195 ! ∂φ_inner/∂x_j = (∂φ_inner/∂a_inner)·(∂a_inner/∂x_j) + (∂φ_inner/∂b_inner)·(∂b_inner/∂x_j)
196 ! where ∂a_inner/∂x_j = -δ_ij, ∂b_inner/∂x_j = -∂F_i/∂x_j
197 if (i == j) then
198 dphiinner_dxj = dphi_inner_da * (-1.0_real64) + dphi_inner_db * (-fjac(i, j))
199 else
200 dphiinner_dxj = dphi_inner_db * (-fjac(i, j))
201 end if
202
203 ! ∂Φ/∂x_j = (∂φ_outer/∂a)·(∂a/∂x_j) + (∂φ_outer/∂b)·(∂φ_inner/∂x_j)
204 ! where ∂a/∂x_j = δ_ij
205 if (i == j) then
206 phi_jac(i, j) = dphi_outer_da + dphi_outer_db * dphiinner_dxj
207 else
208 phi_jac(i, j) = dphi_outer_db * dphiinner_dxj
209 end if
210 end do
211 end select
212 end do
213 end subroutine fb_transform_jacobian
214
215 end module fischer_burmeister