rnsf.h (5653B)
1 /* Copyright (C) 2022, 2023 Centre National de la Recherche Scientifique 2 * Copyright (C) 2022, 2023 Institut Pierre-Simon Laplace 3 * Copyright (C) 2022, 2023 Institut de Physique du Globe de Paris 4 * Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com) 5 * Copyright (C) 2022, 2023 Observatoire de Paris 6 * Copyright (C) 2022, 2023 Université de Reims Champagne-Ardenne 7 * Copyright (C) 2022, 2023 Université de Versaille Saint-Quentin 8 * Copyright (C) 2022, 2023 Université Paul Sabatier 9 * 10 * This program is free software: you can redistribute it and/or modify 11 * it under the terms of the GNU General Public License as published by 12 * the Free Software Foundation, either version 3 of the License, or 13 * (at your option) any later version. 14 * 15 * This program is distributed in the hope that it will be useful, 16 * but WITHOUT ANY WARRANTY; without even the implied warranty of 17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 18 * GNU General Public License for more details. 19 * 20 * You should have received a copy of the GNU General Public License 21 * along with this program. If not, see <http://www.gnu.org/licenses/>. */ 22 23 #ifndef RNSF_H 24 #define RNSF_H 25 26 #include <rsys/rsys.h> 27 28 /* Library symbol management */ 29 #if defined(RNSF_SHARED_BUILD) /* Build shared library */ 30 #define RNSF_API extern EXPORT_SYM 31 #elif defined(RNSF_STATIC) /* Use/build static library */ 32 #define RNSF_API extern LOCAL_SYM 33 #else /* Use shared library */ 34 #define RNSF_API extern IMPORT_SYM 35 #endif 36 37 /* Helper macro that asserts if the invocation of the htcp function `Func' 38 * returns an error. One should use this macro on htcp function calls for 39 * which no explicit error checking is performed */ 40 #ifndef NDEBUG 41 #define RNSF(Func) ASSERT(rnsf_ ## Func == RES_OK) 42 #else 43 #define RNSF(Func) rnsf_ ## Func 44 #endif 45 46 /* Forward declaration of external data types */ 47 struct logger; 48 struct mem_allocator; 49 50 enum rnsf_phase_fn_type { 51 RNSF_PHASE_FN_HG, 52 RNSF_PHASE_FN_DISCRETE, 53 RNSF_PHASE_FN_NONE__ 54 }; 55 56 struct rnsf_create_args { 57 struct logger* logger; /* NULL <=> use default logger */ 58 struct mem_allocator* allocator; /* NULL <=> use default allocator */ 59 int verbose; /* Verbosity level */ 60 }; 61 #define RNSF_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0} 62 static const struct rnsf_create_args RNSF_CREATE_ARGS_DEFAULT = 63 RNSF_CREATE_ARGS_DEFAULT__; 64 65 /* Henyey & Greestein phase function */ 66 struct rnsf_phase_fn_hg { 67 double wavelengths[2]; /* Inclusive wavelength range in nanometers */ 68 double g; /* Asymmetric parameter in [-1, 1] */ 69 }; 70 #define RNSF_PHASE_FN_HG_NULL__ {{0,0}, 0} 71 static const struct rnsf_phase_fn_hg RNSF_PHASE_FN_HG_NULL = 72 RNSF_PHASE_FN_HG_NULL__; 73 74 struct rnsf_discrete_item { 75 double theta; /* In radian */ 76 double value; 77 }; 78 #define RNSF_DISCRETE_ITEM_NULL__ {0,0} 79 static const struct rnsf_discrete_item RNSF_DISCRETE_ITEM_NULL = 80 RNSF_DISCRETE_ITEM_NULL__; 81 82 /* Discrete phase function */ 83 struct rnsf_phase_fn_discrete { 84 double wavelengths[2]; /* Inclusive wavelength range in nanometers */ 85 size_t nitems; 86 const struct rnsf_discrete_item* items; 87 }; 88 #define RNSF_PHASE_FN_DISCRETE_NULL__ {{0,0}, 0, NULL} 89 static const struct rnsf_phase_fn_discrete RNSF_PHASE_FN_DISCRETE_NULL = 90 RNSF_PHASE_FN_DISCRETE_NULL__; 91 92 /* Opaque data types */ 93 struct rnsf; 94 struct rnsf_phase_fn; 95 96 BEGIN_DECLS 97 98 /******************************************************************************* 99 * Rad-Net Scattering Functions API 100 ******************************************************************************/ 101 RNSF_API res_T 102 rnsf_create 103 (const struct rnsf_create_args* args, 104 struct rnsf** rnsf); 105 106 RNSF_API res_T 107 rnsf_ref_get 108 (struct rnsf* rnsf); 109 110 RNSF_API res_T 111 rnsf_ref_put 112 (struct rnsf* rnsf); 113 114 RNSF_API res_T 115 rnsf_load 116 (struct rnsf* rnsf, 117 const char* path); 118 119 RNSF_API res_T 120 rnsf_load_stream 121 (struct rnsf* rnsf, 122 FILE* stream, 123 const char* stream_name); /* May be NULL */ 124 125 RNSF_API size_t 126 rnsf_get_phase_fn_count 127 (const struct rnsf* rnsf); 128 129 RNSF_API const struct rnsf_phase_fn* 130 rnsf_get_phase_fn 131 (const struct rnsf* rnsf, 132 const size_t iphase_fn); 133 134 RNSF_API enum rnsf_phase_fn_type 135 rnsf_phase_fn_get_type 136 (const struct rnsf_phase_fn* phase_fn); 137 138 RNSF_API res_T 139 rnsf_phase_fn_get_hg 140 (const struct rnsf_phase_fn* phase_fn, 141 struct rnsf_phase_fn_hg* hg); 142 143 RNSF_API res_T 144 rnsf_phase_fn_get_discrete 145 (const struct rnsf_phase_fn* phase_fn, 146 struct rnsf_phase_fn_discrete* discrete); 147 148 /* Fetch a phase function with respect to the submitted wavelength and the 149 * given sample. The phase function is chosen according to the alpha 150 * coefficient between [0, 1] defined as below: 151 * 152 * alpha = (lambda1 - wavelength) / (lambda1 - lambda0) 153 * 154 * with lambda0 < lambda1, the phase function wavelengths surrounding the 155 * submitted wavelength. The index returned refers to the phase function 156 * corresponding to lambda0 or lambda1 depending on whether the given sample is 157 * less than or greater than alpha, respectively. 158 * 159 * If the phase functions are stored by spectral band, lambda0 and lambda1 are 160 * the upper boundary of the lower band and the lower boundary of the upper 161 * band, respectively, which surround the wavelength. If the wavelength is in a 162 * specific band, the index for that band is simply returned. 163 * 164 * If the wavelength is outside the domain, the index returned refers to either 165 * the first or the last phase function depending on whether the wavelength is 166 * below or above the domain, respectively. */ 167 RNSF_API res_T 168 rnsf_fetch_phase_fn 169 (const struct rnsf* rnsf, 170 const double wavelength, 171 const double sample, /* In [0, 1[ */ 172 size_t* iphase_fn); 173 174 END_DECLS 175 176 #endif /* RNSF_H */ 177