| 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 |
} |