htgop.h (12288B)
1 /* Copyright (C) 2018-2021, 2023 |Méso|Star> (contact@meso-star.com) 2 * 3 * This program is free software: you can redistribute it and/or modify 4 * it under the terms of the GNU General Public License as published by 5 * the Free Software Foundation, either version 3 of the License, or 6 * (at your option) any later version. 7 * 8 * This program is distributed in the hope that it will be useful, 9 * but WITHOUT ANY WARRANTY; without even the implied warranty of 10 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 11 * GNU General Public License for more details. 12 * 13 * You should have received a copy of the GNU General Public License 14 * along with this program. If not, see <http://www.gnu.org/licenses/>. */ 15 16 #ifndef HTGOP_H 17 #define HTGOP_H 18 19 #include <rsys/rsys.h> 20 21 /* Library symbol management */ 22 #if defined(HTGOP_SHARED_BUILD) /* Build shared library */ 23 #define HTGOP_API extern EXPORT_SYM 24 #elif defined(HTGOP_STATIC) /* Use/build static library */ 25 #define HTGOP_API extern LOCAL_SYM 26 #else /* Use shared library */ 27 #define HTGOP_API extern IMPORT_SYM 28 #endif 29 30 /* Helper macro that asserts if the invocation of the htgop function `Func' 31 * returns an error. One should use this macro on htgop function calls for 32 * which no explicit error checking is performed */ 33 #ifndef NDEBUG 34 #define HTGOP(Func) ASSERT(CONCAT(htgop_, Func) == RES_OK) 35 #else 36 #define HTGOP(Func) CONCAT(htgop_, Func) 37 #endif 38 39 /* Forward declaration of external data types */ 40 struct logger; 41 struct mem_allocator; 42 43 /* Forward declaration of opaque data types */ 44 struct htgop; 45 46 struct htgop_ground { 47 double temperature; /* In Kelvin */ 48 double lw_emissivity; /* Long wave emissivity */ 49 double sw_emissivity; /* Short wave emissivity */ 50 }; 51 52 struct htgop_spectral_interval { 53 double wave_numbers[2]; /* Lower/Upper wave number of the interval in cm^-1 */ 54 const double* quadrature_pdf; /* Normalized PDF of the quadrature */ 55 const double* quadrature_cdf; /* CDF of the quadrature */ 56 size_t quadrature_length; /* #quadrature points of the interval */ 57 const struct htgop* htgop; 58 }; 59 60 struct htgop_level { 61 double pressure; /* In Pascal */ 62 double temperature; /* In Kelvin */ 63 double height; /* In meter */ 64 }; 65 66 struct htgop_layer { 67 double x_h2o_nominal; /* Nominal molar fraction of water vapor */ 68 const double* x_h2o_tab; /* Tabulated xH2O */ 69 size_t tab_length; /* Length of the tabulated xH2O */ 70 size_t lw_spectral_intervals_count; 71 size_t sw_spectral_intervals_count; 72 const struct htgop* htgop; 73 const void* data__; /* Internal data */ 74 }; 75 76 struct htgop_layer_lw_spectral_interval { 77 const double* ka_nominal; /* Per quadrature point absorption coef */ 78 size_t quadrature_length; 79 const struct htgop* htgop; 80 /* Internal data */ 81 const void* data__; 82 const void* layer__; 83 }; 84 85 struct htgop_layer_lw_spectral_interval_tab { 86 const double* x_h2o_tab; /* <=> layer.x_h2o_tab */ 87 const double* ka_tab; /* Tabulated absorption coef */ 88 size_t tab_length; /* == lengh of the tabulated xH2O */ 89 const struct htgop* htgop; 90 }; 91 92 struct htgop_layer_sw_spectral_interval { 93 const double* ka_nominal; /* Per quadrature point absorption coef */ 94 const double* ks_nominal; /* Per quadrature point scattering coef */ 95 size_t quadrature_length; 96 const struct htgop* htgop; 97 /* Internal data */ 98 const void* data__; 99 const void* layer__; 100 }; 101 102 struct htgop_layer_sw_spectral_interval_tab { 103 const double* x_h2o_tab; /* <=> layer.x_h2o_tab */ 104 const double* ka_tab; /* Tabulated absorption coef */ 105 const double* ks_tab; /* Tabulated scattering coef */ 106 size_t tab_length; /* == lengh of the tabulated xH2O */ 107 const struct htgop* htgop; 108 }; 109 110 BEGIN_DECLS /* HTGOP API */ 111 112 /******************************************************************************* 113 * HTGOP device management 114 ******************************************************************************/ 115 HTGOP_API res_T 116 htgop_create 117 (struct logger* logger, /* NULL <=> use default logger */ 118 struct mem_allocator* allocator, /* NULL <=> use default allocator */ 119 const int verbose, /* Verbosity level */ 120 struct htgop** htgop); 121 122 HTGOP_API res_T 123 htgop_ref_get 124 (struct htgop* htgop); 125 126 HTGOP_API res_T 127 htgop_ref_put 128 (struct htgop* htgop); 129 130 /******************************************************************************* 131 * Loading functions 132 ******************************************************************************/ 133 HTGOP_API res_T 134 htgop_load 135 (struct htgop* htgop, 136 const char* filename); 137 138 HTGOP_API res_T 139 htgop_load_stream 140 (struct htgop* htgop, 141 FILE* stream); 142 143 /******************************************************************************* 144 * Getters of the the loaded data 145 ******************************************************************************/ 146 HTGOP_API res_T 147 htgop_get_ground 148 (const struct htgop* htgop, 149 struct htgop_ground* ground); 150 151 HTGOP_API res_T 152 htgop_get_layers_count 153 (const struct htgop* htgop, 154 size_t* nlayers); 155 156 HTGOP_API res_T 157 htgop_get_levels_count 158 (const struct htgop* htgop, 159 size_t* nlevels); 160 161 HTGOP_API res_T 162 htgop_get_level 163 (const struct htgop* htgop, 164 const size_t ilevel, 165 struct htgop_level* level); 166 167 HTGOP_API res_T 168 htgop_get_layer 169 (const struct htgop* htgop, 170 const size_t ilayer, 171 struct htgop_layer* layer); 172 173 HTGOP_API res_T 174 htgop_get_lw_spectral_intervals_count 175 (const struct htgop* htgop, 176 size_t* nspecints); 177 178 HTGOP_API res_T 179 htgop_get_sw_spectral_intervals_count 180 (const struct htgop* htgop, 181 size_t* nspecints); 182 183 HTGOP_API res_T 184 htgop_get_lw_spectral_intervals_wave_numbers 185 (const struct htgop* htgop, 186 const double* wave_numbers[]); 187 188 HTGOP_API res_T 189 htgop_get_sw_spectral_intervals_wave_numbers 190 (const struct htgop* htgop, 191 const double* wave_numbers[]); 192 193 HTGOP_API res_T 194 htgop_get_lw_spectral_interval 195 (const struct htgop* htgop, 196 const size_t ispectral_interval, 197 struct htgop_spectral_interval* interval); 198 199 HTGOP_API res_T 200 htgop_get_sw_spectral_interval 201 (const struct htgop* htgop, 202 const size_t ispectral_interval, 203 struct htgop_spectral_interval* interval); 204 205 /* Find the id of the long wave interval that includes `wave_number'. */ 206 HTGOP_API res_T 207 htgop_find_lw_spectral_interval_id 208 (const struct htgop* htgop, 209 const double wave_number, /* In cm^-1 */ 210 size_t* ispectral_interval); /* SIZE_MAX <=> not found */ 211 212 /* Find the id of the short wave interval that includes `wave_number' */ 213 HTGOP_API res_T 214 htgop_find_sw_spectral_interval_id 215 (const struct htgop* htgop, 216 const double wave_number, /* In cm^-1 */ 217 size_t* ispectral_interval); /* SIZE_MAX <=> not found */ 218 219 HTGOP_API res_T 220 htgop_layer_get_lw_spectral_interval 221 (const struct htgop_layer* layer, 222 const size_t ispectral_interval, 223 struct htgop_layer_lw_spectral_interval* spectral_interval); 224 225 HTGOP_API res_T 226 htgop_layer_get_sw_spectral_interval 227 (const struct htgop_layer* layer, 228 const size_t ispectral_interval, 229 struct htgop_layer_sw_spectral_interval* spectral_interval); 230 231 HTGOP_API res_T 232 htgop_layer_lw_spectral_interval_get_tab 233 (const struct htgop_layer_lw_spectral_interval* spectral_interval, 234 const size_t iquadrature_point, 235 struct htgop_layer_lw_spectral_interval_tab* tab); 236 237 HTGOP_API res_T 238 htgop_layer_sw_spectral_interval_get_tab 239 (const struct htgop_layer_sw_spectral_interval* spectral_interval, 240 const size_t iquadrature_point, 241 struct htgop_layer_sw_spectral_interval_tab* tab); 242 243 /******************************************************************************* 244 * The following functions retrieve the absorption/scattering coefficient in a 245 * layer, in short/long wave, at a given spectral interval for a specific 246 * quadrature point with respect to a submitted water vapor molar fraction 247 * x_h2o. x_h2o is compared to the values of tabulated water vapor molar 248 * fractions of the layer: x_h2o in [x1, x2], with the corresponding tabulated 249 * values of the required radiative property k(x1) = k1 and k(x2) = k2. Now 250 * there is 3 cases: 251 * 252 * - If x_h2o is smaller than the first tabulated value of the water vapor molar 253 * fraction, x1 and k1 is assumed to be null and k(x_h2o) is computed with a 254 * linear interpolation: 255 * k(x_h2o) = x_h2o * k2/x2 256 * 257 * - If either k1 or k2 is null, k(x_h2o) is also computed with a simple linear 258 * interpolation: 259 * k(x_h2o) = k1 + (k2-k1)/(x2-x1) * (x_h2o-x1) 260 * 261 * - Otherwise, k(x_h2o) is computed as bellow: 262 * k(x_h2o) = exp(alpha * ln(x_h2o) + beta) 263 * with: 264 * alpha = (ln(k2) - ln(k1)) / (ln(x2) - ln(x1)) 265 * beta = ln(k1) - alpha * ln(x1) 266 ******************************************************************************/ 267 HTGOP_API res_T 268 htgop_layer_lw_spectral_interval_tab_fetch_ka 269 (const struct htgop_layer_lw_spectral_interval_tab* tab, 270 const double x_h2o, /* H2O mol / mixture mol */ 271 double* ka); 272 273 HTGOP_API res_T 274 htgop_layer_sw_spectral_interval_tab_fetch_ka 275 (const struct htgop_layer_sw_spectral_interval_tab* tab, 276 const double x_h2o, /* H2O mol / mixture mol */ 277 double* ka); 278 279 HTGOP_API res_T 280 htgop_layer_sw_spectral_interval_tab_fetch_ks 281 (const struct htgop_layer_sw_spectral_interval_tab* tab, 282 const double x_h2o, /* H2O mol / mixture mol */ 283 double* ks); 284 285 HTGOP_API res_T 286 htgop_layer_sw_spectral_interval_tab_fetch_kext 287 (const struct htgop_layer_sw_spectral_interval_tab* tab, 288 const double x_h2o, /* H2O mol / mixture mol */ 289 double* kext); 290 291 /******************************************************************************* 292 * Retrieve the boundaries of the radiative properties 293 ******************************************************************************/ 294 HTGOP_API res_T 295 htgop_layer_lw_spectral_interval_quadpoints_get_ka_bounds 296 (const struct htgop_layer_lw_spectral_interval* specint, 297 const size_t iquad_range[2], /* Range of quadrature points to handle */ 298 const double x_h2o_range[2], 299 double bounds[2]); 300 301 HTGOP_API res_T 302 htgop_layer_sw_spectral_interval_quadpoints_get_ka_bounds 303 (const struct htgop_layer_sw_spectral_interval* specint, 304 const size_t iquad_range[2], /* Range of quadrature points to handle */ 305 const double x_h2o_range[2], 306 double bounds[2]); 307 308 HTGOP_API res_T 309 htgop_layer_sw_spectral_interval_quadpoints_get_ks_bounds 310 (const struct htgop_layer_sw_spectral_interval* specint, 311 const size_t iquad_range[2], /* Range of quadrature points to handle */ 312 const double x_h2o_range[2], 313 double bounds[2]); 314 315 HTGOP_API res_T 316 htgop_layer_sw_spectral_interval_quadpoints_get_kext_bounds 317 (const struct htgop_layer_sw_spectral_interval* specint, 318 const size_t iquad_range[2], /* Range of quadrature points to handle */ 319 const double x_h2o_range[2], 320 double bounds[2]); 321 322 HTGOP_API res_T 323 htgop_layer_lw_spectral_interval_tab_get_ka_bounds 324 (const struct htgop_layer_lw_spectral_interval_tab* tab, 325 const double x_h2o_range[2], 326 double bounds[2]); 327 328 HTGOP_API res_T 329 htgop_layer_sw_spectral_interval_tab_get_ka_bounds 330 (const struct htgop_layer_sw_spectral_interval_tab* tab, 331 const double x_h2o_range[2], 332 double bounds[2]); 333 334 HTGOP_API res_T 335 htgop_layer_sw_spectral_interval_tab_get_ks_bounds 336 (const struct htgop_layer_sw_spectral_interval_tab* tab, 337 const double x_h2o_range[2], 338 double bounds[2]); 339 340 HTGOP_API res_T 341 htgop_layer_sw_spectral_interval_tab_get_kext_bounds 342 (const struct htgop_layer_sw_spectral_interval_tab* tab, 343 const double x_h2o_range[2], 344 double bounds[2]); 345 346 /******************************************************************************* 347 * Miscellaneous functions 348 ******************************************************************************/ 349 /* Return the layer index into which the submitted a 1D position lies */ 350 HTGOP_API res_T 351 htgop_position_to_layer_id 352 (const struct htgop* htgop, 353 const double pos, 354 size_t* ilayer); 355 356 HTGOP_API res_T 357 htgop_spectral_interval_sample_quadrature 358 (const struct htgop_spectral_interval* interval, 359 const double r, /* Canonical random number in [0, 1[ */ 360 size_t* iquad_point); /* Id of the sample quadrature point */ 361 362 HTGOP_API res_T 363 htgop_get_sw_spectral_intervals 364 (const struct htgop* htgop, 365 const double wnum_range[2], 366 size_t specint_range[2]); 367 368 HTGOP_API res_T 369 htgop_get_lw_spectral_intervals 370 (const struct htgop* htgop, 371 const double wnum_range[2], 372 size_t specint_range[2]); 373 374 END_DECLS 375 376 #endif /* HTGOP */ 377