Debian Codegraph @

mex/sources/heterogeneity/utils/calibration_types.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 ! Derived types for heterogeneous-agent steady-state computation
19
20 module calibration_types
21 use iso_fortran_env, only: real64, int32
22 use iso_c_binding, only: c_ptr, c_null_ptr, C_FUNPTR, C_DOUBLE, C_INT64_T, c_int, c_associated
23 use blas, only: blint
24
25 implicit none (type, external)
26
27 private
28 public :: grid, tensor_grid_config, gray_code_cache, &
29 time_iteration_options, distribution_options, solver_options, &
30 mcp_solver_config, model_dimensions, broyden_workspace, &
31 grid_point_workspace, matlab_mex_handles, &
32 calibration_input, calibration_output, &
33 time_iteration_output, distribution_output, aggregation_output, &
34 BOUND_NONE, BOUND_LOWER, BOUND_UPPER, BOUND_BOTH
35
36 ! Bound type enumeration for Fischer-Burmeister transformation
37 integer(int32), parameter :: BOUND_NONE = 0 ! lb=-∞, ub=+∞ → Φ = -F (unconstrained)
38 integer(int32), parameter :: BOUND_LOWER = 1 ! lb finite, ub=+∞ → Φ = φ(x-lb, F)
39 integer(int32), parameter :: BOUND_UPPER = 2 ! lb=-∞, ub finite → Φ = φ(ub-x, -F)
40 integer(int32), parameter :: BOUND_BOTH = 3 ! both finite → φ(x-lb, φ(ub-x, -F))
41
42 ! 1D grid for cell array extraction
43 type :: grid
44 real(real64), pointer, contiguous :: nodes(:) => null()
45 end type grid
46
47 ! MCP solver configuration (Fischer-Burmeister transformation)
48 ! Contains data arrays for complementarity constraints; dimensions are in model_dimensions
49 ! NOTE: Defined before tensor_grid_config because it's used as a component
50 type :: mcp_solver_config
51 ! Complementarity bounds for original equations [n_orig]
52 real(real64), allocatable :: lower_bounds(:)
53 real(real64), allocatable :: upper_bounds(:)
54 integer(int32), allocatable :: bound_type(:)
55
56 ! MCP equation reordering [n_het_endo]
57 integer(int32), pointer, contiguous :: eq_reordering(:) => null()
58 ! Inverse of eq_reordering: maps equation index -> variable index [n_het_endo]
59 integer(int32), allocatable :: eq_reordering_inv(:)
60
61 ! Indices of original equations (rows to solve with FB) [n_orig]
62 integer(int32), pointer, contiguous :: orig_eqs(:) => null()
63
64 ! Indices of MULT_* variables in het endo [n_mult]
65 integer(int32), pointer, contiguous :: mult_in_het(:) => null()
66
67 ! Flag: presence of auxiliary het endo variables
68 logical :: set_auxiliary_variables = .false.
69 end type mcp_solver_config
70
71 ! Tensor grid configuration
72 ! Stores precomputed interpolation data from MATLAB
73 type :: tensor_grid_config
74 ! Interpolation matrices for the policy functions [N_sp × n_states]
75 ! Sparse grid
76 integer(int32), allocatable :: pol_ind_sp(:,:) ! Bracketing lower indices
77 real(real64), allocatable :: pol_w_sp(:,:) ! Interpolation weights [0,1]
78 ! Dense grid
79 integer(int32), allocatable :: pol_ind_om(:,:) ! Bracketing lower indices
80 real(real64), allocatable :: pol_w_om(:,:) ! Interpolation weights [0,1]
81
82 ! Interpolation matrices for the dense-to-sparse grids [N_a × n_states]
83 integer(int32), pointer, contiguous :: d_ind(:,:) ! Bracketing lower indices
84 real(real64), pointer, contiguous :: d_w(:,:) ! Interpolation weights [0,1]
85
86 ! State grids (array of 1D grids)
87 ! Corresponds to MATLAB cell array mat.pol.grids_array
88 type(grid), allocatable :: pol_grids(:) ! [n_states]
89 type(grid), allocatable :: d_grids(:) ! [n_states]
90
91 ! Grid dimensions
92 ! Corresponds to MATLAB int32 array mat.pol.dims
93 integer(int32), pointer, contiguous :: pol_dims(:) => null() ! [n_states] - length of each grid
94 integer(int32), pointer, contiguous :: d_dims(:) => null() ! [n_states] - length of each grid
95
96 ! State matrix [(n_e + n_a) × N_sp]
97 ! Corresponds to MATLAB matrix mat.pol.sm
98 ! Contains the state values (shocks and assets) at each grid point
99 real(real64), pointer, contiguous :: sm(:,:) => null()
100
101 ! Transition matrix for shocks [N_e × N_e]
102 ! Corresponds to MATLAB matrix mat.Mu
103 real(real64), pointer, contiguous :: Mu(:,:) => null()
104 real(real64), allocatable :: p(:)
105
106 ! Transpose of Mu for efficient BLAS operations [N_e × N_e]
107 real(real64), allocatable :: MuT(:,:)
108
109 ! MCP solver configuration (Fischer-Burmeister transformation)
110 ! Used only in time iteration for complementarity constraints
111 type(mcp_solver_config) :: mcp
112 end type tensor_grid_config
113
114 ! Gray code infrastructure for multi-dimensional interpolation
115 ! Precomputed once for efficiency in expectation computations
116 type :: gray_code_cache
117 ! Gray code sequence for hypercube traversal
118 integer(int32), allocatable :: flip_idx(:) ! [Kcorn-1] - flip sequence
119 integer(int32) :: Kcorn ! Number of corners: 2^n_states
120
121 ! Grid geometry
122 integer(int32), allocatable :: stride_states(:) ! [n_states] - strides for linear indexing
123 integer(int32), allocatable :: stride_shocks(:) ! [n_states] - strides for linear indexing
124 integer(int32), allocatable :: linear_idx(:) ! [N_sp] - low-corner linear indices (working copy, modified during traversal)
125 integer(int32), allocatable :: corner_idx(:) ! [N_sp] - low-corner linear indices (initial values, never modified)
126
127 ! Common work arrays
128 logical, allocatable :: sk(:)
129
130 ! Work arrays for forward iteration algorithm
131 real(real64), allocatable :: r_up(:,:) ! [N_om × n_states]
132 real(real64), allocatable :: r_down(:,:) ! [N_om × n_states]
133 real(real64), allocatable :: beta_0(:) ! [N_om] initial value, never modified
134 real(real64), allocatable :: beta(:) ! [N_om]
135 real(real64), allocatable :: inc(:) ! [N_om]
136 logical, allocatable :: is_hard_one(:,:) ! [N_om × n_states] w=1 (lower boundary)
137 logical, allocatable :: is_hard_zero(:,:) ! [N_om × n_states] w=0 (upper boundary)
138 integer(int32), allocatable :: z(:)
139 real(real64), allocatable :: acc(:)
140 end type gray_code_cache
141
142 ! Time iteration options
143 type :: time_iteration_options
144 integer(int32) :: max_iter ! Maximum iterations for time iteration
145 real(real64) :: tol ! Convergence tolerance for time iteration
146 real(real64) :: solver_tolf ! Tolerance for pointwise nonlinear solver (tolf)
147 real(real64) :: solver_factor ! Initial trust region radius factor
148 integer(int32) :: solver_max_iter ! Max iterations for trust region solver
149 real(real64) :: solver_tolx ! Tolerance for spurious convergence check (tolx)
150 logical :: solver_stop_on_error ! If true, stop on solver failure; if false, continue with current solution
151 real(real64) :: learning_rate ! Policy update dampening factor (1 = no dampening)
152 integer(int32) :: early_stopping ! Stop after N consecutive diff increases (0 = disabled)
153 end type time_iteration_options
154
155 ! Forward iteration (distribution) options
156 type :: distribution_options
157 integer(int32) :: max_iter ! Maximum iterations
158 real(real64) :: tol ! Convergence tolerance
159 integer(int32) :: check_every ! Check convergence every N iterations
160 end type distribution_options
161
162 ! Equilibrium solver options (generic for MINPACK or KINSOL)
163 type :: solver_options
164 real(real64) :: tol ! Tolerance for equilibrium
165 integer(int32) :: max_iter ! Max iterations
166 end type solver_options
167
168 ! Model dimensions (consolidated from scattered fields)
169 ! Contains all dimension information used across the heterogeneous-agent solver
170 type :: model_dimensions
171 ! Grid sizes
172 integer(int32) :: N_sp = 0 ! Total number of nodes in the sparse policy grid
173 integer(int32) :: N_om = 0 ! Total number of nodes in the dense distribution grid
174 integer(int32) :: N_e = 0 ! Total number of nodes of the shocks grids
175 integer(int32) :: N_a_sp = 0 ! Nodes in sparse policy states grids (= N_sp / N_e)
176 integer(int32) :: N_a_om = 0 ! Nodes in dense distribution states grids
177
178 ! Variable counts
179 integer(int32) :: n_het_endo = 0 ! Heterogeneous endogenous vars (full, including aux)
180 integer(int32) :: n_het_exo = 0 ! Heterogeneous exogenous vars
181 integer(int32) :: n_states = 0 ! Continuous state variables
182 integer(int32) :: n_agg_endo = 0 ! Aggregate endogenous vars
183 integer(int32) :: n_free_parameters = 0 ! Calibrated parameters
184
185 ! Solver-related counts
186 integer(int32) :: n_orig = 0 ! Originally declared het endo vars (solver optimizes over these)
187 integer(int32) :: n_mult = 0 ! Number of multiplier variables
188 integer(int32) :: n_aux_levels = 0 ! Number of topological levels for aux variable computation
189
190 ! Level structure for aux variables (for time-shifting)
191 integer(int32), allocatable :: het_aux_level_sizes(:) ! Size of each level
192 integer(int32), allocatable :: het_aux_level_vars(:) ! Concatenated level vars (1-based indices)
193 end type model_dimensions
194
195 ! Broyden workspace for calibration solver
196 ! Stores pre-allocated work arrays for the Broyden quasi-Newton method
197 ! Following Python SSJ implementation (sequence_jacobian/utilities/solvers.py)
198 type :: broyden_workspace
199 integer(int32) :: n_vars = 0 ! Number of variables/equations
200
201 ! Jacobian approximation and work copy for LU factorization
202 real(real64), allocatable :: J(:,:) ! [n x n] Approximate Jacobian
203 real(real64), allocatable :: J_copy(:,:) ! [n x n] Copy for dgesv (overwrites input)
204
205 ! Newton step and residual work arrays
206 real(real64), allocatable :: dx(:) ! [n] Newton step
207 real(real64), allocatable :: fvec_new(:) ! [n] Residuals at trial point
208 real(real64), allocatable :: df(:) ! [n] Residual change (fvec_new - fvec)
209
210 ! LAPACK pivot indices for dgesv
211 integer(blint), allocatable :: ipiv(:) ! [n] Pivot indices
212 end type broyden_workspace
213
214 ! Grid point workspace for time iteration solver
215 ! Groups all mutable state needed for a single grid point solve
216 ! Designed for future parallelization (one workspace per thread)
217 type :: grid_point_workspace
218 ! Trust region solver workspace (Fischer-Burmeister transformation)
219 ! Dimensions n_orig and n_het_endo are in input%dims
220 real(real64), allocatable :: x_orig(:) ! [n_orig] - current solution
221 real(real64), allocatable :: resid_orig(:) ! [n_orig] - extracted residual (after MCP reordering)
222 real(real64), allocatable :: resid(:) ! [n_het_endo] - full residual from MATLAB
223
224 ! Working Jacobian arrays (extracted directly from sparse, then chain rule applied)
225 real(real64), allocatable :: jac_orig(:,:) ! [n_orig x n_orig] - working Jacobian
226 real(real64), allocatable :: jac(:,:) ! [n_het_endo x n_het_endo] - working Jacobian
227 real(real64), allocatable :: jac_next(:,:) ! [n_het_endo x n_het_endo] - yh(+1) Jacobian for chain rule
228
229 ! Heterogeneous variable buffers (for MATLAB callbacks)
230 real(real64), pointer, contiguous :: yh(:) ! [3*n_het_endo]
231 real(real64), pointer, contiguous :: xh(:) ! [n_het_exo]
232
233 ! Next-period interpolation work arrays
234 real(real64), allocatable :: states_next(:) ! [n_states]
235 real(real64), allocatable :: w_next(:,:) ! [1 x n_states]
236 integer(int32), allocatable :: ind_next(:,:)! [1 x n_states]
237 real(real64), allocatable :: dpol_next(:,:) ! [n_het_endo x n_states] - dE[yh(+1)]/d(state)
238 real(real64), allocatable :: inv_h(:) ! [n_states] - inverse grid spacing
239
240 logical :: initialized = .false.
241 end type grid_point_workspace
242
243 ! Grouped MATLAB MEX array handles
244 ! Separates MATLAB interface pointers from computational data
245 type :: matlab_mex_handles
246 ! Function names
247 character(len=:), allocatable :: het_resid
248 character(len=:), allocatable :: het_jac
249 character(len=:), allocatable :: het_aux
250 character(len=:), allocatable :: agg_resid
251
252 ! Aggregate variables
253 type(c_ptr) :: y_mx = c_null_ptr
254 type(c_ptr) :: x_mx = c_null_ptr
255 type(c_ptr) :: yagg_mx = c_null_ptr
256 type(c_ptr) :: params_mx = c_null_ptr
257
258 ! Heterogeneous variables
259 type(c_ptr) :: yh_mx = c_null_ptr
260 type(c_ptr) :: xh_mx = c_null_ptr
261 type(c_ptr) :: paramsh_mx = c_null_ptr
262
263 ! Auxiliary variable computation
264 type(c_ptr) :: step_mx = c_null_ptr
265
266 ! Sparse Jacobian structure
267 type(c_ptr) :: rowval_mx = c_null_ptr
268 type(c_ptr) :: colval_mx = c_null_ptr
269 type(c_ptr) :: colptr_mx = c_null_ptr
270
271 ! Total number of Jacobian columns
272 integer(int32) :: dynamic_g1_ncols
273 end type matlab_mex_handles
274
275 ! Main input structure for steady-state computation
276 ! NOTE: Most arrays use POINTER instead of ALLOCATABLE to point directly
277 ! to MATLAB memory, avoiding unnecessary copies.
278 type :: calibration_input
279 type(tensor_grid_config), pointer :: tg_config => null()
280
281 ! Algorithm options (value types, assembled from MATLAB fields)
282 type(time_iteration_options), pointer :: ti_options => null()
283 type(distribution_options), pointer :: d_options => null()
284 type(solver_options), pointer :: solver_opts => null()
285
286 ! Calibration targets (unknown parameters)
287 integer(int32), pointer, contiguous :: free_parameters_ind(:) => null() ! Indices in params array
288 real(real64), pointer, contiguous :: free_parameters_init(:) => null() ! Initial guesses
289 real(real64), pointer, contiguous :: free_parameters_bounds(:,:) => null() ! Bounds [2 × n_free_parameters] (-Inf/+Inf for unbounded)
290
291 ! Policy functions
292 real(real64), allocatable :: old_pol(:,:) ! Policy from previous time iteration [n_het_endo × N_sp]
293 real(real64), allocatable :: old_pol_array(:,:,:) ! Transposed policy from previous time iteration [N_e × N_a × n_het_endo]
294 real(real64), allocatable :: weighted_old_pol(:,:) ! Policy from previous time iteration [N_sp × n_het_endo]
295 real(real64), allocatable :: new_pol(:,:) ! Updated policy [n_het_endo × N_sp]
296
297 ! Work arrays for the distribution forward iteration algorithm
298 real(real64), pointer, contiguous :: d_next(:)
299
300 ! Known aggregate steady-state values
301 real(real64), pointer, contiguous :: y(:) => null()
302 real(real64), pointer, contiguous :: x(:) => null()
303 real(real64), pointer, contiguous :: yagg(:) => null()
304
305 ! Grid point workspace (mutable state for time iteration)
306 type(grid_point_workspace) :: gp_ws
307
308 ! MATLAB MEX array handles (grouped for clarity)
309 type(matlab_mex_handles) :: mex
310
311 ! Aggregation indices from indices.Ix
312 integer(int32), pointer, contiguous :: Ix_in_agg(:) => null() ! indices.Ix.in_agg
313 integer(int32), pointer, contiguous :: Ix_in_het(:) => null() ! indices.Ix.in_het
314
315 ! Indices of calibration target equations
316 integer(int32), pointer, contiguous :: target_equations(:) => null() ! indices.target_equations
317
318 ! Model parameters
319 real(real64), pointer, contiguous :: params(:) => null()
320
321 ! Names for calibration free_parameters (from indices.free_parameters.names)
322 character(len=:), allocatable :: free_parameters_names(:) ! [n_free_parameters] - parameter names
323
324 ! Names for aggregate equations (from M_.equation_tags)
325 character(len=:), allocatable :: equation_names(:) ! [n_agg_endo] - equation names
326
327 ! Verbosity: 2 = verbose (print all), 1 = silent (print nothing)
328 integer(int32) :: forward_verbosity = 2
329 integer(int32) :: ti_verbosity = 2
330 integer(int32) :: cal_verbosity = 2
331
332 ! Model dimensions (consolidated)
333 type(model_dimensions) :: dims
334
335 ! State variable names from M_.heterogeneity(1).state_var
336 integer(int32), pointer, contiguous :: state_var(:) => null() ! [n_states] - indices of state variables
337
338 ! Sparse Jacobian structure from M_.heterogeneity(1)
339 ! Used for efficient solver Jacobian evaluation
340
341 ! Broyden solver workspace (for calibration)
342 ! Initialized once in compute_steady_state_tensor, reused across all calls
343 type(broyden_workspace) :: broyden_ws
344
345 ! Gray code cache for efficient expectation computation
346 ! - Forward-iteration algorithm
347 type(gray_code_cache), pointer :: gc_cache_fi => null()
348 ! - Interpolation of policy functions on the dense grid
349 type(gray_code_cache), pointer :: gc_cache_om => null()
350 ! - Next-period policy interpolation on the sparse grid
351 type(gray_code_cache), pointer :: gc_cache_next => null()
352 end type calibration_input
353
354 !---------------------------------------------------------------------------
355 ! Time iteration (backward) output
356 !---------------------------------------------------------------------------
357 type :: time_iteration_output
358 ! Policy functions [n_het_endo × N_sp/N_om]
359 real(real64), allocatable :: policies_sp(:,:)
360 real(real64), pointer, contiguous :: policies_om(:,:)
361
362 ! Convergence diagnostics
363 logical :: converged
364 integer(int32) :: iterations
365 real(real64) :: residual_norm ! Policy change norm (sup norm)
366 end type time_iteration_output
367
368 !---------------------------------------------------------------------------
369 ! Distribution (forward iteration) output
370 !---------------------------------------------------------------------------
371 type :: distribution_output
372 ! Stationary distribution [N_sp]
373 real(real64), pointer, contiguous :: distribution(:) => null()
374
375 ! Convergence diagnostics
376 logical :: converged
377 integer(int32) :: iterations
378 real(real64) :: residual_norm ! Distribution change norm
379 end type distribution_output
380
381 !---------------------------------------------------------------------------
382 ! Aggregation output
383 !---------------------------------------------------------------------------
384 type :: aggregation_output
385 ! Full aggregation of all heterogeneous endogenous variables [n_het_endo]
386 ! Ix_j = sum_i D_i * policy_j(state_i)
387 real(real64), allocatable :: Ix(:)
388
389 ! Full aggregate residuals (all aggregate equations) [n_agg_endo]
390 real(real64), allocatable :: residuals(:)
391 end type aggregation_output
392
393 !---------------------------------------------------------------------------
394 ! Calibration output (master output structure)
395 !---------------------------------------------------------------------------
396 type :: calibration_output
397 ! Sub-outputs (pointers to instances declared in calling scope)
398 type(time_iteration_output), pointer :: ti_output => null()
399 type(distribution_output), pointer :: dist_output => null()
400 type(aggregation_output), pointer :: agg_output => null()
401
402 ! Calibrated parameters [n_free_parameters]
403 real(real64), allocatable :: params(:)
404
405 ! Calibration target equations residuals [n_target_eqs]
406 real(real64), allocatable :: residuals(:)
407
408 ! Convergence info (for calibration loop)
409 logical :: converged
410 integer(int32) :: iterations
411 real(real64) :: residual_norm
412 end type calibration_output
413
414 end module calibration_types