1 #ifndef VIENNA_RNA_PACKAGE_DP_MATRICES_H 2 #define VIENNA_RNA_PACKAGE_DP_MATRICES_H 3 4 /** 5 * @file dp_matrices.h 6 * @ingroup data_structures 7 * @brief Functions to deal with standard dynamic programming (DP) matrices 8 */ 9 10 /** 11 * @addtogroup dp_matrices The Dynamic Programming Matrices 12 * @{ 13 * 14 * @brief This module provides interfaces that deal with creation and destruction of 15 * dynamic programming matrices used within the RNAlib. 16 * 17 */ 18 19 /** @brief Typename for the Minimum Free Energy (MFE) DP matrices data structure #vrna_mx_mfe_s */ 20 typedef struct vrna_mx_mfe_s vrna_mx_mfe_t; 21 /** @brief Typename for the Partition Function (PF) DP matrices data structure #vrna_mx_pf_s */ 22 typedef struct vrna_mx_pf_s vrna_mx_pf_t; 23 24 #include <ViennaRNA/datastructures/basic.h> 25 #include <ViennaRNA/fold_compound.h> 26 27 /** 28 * @brief An enumerator that is used to specify the type of a polymorphic Dynamic Programming (DP) 29 * matrix data structure 30 * @see #vrna_mx_mfe_t, #vrna_mx_pf_t 31 */ 32 typedef enum { 33 VRNA_MX_DEFAULT, /**< @brief Default DP matrices */ 34 VRNA_MX_WINDOW, /**< @brief DP matrices suitable for local structure prediction using 35 * window approach. 36 * @see vrna_mfe_window(), vrna_mfe_window_zscore(), pfl_fold() 37 */ 38 VRNA_MX_2DFOLD /**< @brief DP matrices suitable for distance class partitioned structure prediction 39 * @see vrna_mfe_TwoD(), vrna_pf_TwoD() 40 */ 41 } vrna_mx_type_e; 42 43 /** 44 * @brief Minimum Free Energy (MFE) Dynamic Programming (DP) matrices data structure required within the #vrna_fold_compound_t 45 */ 46 struct vrna_mx_mfe_s { 47 /** @name Common fields for MFE matrices 48 * @{ 49 */ 50 vrna_mx_type_e type; 51 unsigned int length; /**< @brief Length of the sequence, therefore an indicator of the size of the DP matrices */ 52 /** 53 * @} 54 */ 55 56 #ifndef VRNA_DISABLE_C11_FEATURES 57 /* C11 support for unnamed unions/structs */ 58 union { 59 struct { 60 #endif 61 /** @name Default DP matrices 62 * @note These data fields are available if 63 * @code vrna_mx_mfe_t.type == VRNA_MX_DEFAULT @endcode 64 * @{ 65 */ 66 int *c; /**< @brief Energy array, given that i-j pair */ 67 int *f5; /**< @brief Energy of 5' end */ 68 int *f3; /**< @brief Energy of 3' end */ 69 int *fc; /**< @brief Energy from i to cutpoint (and vice versa if i>cut) */ 70 int *fML; /**< @brief Multi-loop auxiliary energy array */ 71 int *fM1; /**< @brief Second ML array, only for unique multibrnach loop decomposition */ 72 int *fM2; /**< @brief Energy for a multibranch loop region with exactly two stems, extending to 3' end */ 73 int *ggg; /**< @brief Energies of g-quadruplexes */ 74 int Fc; /**< @brief Minimum Free Energy of entire circular RNA */ 75 int FcH; 76 int FcI; 77 int FcM; 78 /** 79 * @} 80 */ 81 82 #ifndef VRNA_DISABLE_C11_FEATURES 83 /* C11 support for unnamed unions/structs */ 84 }; 85 struct { 86 #endif 87 /** @name Local Folding DP matrices using window approach 88 * @note These data fields are available if 89 * @code vrna_mx_mfe_t.type == VRNA_MX_WINDOW @endcode 90 * @{ 91 */ 92 int **c_local; /**< @brief Energy array, given that i-j pair */ 93 int *f3_local; /**< @brief Energy of 5' end */ 94 int **fML_local; /**< @brief Multi-loop auxiliary energy array */ 95 int **ggg_local; /**< @brief Energies of g-quadruplexes */ 96 /** 97 * @} 98 */ 99 #ifndef VRNA_DISABLE_C11_FEATURES 100 /* C11 support for unnamed unions/structs */ 101 }; 102 struct { 103 #endif 104 105 /** @name Distance Class DP matrices 106 * @note These data fields are available if 107 * @code vrna_mx_mfe_t.type == VRNA_MX_2DFOLD @endcode 108 * @{ 109 */ 110 int ***E_F5; 111 int **l_min_F5; 112 int **l_max_F5; 113 int *k_min_F5; 114 int *k_max_F5; 115 116 int ***E_F3; 117 int **l_min_F3; 118 int **l_max_F3; 119 int *k_min_F3; 120 int *k_max_F3; 121 122 int ***E_C; 123 int **l_min_C; 124 int **l_max_C; 125 int *k_min_C; 126 int *k_max_C; 127 128 int ***E_M; 129 int **l_min_M; 130 int **l_max_M; 131 int *k_min_M; 132 int *k_max_M; 133 134 int ***E_M1; 135 int **l_min_M1; 136 int **l_max_M1; 137 int *k_min_M1; 138 int *k_max_M1; 139 140 int ***E_M2; 141 int **l_min_M2; 142 int **l_max_M2; 143 int *k_min_M2; 144 int *k_max_M2; 145 146 int **E_Fc; 147 int *l_min_Fc; 148 int *l_max_Fc; 149 int k_min_Fc; 150 int k_max_Fc; 151 152 int **E_FcH; 153 int *l_min_FcH; 154 int *l_max_FcH; 155 int k_min_FcH; 156 int k_max_FcH; 157 158 int **E_FcI; 159 int *l_min_FcI; 160 int *l_max_FcI; 161 int k_min_FcI; 162 int k_max_FcI; 163 164 int **E_FcM; 165 int *l_min_FcM; 166 int *l_max_FcM; 167 int k_min_FcM; 168 int k_max_FcM; 169 170 /* auxilary arrays for remaining set of coarse graining (k,l) > (k_max, l_max) */ 171 int *E_F5_rem; 172 int *E_F3_rem; 173 int *E_C_rem; 174 int *E_M_rem; 175 int *E_M1_rem; 176 int *E_M2_rem; 177 178 int E_Fc_rem; 179 int E_FcH_rem; 180 int E_FcI_rem; 181 int E_FcM_rem; 182 183 #ifdef COUNT_STATES 184 unsigned long ***N_F5; 185 unsigned long ***N_C; 186 unsigned long ***N_M; 187 unsigned long ***N_M1; 188 #endif 189 190 /** 191 * @} 192 */ 193 194 #ifndef VRNA_DISABLE_C11_FEATURES 195 /* C11 support for unnamed unions/structs */ 196 }; 197 }; 198 #endif 199 }; 200 201 /** 202 * @brief Partition function (PF) Dynamic Programming (DP) matrices data structure required within the #vrna_fold_compound_t 203 */ 204 struct vrna_mx_pf_s { 205 /** @name Common fields for DP matrices 206 * @{ 207 */ 208 vrna_mx_type_e type; 209 unsigned int length; 210 FLT_OR_DBL *scale; 211 FLT_OR_DBL *expMLbase; 212 213 214 /** 215 * @} 216 */ 217 218 #ifndef VRNA_DISABLE_C11_FEATURES 219 /* C11 support for unnamed unions/structs */ 220 union { 221 struct { 222 #endif 223 224 /** @name Default PF matrices 225 * @note These data fields are available if 226 * @code vrna_mx_pf_t.type == VRNA_MX_DEFAULT @endcode 227 * @{ 228 */ 229 FLT_OR_DBL *q; 230 FLT_OR_DBL *qb; 231 FLT_OR_DBL *qm; 232 FLT_OR_DBL *qm1; 233 FLT_OR_DBL *probs; 234 FLT_OR_DBL *q1k; 235 FLT_OR_DBL *qln; 236 FLT_OR_DBL *G; 237 238 FLT_OR_DBL qo; 239 FLT_OR_DBL *qm2; 240 FLT_OR_DBL qho; 241 FLT_OR_DBL qio; 242 FLT_OR_DBL qmo; 243 244 /** 245 * @} 246 */ 247 248 #ifndef VRNA_DISABLE_C11_FEATURES 249 /* C11 support for unnamed unions/structs */ 250 }; 251 struct { 252 #endif 253 254 /** @name Local Folding DP matrices using window approach 255 * @note These data fields are available if 256 * @code vrna_mx_mfe_t.type == VRNA_MX_WINDOW @endcode 257 * @{ 258 */ 259 FLT_OR_DBL **q_local; 260 FLT_OR_DBL **qb_local; 261 FLT_OR_DBL **qm_local; 262 FLT_OR_DBL **pR; 263 FLT_OR_DBL **qm2_local; 264 FLT_OR_DBL **QI5; 265 FLT_OR_DBL **q2l; 266 FLT_OR_DBL **qmb; 267 FLT_OR_DBL **G_local; 268 /** 269 * @} 270 */ 271 272 #ifndef VRNA_DISABLE_C11_FEATURES 273 /* C11 support for unnamed unions/structs */ 274 }; 275 struct { 276 #endif 277 278 /** @name Distance Class DP matrices 279 * @note These data fields are available if 280 * @code vrna_mx_pf_t.type == VRNA_MX_2DFOLD @endcode 281 * @{ 282 */ 283 FLT_OR_DBL ***Q; 284 int **l_min_Q; 285 int **l_max_Q; 286 int *k_min_Q; 287 int *k_max_Q; 288 289 290 FLT_OR_DBL ***Q_B; 291 int **l_min_Q_B; 292 int **l_max_Q_B; 293 int *k_min_Q_B; 294 int *k_max_Q_B; 295 296 FLT_OR_DBL ***Q_M; 297 int **l_min_Q_M; 298 int **l_max_Q_M; 299 int *k_min_Q_M; 300 int *k_max_Q_M; 301 302 FLT_OR_DBL ***Q_M1; 303 int **l_min_Q_M1; 304 int **l_max_Q_M1; 305 int *k_min_Q_M1; 306 int *k_max_Q_M1; 307 308 FLT_OR_DBL ***Q_M2; 309 int **l_min_Q_M2; 310 int **l_max_Q_M2; 311 int *k_min_Q_M2; 312 int *k_max_Q_M2; 313 314 FLT_OR_DBL **Q_c; 315 int *l_min_Q_c; 316 int *l_max_Q_c; 317 int k_min_Q_c; 318 int k_max_Q_c; 319 320 FLT_OR_DBL **Q_cH; 321 int *l_min_Q_cH; 322 int *l_max_Q_cH; 323 int k_min_Q_cH; 324 int k_max_Q_cH; 325 326 FLT_OR_DBL **Q_cI; 327 int *l_min_Q_cI; 328 int *l_max_Q_cI; 329 int k_min_Q_cI; 330 int k_max_Q_cI; 331 332 FLT_OR_DBL **Q_cM; 333 int *l_min_Q_cM; 334 int *l_max_Q_cM; 335 int k_min_Q_cM; 336 int k_max_Q_cM; 337 338 /* auxilary arrays for remaining set of coarse graining (k,l) > (k_max, l_max) */ 339 FLT_OR_DBL *Q_rem; 340 FLT_OR_DBL *Q_B_rem; 341 FLT_OR_DBL *Q_M_rem; 342 FLT_OR_DBL *Q_M1_rem; 343 FLT_OR_DBL *Q_M2_rem; 344 345 FLT_OR_DBL Q_c_rem; 346 FLT_OR_DBL Q_cH_rem; 347 FLT_OR_DBL Q_cI_rem; 348 FLT_OR_DBL Q_cM_rem; 349 /** 350 * @} 351 */ 352 353 #ifndef VRNA_DISABLE_C11_FEATURES 354 /* C11 support for unnamed unions/structs */ 355 }; 356 }; 357 #endif 358 }; 359 360 /** 361 * @brief Add Dynamic Programming (DP) matrices (allocate memory) 362 * 363 * This function adds DP matrices of a specific type to the provided 364 * #vrna_fold_compound_t, such that successive DP recursion can be applied. 365 * The function caller has to specify which type of DP matrix is requested, 366 * see #vrna_mx_type_e, and what kind of recursive algorithm will be applied 367 * later on, using the parameters type, and options, respectively. For the 368 * latter, Minimum free energy (MFE), and Partition function (PF) 369 * computations are distinguished. A third option that may be passed 370 * is #VRNA_OPTION_HYBRID, indicating that auxiliary DP arrays are 371 * required for RNA-RNA interaction prediction. 372 * 373 * @note Usually, there is no need to call this function, since 374 * the constructors of #vrna_fold_compound_t are handling all the DP 375 * matrix memory allocation. 376 * 377 * @see vrna_mx_mfe_add(), vrna_mx_pf_add(), vrna_fold_compound(), 378 * vrna_fold_compound_comparative(), vrna_fold_compound_free(), 379 * vrna_mx_pf_free(), vrna_mx_mfe_free(), #vrna_mx_type_e, 380 * #VRNA_OPTION_MFE, #VRNA_OPTION_PF, #VRNA_OPTION_HYBRID, #VRNA_OPTION_EVAL_ONLY 381 * 382 * @param vc The #vrna_fold_compound_t that holds pointers to the DP matrices 383 * @param type The type of DP matrices requested 384 * @param options Option flags that specify the kind of DP matrices, such 385 * as MFE or PF arrays, and auxiliary requirements 386 * @returns 1 if DP matrices were properly allocated and attached, 387 * 0 otherwise 388 */ 389 int 390 vrna_mx_add(vrna_fold_compound_t *vc, 391 vrna_mx_type_e type, 392 unsigned int options); 393 394 395 int 396 vrna_mx_mfe_add(vrna_fold_compound_t *vc, 397 vrna_mx_type_e mx_type, 398 unsigned int options); 399 400 401 int 402 vrna_mx_pf_add(vrna_fold_compound_t *vc, 403 vrna_mx_type_e mx_type, 404 unsigned int options); 405 406 407 int 408 vrna_mx_prepare(vrna_fold_compound_t *vc, 409 unsigned int options); 410 411 412 /** 413 * @brief Free memory occupied by the Minimum Free Energy (MFE) Dynamic Programming (DP) matrices 414 * 415 * @see vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_fold_compound_free(), vrna_mx_pf_free() 416 * 417 * @param vc The #vrna_fold_compound_t storing the MFE DP matrices that are to be erased from memory 418 */ 419 void 420 vrna_mx_mfe_free(vrna_fold_compound_t *vc); 421 422 423 /** 424 * @brief Free memory occupied by the Partition Function (PF) Dynamic Programming (DP) matrices 425 * 426 * @see vrna_fold_compound(), vrna_fold_compound_comparative(), vrna_fold_compound_free(), vrna_mx_mfe_free() 427 * 428 * @param vc The #vrna_fold_compound_t storing the PF DP matrices that are to be erased from memory 429 */ 430 void 431 vrna_mx_pf_free(vrna_fold_compound_t *vc); 432 433 434 /** 435 * @} 436 */ 437 438 #endif 439