Debian Codegraph @

mex/sources/heterogeneity/utils/time_iteration_tensor.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 ! Time iteration for tensor product grids
19
20 module time_iteration_tensor
21 use iso_fortran_env, only: real64, int32
22 use iso_c_binding, only: C_DOUBLE, C_INT, C_INT64_T, c_ptr, c_f_procpointer, c_loc, &
23 c_f_pointer, c_associated, c_funloc
24 use calibration_types
25 use gray_code
26 use matlab_mex
27 use blas, only: matvecmul_add, matmul_add ! BLAS matrix-vector and matrix-matrix multiplication
28 use interpolation
29
30 ! Trust region solver with Fischer-Burmeister bounds
31 use trust_region, only: trust_region_solve
32 use fischer_burmeister, only: fb_transform, fb_transform_jacobian, FB_EPS
33
34 implicit none (type, external)
35
36 private
37 public :: solve_time_iteration_tensor, set_het_input, call_matlab_het_resid_tensor
38
39 contains
40
41 !---------------------------------------------------------------------------
42 ! Time iteration on fixed tensor product grid
43 !---------------------------------------------------------------------------
44 function solve_time_iteration_tensor( &
45 dims, ti_options, ti_verbosity, state_var, &
46 tg_config, &
47 old_pol, old_pol_array, new_pol, weighted_old_pol, &
48 gc_cache_next, gc_cache_om, gc_cache_fi, &
49 gp_ws, mex, &
50 ti_output) result(status)
51
52 ! Input parameters
53 type(model_dimensions), intent(in) :: dims
54 type(time_iteration_options), intent(in) :: ti_options
55 integer(int32), intent(in) :: ti_verbosity
56 integer(int32), intent(in), contiguous :: state_var(:)
57 type(tensor_grid_config), pointer, intent(in) :: tg_config
58
59 ! Policy arrays (inout - modified during iteration)
60 real(real64), intent(inout), contiguous :: old_pol(:,:)
61 real(real64), intent(inout), contiguous :: old_pol_array(:,:,:)
62 real(real64), intent(inout), contiguous :: new_pol(:,:)
63 real(real64), intent(inout), contiguous :: weighted_old_pol(:,:)
64
65 ! Gray code caches (inout - modified for interpolation/forward iteration)
66 type(gray_code_cache), intent(inout) :: gc_cache_next
67 type(gray_code_cache), pointer, intent(inout) :: gc_cache_om
68 type(gray_code_cache), pointer, intent(inout) :: gc_cache_fi
69
70 ! Workspace and MATLAB handles
71 type(grid_point_workspace), intent(inout) :: gp_ws
72 type(matlab_mex_handles), intent(inout) :: mex
73
74 ! Output
75 type(time_iteration_output), target, intent(inout) :: ti_output
76
77 ! Local variables
78 integer(int32) :: status, iter, k, j, i
79 integer(int32) :: n_consecutive_increases
80 real(real64) :: diff_norm, prev_diff_norm
81 real(real64), pointer :: policy(:)
82 character(len=256) :: msg
83
84 status = 0
85
86 if (ti_verbosity == 2) call mexPrintf(' === Time Iteration ==='//NEW_LINE('A'))
87
88 ! Initialize early stopping tracking
89 prev_diff_norm = huge(1.0_real64)
90 n_consecutive_increases = 0
91
92 ! Time iteration loop
93 do iter = 1, ti_options%max_iter
94
95 ! Step 1: Solve household problem at all grid points using trust region solver
96 call solve_household_all_points( &
97 dims, &
98 tg_config%mcp, &
99 tg_config%sm, &
100 tg_config%pol_grids, &
101 tg_config%pol_dims, &
102 tg_config%Mu, &
103 ti_options, &
104 state_var, &
105 old_pol, &
106 old_pol_array, &
107 new_pol, &
108 weighted_old_pol, &
109 gc_cache_next, &
110 gp_ws, &
111 mex, &
112 status)
113
114 if (status /= 0) &
115 call mexErrMsgTxt('Time iteration failed: Household solver did not converge')
116
117 ! Step 2: Check convergence
118 diff_norm = maxval(abs(new_pol - old_pol))
119
120 if (ti_verbosity == 2) then
121 write(msg, '(A,I4,A,ES12.4,A,ES12.4)') ' Iter ', iter, &
122 ': ||Δpolicy|| = ', diff_norm, ', tol = ', ti_options%tol
123 call mexPrintf(trim(msg)//NEW_LINE('A'))
124 end if
125
126 ! Early stopping: track consecutive increases in diff_norm
127 if (diff_norm > prev_diff_norm) then
128 n_consecutive_increases = n_consecutive_increases + 1
129 else
130 n_consecutive_increases = 0
131 end if
132 prev_diff_norm = diff_norm
133
134 ! Check early stopping condition (if enabled)
135 if (ti_options%early_stopping > 0 .and. &
136 n_consecutive_increases >= ti_options%early_stopping) then
137 if (ti_verbosity == 2) then
138 write(msg, '(A,I3,A)') ' Early stopping: ', n_consecutive_increases, &
139 ' consecutive increases in ||Δpolicy||'
140 call mexPrintf(trim(msg)//NEW_LINE('A'))
141 end if
142 ti_output%policies_sp = new_pol
143 ti_output%converged = .false.
144 ti_output%iterations = iter
145 ti_output%residual_norm = diff_norm
146 old_pol = new_pol
147 exit
148 end if
149
150 if (diff_norm < ti_options%tol) then
151 if (ti_verbosity == 2) then
152 write(msg, '(A,I4,A)') ' Converged in ', iter, ' iterations'
153 call mexPrintf(trim(msg)//NEW_LINE('A'))
154 end if
155 ti_output%policies_sp = new_pol
156 ti_output%converged = .true.
157 ti_output%iterations = iter
158 ti_output%residual_norm = diff_norm
159 old_pol = new_pol
160 exit
161 end if
162
163 ! Update for next iteration (with learning rate dampening)
164 old_pol = ti_options%learning_rate * new_pol &
165 + (1.0_real64 - ti_options%learning_rate) * old_pol
166 end do
167
168 if (.not. ti_output%converged) then
169 if (ti_verbosity == 2) &
170 call mexPrintf(' Warning: Time iteration did not converge'//NEW_LINE('A'))
171 ! If we exited the loop without convergence and without early stopping,
172 ! we still need to store the last computed policy (not the dampened one)
173 if (ti_output%iterations == 0) then
174 ! Max iterations reached - store final policy
175 ti_output%policies_sp = new_pol
176 ti_output%iterations = ti_options%max_iter
177 ti_output%residual_norm = diff_norm
178 old_pol = new_pol
179 end if
180 end if
181
182 ! Snap policy values to exact bounds where they are within FB tolerance.
183 ! The Fischer-Burmeister regularization (FB_EPS > 0) prevents the solver
184 ! from placing constrained variables exactly at their bounds.
185 do i = 1, dims%n_orig
186 do concurrent (j = 1:dims%N_sp)
187 select case (tg_config%mcp%bound_type(i))
188 case (BOUND_LOWER, BOUND_BOTH)
189 if (old_pol(i,j) - tg_config%mcp%lower_bounds(i) < sqrt(FB_EPS)) then
190 old_pol(i,j) = tg_config%mcp%lower_bounds(i)
191 end if
192 end select
193 select case (tg_config%mcp%bound_type(i))
194 case (BOUND_UPPER, BOUND_BOTH)
195 if (tg_config%mcp%upper_bounds(i) - old_pol(i,j) < sqrt(FB_EPS)) then
196 old_pol(i,j) = tg_config%mcp%upper_bounds(i)
197 end if
198 end select
199 end do
200 end do
201 ti_output%policies_sp = old_pol
202
203 ! Compute the interpolated values of the policy function on the dense grid
204 call interpolate(gc_cache_om, old_pol)
205 ti_output%policies_om(1:dims%n_het_endo,1:dims%N_om) => gc_cache_om%acc
206
207 ! Compute bracketing indices and weights for each state dimension on the dense grid
208 do k = 1, dims%n_states
209 policy(1:dims%N_om) => ti_output%policies_om(state_var(k),:)
210 call bracket_linear_weight(tg_config%d_grids(k)%nodes, & ! grid
211 tg_config%d_dims(k), & ! n_grid
212 policy, & ! query points
213 dims%N_om, & ! n_query
214 tg_config%pol_ind_om(:, k), & ! indices (out)
215 tg_config%pol_w_om(:, k)) ! weights (out)
216 end do
217
218 ! Update linear indices from multi-dimensional indices in 1,...,N_a
219 call compute_linear_indices(tg_config%pol_ind_om, gc_cache_fi%stride_states, &
220 gc_cache_fi%corner_idx)
221
222 ! Cast the linear indices in 1,...,N_om
223 do j=1, dims%N_a_om
224 do i=1, dims%N_e
225 gc_cache_fi%corner_idx((j-1)*dims%N_e+i) = (gc_cache_fi%corner_idx((j-1)*dims%N_e+i)-1)*dims%N_e+i
226 end do
227 end do
228
229 ! Update coefficient updates (r_up, r_down, is_hard_one, is_hard_zero)
230 call compute_coefficient_updates(tg_config%pol_w_om, &
231 gc_cache_fi%r_up, &
232 gc_cache_fi%r_down, &
233 gc_cache_fi%is_hard_one, &
234 gc_cache_fi%is_hard_zero)
235
236 ! Update initial beta weights (product of all w's at each grid point)
237 gc_cache_fi%beta_0 = product(tg_config%pol_w_om, dim=2, mask=(.not. gc_cache_fi%is_hard_zero))
238
239 end function solve_time_iteration_tensor
240
241 !---------------------------------------------------------------------------
242 ! Set heterogeneous input: construct yh array and expected future policy
243 !
244 ! Prepares grid-point-specific inputs for household solver callback:
245 ! - Builds yh array [yh(-1), yh(0), yh(+1)] from current policy and states
246 ! - Computes E[yh(+1)] via multilinear interpolation over shock realizations
247 ! - Computes dpol_next = ∂E[yh(+1)]/∂state for chain rule in Jacobian
248 !---------------------------------------------------------------------------
249 subroutine set_het_input(policy, j, j_e, dims, mcp, sm, state_var, &
250 pol_grids, pol_dims, weighted_old_pol, &
251 gc_cache_next, gp_ws, input_mex)
252 use interpolation, only: bracket_linear_weight
253
254 ! Grid point identification
255 real(real64), intent(in) :: policy(:) ! Current policy guess [n_orig]
256 integer(int32), intent(in) :: j ! Linear grid point index
257 integer(int32), intent(in) :: j_e ! Shock dimension index
258
259 ! Model structure
260 type(model_dimensions), intent(in) :: dims
261 type(mcp_solver_config), intent(in) :: mcp
262 real(real64), intent(in) :: sm(:,:) ! State matrix [(n_het_exo+n_states) × N_sp]
263 integer(int32), intent(in) :: state_var(:) ! Indices of state vars [n_states]
264
265 ! Grid configuration
266 type(grid), intent(in) :: pol_grids(:) ! 1D state grids [n_states]
267 integer(int32), intent(in) :: pol_dims(:) ! Grid dimensions [n_states]
268
269 ! Policy data
270 real(real64), intent(in) :: weighted_old_pol(:,:) ! Mu-weighted policy [N_sp × n_het_endo]
271
272 ! Gray code cache for next-period interpolation
273 type(gray_code_cache), intent(inout) :: gc_cache_next
274
275 ! Workspace (outputs written here)
276 type(grid_point_workspace), intent(inout) :: gp_ws
277
278 ! MATLAB handles (inout because step_mx may be lazily created)
279 type(matlab_mex_handles), intent(inout) :: input_mex
280
281 ! Local variables
282 integer(int32) :: l, k, t, kf, z, a(1), lv_idx
283 integer(int32), allocatable :: dz(:)
284 real(real64) :: beta
285 real(real64), allocatable :: dbeta(:)
286 real(real64), pointer :: pol_next(:)
287
288 allocate(dbeta(dims%n_states))
289 allocate(dz(dims%n_states))
290
291 ! Build yh array: [yh(-1), yh(0), yh(+1)]
292 gp_ws%yh = 0.0_real64
293 ! Use state_var to place state values in correct positions
294 gp_ws%yh(state_var) = sm(dims%n_het_exo+1:dims%n_het_exo+dims%n_states, j)
295 ! Current policy guess
296 gp_ws%yh(dims%n_het_endo+1:dims%n_het_endo+dims%n_orig) = policy
297 ! Call dynamic_het1_set_auxiliary_variables to compute auxiliary variables
298 ! This sets yh(0) auxiliaries from the originally declared variables
299 ! Currently, the only level that's used is the level 0
300 ! As we don't need the MCP multipliers value, we don't need the level 1
301 if (mcp%set_auxiliary_variables) then
302 lv_idx = 0
303 call call_matlab_set_auxiliary_variables(gp_ws%yh, input_mex, lv_idx)
304 end if
305 if (dims%n_mult > 0) then
306 ! Set MCP multipliers to zero for the FB function to work correctly
307 gp_ws%yh(dims%n_het_endo+mcp%mult_in_het) = 0.0_real64
308 end if
309
310 ! Build xh array: current shocks (from grid point)
311 gp_ws%xh = sm(1:dims%n_het_exo, j)
312
313 ! Interpolate policy at t+1 for all shock realizations
314 ! Extract next-period state values from policy
315 do k = 1, dims%n_states
316 gp_ws%states_next(k) = policy(state_var(k))
317 end do
318
319 ! Find bracketing indices and weights for next-period states
320 do k = 1, dims%n_states
321 call bracket_linear_weight(pol_grids(k)%nodes, &
322 pol_dims(k), &
323 gp_ws%states_next(k:k), 1_int32, &
324 gp_ws%ind_next(1,k:k), gp_ws%w_next(1,k:k))
325 ! Compute inverse grid spacing for derivative
326 if (gp_ws%ind_next(1,k) == pol_dims(k)) then
327 gp_ws%inv_h(k) = 1.0_real64 / (pol_grids(k)%nodes(pol_dims(k)) - pol_grids(k)%nodes(pol_dims(k)-1))
328 else
329 gp_ws%inv_h(k) = 1.0_real64 / (pol_grids(k)%nodes(gp_ws%ind_next(1,k)+1) - pol_grids(k)%nodes(gp_ws%ind_next(1,k)))
330 end if
331 end do
332
333 ! Low-corner linear index in 1,...,N_a (state-space only)
334 call compute_linear_indices(gp_ws%ind_next, gc_cache_next%stride_states, a)
335
336 ! Fetch it into 1, ..., N_sp (including shock dimension)
337 l = (a(1)-1)*dims%N_e+j_e
338
339 ! Coefficient updates and hard dimensions
340 call compute_coefficient_updates(gp_ws%w_next, &
341 gc_cache_next%r_up, &
342 gc_cache_next%r_down, &
343 gc_cache_next%is_hard_one, &
344 gc_cache_next%is_hard_zero)
345
346 ! Low-corner initial weight
347 beta = product(gp_ws%w_next(1,:), mask=(.not. gc_cache_next%is_hard_zero(1,:)))
348 ! dbeta is a n_states vector where the index is the states w.r.t which
349 ! we differentiate the policy function
350 dbeta = -gp_ws%inv_h * beta
351 where (.not. gc_cache_next%is_hard_zero(1,:)) dbeta = dbeta / gp_ws%w_next(1,:)
352
353 ! Initialization at the low corner
354 gc_cache_next%sk = .false.
355 z = count(gc_cache_next%is_hard_zero(1,:))
356 pol_next(1:dims%n_het_endo) => gp_ws%yh(2*dims%n_het_endo+1:3*dims%n_het_endo)
357 pol_next = 0.0_real64
358 if (z==0_int32) pol_next = pol_next + beta * weighted_old_pol(l,:)
359 gp_ws%dpol_next = 0.0_real64
360 do k=1, dims%n_states
361 dz(k) = count(gc_cache_next%is_hard_zero(1,:))
362 if (gc_cache_next%is_hard_zero(1,k)) then
363 dz(k) = dz(k) - 1_int32
364 end if
365 if (dz(k) == 0_int32) then
366 gp_ws%dpol_next(:,k) = gp_ws%dpol_next(:,k) + dbeta(k) * weighted_old_pol(l,:)
367 end if
368 end do
369
370 ! Going through the remaining corners
371 do t = 1, gc_cache_next%Kcorn - 1
372 kf = gc_cache_next%flip_idx(t)
373 ! For the expected derivative, the kf-state coefficient changes sign
374 dbeta(kf) = -dbeta(kf)
375 if (.not. gc_cache_next%sk(kf)) then
376 ! lower -> upper on dimension kf
377 l = l + gc_cache_next%stride_shocks(kf)
378 gc_cache_next%sk(kf) = .true.
379 ! If kf dim is hard one, the number of hard-one dims flipped to
380 ! upper increases.
381 if (gc_cache_next%is_hard_one(1,kf)) then
382 z = z + 1_int32
383 ! For the expected derivative, the number of hard-one dims
384 ! flipped to upper increases only for the dimensions k /= kf
385 do k=1, dims%n_states
386 if (kf /= k) dz(k) = dz(k)+1
387 end do
388 else if (gc_cache_next%is_hard_zero(1,kf)) then
389 ! Similar case for hard-zero dims.
390 z = z-1_int32
391 do k=1, dims%n_states
392 if (kf /= k) dz(k) = dz(k)-1_int32
393 end do
394 else
395 ! Otherwise the kf dim is soft and we update the beta
396 ! coefficient
397 beta = beta * gc_cache_next%r_up(1,kf)
398 ! For the expected derivative, we update the coefficient for
399 ! dimensions k /= kf
400 do k = 1, dims%n_states
401 if (kf /= k) dbeta(k) = dbeta(k) * gc_cache_next%r_up(1,kf)
402 end do
403 end if
404 else
405 ! upper -> lower on dim kf
406 l = l - gc_cache_next%stride_shocks(kf)
407 gc_cache_next%sk(kf) = .false.
408 ! If kf dim is hard-one, the number of hard dims flipped
409 ! to upper decreases.
410 if (gc_cache_next%is_hard_one(1,kf)) then
411 z = z - 1_int32
412 ! For the expected derivative, the number of hard-one dims
413 ! flipped to upper decreases only for the dimensions k /= kf
414 do k=1, dims%n_states
415 if (kf /= k) dz(k) = dz(k)-1_int32
416 end do
417 else if (gc_cache_next%is_hard_zero(1,kf)) then
418 z = z + 1_int32
419 ! For the expected derivative, the number of hard-zero dims
420 ! flipped to lower increases only for the dimensions k /= kf
421 do k=1, dims%n_states
422 if (kf /= k) dz(k) = dz(k)+1_int32
423 end do
424 else
425 ! Otherwise the kf dim is soft and we update the beta
426 ! coefficient
427 beta = beta * gc_cache_next%r_down(1,kf)
428 ! For the expected derivative, we update the coefficient for
429 ! dimensions k /= kf
430 do k = 1, dims%n_states
431 if (kf /= k) dbeta(k) = dbeta(k) * gc_cache_next%r_down(1,kf)
432 end do
433 end if
434 end if
435 ! If the number of hard dims flipped to upper is zero, there is
436 ! a contribution
437 if (z == 0_int32) pol_next = pol_next + beta * weighted_old_pol(l,:)
438 do k=1, dims%n_states
439 if (dz(k) == 0_int32) gp_ws%dpol_next(:,k) = gp_ws%dpol_next(:,k) + dbeta(k)*weighted_old_pol(l,:)
440 end do
441 end do
442
443 end subroutine set_het_input
444
445 !---------------------------------------------------------------------------
446 ! Solve household problem at all grid points using Trust Region + Fischer-Burmeister
447 !
448 ! This solver properly handles bound constraints by:
449 ! 1. Eliminating multiplier variables (setting them to 0)
450 ! 2. Skipping slackness equations
451 ! 3. Applying Fischer-Burmeister transformation to handle bounds
452 ! 4. Solving the reduced system with trust_region_solve
453 !---------------------------------------------------------------------------
454 subroutine solve_household_all_points( &
455 dims, & ! Model dimensions (value type)
456 mcp, & ! MCP solver config (bounds, reordering)
457 sm, & ! State matrix [(n_het_exo+n_states) × N_sp]
458 pol_grids, & ! 1D state grids [n_states]
459 pol_dims, & ! Grid dimensions [n_states]
460 Mu, & ! Transition matrix [N_e × N_e]
461 ti_options, & ! Trust region solver options
462 state_var, & ! State variable indices [n_states]
463 old_pol, & ! Previous policy [n_het_endo × N_sp] (read)
464 old_pol_array, & ! Previous policy [N_e × N_a × n_het_endo] (read)
465 new_pol, & ! Updated policy [n_het_endo × N_sp] (write)
466 weighted_old_pol, & ! Mu-weighted policy [N_sp × n_het_endo] (write)
467 gc_cache_next, & ! Gray code cache for interpolation
468 gp_ws, & ! Grid point workspace
469 mex, & ! MATLAB MEX handles
470 status)
471
472 ! Model dimensions
473 type(model_dimensions), intent(in) :: dims
474
475 ! MCP solver configuration (bounds, equation reordering)
476 type(mcp_solver_config), intent(in) :: mcp
477
478 ! State matrix [(n_het_exo+n_states) × N_sp]
479 real(real64), intent(in), contiguous :: sm(:,:)
480
481 ! Grid configuration
482 type(grid), intent(in) :: pol_grids(:) ! 1D state grids [n_states]
483 integer(int32), intent(in), contiguous :: pol_dims(:) ! Grid dimensions [n_states]
484
485 ! Transition matrix [N_e × N_e]
486 real(real64), intent(in), contiguous :: Mu(:,:)
487
488 ! Trust region solver options
489 type(time_iteration_options), intent(in) :: ti_options
490
491 ! State variable indices [n_states]
492 integer(int32), intent(in), contiguous :: state_var(:)
493
494 ! Policy arrays
495 real(real64), intent(in), contiguous, target :: old_pol(:,:) ! [n_het_endo × N_sp]
496 real(real64), intent(inout), contiguous, target :: old_pol_array(:,:,:) ! [n_het_endo × N_e × N_a]
497 real(real64), intent(inout), contiguous :: new_pol(:,:) ! [n_het_endo × N_sp]
498 real(real64), intent(inout), contiguous, target :: weighted_old_pol(:,:) ! [N_sp × n_het_endo]
499
500 ! Gray code cache for next-period interpolation
501 type(gray_code_cache), intent(inout) :: gc_cache_next
502
503 ! Grid point workspace
504 type(grid_point_workspace), intent(inout) :: gp_ws
505
506 ! MATLAB MEX handles
507 type(matlab_mex_handles), intent(inout) :: mex
508
509 ! Output status
510 integer(int32), intent(out) :: status
511
512 ! Local variables
513 integer(int32) :: j_a, j_e, j, i, info
514 character(len=256) :: msg
515 real(real64), pointer, contiguous :: old_pol_3d_ptr(:,:,:), weighted_old_pol_mat_ptr(:,:), old_pol_mat_ptr(:,:)
516
517 ! Initialize status
518 status = 0
519
520 ! Weight the previous-iteration policy function with the Mu matrix
521 ! (Useful to compute expectations)
522 old_pol_3d_ptr(1:dims%n_het_endo,1:dims%N_e,1:dims%N_a_sp) => old_pol
523 old_pol_array = reshape(old_pol_3d_ptr, [dims%N_e, dims%N_a_sp, dims%n_het_endo], order=[3, 1, 2])
524 old_pol_mat_ptr(1:dims%N_e,1:(dims%N_a_sp*dims%n_het_endo)) => old_pol_array
525 weighted_old_pol_mat_ptr(1:dims%N_e,1:(dims%N_a_sp*dims%n_het_endo))=>weighted_old_pol
526 call matmul_add("N", "N", 1.0_real64, Mu, old_pol_mat_ptr, 0.0_real64, weighted_old_pol_mat_ptr)
527
528 ! Loop over all grid points
529 do j_a = 1, dims%N_a_sp
530 do j_e = 1, dims%N_e
531 j = dims%N_e*(j_a-1)+j_e
532
533 ! Extract originally declared variables
534 gp_ws%x_orig = old_pol(1:dims%n_orig, j)
535
536
537 ! Solve using trust_region with FB transformation
538 call trust_region_solve(gp_ws%x_orig, fb_callback, info, &
539 tolx=ti_options%solver_tolx, &
540 tolf=ti_options%solver_tolf, &
541 maxiter=ti_options%solver_max_iter, &
542 factor=ti_options%solver_factor)
543
544
545 ! Check for errors (info=1 is success, info=-1 means initial
546 ! guess is already solution). Otherwise, continue with current
547 ! solution (x_orig was updated by trust_region_solve)
548 if (info /= 1 .and. info /= -1) then
549 ! If stop_on_error is true, print diagnostics and fail
550 if (ti_options%solver_stop_on_error) then
551 write(msg, '(A,I0,A,I0,A)') &
552 ' Trust region failed at grid point (j_e=', j_e, ', j_a=', j_a, ')'
553 call mexPrintf(trim(msg)//NEW_LINE('A'))
554 select case (info)
555 case (0)
556 call mexPrintf(' Reason: Nonlinear system ill-behaved at the initial guess'//NEW_LINE('A'))
557 case (2)
558 call mexPrintf(' Reason: Maximum number of iterations reached'//NEW_LINE('A'))
559 case (3)
560 call mexPrintf(' Reason: Spurious convergence (trust region radius too small)'//NEW_LINE('A'))
561 case (4)
562 call mexPrintf(' Reason: Iteration not making good progress'//NEW_LINE('A'))
563 case (5)
564 call mexPrintf(' Reason: Tolerance too small, no further improvement possible'//NEW_LINE('A'))
565 end select
566 ! Print diagnostic information
567 call mexPrintf(' Initial guess (x_orig):'//NEW_LINE('A'))
568 do i = 1, dims%n_orig
569 write(msg, '(A,I0,A,ES15.6)') ' x(', i, ') = ', gp_ws%x_orig(i)
570 call mexPrintf(trim(msg)//NEW_LINE('A'))
571 end do
572 ! Also print grid point state values
573 call mexPrintf(' Grid point states:'//NEW_LINE('A'))
574 do i = 1, dims%n_states
575 write(msg, '(A,I0,A,ES15.6)') ' state(', i, ') = ', &
576 sm(dims%n_het_exo+i, j)
577 call mexPrintf(trim(msg)//NEW_LINE('A'))
578 end do
579 call mexPrintf(' Shocks:'//NEW_LINE('A'))
580 do i = 1, dims%n_het_exo
581 write(msg, '(A,I0,A,ES15.6)') ' shock(', i, ') = ', &
582 sm(i, j)
583 call mexPrintf(trim(msg)//NEW_LINE('A'))
584 end do
585 ! Print bounds info
586 call mexPrintf(' Bounds:'//NEW_LINE('A'))
587 do i = 1, dims%n_orig
588 write(msg, '(A,I0,A,ES12.4,A,ES12.4,A,I0)') ' var ', i, &
589 ': [', mcp%lower_bounds(i), &
590 ', ', mcp%upper_bounds(i), &
591 '], type=', mcp%bound_type(i)
592 call mexPrintf(trim(msg)//NEW_LINE('A'))
593 end do
594 ! Evaluate residuals at current point to show their values
595 call mexPrintf(' Evaluating residuals at failed point...'//NEW_LINE('A'))
596 call set_het_input(gp_ws%x_orig, j, j_e, dims, mcp, &
597 sm, state_var, &
598 pol_grids, pol_dims, &
599 weighted_old_pol, gc_cache_next, &
600 gp_ws, mex)
601 call call_matlab_het_resid_tensor(gp_ws%resid, mex)
602 call mexPrintf(' Full residuals (before extraction):'//NEW_LINE('A'))
603 do i = 1, dims%n_het_endo
604 write(msg, '(A,I0,A,ES15.6)') ' resid(', i, ') = ', gp_ws%resid(i)
605 call mexPrintf(trim(msg)//NEW_LINE('A'))
606 end do
607 status = 1
608 return
609 end if
610
611 end if
612
613 ! Store solution for originally declared variables
614 ! We use yh as temporary storage
615 gp_ws%yh(dims%n_het_endo+1:dims%n_het_endo+dims%n_orig) = gp_ws%x_orig
616 ! Set the auxiliary variables (loop over topological levels)
617 if (mcp%set_auxiliary_variables) then
618 do i = 0, dims%n_aux_levels - 1
619 call call_matlab_set_auxiliary_variables(gp_ws%yh, mex, i)
620 end do
621 end if
622 ! Copy back into new_pol
623 new_pol(:, j) = gp_ws%yh(dims%n_het_endo+1:2*dims%n_het_endo)
624 ! Set MCP multipliers to zero for the FB function to work correctly
625 if (dims%n_mult > 0) new_pol(mcp%mult_in_het, j) = 0.0_real64
626 end do
627 end do
628
629 contains
630 ! Callback for trust_region_solve: computes FB-transformed residual and Jacobian
631 subroutine fb_callback(x1, fvec, fjac)
632 real(real64), dimension(:), intent(in) :: x1
633 real(real64), dimension(size(x1)), intent(out) :: fvec
634 real(real64), dimension(size(x1),size(x1)), intent(out), optional :: fjac
635
636 integer(int32) :: ii, kk, eq_idx
637
638 ! Set up heterogeneous input (yh, xh) and compute expected future policy
639 ! yh(+1) = E[yh(+1)] and Ex = ∂E[yh(+1)]/∂state (for chain rule)
640 call set_het_input(x1, j, j_e, dims, mcp, &
641 sm, state_var, &
642 pol_grids, pol_dims, &
643 weighted_old_pol, gc_cache_next, &
644 gp_ws, mex)
645
646
647 ! Evaluate residual
648 call call_matlab_het_resid_tensor(gp_ws%resid, mex)
649
650 ! Extract equations for originally declared variables with MCP reordering
651 ! Variable ii has its residual from equation mcp_eq_reordering(ii)
652 ! This ensures bounds on variable i are paired with the correct equation's residual
653 ! NOTE: Only extract n_orig equations, not n_het_endo (auxiliary vars are computed, not solved)
654 do ii = 1, dims%n_orig
655 eq_idx = mcp%eq_reordering(ii)
656 gp_ws%resid_orig(ii) = gp_ws%resid(eq_idx)
657 end do
658
659
660 ! Apply Fischer-Burmeister transformation
661 call fb_transform(dims%n_orig, x1, gp_ws%resid_orig, &
662 mcp%lower_bounds, &
663 mcp%upper_bounds, &
664 mcp%bound_type, &
665 fvec)
666
667 ! Compute Jacobian if requested
668 if (present(fjac)) then
669 ! Evaluate Jacobian at the certainty equivalent point
670 ! yh(+1) is already set to Eyh_next above
671 ! jac and jac_next are extracted directly with MCP reordering
672 call call_matlab_het_g1_tensor(gp_ws%jac, &
673 gp_ws%jac_next, &
674 mcp%eq_reordering_inv, &
675 mex)
676
677
678 ! Apply chain rule: jac(:, state_var(kk)) += jac_next * dpol_next(:, kk)
679 ! Using BLAS DGEMV for each state dimension
680 do kk = 1, dims%n_states
681 call matvecmul_add("N", 1.0_real64, gp_ws%jac_next, &
682 gp_ws%dpol_next(:,kk), 1.0_real64, &
683 gp_ws%jac(:, state_var(kk)))
684 end do
685
686
687 ! Get the jacobian over originally declared variables
688 gp_ws%jac_orig = gp_ws%jac(1:dims%n_orig,1:dims%n_orig)
689
690
691 ! Apply FB transformation to Jacobian
692 call fb_transform_jacobian(dims%n_orig, x1, gp_ws%resid_orig, gp_ws%jac_orig, &
693 mcp%lower_bounds, &
694 mcp%upper_bounds, &
695 mcp%bound_type, &
696 fjac)
697 end if
698
699 end subroutine fb_callback
700
701 end subroutine solve_household_all_points
702
703 !---------------------------------------------------------------------------
704 ! MATLAB MEX Fallback: Call dynamic_het1_resid via mexCallMATLAB
705 ! Used when C DLL is not available
706 ! Signature matches dynamic_het1_resid_mex.c with 7 inputs (no T management)
707 !---------------------------------------------------------------------------
708 subroutine call_matlab_het_resid_tensor(resid, input_mex)
709 type(matlab_mex_handles), intent(inout) :: input_mex
710 real(real64), contiguous, intent(inout) :: resid(:)
711
712 ! MATLAB interface variables
713 type(c_ptr), dimension(7) :: prhs
714 type(c_ptr), dimension(1) :: plhs
715 integer(C_INT) :: retval
716 real(real64), pointer, contiguous :: resid_ptr(:)
717
718 ! Build input array for mexCallMATLAB (7 inputs, no T management)
719 prhs(1) = input_mex%y_mx
720 prhs(2) = input_mex%x_mx
721 prhs(3) = input_mex%params_mx
722 prhs(4) = input_mex%y_mx ! steady state (same as y for SS computation)
723 prhs(5) = input_mex%yh_mx
724 prhs(6) = input_mex%xh_mx
725 prhs(7) = input_mex%params_mx ! paramsh (same as params)
726
727 ! Call MATLAB MEX function: resid = model_name.dynamic_het1_resid(y, x, params, ss, yh, xh, paramsh)
728 retval = mexCallMATLAB(1_C_INT, plhs, 7_C_INT, prhs, input_mex%het_resid)
729 if (retval /= 0) &
730 call mexErrMsgTxt("MATLAB fallback: Failed to call " // input_mex%het_resid)
731
732 ! Extract residual from MATLAB output
733 resid_ptr(1:size(resid)) => mxGetDoubles(plhs(1))
734 resid = resid_ptr
735
736 end subroutine call_matlab_het_resid_tensor
737
738 !---------------------------------------------------------------------------
739 ! MATLAB MEX Fallback: Call dynamic_het1_g1 via mexCallMATLAB
740 ! Used when C DLL is not available
741 ! Signature matches dynamic_het1_g1_mex.c with 10 inputs (no T management)
742 ! Returns sparse Jacobian values directly
743 !---------------------------------------------------------------------------
744 subroutine call_matlab_het_g1_tensor(jac, jac_next, eq_reordering_inv, input_mex)
745 type(matlab_mex_handles), intent(inout) :: input_mex
746 real(real64), contiguous, intent(inout) :: jac(:,:), jac_next(:,:)
747 integer(int32), contiguous, intent(in) :: eq_reordering_inv(:)
748
749 ! MATLAB interface variables
750 type(c_ptr), dimension(10) :: prhs
751 type(c_ptr), dimension(1) :: plhs
752 type(c_ptr) :: g1_mx
753 integer(C_INT) :: retval
754 real(real64), pointer, contiguous :: pr(:)
755 integer(mwSize), pointer, contiguous :: rowval(:), colptr(:)
756 integer(mwSize) :: sparse_row, l, dynamic_g1_nnz
757 integer(int32) :: ii, jj, n_het_endo
758
759 n_het_endo = size(eq_reordering_inv)
760
761 ! Build input array for mexCallMATLAB (10 inputs, no T management)
762 ! Signature: (y, x, params, ss, yh, xh, paramsh, sparse_rowval, sparse_colval, sparse_colptr)
763 prhs(1) = input_mex%y_mx
764 prhs(2) = input_mex%x_mx
765 prhs(3) = input_mex%params_mx
766 prhs(4) = input_mex%y_mx
767 prhs(5) = input_mex%yh_mx
768 prhs(6) = input_mex%xh_mx
769 prhs(7) = input_mex%params_mx
770 prhs(8) = input_mex%rowval_mx
771 prhs(9) = input_mex%colval_mx
772 prhs(10) = input_mex%colptr_mx
773
774 ! Call MATLAB MEX function: g1 = model_name.dynamic_het1_g1(...)
775 retval = mexCallMATLAB(1_C_INT, plhs, 10_C_INT, prhs, input_mex%het_jac)
776 if (retval /= 0) &
777 call mexErrMsgTxt("MATLAB fallback: Failed to call " // input_mex%het_jac)
778 g1_mx = plhs(1)
779
780 ! Check that output is sparse
781 if (.not. mxIsSparse(g1_mx)) &
782 call mexErrMsgTxt("MATLAB fallback: " // input_mex%het_jac // " must return sparse matrix")
783
784 ! Extract sparse matrix data
785 colptr(1:input_mex%dynamic_g1_ncols) => mxGetJc(g1_mx)
786 dynamic_g1_nnz = colptr(input_mex%dynamic_g1_ncols)
787 rowval(1:dynamic_g1_nnz) => mxGetIr(g1_mx)
788 pr(1:dynamic_g1_nnz) => mxGetDoubles(g1_mx)
789
790 ! Extract yh(0) Jacobian directly into jac [n_orig x n_orig]
791 ! Only extract rows eq_reordering(1:n_orig) and columns 1:n_orig
792 ! Columns (n_het_endo+1) to (2*n_het_endo) of full Jacobian correspond to yh(0)
793 jac = 0.0_real64
794 do jj = 1, n_het_endo
795 ! Column jj of yh(0) submatrix corresponds to column (n_het_endo + jj) of full Jacobian
796 do l = colptr(n_het_endo + jj) + 1, colptr(n_het_endo + jj + 1)
797 sparse_row = int(rowval(l), int32) + 1 ! Convert 0-based to 1-based
798 ! Use inverse permutation for O(1) lookup
799 ii = eq_reordering_inv(sparse_row)
800 jac(ii, jj) = pr(l)
801 end do
802 end do
803
804 ! Extract yh(+1) Jacobian directly into jac_next [n_orig x n_orig]
805 ! Only extract rows eq_reordering(1:n_orig) and columns 1:n_orig
806 ! Columns (2*n_het_endo+1) to (3*n_het_endo) of full Jacobian correspond to yh(+1)
807 jac_next = 0.0_real64
808 do jj = 1, n_het_endo
809 ! Column jj of yh(+1) submatrix corresponds to column (2*n_het_endo + jj) of full Jacobian
810 do l = colptr(2*n_het_endo + jj) + 1, colptr(2*n_het_endo + jj + 1)
811 sparse_row = int(rowval(l), int32) + 1 ! Convert 0-based to 1-based
812 ! Use inverse permutation for O(1) lookup
813 ii = eq_reordering_inv(sparse_row)
814 jac_next(ii, jj) = pr(l)
815 end do
816 end do
817
818 end subroutine call_matlab_het_g1_tensor
819
820 !---------------------------------------------------------------------------
821 ! MATLAB MEX Fallback: Call dynamic_het1_set_auxiliary_variables
822 ! Computes auxiliary variables from originally declared variables
823 ! Signature: yh = set_aux_fn(y, x, params, ss, yh, xh, paramsh)
824 !---------------------------------------------------------------------------
825 subroutine call_matlab_set_auxiliary_variables(yh, input_mex, step)
826 real(real64), dimension(:), intent(inout) :: yh
827 type(matlab_mex_handles), intent(inout) :: input_mex
828 integer(int32), intent(in) :: step
829
830 ! MATLAB interface variables
831 type(c_ptr), dimension(8) :: prhs
832 type(c_ptr), dimension(1) :: plhs
833 integer(C_INT) :: retval
834
835 ! Pointer to the results
836 real(real64), pointer, contiguous :: yh_ptr(:)
837
838 ! Create mxArray for step parameter
839 input_mex%step_mx = mxCreateDoubleScalar(real(step, c_double))
840
841 ! Build input array for mexCallMATLAB (8 inputs)
842 ! Signature: (y, x, params, ss, yh, xh, paramsh, step)
843 prhs(1) = input_mex%y_mx
844 prhs(2) = input_mex%x_mx
845 prhs(3) = input_mex%params_mx
846 prhs(4) = input_mex%y_mx ! steady state (same as y for SS computation)
847 prhs(5) = input_mex%yh_mx
848 prhs(6) = input_mex%xh_mx
849 prhs(7) = input_mex%params_mx ! paramsh (same as params)
850 prhs(8) = input_mex%step_mx
851
852 ! Call MATLAB MEX function: yh = model_name.dynamic_het1_set_auxiliary_variables(...)
853 retval = mexCallMATLAB(1_C_INT, plhs, 8_C_INT, prhs, input_mex%het_aux)
854 if (retval /= 0) &
855 call mexErrMsgTxt("MATLAB fallback: Failed to call " // input_mex%het_aux)
856
857 ! Extract updated yh from MATLAB output (auxiliary variables have been set)
858 yh_ptr(1:size(yh)) => mxGetDoubles(plhs(1))
859 yh = yh_ptr
860
861 end subroutine call_matlab_set_auxiliary_variables
862
863 end module time_iteration_tensor