sars.h (5163B)
1 /* Copyright (C) 2022, 2023 |Méso|Star> (contact@meso-star.com) 2 * 3 * This program is free software: you can redismshbute 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 dismshbuted 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 SARS_H 17 #define SARS_H 18 19 #include <rsys/hash.h> 20 #include <rsys/rsys.h> 21 22 /* Library symbol management */ 23 #if defined(SARS_SHARED_BUILD) /* Build shared library */ 24 #define SARS_API extern EXPORT_SYM 25 #elif defined(SARS_STATIC) /* Use/build static library */ 26 #define SARS_API extern LOCAL_SYM 27 #else /* Use shared library */ 28 #define SARS_API extern IMPORT_SYM 29 #endif 30 31 /* Helper macro that asserts if the invocation of the smsh function `Func' 32 * returns an error. One should use this macro on smsh function calls for 33 * which no explicit error checking is performed */ 34 #ifndef NDEBUG 35 #define SARS(Func) ASSERT(sars_ ## Func == RES_OK) 36 #else 37 #define SARS(Func) sars_ ## Func 38 #endif 39 40 /* Forward declaration of external data types */ 41 struct logger; 42 struct mem_allocator; 43 44 struct sars_create_args { 45 struct logger* logger; /* May be NULL <=> default logger */ 46 struct mem_allocator* allocator; /* NULL <=> use default allocator */ 47 int verbose; /* Verbosity level */ 48 }; 49 #define SARS_CREATE_ARGS_DEFAULT__ {NULL, NULL, 0} 50 static const struct sars_create_args SARS_CREATE_ARGS_DEFAULT = 51 SARS_CREATE_ARGS_DEFAULT__; 52 53 struct sars_load_args { 54 const char* path; 55 int memory_mapping; /* Use memory mapping instead of normal loading */ 56 }; 57 #define SARS_LOAD_ARGS_NULL__ {NULL, 0} 58 static const struct sars_load_args SARS_LOAD_ARGS_NULL = SARS_LOAD_ARGS_NULL__; 59 60 struct sars_load_stream_args { 61 FILE* stream; 62 const char* name; /* Stream name */ 63 /* Use memory mapping instead of normal loading. Note that memory mapping 64 * cannot be used on some stream like stdin */ 65 int memory_mapping; 66 }; 67 #define SARS_LOAD_STREAM_ARGS_NULL__ {NULL, "stream", 0} 68 static const struct sars_load_stream_args SARS_LOAD_STREAM_ARGS_NULL = 69 SARS_LOAD_STREAM_ARGS_NULL__; 70 71 struct sars_band { 72 double lower; /* Lower band wavelength in nm (inclusive) */ 73 double upper; /* Upper band wavelength in nm (exclusive) */ 74 size_t id; 75 76 float* k_list; /* Per node radiative coefficients */ 77 }; 78 #define SARS_BAND_NULL__ {0, 0, 0, NULL} 79 static const struct sars_band SARS_BAND_NULL = SARS_BAND_NULL__; 80 81 /* Forward declaration of opaque data types */ 82 struct sars; 83 84 BEGIN_DECLS 85 86 /******************************************************************************* 87 * Star-AeRoSol API 88 ******************************************************************************/ 89 SARS_API res_T 90 sars_create 91 (const struct sars_create_args* args, 92 struct sars** sars); 93 94 SARS_API res_T 95 sars_ref_get 96 (struct sars* sars); 97 98 SARS_API res_T 99 sars_ref_put 100 (struct sars* sars); 101 102 SARS_API res_T 103 sars_load 104 (struct sars* sars, 105 const struct sars_load_args* args); 106 107 SARS_API res_T 108 sars_load_stream 109 (struct sars* sars, 110 const struct sars_load_stream_args* args); 111 112 /* Validates radiative coefficients. Data checks have already been carried out 113 * during loading, notably on spectral bands, but this function performs longer 114 * and more thorough tests. It reviews all scattering and absorption 115 * coefficients to check their validity, i.e. whether they are positive or zero. 116 * Note that checking radiative coefficients is not mandatory, in order to speed 117 * up the loading step and avoid loading/unloading them when using memory 118 * mapping. */ 119 SARS_API res_T 120 sars_validate 121 (const struct sars* sars); 122 123 SARS_API size_t 124 sars_get_bands_count 125 (const struct sars* sars); 126 127 SARS_API size_t 128 sars_get_nodes_count 129 (const struct sars* sars); 130 131 SARS_API res_T 132 sars_get_band 133 (const struct sars* sars, 134 const size_t iband, 135 struct sars_band* band); 136 137 /* Returns the range of band indices covered by a given spectral range. The 138 * returned index range is degenerated (i.e. ibands[0] > ibands[1]) if no band 139 * is found */ 140 SARS_API res_T 141 sars_find_bands 142 (const struct sars* sars, 143 const double range[2], /* In nm. Limits are inclusive */ 144 size_t ibands[2]); /* Range of overlaped bands. Limits are inclusive */ 145 146 SARS_API res_T 147 sars_band_compute_hash 148 (const struct sars* sars, 149 const size_t iband, 150 hash256_T hash); 151 152 SARS_API res_T 153 sars_compute_hash 154 (const struct sars* sars, 155 hash256_T hash); 156 157 SARS_API const char* 158 sars_get_name 159 (const struct sars* sars); 160 161 static INLINE float 162 sars_band_get_ka(const struct sars_band* band, const size_t inode) 163 { 164 ASSERT(band); 165 return band->k_list[inode*2 + 0]; 166 } 167 168 static INLINE float 169 sars_band_get_ks(const struct sars_band* band, const size_t inode) 170 { 171 ASSERT(band); 172 return band->k_list[inode*2 + 1]; 173 } 174 175 END_DECLS 176 177 #endif /* SARS_H */