1 #ifndef VIENNA_RNA_PACKAGE_WALK_H 2 #define VIENNA_RNA_PACKAGE_WALK_H 3 4 /** 5 * @file ViennaRNA/landscape/walk.h 6 * @ingroup paths 7 * @brief Methods to generate particular paths such as gradient or random walks through the energy landscape of an RNA sequence 8 * 9 */ 10 11 #include <ViennaRNA/fold_compound.h> 12 #include <ViennaRNA/landscape/move.h> 13 14 /** 15 * @addtogroup paths_walk 16 * @{ 17 * @brief Implementation of gradient- and random walks starting from a single secondary structure 18 */ 19 20 /** 21 * @brief Option flag to request a steepest descent / gradient path 22 * @see vrna_path() 23 */ 24 #define VRNA_PATH_STEEPEST_DESCENT 128 25 26 /** 27 * @brief Option flag to request a random walk path 28 * @see vrna_path() 29 */ 30 #define VRNA_PATH_RANDOM 256 31 32 /** 33 * @brief Option flag to omit returning the transition path 34 * @see vrna_path(), vrna_path_gradient(), vrna_path_random() 35 */ 36 #define VRNA_PATH_NO_TRANSITION_OUTPUT 512 37 38 /** 39 * @brief Option flag to request defaults (steepest descent / default move set) 40 * @see vrna_path(), #VRNA_PATH_STEEPEST_DESCENT, #VRNA_MOVESET_DEFAULT 41 */ 42 43 #define VRNA_PATH_DEFAULT (VRNA_PATH_STEEPEST_DESCENT | VRNA_MOVESET_DEFAULT) 44 45 /** 46 * @brief Compute a path, store the final structure, and return a list of transition moves 47 * from the start to the final structure. 48 * 49 * This function computes, given a start structure in pair table format, a transition path, 50 * updates the pair table to the final structure of the path. Finally, if not requested otherwise 51 * by using the #VRNA_PATH_NO_TRANSITION_OUTPUT flag in the @p options field, this function returns a list 52 * of individual transitions that lead from the start to the final 53 * structure if requested. 54 * 55 * The currently available transition paths are 56 * - Steepest Descent / Gradient walk (flag: #VRNA_PATH_STEEPEST_DESCENT) 57 * - Random walk (flag: #VRNA_PATH_RANDOM) 58 * 59 * The type of transitions must be set through the @p options parameter 60 * 61 * @note Since the result is written to the input structure you may want to use 62 * vrna_ptable_copy() before calling this function to keep the initial structure 63 * 64 * @see vrna_path_gradient(), vrna_path_random(), vrna_ptable(), vrna_ptable_copy(), vrna_fold_compound() 65 * #VRNA_PATH_STEEPEST_DESCENT, #VRNA_PATH_RANDOM, #VRNA_MOVESET_DEFAULT, #VRNA_MOVESET_SHIFT, 66 * #VRNA_PATH_NO_TRANSITION_OUTPUT 67 * 68 * @param[in] vc A vrna_fold_compound_t containing the energy parameters and model details 69 * @param[in,out] pt The pair table containing the start structure. Used to update to the final structure after execution of this function 70 * @param[in] options Options to modify the behavior of this function 71 * @return A list of transition moves (default), or NULL (if options & #VRNA_PATH_NO_TRANSITION_OUTPUT) 72 */ 73 vrna_move_t * 74 vrna_path(vrna_fold_compound_t *vc, 75 short *pt, 76 unsigned int steps, 77 unsigned int options); 78 79 80 /** 81 * @brief Compute a steepest descent / gradient path, store the final structure, and return a 82 * list of transition moves from the start to the final structure. 83 * 84 * This function computes, given a start structure in pair table format, a steepest descent path, 85 * updates the pair table to the final structure of the path. Finally, if not requested otherwise 86 * by using the #VRNA_PATH_NO_TRANSITION_OUTPUT flag in the @p options field, this function returns a list 87 * of individual transitions that lead from the start to the final 88 * structure if requested. 89 * 90 * @note Since the result is written to the input structure you may want to use 91 * vrna_ptable_copy() before calling this function to keep the initial structure 92 * 93 * @see vrna_path_random(), vrna_path(), vrna_ptable(), vrna_ptable_copy(), vrna_fold_compound() 94 * #VRNA_MOVESET_DEFAULT, #VRNA_MOVESET_SHIFT, #VRNA_PATH_NO_TRANSITION_OUTPUT 95 * 96 * @param[in] vc A vrna_fold_compound_t containing the energy parameters and model details 97 * @param[in,out] pt The pair table containing the start structure. Used to update to the final structure after execution of this function 98 * @param[in] options Options to modify the behavior of this function 99 * @return A list of transition moves (default), or NULL (if options & #VRNA_PATH_NO_TRANSITION_OUTPUT) 100 */ 101 vrna_move_t * 102 vrna_path_gradient(vrna_fold_compound_t *vc, 103 short *pt, 104 unsigned int options); 105 106 107 /** 108 * @brief Generate a random walk / path of a given length, store the final structure, and return a 109 * list of transition moves from the start to the final structure. 110 * 111 * This function generates, given a start structure in pair table format, a random walk / path, 112 * updates the pair table to the final structure of the path. Finally, if not requested otherwise 113 * by using the #VRNA_PATH_NO_TRANSITION_OUTPUT flag in the @p options field, this function returns a list 114 * of individual transitions that lead from the start to the final 115 * structure if requested. 116 * 117 * @note Since the result is written to the input structure you may want to use 118 * vrna_ptable_copy() before calling this function to keep the initial structure 119 * 120 * @see vrna_path_gradient(), vrna_path(), vrna_ptable(), vrna_ptable_copy(), vrna_fold_compound() 121 * #VRNA_MOVESET_DEFAULT, #VRNA_MOVESET_SHIFT, #VRNA_PATH_NO_TRANSITION_OUTPUT 122 * 123 * @param[in] vc A vrna_fold_compound_t containing the energy parameters and model details 124 * @param[in,out] pt The pair table containing the start structure. Used to update to the final structure after execution of this function 125 * @param[in] steps The length of the path, i.e. the total number of transitions / moves 126 * @param[in] options Options to modify the behavior of this function 127 * @return A list of transition moves (default), or NULL (if options & #VRNA_PATH_NO_TRANSITION_OUTPUT) 128 */ 129 vrna_move_t * 130 vrna_path_random(vrna_fold_compound_t *vc, 131 short *pt, 132 unsigned int steps, 133 unsigned int options); 134 135 136 /** 137 * @} 138 */ 139 140 #endif /* VIENNA_RNA_PACKAGE_WALK_H */ 141