! Copyright © 2025-2026 Dynare Team ! ! This file is part of Dynare. ! ! Dynare is free software: you can redistribute it and/or modify it under the terms of the ! GNU General Public License as published by the Free Software Foundation, either version 3 of ! the License, or (at your option) any later version. ! ! Dynare is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without ! even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the ! GNU General Public License for more details. ! ! You should have received a copy of the GNU General Public License along with Dynare. If not, ! see . ! ! Original author: Normann Rion ! ! Main entry point for heterogeneous-agent steady-state computation module aggregate_residuals_tensor use iso_fortran_env, only: real64, int32 use iso_c_binding, only: C_DOUBLE, C_INT use calibration_types use matlab_mex use time_iteration_tensor use blas implicit none (type, external) private public :: agg_resid_tensor contains !--------------------------------------------------------------------------- ! Main solver function for tensor product grids (Cases 1 & 2) ! Simpler than solve_steady_state since grid is already constructed ! Returns: status (0=success, >0=error code) !--------------------------------------------------------------------------- function agg_resid_tensor(input, output) result(status) type(calibration_input), intent(inout) :: input type(calibration_output), intent(inout) :: output integer(int32) :: status ! Initialize status = 0 ! Phase 1: Time iteration on fixed tensor grid status = solve_time_iteration_tensor( & input%dims, input%ti_options, input%ti_verbosity, input%state_var, & input%tg_config, & input%old_pol, input%old_pol_array, input%new_pol, input%weighted_old_pol, & input%gc_cache_next, input%gc_cache_om, input%gc_cache_fi, & input%gp_ws, input%mex, & output%ti_output) ! Phase 2: Forward iteration for distribution status = solve_distribution_tensor(input, output%dist_output) ! Phase 3: Compute aggregated heterogeneous variables call compute_agg_het_variables(input, output) ! Phase 4: Compute aggregate residuals for calibration target equations call compute_aggregate_residuals(input, output) ! Only print "Calibration iteration complete" when there's actual calibration if (input%dims%n_free_parameters > 0 .and. input%cal_verbosity == 2) & call mexPrintf(' Calibration iteration complete'//NEW_LINE('A')) end function agg_resid_tensor function solve_distribution_tensor(input, dist_output) result(status) type(calibration_input), intent(inout) :: input type(distribution_output), intent(inout) :: dist_output integer(int32) :: status integer(int32) :: N_om, N_a, N_e, j, j_a, iter, m, kf, t, Kcorn, n_states real(real64) :: diff_norm real(real64), pointer, contiguous :: d_mat(:,:), d_mat_next(:,:) character(len=256) :: msg real(real64), pointer, contiguous :: inc(:), acc(:), r_up(:,:), r_down(:,:), beta_0(:) integer(int32), pointer, contiguous :: z(:), linear_idx(:), stride_shocks(:) logical, pointer, contiguous :: is_hard_one(:,:), is_hard_zero(:,:), sk(:) ! Initialize status status = 0 dist_output%converged = .false. ! Useful size variables N_om = input%dims%N_om N_a = input%dims%N_a_om N_e = input%dims%N_e n_states = input%dims%n_states Kcorn = input%gc_cache_fi%Kcorn ! Create a few pointers to make the code more readable inc(1:N_om) => input%gc_cache_fi%inc acc(1:N_om) => input%gc_cache_fi%acc r_up(1:N_om, 1:n_states) => input%gc_cache_fi%r_up r_down(1:N_om, 1:n_states) => input%gc_cache_fi%r_down beta_0(1:N_om) => input%gc_cache_fi%beta_0 z(1:N_om) => input%gc_cache_fi%z linear_idx(1:N_om) => input%gc_cache_fi%linear_idx stride_shocks(1:n_states) => input%gc_cache_fi%stride_shocks is_hard_one(1:N_om, 1:n_states) => input%gc_cache_fi%is_hard_one is_hard_zero(1:N_om, 1:n_states) => input%gc_cache_fi%is_hard_zero sk(1:n_states) => input%gc_cache_fi%sk ! Initialize the distribution to a uniform one d_mat(1:N_e, 1:N_a) => dist_output%distribution do j_a = 1, N_a d_mat(:,j_a) = input%tg_config%p / N_a end do input%d_next = dist_output%distribution d_mat_next(1:N_e, 1:N_a) => input%d_next if (input%forward_verbosity == 2) & call mexPrintf(' === Forward Iteration ==='//NEW_LINE('A')) ! Perform forward iterations do iter = 1, input%d_options%max_iter ! Perform the forward iteration algorithm ! Initialization linear_idx = input%gc_cache_fi%corner_idx ! Reset to initial low-corner indices sk = .false. z = count(is_hard_zero, dim=2) ! Start at the low corner inc = beta_0*dist_output%distribution acc = 0.0_real64 do j = 1, N_om if (z(j) == 0_int32) then m = linear_idx(j) acc(m) = acc(m) + inc(j) end if end do ! Go over the other corners do t = 1, input%gc_cache_fi%Kcorn-1 kf = input%gc_cache_fi%flip_idx(t) if (.not. sk(kf)) then ! lower -> upper on dim kf linear_idx = linear_idx+stride_shocks(kf) sk(kf) = .true. do j = 1, N_om if (is_hard_one(j,kf)) then z(j) = z(j)+1_int32 else if (is_hard_zero(j,kf)) then z(j) = z(j)-1_int32 else inc(j) = inc(j)*r_up(j,kf) end if end do else ! upper -> lower on dim kf linear_idx = linear_idx-stride_shocks(kf) sk(kf) = .false. do j = 1, N_om if (is_hard_one(j,kf)) then z(j) = z(j)-1_int32 else if (is_hard_zero(j,kf)) then z(j) = z(j)+1_int32 else inc(j) = inc(j)*r_down(j,kf) end if end do end if do j=1, N_om if (z(j) == 0_int32) then m = linear_idx(j) acc(m) = acc(m)+inc(j) end if end do end do ! Weighting with the Markov kernel and update for the next distribution d_mat(1:N_e, 1:N_a) => acc call matmul_add("N", "N", 1.0_real64, input%tg_config%MuT, d_mat, & 0.0_real64, d_mat_next) ! Check convergence every check_every iterations if (mod(iter, input%d_options%check_every) == 0 .or. iter == input%d_options%max_iter) then diff_norm = maxval(abs(dist_output%distribution - input%d_next)) ! Print per-iteration trace for verbosity == 2 if (input%forward_verbosity == 2) then write(msg, '(A,I6,A,ES10.3,A,ES10.3)') ' Forward iter ', iter, & ': ||ΔD|| = ', diff_norm, ', tol = ', input%d_options%tol call mexPrintf(trim(msg)//NEW_LINE('A')) end if if (diff_norm < input%d_options%tol) then dist_output%converged = .true. dist_output%iterations = iter dist_output%residual_norm = diff_norm if (input%forward_verbosity == 2) then write(msg, '(A,I0,A,ES10.3,A)') ' Distribution converged in ', iter, & ' iterations (norm: ', diff_norm, ')' call mexPrintf(trim(msg)//NEW_LINE('A')) end if ! Final update dist_output%distribution = input%d_next exit end if end if ! Update for next iteration dist_output%distribution = input%d_next end do ! Check if converged if (.not. dist_output%converged) then status = 1 dist_output%iterations = input%d_options%max_iter dist_output%residual_norm = diff_norm if (input%forward_verbosity >= 1) then write(msg, '(A,I0,A,ES10.3,A)') ' WARNING: Distribution did not converge after ', & input%d_options%max_iter, ' iterations (norm: ', diff_norm, ')' call mexPrintf(trim(msg)//NEW_LINE('A')) end if end if end function solve_distribution_tensor subroutine compute_agg_het_variables(input, output) type(calibration_input), intent(inout) :: input type(calibration_output), intent(inout) :: output integer(int32) :: k, N_Ix if (input%cal_verbosity == 2) & call mexPrintf(' === Aggregate variables and residuals ==='//NEW_LINE('A')) ! Compute the aggregated heterogeneous policy functions ! Ix_j = sum_i D_i * policy_j(state_i) call matvecmul_add("N", 1.0_real64, output%ti_output%policies_om, & output%dist_output%distribution, 0.0_real64, output%agg_output%Ix) ! Fill yagg - subset corresponding to SUM operators ! yagg = Ix(indices.Ix.in_x) input%yagg = output%agg_output%Ix(input%Ix_in_het) ! Fill the SUM_x variables in y N_Ix = size(input%Ix_in_agg,1) do k=1,N_Ix input%y(input%dims%n_agg_endo+input%Ix_in_agg(k)) = input%yagg(k) end do end subroutine compute_agg_het_variables subroutine compute_aggregate_residuals(input, output) type(calibration_input), intent(inout) :: input type(calibration_output), intent(inout) :: output character(len=256) :: msg integer :: i if (input%dims%n_agg_endo > 0_int32) & ! Use MATLAB MEX function call call_matlab_resid_tensor(output%agg_output%residuals, input%mex) ! Print all aggregate residuals if verbosity == 2 if (input%cal_verbosity == 2) then call mexPrintf(' Aggregate residuals:'//NEW_LINE('A')) do i = 1, size(input%equation_names, 1) if (len_trim(input%equation_names(i)) > 0) then ! Use equation name if available write(msg, '(A,A,A,ES15.6)') ' ', trim(input%equation_names(i)), ': ', & output%agg_output%residuals(i) else ! Fall back to equation number write(msg, '(A,I3,A,ES15.6)') ' ', i, ': ', & output%agg_output%residuals(i) end if call mexPrintf(trim(msg)//NEW_LINE('A')) end do write(msg, '(A,ES15.6,A,ES15.6)') ' Max norm: ', & maxval(abs(output%agg_output%residuals(1:input%dims%n_agg_endo))), & ', tol = ', input%solver_opts%tol call mexPrintf(trim(msg)//NEW_LINE('A')) end if end subroutine compute_aggregate_residuals !--------------------------------------------------------------------------- ! Call dynamic_het1_resid via mexCallMATLAB !--------------------------------------------------------------------------- subroutine call_matlab_resid_tensor(residuals, input_mex) type(matlab_mex_handles), intent(in) :: input_mex real(real64), contiguous, intent(inout) :: residuals(:) ! MATLAB interface variables type(c_ptr), dimension(7) :: prhs type(c_ptr), dimension(1) :: plhs integer(C_INT) :: retval real(real64), pointer, contiguous :: resid(:) ! Build input array for mexCallMATLAB (7 inputs, no T management) prhs(1) = input_mex%y_mx prhs(2) = input_mex%x_mx prhs(3) = input_mex%params_mx prhs(4) = input_mex%y_mx prhs(5) = input_mex%yagg_mx ! Call MATLAB function: resid = model_name.dynamic_resid(y, x, params, ss, yagg) retval = mexCallMATLAB(1_C_INT, plhs, 5_C_INT, prhs, input_mex%agg_resid) if (retval /= 0) & call mexErrMsgTxt("MATLAB fallback: Failed to call " // input_mex%agg_resid) ! Extract residual from MATLAB output resid(1:size(residuals)) => mxGetDoubles(plhs(1)) residuals = resid call mxDestroyArray(plhs(1)) end subroutine call_matlab_resid_tensor end module aggregate_residuals_tensor