1 #ifndef VIENNA_RNA_PACKAGE_FIND_PATH_H 2 #define VIENNA_RNA_PACKAGE_FIND_PATH_H 3 4 #ifdef VRNA_WARN_DEPRECATED 5 # if defined(__clang__) 6 # define DEPRECATED(func, msg) func __attribute__ ((deprecated("", msg))) 7 # elif defined(__GNUC__) 8 # define DEPRECATED(func, msg) func __attribute__ ((deprecated(msg))) 9 # else 10 # define DEPRECATED(func, msg) func 11 # endif 12 #else 13 # define DEPRECATED(func, msg) func 14 #endif 15 16 /** 17 * @file ViennaRNA/landscape/findpath.h 18 * @ingroup paths 19 * @brief A breadth-first search heuristic for optimal direct folding paths 20 */ 21 22 /** 23 * @addtogroup paths_direct 24 * @{ 25 * 26 * @brief Heuristics to explore direct, optimal (re-)folding paths between two secondary structures 27 * 28 */ 29 30 #include <ViennaRNA/fold_compound.h> 31 #include <ViennaRNA/landscape/paths.h> 32 33 /** 34 * @brief Find energy of a saddle point between 2 structures (search only direct path) 35 * 36 * This function uses an inplementation of the @em findpath algorithm @cite flamm:2001 37 * for near-optimal direct refolding path prediction. 38 * 39 * Model details, and energy parameters are used as provided via the parameter 'fc'. 40 * The #vrna_fold_compound_t does not require memory for any DP matrices, 41 * but requires all most basic init values as one would get from a call like this: 42 * @code{.c} 43 * fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT); 44 * @endcode 45 * 46 * @see vrna_path_findpath_saddle_ub(), vrna_fold_compound(), #vrna_fold_compound_t, vrna_path_findpath() 47 * 48 * @param fc The #vrna_fold_compound_t with precomputed sequence encoding and model details 49 * @param s1 The start structure in dot-bracket notation 50 * @param s2 The target structure in dot-bracket notation 51 * @param width A number specifying how many strutures are being kept at each step during the search 52 * @returns The saddle energy in 10cal/mol 53 */ 54 int 55 vrna_path_findpath_saddle(vrna_fold_compound_t *fc, 56 const char *s1, 57 const char *s2, 58 int width); 59 60 61 /** 62 * @brief Find energy of a saddle point between 2 structures (search only direct path) 63 * 64 * This function uses an inplementation of the @em findpath algorithm @cite flamm:2001 65 * for near-optimal direct refolding path prediction. 66 * 67 * Model details, and energy parameters are used as provided via the parameter 'fc'. 68 * The #vrna_fold_compound_t does not require memory for any DP matrices, 69 * but requires all most basic init values as one would get from a call like this: 70 * @code{.c} 71 * fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT); 72 * @endcode 73 * 74 * @warning The argument @p maxE (@f$E_{max}@f$) enables one to specify an upper bound, or maximum free 75 * energy for the saddle point between the two input structures. If no path 76 * with @f$E_{saddle} < E_{max}@f$ is found, the function simply returns @p maxE 77 * 78 * @see vrna_path_findpath_saddle(), vrna_fold_compound(), #vrna_fold_compound_t, vrna_path_findpath() 79 * 80 * @param fc The #vrna_fold_compound_t with precomputed sequence encoding and model details 81 * @param s1 The start structure in dot-bracket notation 82 * @param s2 The target structure in dot-bracket notation 83 * @param width A number specifying how many strutures are being kept at each step during the search 84 * @param maxE An upper bound for the saddle point energy in 10cal/mol 85 * @returns The saddle energy in 10cal/mol 86 */ 87 int 88 vrna_path_findpath_saddle_ub(vrna_fold_compound_t *fc, 89 const char *s1, 90 const char *s2, 91 int width, 92 int maxE); 93 94 95 /** 96 * @brief Find refolding path between 2 structures (search only direct path) 97 * 98 * This function uses an inplementation of the @em findpath algorithm @cite flamm:2001 99 * for near-optimal direct refolding path prediction. 100 * 101 * Model details, and energy parameters are used as provided via the parameter 'fc'. 102 * The #vrna_fold_compound_t does not require memory for any DP matrices, 103 * but requires all most basic init values as one would get from a call like this: 104 * @code{.c} 105 * fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT); 106 * @endcode 107 * 108 * @see vrna_path_findpath_ub(), vrna_fold_compound(), #vrna_fold_compound_t, vrna_path_findpath_saddle() 109 * 110 * @param fc The #vrna_fold_compound_t with precomputed sequence encoding and model details 111 * @param s1 The start structure in dot-bracket notation 112 * @param s2 The target structure in dot-bracket notation 113 * @param width A number specifying how many strutures are being kept at each step during the search 114 * @returns The saddle energy in 10cal/mol 115 */ 116 vrna_path_t * 117 vrna_path_findpath(vrna_fold_compound_t *fc, 118 const char *s1, 119 const char *s2, 120 int width); 121 122 123 /** 124 * @brief Find refolding path between 2 structures 125 * (search only direct path) 126 * 127 * This function uses an inplementation of the @em findpath algorithm @cite flamm:2001 128 * for near-optimal direct refolding path prediction. 129 * 130 * Model details, and energy parameters are used as provided via the parameter 'fc'. 131 * The #vrna_fold_compound_t does not require memory for any DP matrices, 132 * but requires all most basic init values as one would get from a call like this: 133 * @code{.c} 134 * fc = vrna_fold_compound(sequence, NULL, VRNA_OPTION_DEFAULT); 135 * @endcode 136 * 137 * @warning The argument @p maxE enables one to specify an upper bound, or maximum free 138 * energy for the saddle point between the two input structures. If no path 139 * with @f$E_{saddle} < E_{max}@f$ is found, the function simply returns @em NULL 140 * 141 * @see vrna_path_findpath(), vrna_fold_compound(), #vrna_fold_compound_t, vrna_path_findpath_saddle() 142 * 143 * @param fc The #vrna_fold_compound_t with precomputed sequence encoding and model details 144 * @param s1 The start structure in dot-bracket notation 145 * @param s2 The target structure in dot-bracket notation 146 * @param width A number specifying how many strutures are being kept at each step during the search 147 * @param maxE An upper bound for the saddle point energy in 10cal/mol 148 * @returns The saddle energy in 10cal/mol 149 */ 150 vrna_path_t * 151 vrna_path_findpath_ub(vrna_fold_compound_t *fc, 152 const char *s1, 153 const char *s2, 154 int width, 155 int maxE); 156 157 158 #ifndef VRNA_DISABLE_BACKWARD_COMPATIBILITY 159 160 /** 161 * @brief Find energy of a saddle point between 2 structures 162 * (search only direct path) 163 * 164 * @deprecated Use vrna_path_findpath_saddle() instead! 165 * 166 * @ingroup paths_deprecated 167 * 168 * @param seq RNA sequence 169 * @param s1 A pointer to the character array where the first 170 * secondary structure in dot-bracket notation will be written to 171 * @param s2 A pointer to the character array where the second 172 * secondary structure in dot-bracket notation will be written to 173 * @param width integer how many strutures are being kept during the search 174 * @returns the saddle energy in 10cal/mol 175 */ 176 DEPRECATED(int 177 find_saddle(const char *seq, 178 const char *s1, 179 const char *s2, 180 int width), 181 "Use vrna_path_findpath_saddle() instead!"); 182 183 184 /** 185 * @brief Free memory allocated by get_path() function 186 * 187 * @deprecated Use vrna_path_free() instead! 188 * 189 * @ingroup paths_deprecated 190 * 191 * @param path pointer to memory to be freed 192 */ 193 DEPRECATED(void 194 free_path(vrna_path_t *path), 195 "Use vrna_path_free() instead!"); 196 197 198 /** 199 * @brief Find refolding path between 2 structures 200 * (search only direct path) 201 * 202 * @deprecated Use vrna_path_findpath() instead! 203 * 204 * @ingroup paths_deprecated 205 * 206 * @param seq RNA sequence 207 * @param s1 A pointer to the character array where the first 208 * secondary structure in dot-bracket notation will be written to 209 * @param s2 A pointer to the character array where the second 210 * secondary structure in dot-bracket notation will be written to 211 * @param width integer how many strutures are being kept during the search 212 * @returns direct refolding path between two structures 213 */ 214 DEPRECATED(vrna_path_t * 215 get_path(const char *seq, 216 const char *s1, 217 const char *s2, 218 int width), 219 "Use vrna_path_findpath() instead!"); 220 221 222 #endif 223 224 /** 225 * @} 226 */ 227 228 #endif 229