1 #ifndef VIENNA_RNA_PACKAGE_MELTING_H 2 #define VIENNA_RNA_PACKAGE_MELTING_H 3 4 #include <stdio.h> 5 6 #include <ViennaRNA/datastructures/basic.h> 7 8 /** 9 * 10 * @file heat_capacity.h 11 * @ingroup thermodynamics 12 * 13 * @brief Compute heat capacity for an RNA 14 * 15 * This file includes the interface to all functions related to predicting the heat capacity for an RNA. 16 */ 17 18 19 /** 20 * @addtogroup thermodynamics 21 * @{ 22 */ 23 24 25 /** 26 * @brief The callback for heat capacity predictions 27 * 28 * @callback 29 * @parblock 30 * This function will be called for each evaluated temperature in the heat capacity prediction. 31 * @endparblock 32 * @see vrna_heat_capacity_cb() 33 * 34 * @param temp The current temperature this results corresponds to in °C 35 * @param heat_capacity The heat capacity in Kcal/(Mol * K) 36 * @param data Some arbitrary data pointer passed through by the function executing the callback 37 */ 38 typedef void (vrna_heat_capacity_callback)(float temp, 39 float heat_capacity, 40 void *data); 41 42 43 /** 44 * @brief A single result from heat capacity computations 45 * 46 * This is a convenience typedef for #vrna_heat_capacity_s, i.e. results as obtained from vrna_heat_capacity() 47 */ 48 typedef struct vrna_heat_capacity_s vrna_heat_capacity_t; 49 50 51 /** 52 * @brief A single result from heat capacity computations 53 * 54 * @see vrna_heat_capacity() 55 */ 56 struct vrna_heat_capacity_s { 57 float temperature; /**< @brief The temperature in °C */ 58 float heat_capacity; /**< @brief The specific heat at this temperature in Kcal/(Mol * K) */ 59 }; 60 61 62 /** 63 * @name Basic heat capacity function interface 64 * @{ 65 */ 66 67 /** 68 * @brief Compute the specific heat for an RNA 69 * 70 * This function computes an RNAs specific heat in a given temperature range 71 * from the partition function by numeric differentiation. The result is returned 72 * as a list of pairs of temperature in °C and specific heat in Kcal/(Mol*K). 73 * 74 * Users can specify the temperature range for the computation from @p T_min to 75 * @p T_max, as well as the increment step size @p T_increment. The latter also determines 76 * how many times the partition function is computed. Finally, the parameter @p mpoints 77 * determines how smooth the curve should be. The algorithm itself fits a parabola 78 * to @f$ 2 \cdot mpoints + 1 @f$ data points to calculate 2nd derivatives. Increasing this 79 * parameter produces a smoother curve. 80 * 81 * @see vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s 82 * 83 * @param fc The #vrna_fold_compound_t with the RNA sequence to analyze 84 * @param T_min Lowest temperature in °C 85 * @param T_max Highest temperature in °C 86 * @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) 87 * @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) 88 * @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. 89 * The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min 90 */ 91 vrna_heat_capacity_t * 92 vrna_heat_capacity(vrna_fold_compound_t *fc, 93 float T_min, 94 float T_max, 95 float T_increment, 96 unsigned int mpoints); 97 98 99 /** 100 * @brief Compute the specific heat for an RNA (callback variant) 101 * 102 * Similar to vrna_heat_capacity(), this function computes an RNAs specific heat in 103 * a given temperature range from the partition function by numeric differentiation. 104 * Instead of returning a list of temperature/specific heat pairs, however, this 105 * function returns the individual results through a callback mechanism. The provided 106 * function will be called for each result and passed the corresponding temperature 107 * and specific heat values along with the arbitrary data as provided through the 108 * @p data pointer argument. 109 * 110 * Users can specify the temperature range for the computation from @p T_min to 111 * @p T_max, as well as the increment step size @p T_increment. The latter also determines 112 * how many times the partition function is computed. Finally, the parameter @p mpoints 113 * determines how smooth the curve should be. The algorithm itself fits a parabola 114 * to @f$ 2 \cdot mpoints + 1 @f$ data points to calculate 2nd derivatives. Increasing this 115 * parameter produces a smoother curve. 116 * 117 * @see vrna_heat_capacity(), vrna_heat_capacity_callback 118 * 119 * @param fc The #vrna_fold_compound_t with the RNA sequence to analyze 120 * @param T_min Lowest temperature in °C 121 * @param T_max Highest temperature in °C 122 * @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) 123 * @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) 124 * @param cb The user-defined callback function that receives the individual results 125 * @param data An arbitrary data structure that will be passed to the callback in conjunction with the results 126 * @return Returns 0 upon failure, and non-zero otherwise 127 */ 128 int 129 vrna_heat_capacity_cb(vrna_fold_compound_t *fc, 130 float T_min, 131 float T_max, 132 float T_increment, 133 unsigned int mpoints, 134 vrna_heat_capacity_callback *cb, 135 void *data); 136 137 138 /* End basic interface */ 139 /**@}*/ 140 141 /** 142 * @name Simplified heat capacity computation 143 * @{ 144 */ 145 146 /** 147 * @brief Compute the specific heat for an RNA (simplified variant) 148 * 149 * Similar to vrna_heat_capacity(), this function computes an RNAs specific heat 150 * in a given temperature range from the partition function by numeric differentiation. 151 * This simplified version, however, only requires the RNA sequence as input instead of 152 * a vrna_fold_compound_t data structure. The result is returned as a list of pairs of 153 * temperature in °C and specific heat in Kcal/(Mol*K). 154 * 155 * Users can specify the temperature range for the computation from @p T_min to 156 * @p T_max, as well as the increment step size @p T_increment. The latter also determines 157 * how many times the partition function is computed. Finally, the parameter @p mpoints 158 * determines how smooth the curve should be. The algorithm itself fits a parabola 159 * to @f$ 2 \cdot mpoints + 1 @f$ data points to calculate 2nd derivatives. Increasing this 160 * parameter produces a smoother curve. 161 * 162 * @see vrna_heat_capacity(), vrna_heat_capacity_cb(), vrna_heat_capacity_t, vrna_heat_capacity_s 163 * 164 * @param sequence The RNA sequence input (must be uppercase) 165 * @param T_min Lowest temperature in °C 166 * @param T_max Highest temperature in °C 167 * @param T_increment Stepsize for temperature incrementation in °C (a reasonable choice might be 1°C) 168 * @param mpoints The number of interpolation points to calculate 2nd derivative (a reasonable choice might be 2, min: 1, max: 100) 169 * @return A list of pairs of temperatures and corresponding heat capacity or @em NULL upon any failure. 170 * The last entry of the list is indicated by a @b temperature field set to a value smaller than @p T_min 171 */ 172 vrna_heat_capacity_t * 173 vrna_heat_capacity_simple(const char *sequence, 174 float T_min, 175 float T_max, 176 float T_increment, 177 unsigned int mpoints); 178 179 /* End basic interface */ 180 /**@}*/ 181 182 /* End thermodynamics */ 183 /**@}*/ 184 185 #endif 186