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