Debian Codegraph @

mex/sources/kalman_steady_state/kalman_steady_state.cc

raw
1 /*
2 * Copyright © 2009-2026 Dynare Team.
3 *
4 * This file is part of Dynare.
5 *
6 * Dynare is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation, either version 3 of the License, or
9 * (at your option) any later version.
10 *
11 * Dynare is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with Dynare. If not, see <https://www.gnu.org/licenses/>.
18 *
19 * This mex file calls fortran routines from the Slicot library.
20 */
21
22 /*
23 ++ INPUTS
24 ++ ======
25 ++
26 ++
27 ++ [0] T (double) n×n transition matrix.
28 ++
29 ++ [1] QQ (double) n×n matrix (=R·Q·Rᵀ, where Q is the covariance matrix of the
30 structural innovations).
31 ++
32 ++ [2] Z (double) n×p selection matrix.
33 ++
34 ++ [3] H (double) p×p covariance matrix of the measurement errors.
35 ++
36 ++
37 ++
38 ++
39 ++ OUTPUTS
40 ++ =======
41 ++
42 ++
43 ++ [0] P (double) n×n covariance matrix of the state vector.
44 ++
45 ++
46 ++ NOTES
47 ++ =====
48 ++
49 ++ [1] T = transpose(dynare transition matrix) and Z = transpose(dynare selection matrix).
50 */
51
52 #include <algorithm>
53 #include <dynlapack.h>
54 #include <dynmex.h>
55 #include <memory>
56
57 #define sb02od FORTRAN_WRAPPER(sb02od)
58
59 extern "C"
60 {
61 /* Note: matrices q, r and l may be modified internally (though they are
62 restored on exit), hence their pointers are not declared as const */
63 void sb02od(const char* dico, const char* jobb, const char* fact, const char* uplo,
64 const char* jobl, const char* sort, const lapack_int* n, const lapack_int* m,
65 const lapack_int* p, const double* a, const lapack_int* lda, const double* b,
66 const lapack_int* ldb, double* q, const lapack_int* ldq, double* r,
67 const lapack_int* ldr, double* l, const lapack_int* ldl, double* rcond, double* x,
68 const lapack_int* ldx, double* alfar, double* alfai, double* beta, double* s,
69 const lapack_int* lds, double* t, const lapack_int* ldt, double* u,
70 const lapack_int* ldu, const double* tol, lapack_int* iwork, double* dwork,
71 const lapack_int* ldwork, lapack_int* bwork, lapack_int* info);
72 }
73
74 void
75 mexFunction(int nlhs, mxArray* plhs[], int nrhs, const mxArray* prhs[])
76 {
77 // Check the number of arguments and set some flags.
78 bool measurement_error_flag = true;
79 if (nrhs < 3 || 4 < nrhs)
80 mexErrMsgTxt("kalman_steady_state accepts either 3 or 4 input arguments!");
81
82 if (nlhs != 1)
83 mexErrMsgTxt("kalman_steady_state accepts exactly one output argument!");
84
85 if (nrhs == 3)
86 measurement_error_flag = false;
87
88 // Check the type of the input arguments and get the size of the matrices.
89 lapack_int n = mxGetM(prhs[0]);
90 if (static_cast<size_t>(n) != mxGetN(prhs[0]))
91 mexErrMsgTxt("kalman_steady_state: The first input argument (T) must be a square matrix!");
92 if (mxIsNumeric(prhs[0]) == 0 || mxIsComplex(prhs[0]) == 1)
93 mexErrMsgTxt("kalman_steady_state: The first input argument (T) must be a real matrix!");
94
95 lapack_int q = mxGetM(prhs[1]);
96 if (static_cast<size_t>(q) != mxGetN(prhs[1]))
97 mexErrMsgTxt("kalman_steady_state: The second input argument (QQ) must be a square matrix!");
98 if (mxIsNumeric(prhs[1]) == 0 || mxIsComplex(prhs[1]) == 1)
99 mexErrMsgTxt("kalman_steady_state: The second input argument (QQ) must be a real matrix!");
100 if (q != n)
101 mexErrMsgTxt("kalman_steady_state: The size of the second input argument (QQ) must match the "
102 "size of the first argument (T)!");
103 lapack_int p = mxGetN(prhs[2]);
104 if (mxGetM(prhs[2]) != static_cast<size_t>(n))
105 mexErrMsgTxt("kalman_steady_state: The number of rows of the third argument (Z) must match the "
106 "number of rows of the first argument (T)!");
107 if (mxIsNumeric(prhs[2]) == 0 || mxIsComplex(prhs[2]) == 1)
108 mexErrMsgTxt("kalman_steady_state: The third input argument (Z) must be a real matrix!");
109 if (measurement_error_flag)
110 {
111 if (mxGetM(prhs[3]) != mxGetN(prhs[3]))
112 mexErrMsgTxt("kalman_steady_state: The fourth input argument (H) must be a square matrix!");
113 if (mxGetM(prhs[3]) != static_cast<size_t>(p))
114 mexErrMsgTxt("kalman_steady_state: The number of rows of the fourth input argument (H) "
115 "must match the number of rows of the third input argument!");
116 if (mxIsNumeric(prhs[3]) == 0 || mxIsComplex(prhs[3]) == 1)
117 mexErrMsgTxt("kalman_steady_state: The fifth input argument (H) must be a real matrix!");
118 }
119 // Get input matrices.
120 const double* T = mxGetDoubles(prhs[0]);
121 auto QQ = std::make_unique<double[]>(n * n);
122 std::ranges::copy_n(mxGetDoubles(prhs[1]), n * n, QQ.get());
123 const double* Z = mxGetDoubles(prhs[2]);
124 auto H = std::make_unique<double[]>(p * p);
125 if (measurement_error_flag)
126 std::ranges::copy_n(mxGetDoubles(prhs[3]), p * p, H.get());
127 // L will not be used.
128 auto L = std::make_unique<double[]>(n * p);
129 lapack_int nn = 2 * n;
130 lapack_int LDA = std::max(static_cast<lapack_int>(1), n);
131 lapack_int LDQ = LDA;
132 lapack_int LDU = std::max(static_cast<lapack_int>(1), nn);
133 lapack_int LDS = std::max(static_cast<lapack_int>(1), nn + p);
134 lapack_int LIWORK = std::max({static_cast<lapack_int>(1), p, nn});
135 lapack_int LDR = std::max(static_cast<lapack_int>(1), p);
136 lapack_int LDB = LDA, LDL = LDA, LDT = LDS, LDX = LDA;
137 lapack_int LDWORK = std::max(
138 static_cast<lapack_int>(7) * (static_cast<lapack_int>(2) * n + static_cast<lapack_int>(1))
139 + static_cast<lapack_int>(16),
140 static_cast<lapack_int>(16) * n);
141 LDWORK = std::max({LDWORK, static_cast<lapack_int>(2) * n + p, static_cast<lapack_int>(3) * p});
142 double tolerance = 1e-16;
143 lapack_int INFO;
144 // Outputs of subroutine sb02OD
145 double rcond;
146 auto WR = std::make_unique<double[]>(nn);
147 auto WI = std::make_unique<double[]>(nn);
148 auto BETA = std::make_unique<double[]>(nn);
149 auto S = std::make_unique<double[]>(LDS * (nn + p));
150 auto TT = std::make_unique<double[]>(LDT * nn);
151 auto UU = std::make_unique<double[]>(LDU * nn);
152 // Working arrays
153 auto IWORK = std::make_unique<lapack_int[]>(LIWORK);
154 auto DWORK = std::make_unique<double[]>(LDWORK);
155 auto BWORK = std::make_unique<lapack_int[]>(nn);
156 // Initialize the output of the mex file
157 plhs[0] = mxCreateDoubleMatrix(n, n, mxREAL);
158 double* P = mxGetDoubles(plhs[0]);
159 // Call the slicot routine
160 sb02od("D", // We want to solve a discrete Riccati equation.
161 "B", // Matrices Z and H are given.
162 "N", // Given matrices H and QQ are not factored.
163 "U", // Upper triangle of matrix H is stored.
164 "Z", // L matrix is zero.
165 "S", // Stable eigenvalues come first.
166 &n, &p, &p, T, &LDA, Z, &LDB, QQ.get(), &LDQ, H.get(), &LDR, L.get(), &LDL, &rcond, P,
167 &LDX, WR.get(), WI.get(), BETA.get(), S.get(), &LDS, TT.get(), &LDT, UU.get(), &LDU,
168 &tolerance, IWORK.get(), DWORK.get(), &LDWORK, BWORK.get(), &INFO);
169 switch (INFO)
170 {
171 case 0:
172 break;
173 case 1:
174 mexErrMsgTxt(
175 "The computed extended matrix pencil is singular, possibly due to rounding errors.");
176 break;
177 case 2:
178 mexErrMsgTxt("The QZ (or QR) algorithm failed!");
179 break;
180 case 3:
181 mexErrMsgTxt("The reordering of the (generalized) eigenvalues failed!");
182 break;
183 case 4:
184 mexErrMsgTxt("After reordering, roundoff changed values of some complex eigenvalues so that "
185 "leading eigenvalues\n in the (generalized) Schur form no longer satisfy the "
186 "stability condition; this could also be caused due to scaling.");
187 break;
188 case 5:
189 mexErrMsgTxt("The computed dimension of the solution does not equal n!");
190 break;
191 case 6:
192 mexErrMsgTxt(
193 "A singular matrix was encountered during the computation of the solution matrix P!");
194 break;
195 default:
196 mexErrMsgTxt("Unknown problem!");
197 }
198 }