1 #ifndef VIENNA_RNA_PACKAGE_BOLTZMANN_SAMPLING_H 2 #define VIENNA_RNA_PACKAGE_BOLTZMANN_SAMPLING_H 3 4 /** 5 * @file boltzmann_sampling.h 6 * @ingroup subopt_and_representatives 7 * @brief Boltzmann Sampling of secondary structures from the ensemble 8 * 9 * A.k.a. Stochastic backtracking 10 */ 11 12 13 /** 14 * @addtogroup subopt_stochbt 15 * @{ 16 * @brief Functions to draw random structure samples from the ensemble according to their 17 * equilibrium probability 18 */ 19 20 21 /** 22 * @brief Boltzmann sampling flag indicating default backtracing mode 23 * 24 * @see vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack5_resume(), 25 * vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_num(), vrna_pbacktrack_cb(), 26 * vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb() 27 */ 28 #define VRNA_PBACKTRACK_DEFAULT 0 29 30 /** 31 * @brief Boltzmann sampling flag indicating non-redundant backtracing mode 32 * 33 * This flag will turn the Boltzmann sampling into non-redundant backtracing 34 * mode along the lines of Michalik et al. 2017 @cite michalik:2017 35 * 36 * @see vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack5_resume(), 37 * vrna_pbacktrack5_resume_cb(), vrna_pbacktrack_num(), vrna_pbacktrack_cb(), 38 * vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb() 39 */ 40 #define VRNA_PBACKTRACK_NON_REDUNDANT 1 41 42 /** 43 * @brief Callback for Boltzmann sampling 44 * 45 * @callback 46 * @parblock 47 * This function will be called for each secondary structure that has been successfully backtraced 48 * from the partition function DP matrices. 49 * @endparblock 50 * 51 * @see vrna_pbacktrack5_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), 52 * vrna_pbacktrack_resume_cb() 53 * 54 * @param structure The secondary structure in dot-bracket notation 55 * @param data Some arbitrary, auxiliary data address as provided to the calling function 56 */ 57 typedef void (vrna_boltzmann_sampling_callback)(const char *stucture, 58 void *data); 59 60 /** 61 * @brief Boltzmann sampling memory data structure 62 * 63 * This structure is required for properly resuming a previous sampling round in 64 * specialized Boltzmann sampling, such as non-redundant backtracking. 65 * 66 * Initialize with @p NULL and pass its address to the corresponding 67 * functions vrna_pbacktrack5_resume(), etc. 68 * 69 * @note Do not forget to release memory occupied by this data structure before 70 * losing its context! Use vrna_pbacktrack_mem_free(). 71 * 72 * @see vrna_pbacktrack5_resume(), vrna_pbacktrack_resume(), vrna_pbacktrack5_resume_cb(), 73 * vrna_pbacktrack_resume_cb(), vrna_pbacktrack_mem_free() 74 */ 75 typedef struct vrna_pbacktrack_memory_s *vrna_pbacktrack_mem_t; 76 77 #include <ViennaRNA/fold_compound.h> 78 79 /** 80 * @brief Sample a secondary structure of a subsequence from the Boltzmann ensemble according its probability 81 * 82 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 83 * to obtain a secondary structure. The parameter @p length specifies the length 84 * of the substructure starting from the 5' end. 85 * 86 * The structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 87 * ensemble according to its probability 88 * @f[ 89 * p(s) = \frac{exp(-E(s) / kT)}{Z} 90 * @f] 91 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 92 * thermodynamic temperature @f$ T @f$. 93 * 94 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 95 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 96 * with vrna_md_t.uniq_ML = 1. 97 * @pre vrna_pf() has to be called first to fill the partition function matrices 98 * 99 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 100 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 101 * 102 * @see vrna_pbacktrack5_num(), vrna_pbacktrack5_cb(), vrna_pbacktrack() 103 * 104 * @param fc The fold compound data structure 105 * @param length The length of the subsequence to consider (starting with 5' end) 106 * @return A sampled secondary structure in dot-bracket notation (or NULL on error) 107 */ 108 char * 109 vrna_pbacktrack5(vrna_fold_compound_t *fc, 110 unsigned int length); 111 112 113 /** 114 * @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability 115 * 116 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 117 * to obtain a set of @p num_samples secondary structures. The parameter @p length specifies 118 * the length of the substructure starting from the 5' end. 119 * 120 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 121 * ensemble according to its probability 122 * @f[ 123 * p(s) = \frac{exp(-E(s) / kT)}{Z} 124 * @f] 125 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 126 * thermodynamic temperature @f$ T @f$. 127 * 128 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 129 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 130 * et al. 2017 @cite michalik:2017. 131 * 132 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 133 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 134 * with vrna_md_t.uniq_ML = 1. 135 * @pre vrna_pf() has to be called first to fill the partition function matrices 136 * 137 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 138 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 139 * 140 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 141 * not yield the full number of requested samples. This may happen if 142 * a) the number of requested structures is larger than the total number 143 * of structuresin the ensemble, 144 * b) numeric instabilities prevent the backtracking function to enumerate 145 * structures with high free energies, or 146 * c) any other error occurs. 147 * 148 * @see vrna_pbacktrack5(), vrna_pbacktrack5_cb(), vrna_pbacktrack_num(), 149 * #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT 150 * 151 * @param fc The fold compound data structure 152 * @param num_samples The size of the sample set, i.e. number of structures 153 * @param length The length of the subsequence to consider (starting with 5' end) 154 * @param options A bitwise OR-flag indicating the backtracing mode. 155 * @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) 156 */ 157 char ** 158 vrna_pbacktrack5_num(vrna_fold_compound_t *fc, 159 unsigned int num_samples, 160 unsigned int length, 161 unsigned int options); 162 163 164 /** 165 * @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability 166 * 167 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 168 * to obtain a set of @p num_samples secondary structures. The parameter @p length specifies 169 * the length of the substructure starting from the 5' end. 170 * 171 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 172 * ensemble according to its probability 173 * @f[ 174 * p(s) = \frac{exp(-E(s) / kT)}{Z} 175 * @f] 176 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 177 * thermodynamic temperature @f$ T @f$. 178 * 179 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 180 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 181 * et al. 2017 @cite michalik:2017. 182 * 183 * In contrast to vrna_pbacktrack5() and vrna_pbacktrack5_num() this function yields the 184 * structure samples through a callback mechanism. 185 * 186 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 187 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 188 * with vrna_md_t.uniq_ML = 1. 189 * @pre vrna_pf() has to be called first to fill the partition function matrices 190 * 191 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 192 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 193 * 194 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 195 * not yield the full number of requested samples. This may happen if 196 * a) the number of requested structures is larger than the total number 197 * of structuresin the ensemble, 198 * b) numeric instabilities prevent the backtracking function to enumerate 199 * structures with high free energies, or 200 * c) any other error occurs. 201 * 202 * @see vrna_pbacktrack5(), vrna_pbacktrack5_num(), vrna_pbacktrack_cb(), 203 * #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT 204 * 205 * @param fc The fold compound data structure 206 * @param num_samples The size of the sample set, i.e. number of structures 207 * @param length The length of the subsequence to consider (starting with 5' end) 208 * @param cb The callback that receives the sampled structure 209 * @param data A data structure passed through to the callback @p cb 210 * @param options A bitwise OR-flag indicating the backtracing mode. 211 * @return The number of structures actually backtraced 212 */ 213 unsigned int 214 vrna_pbacktrack5_cb(vrna_fold_compound_t *fc, 215 unsigned int num_samples, 216 unsigned int length, 217 vrna_boltzmann_sampling_callback *cb, 218 void *data, 219 unsigned int options); 220 221 222 /** 223 * @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability 224 * 225 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 226 * to obtain a set of @p num_samples secondary structures. The parameter @p length specifies 227 * the length of the substructure starting from the 5' end. 228 * 229 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 230 * ensemble according to its probability 231 * @f[ 232 * p(s) = \frac{exp(-E(s) / kT)}{Z} 233 * @f] 234 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 235 * thermodynamic temperature @f$ T @f$. 236 * 237 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 238 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 239 * et al. 2017 @cite michalik:2017. 240 * 241 * In contrast to vrna_pbacktrack5_cb() this function allows for resuming a previous 242 * sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. 243 * For that purpose, the user passes the address of a Boltzmann sampling data structure 244 * (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each 245 * successive call to vrna_pbacktrack5_resume_cb() or vrna_pbacktrack5_resume(). 246 * 247 * A successive sample call to this function may look like: 248 * @code{.c} 249 * vrna_pbacktrack_mem_t nonredundant_memory = NULL; 250 * 251 * // sample the first 100 structures 252 * vrna_pbacktrack5_resume(fc, 253 * 100, 254 * fc->length, 255 * &nonredundant_memory, 256 * options); 257 * 258 * // sample another 500 structures 259 * vrna_pbacktrack5_resume(fc, 260 * 500, 261 * fc->length, 262 * &nonredundant_memory, 263 * options); 264 * 265 * // release memory occupied by the non-redundant memory data structure 266 * vrna_pbacktrack_mem_free(nonredundant_memory); 267 * @endcode 268 * 269 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 270 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 271 * with vrna_md_t.uniq_ML = 1. 272 * @pre vrna_pf() has to be called first to fill the partition function matrices 273 * 274 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 275 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 276 * 277 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 278 * not yield the full number of requested samples. This may happen if 279 * a) the number of requested structures is larger than the total number 280 * of structuresin the ensemble, 281 * b) numeric instabilities prevent the backtracking function to enumerate 282 * structures with high free energies, or 283 * c) any other error occurs. 284 * 285 * @see vrna_pbacktrack5_resume_cb(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume(), 286 * #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, 287 * vrna_pbacktrack_mem_free 288 * 289 * @param fc The fold compound data structure 290 * @param num_samples The size of the sample set, i.e. number of structures 291 * @param length The length of the subsequence to consider (starting with 5' end) 292 * @param nr_mem The address of the Boltzmann sampling memory data structure 293 * @param options A bitwise OR-flag indicating the backtracing mode. 294 * @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) 295 */ 296 char ** 297 vrna_pbacktrack5_resume(vrna_fold_compound_t *vc, 298 unsigned int num_samples, 299 unsigned int length, 300 vrna_pbacktrack_mem_t *nr_mem, 301 unsigned int options); 302 303 304 /** 305 * @brief Obtain a set of secondary structure samples for a subsequence from the Boltzmann ensemble according their probability 306 * 307 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 308 * to obtain a set of @p num_samples secondary structures. The parameter @p length specifies 309 * the length of the substructure starting from the 5' end. 310 * 311 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 312 * ensemble according to its probability 313 * @f[ 314 * p(s) = \frac{exp(-E(s) / kT)}{Z} 315 * @f] 316 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 317 * thermodynamic temperature @f$ T @f$. 318 * 319 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 320 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 321 * et al. 2017 @cite michalik:2017. 322 * 323 * In contrast to vrna_pbacktrack5_resume() this function yields the structure samples 324 * through a callback mechanism. 325 * 326 * A successive sample call to this function may look like: 327 * @code{.c} 328 * vrna_pbacktrack_mem_t nonredundant_memory = NULL; 329 * 330 * // sample the first 100 structures 331 * vrna_pbacktrack5_resume_cb(fc, 332 * 100, 333 * fc->length, 334 * &callback_function, 335 * (void *)&callback_data, 336 * &nonredundant_memory, 337 * options); 338 * 339 * // sample another 500 structures 340 * vrna_pbacktrack5_resume_cb(fc, 341 * 500, 342 * fc->length, 343 * &callback_function, 344 * (void *)&callback_data, 345 * &nonredundant_memory, 346 * options); 347 * 348 * // release memory occupied by the non-redundant memory data structure 349 * vrna_pbacktrack_mem_free(nonredundant_memory); 350 * @endcode 351 * 352 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 353 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 354 * with vrna_md_t.uniq_ML = 1. 355 * @pre vrna_pf() has to be called first to fill the partition function matrices 356 * 357 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 358 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 359 * 360 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 361 * not yield the full number of requested samples. This may happen if 362 * a) the number of requested structures is larger than the total number 363 * of structuresin the ensemble, 364 * b) numeric instabilities prevent the backtracking function to enumerate 365 * structures with high free energies, or 366 * c) any other error occurs. 367 * 368 * @see vrna_pbacktrack5_resume(), vrna_pbacktrack5_cb(), vrna_pbacktrack_resume_cb(), 369 * #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, 370 * vrna_pbacktrack_mem_free 371 * 372 * @param fc The fold compound data structure 373 * @param num_samples The size of the sample set, i.e. number of structures 374 * @param length The length of the subsequence to consider (starting with 5' end) 375 * @param cb The callback that receives the sampled structure 376 * @param data A data structure passed through to the callback @p cb 377 * @param nr_mem The address of the Boltzmann sampling memory data structure 378 * @param options A bitwise OR-flag indicating the backtracing mode. 379 * @return The number of structures actually backtraced 380 */ 381 unsigned int 382 vrna_pbacktrack5_resume_cb(vrna_fold_compound_t *fc, 383 unsigned int num_samples, 384 unsigned int length, 385 vrna_boltzmann_sampling_callback *cb, 386 void *data, 387 vrna_pbacktrack_mem_t *nr_mem, 388 unsigned int options); 389 390 391 /** 392 * @brief Sample a secondary structure from the Boltzmann ensemble according its probability 393 * 394 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 395 * to obtain a secondary structure. 396 * 397 * The structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 398 * ensemble according to its probability 399 * @f[ 400 * p(s) = \frac{exp(-E(s) / kT)}{Z} 401 * @f] 402 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 403 * thermodynamic temperature @f$ T @f$. 404 * 405 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 406 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 407 * with vrna_md_t.uniq_ML = 1. 408 * @pre vrna_pf() has to be called first to fill the partition function matrices 409 * 410 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 411 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 412 * 413 * @see vrna_pbacktrack5(), vrna_pbacktrack_num, vrna_pbacktrack_cb() 414 * 415 * @param fc The fold compound data structure 416 * @return A sampled secondary structure in dot-bracket notation (or NULL on error) 417 */ 418 char * 419 vrna_pbacktrack(vrna_fold_compound_t *fc); 420 421 422 /** 423 * @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability 424 * 425 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 426 * to obtain a set of @p num_samples secondary structures. 427 * 428 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 429 * ensemble according to its probability 430 * @f[ 431 * p(s) = \frac{exp(-E(s) / kT)}{Z} 432 * @f] 433 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 434 * thermodynamic temperature @f$ T @f$. 435 * 436 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 437 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 438 * et al. 2017 @cite michalik:2017. 439 * 440 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 441 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 442 * with vrna_md_t.uniq_ML = 1. 443 * @pre vrna_pf() has to be called first to fill the partition function matrices 444 * 445 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 446 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 447 * 448 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 449 * not yield the full number of requested samples. This may happen if 450 * a) the number of requested structures is larger than the total number 451 * of structuresin the ensemble, 452 * b) numeric instabilities prevent the backtracking function to enumerate 453 * structures with high free energies, or 454 * c) any other error occurs. 455 * 456 * @see vrna_pbacktrack(), vrna_pbacktrack_cb(), vrna_pbacktrack5_num(), 457 * #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT 458 * 459 * @param fc The fold compound data structure 460 * @param num_samples The size of the sample set, i.e. number of structures 461 * @param options A bitwise OR-flag indicating the backtracing mode. 462 * @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) 463 */ 464 char ** 465 vrna_pbacktrack_num(vrna_fold_compound_t *fc, 466 unsigned int num_samples, 467 unsigned int options); 468 469 470 /** 471 * @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability 472 * 473 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 474 * to obtain a set of @p num_samples secondary structures. 475 * 476 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 477 * ensemble according to its probability 478 * @f[ 479 * p(s) = \frac{exp(-E(s) / kT)}{Z} 480 * @f] 481 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 482 * thermodynamic temperature @f$ T @f$. 483 * 484 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 485 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 486 * et al. 2017 @cite michalik:2017. 487 * 488 * In contrast to vrna_pbacktrack() and vrna_pbacktrack_num() this function yields the 489 * structure samples through a callback mechanism. 490 * 491 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 492 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 493 * with vrna_md_t.uniq_ML = 1. 494 * @pre vrna_pf() has to be called first to fill the partition function matrices 495 * 496 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 497 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 498 * 499 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 500 * not yield the full number of requested samples. This may happen if 501 * a) the number of requested structures is larger than the total number 502 * of structuresin the ensemble, 503 * b) numeric instabilities prevent the backtracking function to enumerate 504 * structures with high free energies, or 505 * c) any other error occurs. 506 * 507 * @see vrna_pbacktrack(), vrna_pbacktrack_num(), vrna_pbacktrack5_cb(), 508 * #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT 509 * 510 * @param fc The fold compound data structure 511 * @param num_samples The size of the sample set, i.e. number of structures 512 * @param cb The callback that receives the sampled structure 513 * @param data A data structure passed through to the callback @p cb 514 * @param options A bitwise OR-flag indicating the backtracing mode. 515 * @return The number of structures actually backtraced 516 */ 517 unsigned int 518 vrna_pbacktrack_cb(vrna_fold_compound_t *fc, 519 unsigned int num_samples, 520 vrna_boltzmann_sampling_callback *cb, 521 void *data, 522 unsigned int options); 523 524 525 /** 526 * @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability 527 * 528 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 529 * to obtain a set of @p num_samples secondary structures. 530 * 531 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 532 * ensemble according to its probability 533 * @f[ 534 * p(s) = \frac{exp(-E(s) / kT)}{Z} 535 * @f] 536 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 537 * thermodynamic temperature @f$ T @f$. 538 * 539 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 540 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 541 * et al. 2017 @cite michalik:2017. 542 * 543 * In contrast to vrna_pbacktrack_cb() this function allows for resuming a previous 544 * sampling round in specialized Boltzmann sampling, such as non-redundant backtracking. 545 * For that purpose, the user passes the address of a Boltzmann sampling data structure 546 * (#vrna_pbacktrack_mem_t) which will be re-used in each round of sampling, i.e. each 547 * successive call to vrna_pbacktrack_resume_cb() or vrna_pbacktrack_resume(). 548 * 549 * A successive sample call to this function may look like: 550 * @code{.c} 551 * vrna_pbacktrack_mem_t nonredundant_memory = NULL; 552 * 553 * // sample the first 100 structures 554 * vrna_pbacktrack_resume(fc, 555 * 100, 556 * &nonredundant_memory, 557 * options); 558 * 559 * // sample another 500 structures 560 * vrna_pbacktrack_resume(fc, 561 * 500, 562 * &nonredundant_memory, 563 * options); 564 * 565 * // release memory occupied by the non-redundant memory data structure 566 * vrna_pbacktrack_mem_free(nonredundant_memory); 567 * @endcode 568 * 569 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 570 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 571 * with vrna_md_t.uniq_ML = 1. 572 * @pre vrna_pf() has to be called first to fill the partition function matrices 573 * 574 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 575 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 576 * 577 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 578 * not yield the full number of requested samples. This may happen if 579 * a) the number of requested structures is larger than the total number 580 * of structuresin the ensemble, 581 * b) numeric instabilities prevent the backtracking function to enumerate 582 * structures with high free energies, or 583 * c) any other error occurs. 584 * 585 * @see vrna_pbacktrack_resume_cb(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume(), 586 * #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, 587 * vrna_pbacktrack_mem_free 588 * 589 * @param fc The fold compound data structure 590 * @param num_samples The size of the sample set, i.e. number of structures 591 * @param nr_mem The address of the Boltzmann sampling memory data structure 592 * @param options A bitwise OR-flag indicating the backtracing mode. 593 * @return A set of secondary structure samples in dot-bracket notation terminated by NULL (or NULL on error) 594 */ 595 char ** 596 vrna_pbacktrack_resume(vrna_fold_compound_t *fc, 597 unsigned int num_samples, 598 vrna_pbacktrack_mem_t *nr_mem, 599 unsigned int options); 600 601 602 /** 603 * @brief Obtain a set of secondary structure samples from the Boltzmann ensemble according their probability 604 * 605 * Perform a probabilistic (stochastic) backtracing in the partition function DP arrays 606 * to obtain a set of @p num_samples secondary structures. 607 * 608 * Any structure @f$ s @f$ with free energy @f$ E(s) @f$ is picked from the Boltzmann distributed 609 * ensemble according to its probability 610 * @f[ 611 * p(s) = \frac{exp(-E(s) / kT)}{Z} 612 * @f] 613 * with partition function @f$ Z = \sum_s exp(-E(s) / kT) @f$, Boltzmann constant @f$ k @f$ and 614 * thermodynamic temperature @f$ T @f$. 615 * 616 * Using the @p options flag one can switch between regular (#VRNA_PBACKTRACK_DEFAULT) backtracing 617 * mode, and non-redundant sampling (#VRNA_PBACKTRACK_NON_REDUNDANT) along the lines of Michalik 618 * et al. 2017 @cite michalik:2017. 619 * 620 * In contrast to vrna_pbacktrack5_resume() this function yields the structure samples 621 * through a callback mechanism. 622 * 623 * A successive sample call to this function may look like: 624 * @code{.c} 625 * vrna_pbacktrack_mem_t nonredundant_memory = NULL; 626 * 627 * // sample the first 100 structures 628 * vrna_pbacktrack5_resume_cb(fc, 629 * 100, 630 * &callback_function, 631 * (void *)&callback_data, 632 * &nonredundant_memory, 633 * options); 634 * 635 * // sample another 500 structures 636 * vrna_pbacktrack5_resume_cb(fc, 637 * 500, 638 * &callback_function, 639 * (void *)&callback_data, 640 * &nonredundant_memory, 641 * options); 642 * 643 * // release memory occupied by the non-redundant memory data structure 644 * vrna_pbacktrack_mem_free(nonredundant_memory); 645 * @endcode 646 * 647 * @pre Unique multiloop decomposition has to be active upon creation of @p fc with vrna_fold_compound() 648 * or similar. This can be done easily by passing vrna_fold_compound() a model details parameter 649 * with vrna_md_t.uniq_ML = 1. 650 * @pre vrna_pf() has to be called first to fill the partition function matrices 651 * 652 * @note This function is polymorphic. It accepts #vrna_fold_compound_t of type 653 * #VRNA_FC_TYPE_SINGLE, and #VRNA_FC_TYPE_COMPARATIVE. 654 * 655 * @warning In non-redundant sampling mode (#VRNA_PBACKTRACK_NON_REDUNDANT), this function may 656 * not yield the full number of requested samples. This may happen if 657 * a) the number of requested structures is larger than the total number 658 * of structuresin the ensemble, 659 * b) numeric instabilities prevent the backtracking function to enumerate 660 * structures with high free energies, or 661 * c) any other error occurs. 662 * 663 * @see vrna_pbacktrack_resume(), vrna_pbacktrack_cb(), vrna_pbacktrack5_resume_cb(), 664 * #vrna_pbacktrack_mem_t, #VRNA_PBACKTRACK_DEFAULT, #VRNA_PBACKTRACK_NON_REDUNDANT, 665 * vrna_pbacktrack_mem_free 666 * 667 * @param fc The fold compound data structure 668 * @param num_samples The size of the sample set, i.e. number of structures 669 * @param cb The callback that receives the sampled structure 670 * @param data A data structure passed through to the callback @p cb 671 * @param nr_mem The address of the Boltzmann sampling memory data structure 672 * @param options A bitwise OR-flag indicating the backtracing mode. 673 * @return The number of structures actually backtraced 674 */ 675 unsigned int 676 vrna_pbacktrack_resume_cb(vrna_fold_compound_t *fc, 677 unsigned int num_samples, 678 vrna_boltzmann_sampling_callback *cb, 679 void *data, 680 vrna_pbacktrack_mem_t *nr_mem, 681 unsigned int options); 682 683 684 /** 685 * @brief Release memory occupied by a Boltzmann sampling memory data structure 686 * 687 * @see #vrna_pbacktrack_mem_t, vrna_pbacktrack5_resume(), vrna_pbacktrack5_resume_cb(), 688 * vrna_pbacktrack_resume(), vrna_pbacktrack_resume_cb() 689 * 690 * @param s The non-redundancy memory data structure 691 */ 692 void 693 vrna_pbacktrack_mem_free(vrna_pbacktrack_mem_t s); 694 695 696 /**@}*/ 697 698 699 #endif 700