stardis_smeteo.h (8932B)
1 /* Copyright (C) 2025 |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 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 STARDIS_SMETEO_H 17 #define STARDIS_SMETEO_H 18 19 #include <stardis/stardis-prog-properties.h> 20 #include <rsys/rsys.h> 21 22 BEGIN_DECLS 23 24 /******************************************************************************* 25 * Library data, i.e., constant data for all physical properties created from 26 * this instance of the plugin, i.e., those used to define media, connections, 27 * or boundary conditions. In this case, it is data read from meteorological 28 * data 29 ******************************************************************************/ 30 STARDIS_API void* 31 stardis_create_library_data 32 (const struct stardis_program_context* ctx, 33 size_t argc, 34 char* argv[]); 35 36 STARDIS_API void 37 stardis_release_library_data 38 (void* lib_data); 39 40 STARDIS_API enum stardis_return_status 41 stardis_finalize_library_data 42 (void* lib_data); 43 44 /******************************************************************************* 45 * Create a boundary condition 46 ******************************************************************************/ 47 STARDIS_API void* 48 stardis_create_data 49 (const struct stardis_description_create_context* ctx, 50 void* lib_data, 51 size_t argc, 52 char* argv[]); 53 54 /******************************************************************************* 55 * Functions for a Neumann + Robin boundary condition. 56 * This condition is used to couple Stardis with meteorological data via a net 57 * flux imposed at the ground interface. 58 ******************************************************************************/ 59 /* Returns the convection coefficient retrieved from meteorological data */ 60 STARDIS_API double /* > 0 [W/K/m^2] */ 61 stardis_convection_coefficient 62 (const struct stardis_interface_fragment* frag, 63 void* data); 64 65 /* Maximum H value calculated from the meteorological data set. 66 * 67 * This function is mandatory for Stardis, as it cannot assume that the 68 * atmospheric temperature is known, since it queries it through a plugin 69 * function on which it cannot make any assumptions, even if the caller knows 70 * that it always returns a known temperature. Stardis must therefore ensure 71 * that it is able to sample a convective path, a procedure that requires this 72 * upper limit. But in reality, this data should never be used. In any case, it 73 * must provide Stardis with this expected value as long as this (questionable) 74 * constraint is an expected value of its API.*/ 75 STARDIS_API double /* >0 [W/K/m^2] */ 76 stardis_max_convection_coefficient 77 (void* data); 78 79 /* Net flux on the ground side, i.e. downward flux - upward flux */ 80 STARDIS_API double /* [W/m^2] */ 81 stardis_boundary_flux 82 (const struct stardis_interface_fragment* frag, 83 void* data); 84 85 /* Atmospheric temperature retrieve from meteorological data */ 86 STARDIS_API double /* >0 [K] */ 87 stardis_medium_temperature 88 (const struct stardis_vertex* vtx, 89 void* data); 90 91 /* Ground emissivity, which should depend on the type of source. For short 92 * waves, it should be retrieved from the constant albedo of the ground, while 93 * for long waves, it should be defined by the user when creating the data. 94 * However, the way in which solar flux is currently handled does not allow for 95 * a distinction between sources: it is simply a net flux imposed on the ground. 96 * Until the sun is explicitly handled by an external source, emissivity will 97 * therefore always be retrieved from the albedo of the ground. */ 98 STARDIS_API double 99 stardis_emissivity 100 (const struct stardis_interface_fragment* frag, 101 const unsigned source_id, 102 void* data); 103 104 /* Controls the specular part of the BRDF of the ground. The ground is assumed 105 * to be purely diffuse, therefore its specular fraction is zero. */ 106 STARDIS_API double 107 stardis_specular_fraction 108 (const struct stardis_interface_fragment* frag, 109 const unsigned source_id, 110 void* data); 111 112 /* Reference ground temperature used by Stardis to calculate exchanges by 113 * radiative transfer. It returns the surface temperature provided by 114 * meteorological data, as this should be a good estimate of the ground 115 * temperature, at least as long as the geometry of the ground corresponds to 116 * the model used to estimate it (a priori an infinite slab). */ 117 STARDIS_API double /* >0 [K] */ 118 stardis_reference_temperature 119 (const struct stardis_interface_fragment* frag, 120 void* data); 121 122 /* Radiative temperature obtained from meteorological data. This is the to 123 * calculate radiative exchanges between the ground and the sky */ 124 STARDIS_API double 125 stardis_radiative_env_temperature 126 (const double time, /* [s] */ 127 const double dir[3], 128 void* data); 129 130 /* Reference sky temperature used to linearized radiative transfert */ 131 STARDIS_API double 132 stardis_radiative_env_reference_temperature 133 (const double time, /* [s] */ 134 const double dir[3], 135 void* data); 136 137 /* Range of reference temperatures calculated from the entire set of surface 138 * temperatures and the radiative temperatures provided by meteorological data */ 139 STARDIS_API double* /* <=> range */ 140 stardis_t_range 141 (void* data, 142 double range[2]); /* >0 [K] */ 143 144 /******************************************************************************* 145 * Functions for the sky fluid. 146 * They are used to determine the sky temperature from meteorological data and 147 * enable the evaluation of radiative transfer using the Monte Carlo method. 148 ******************************************************************************/ 149 /* Dummy function since fluid as fixed temperature */ 150 STARDIS_API double 151 stardis_calorific_capacity 152 (const struct stardis_vertex* vtx, 153 void* data); 154 155 /* Dummy function since fluid as fixed temperature */ 156 STARDIS_API double 157 stardis_volumic_mass 158 (const struct stardis_vertex* vtx, 159 void* data); 160 161 /* Atmospheric temperature retrieve from meteorological data */ 162 STARDIS_API double /* >0 [K] */ 163 stardis_medium_temperature 164 (const struct stardis_vertex* vtx, 165 void* data); 166 167 /******************************************************************************* 168 * Functions for a Dirichlet boundary condition. 169 * This condition is used as a very basic coupling between Stardis and the 170 * meteorological data, of which only its ground temperature is used. 171 ******************************************************************************/ 172 /* Ground temperature */ 173 STARDIS_API double /* >0 [K] */ 174 stardis_boundary_temperature 175 (const struct stardis_interface_fragment* frag, 176 void* data); 177 178 /* Range of ground temperatures calculated from the entire set of surface 179 * temperatures provided by meteorological data */ 180 STARDIS_API double* /* <=> range */ 181 stardis_t_range 182 (void* data, 183 double range[2]); /* >0 [K] */ 184 185 /******************************************************************************* 186 * Functions used to treat solar flux not as a flux imposed on the ground 187 * surface, but as a flux coming from an external source, i.e., the sun. 188 ******************************************************************************/ 189 /* Position of the sun based on the time, as well as the location and 190 * time zone associated with the meteorological data */ 191 STARDIS_API double* 192 stardis_spherical_source_position 193 (const double time, /* [s] */ 194 double position[3], /* [m] */ 195 void* data); 196 197 /* Solar power at a given time. It is computed from the direct component of 198 * the shortwave downward flux provided by meteorological data */ 199 STARDIS_API double /* [W] */ 200 stardis_spherical_source_power 201 (const double time, 202 void* data); 203 204 /* Describes the diffuse part of the sun's contribution at a given time, i.e. 205 * the radiance emitted by the sun and scattered at least once in the 206 * atmosphere. It is computed from the diffuse component of the shortwave 207 * downward flux provided by meteorological data */ 208 STARDIS_API double /* [W/m^2/sr] */ 209 stardis_spherical_source_diffuse_radiance 210 (const double time, 211 const double dir[3], 212 void* data); 213 214 /******************************************************************************* 215 * Various mandatory legal functions 216 ******************************************************************************/ 217 STARDIS_API const char* 218 get_copyright_notice 219 (void* data); 220 221 STARDIS_API const char* 222 get_license_short 223 (void* data); 224 225 STARDIS_API const char* 226 get_license_text 227 (void* data); 228 229 END_DECLS 230 231 #endif /* STARDIS_SMETEO_H */