libstardis_smeteo.3 (9970B)
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 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 Lesser General Public License for more details. 12 .\" 13 .\" You should have received a copy of the GNU Lesser General Public License 14 .\" along with this program. If not, see <http://www.gnu.org/licenses/>. 15 .Dd November 5, 2025 16 .Dt LIBSTARDIS_SMETEO 3 17 .Os 18 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 19 .Sh NAME 20 .Nm libstardis_smeteo 21 .Nd 22 .Xr stardis 1 23 plugin for handling meteorological data 24 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 25 .Sh SYNOPSIS 26 .In stardis_smeteo.h 27 .Ft void* 28 .Fo stardis_create_library_data 29 .Fa "const struct stardis_program_context* ctx" 30 .Fa "size_t argc" 31 .Fa "char* argv[]" 32 .Fc 33 .Ft void* 34 .Fo stardis_create_data 35 .Fa "const struct stardis_description_create_context* ctx" 36 .Fa "void* lib_data" 37 .Fa "size_t argc" 38 .Fa "char* argv" 39 .Fc 40 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 41 .Sh DESCRIPTION 42 These functions implement the interface for creating programmable data 43 for 44 .Xr stardis 1 . 45 They are part of a stardis plugin that loads meteorological data as 46 described by the 47 .Xr smeteo 5 48 file format. 49 This data is used by the plugin to define connection conditions and 50 boundary conditions based on meteorological data, i.e. 51 which varies depending on time. 52 .Pp 53 .Nm 54 is intended to be dynamically loaded by 55 .Xr stardis 1 56 as programmable boundary or connection conditions. 57 The functions described in this documentation are therefore not intended 58 to be called directly by a programmer, but by the 59 .Xr stardis 1 60 programmable interface, which internally manages input arguments such as 61 .Fa ctx 62 and 63 .Fa lib_data . 64 Only the 65 .Fa argc 66 and 67 .Fa argv 68 parameters are meaningful to the 69 .Xr stardis 1 70 user. 71 They reflect the options that he can define via this programmable 72 interface 73 .Po 74 see the 75 .Xr stardis-input 5 76 file format 77 .Pc . 78 This documentation therefore lists the values of these arguments that 79 the user can enter when declaring programmable properties via this 80 plugin. 81 .\"""""""""""""""""""""""""""""""""""""" 82 .Ss Library data 83 The 84 .Fn stardis_create_library_data 85 function is called once when the plugin is loaded by 86 .Xr stardis 1 87 .Po 88 see the 89 .Ql PROGRAM 90 keyword in 91 .Xr stardis-input 5 92 .Pc . 93 .Pp 94 This function creates the data shared by all physical properties that 95 will rely on this instance of the library. 96 Its behavior depends on its 97 .Fa argc 98 and 99 .Fa argv 100 variables. 101 Their values are those that would be taken by the 102 .Fa argc 103 and 104 .Fa argv 105 arguments of the 106 .Fn main 107 function of a C program whose synopsis would be: 108 .Pp 109 .Nm stardis-smeteo 110 .Op Fl a Ar sun_algo 111 .Ar file 112 .Pp 113 except for the name of the program, i.e. 114 .Nm stardis-smeteo , 115 which is purely 116 fictitious here, replaced by the name defined in the 117 .Ql PROGRAM 118 directive 119 of the 120 .Xr stardis-input 5 121 file responsible for instantiating the plugin for 122 .Xr stardis 1 . 123 .Pp 124 The 125 .Ar file 126 argument is the path to a 127 .Xr smeteo 5 128 file that defines the meteorological data to be loaded. 129 .Pp 130 The options are as follows: 131 .Bl -tag -width Ds 132 .It Fl a Ar sun_algo 133 Defines the algorithm to use to calculate the position of the sun when 134 its contribution is modeled by a spherical external source 135 .Po 136 see the 137 .Ql SPHERICAL_SOURCE[_PROG] 138 directive in the 139 .Xr stardis-input 5 140 file format 141 .Pc . 142 .Pp 143 The solar position algorithms are as follows: 144 .Bl -tag -width Ds 145 .It Cm meeus 146 The algorithm described in the Jean Meeus' book, 147 .Dq Astronomical Algorithm . 148 This is the default algorithm if no other is explicitly defined. 149 .It Cm psa 150 The algorithm developed by the 151 .Dq Plataforma Solar de Almería . 152 .El 153 .El 154 .\"""""""""""""""""""""""""""""""""""""" 155 .Ss Physical properties 156 The 157 .Fn stardis_create_data 158 function is called each time a 159 stardis property is declared as dependent on an instance of the 160 .Nm 161 plugin, i.e., as a programmable property using the 162 .Nm 163 library on the meteorological data loaded when the library data was 164 created 165 .Pq see the Sx Library data No sub-section . 166 .Pp 167 This function creates the corresponding physical property from its 168 .Fa argc 169 and 170 .Fa argv 171 variables. 172 Their values are those that would be taken by the 173 .Fa argc 174 and 175 .Fa argv 176 arguments of the 177 .Fn main 178 function of a C program whose synopsis would be: 179 .Pp 180 .Nm stardis-smeteo-phyprop 181 .Op Fl hls 182 .Op Fl t Ar temperature 183 .Pp 184 except for the name of the program, i.e. 185 .Nm stardis-smeteo-phyprop , 186 which is purely fictitious here, replaced by the name of the 187 programmable physical property defined in the 188 .Xr stardis-input 5 189 file. 190 .Pp 191 The options are as follows: 192 .Bl -tag -width Ds 193 .It Fl h 194 When used to declare a boundary condition or a connection condition, the 195 interface convection coefficient is retrieved from the meteorological 196 data loaded by the library instance 197 .Pq see Xr smeteo 5 . 198 If this option is not defined, the interface convection coefficient is 199 assumed to be zero. 200 .It Fl l 201 When used to declare a boundary condition or a connection condition, 202 latent flux is taken into account as an imposed flux at the interface. 203 .It Fl s 204 When used to declare a boundary condition or a connection condition, 205 solar flux is taken into account as an imposed flux at the interface. 206 .It Fl t Ar temperature 207 When used to declare a Dirichlet boundary condition, set the interface 208 temperature to 209 .Ar temperature 210 .Pq in Kelvin . 211 If this option is not defined, the Dirichlet boundary condition uses the 212 surface temperature defined in the meteorological data loaded by the 213 library instance 214 .Pq see Xr smeteo 5 . 215 .El 216 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 217 .Sh EXIT STATUS 218 Upon successful, a pointer to the allocated data is returned. 219 Otherwise, a null pointer is returned. 220 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 221 .Sh EXAMPLES 222 The functions documented here are not intended to be called directly, 223 but via the 224 .Xr stardis 1 225 programmable properties interface. 226 The following examples therefore illustrate 227 .Xr stardis-input 5 228 files based on the 229 .Nm 230 plugin to define programmable properties that ultimately call these 231 functions. 232 .Pp 233 The following 234 .Xr stardis-input 5 235 file, defines a slab whose lower surface has a fixed temperature of 236 284K. 237 A Robin+Neumann boundary condition is imposed on its upper surface. 238 Its convection coefficient, fluid temperature (i.e., atmosphere), and 239 imposed flux are retrieved from meteorological data 240 .Pq solar and latent . 241 The other surfaces are adiabatic to simulate an infinite slab: 242 .Bd -literal -offset Ds 243 # Configure the plugin to use the meteorological data stored 244 # in the smeteo.txt file. 245 PROGRAM Meteo libstardis_smeteo.so smeteo.txt 246 247 # Define the ground 248 SOLID ground 1 1500 1500 0.02 281.85 UNKNOWN 0 FRONT ground.stl 249 250 # Use the "Meteo" plugin to define convective exchange between 251 # the surface and the atmosphere and take into account solar 252 # contribution by imposing a flux 253 HF_BOUNDARY_FOR_SOLID_PROG atm Meteo ground_Z.stl PROG_PARAMS -hls 254 255 # Fix the underground temperature to 284 K 256 T_BOUNDARY_FOR_SOLID underground 284.0 ground_z.stl 257 258 # Make other interfaces adiabatic 259 H_BOUNDARY_FOR_SOLID adiabatic 0 0 0 0 0 ground_xXyY.stl 260 .Ed 261 .Pp 262 Below, the 263 .Xr stardis-input 5 264 file defines the ground as a slab-shaped geometry immersed in a fluid 265 .Pq i.e., the atmosphere 266 whose temperature is retrieved from meteorological data. 267 A convective exchange is added between the atmosphere and the ground 268 using the convection coefficient described in the meteorological data. 269 The latent flux is defined as a flux imposed on this same interface. 270 The underground temperature is fixed to 284 K. 271 The contribution of the sun is modeled by an external spherical source 272 with a radius of 6.987e8 m, whose position is calculated by 273 .Nm 274 based on the location of the meteorological data and the time, using the 275 PSA algorithm. 276 Its direct and diffuse contribution is retrieved from meteorological 277 data as is the ambiant radiative temperature. 278 The other surfaces are adiabatic: 279 .Bd -literal -offset Ds 280 # Configure the plugin to use the meteorological data stored 281 # in the smeteo.txt file and to use the algorithm developed 282 # by the "Plataforma Solar de Almería" to calculate the 283 # position of the sun 284 PROGRAM Meteo libstardis_smeteo.so smeteo.txt PROG_PARAMS -a psa 285 286 # Define the ground 287 SOLID ground 1 1500 1500 0.02 281.85 UNKNOWN 0 FRONT ground.stl 288 289 # Define the atmosphere as a fluid at a fixed temperature 290 # retrieved from the "Meteo" plugin 291 FLUID_PROG atmosphere Meteo BACK ground.stl 292 293 # Use the "Meteo" plugin to add a convective exchange 294 # between the ground surface and the atmosphere 295 SOLID_FLUID_CONNECTION_PROG hdT Meteo ground_Z.stl PROG_PARAMS -hl 296 297 # Fix the underground temperature to 284 K 298 SOLID_FLUID_CONNECTION_PROG ut Meteo ground_z.stl PROG_PARAMS -t284 299 300 # Make other interfaces adiabatic 301 SOLID_FLUID_CONNECTION adiabatic 300 0 0 0 ground_xXyY.stl 302 303 # Use the "Meteo" plugin to calculate the position and 304 # contribution of the sun declared as an external spherical 305 # source 306 SPHERICAL_SOURCE_PROG 6.987e8 Meteo 307 308 # Retrieve the radiative temperature from the meteorological data 309 # loaded by the "Meteo" plugin 310 TRAD_PROG Meteo 311 .Ed 312 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 313 .Sh SEE ALSO 314 .Xr stardis 1 , 315 .Xr smeteo 5 , 316 .Xr stardis-input 5 317 .Rs 318 .%A Jean Meeus 319 .%B Astronomical Algorithms 320 .%D 1991 321 .Re 322 .Rs 323 .%A Manuel Blanco-Muriel 324 .%A Diego C. Alarcón-Padilla 325 .%A Teodoro López-Moratalla 326 .%A Martín Lara-Coira 327 .%T Computing the solar vector 328 .%J Solar Energy 329 .%V 70 330 .%N 5 331 .%D 2001 332 .%P 431-441 333 .Re