stardis-input.5.in (17092B)
1 .\" Copyright (C) 2018-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 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 .Dd April 18, 2024 16 .Dt STARDIS-INPUT 5 17 .Os 18 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 19 .\" Name and short description 20 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 21 .Sh NAME 22 .Nm stardis-input 23 .Nd thermal system description for 24 .Xr stardis 1 25 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 26 .\" Detailed description 27 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 28 .Sh DESCRIPTION 29 .Nm 30 is the format used by the 31 .Xr stardis 1 32 program to describe a thermal system. 33 It is a line-by-line ASCII syntax. 34 .Pp 35 A thermal system is composed of lines of text, each one describing 36 either a program 37 .Pq an user-provided shared object , 38 a medium frontier 39 .Pq solid or fluid , 40 a boundary condition, a connection between two media, the scale of the 41 whole geometry, or the radiative temperature around the system. 42 In the medium, boundary and connection cases, description lines include 43 a list of file names that constitute the limit, boundary or connection. 44 .Xr stardis 1 45 only accepts triangle mesh geometry files in STL format. 46 If a scale is specified, it defines the scaling factor to apply to the 47 geometry to have it expressed in meters 48 .Pq e.g. 1e-3 if the geometry is in mm . 49 .Pp 50 Any physical quantity involved in descriptions is expected in the 51 International System of Units 52 .Pq second, meter, kilogram, kelvin, watt, joule . 53 However, the geometry provided to 54 .Xr stardis 1 55 can be described in any unit, multiple of meters or not, as long as the 56 scaling factor is provided. 57 .Pp 58 Properties are defined directly as constants in the input file. 59 Several properties can also be defined by programs, i.e. shared objects 60 provided by the user 61 .Pq compiled libraries . 62 The latter allow user-defined variable properties to be supplied to 63 .Xr stardis 1 . 64 Depending on the type of description they use, programs must 65 export a given list of mandatory functions. 66 They can also export some other optional functions. 67 The exact list with names and types can be found in the public header 68 .Pa stardis-prog-properties.h , 69 which is installed together with 70 .Xr stardis 1 71 binary. 72 .Pp 73 A medium limit, a boundary or a connection description can be split 74 across files and a single file or description line can describe more 75 than one frontier 76 .Pq more than one connex region . 77 The main semantic constraint on descriptions is that enclosures must be 78 defined by a single description line, to ensure that every constitutive 79 part of the system is made from a single medium. 80 .Pp 81 Description lines can be submitted to 82 .Xr stardis 1 83 in any order, with the exception of programs that must be 84 defined before use, and can be split across more than one file, through 85 multiple use of option 86 .Fl M . 87 .Pp 88 When a description line is parsed, the first step is to split it in 89 different parts. 90 .Xr stardis 1 91 relies on the 92 .Xr wordexp 3 93 POSIX function for this step. 94 As a consequence the rules that apply at this stage all come from 95 the wordexp rules: environment variables can be used and are 96 substituted, including inside arithmetic expressions, text inside quote 97 pairs is considered a single item, whitespace characters can be escaped 98 so that the current item continues past it 99 .Po see 100 .Xr wordexp 3 101 for details 102 .Pc . 103 Note however that both the use of undefined environment variables and 104 the use of command substitution will be reported as an error as these 105 features are not enabled in 106 .Xr stardis 1 . 107 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 108 .\" Grammar in Backus-Naur form 109 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 110 .Sh GRAMMAR 111 In what follows, some lines end with a backslash 112 .Pq Li \e . 113 This is used as a convenience to continue a description next line. 114 However, this trick cannot be used in actual description files and 115 actual description lines must be kept single-line. 116 Text introduced by the sharp character 117 .Pq Li # 118 in descriptions is a comment and is not part of the description. 119 .Pp 120 The file format is as follows: 121 .Bl -column (description-line) (::) () 122 .It Ao Va thermal-system Ac Ta ::= Ta Ao Va description-line Ac 123 .It Ta Ta ... 124 .It Ao Va description-line Ac Ta ::= Ta Ao Va comment Ac 125 .It Ta \& \& | Ta Ao Va program Ac Op Ao Va comment Ac 126 .It Ta \& \& | Ta Ao Va medium Ac Op Ao Va comment Ac 127 .It Ta \& \& | Ta Ao Va connection Ac Op Ao Va comment Ac 128 .It Ta \& \& | Ta Ao Va boundary-condition Ac Op Ao Va comment Ac 129 .It Ta \& \& | Ta Ao Va scaling Ac Op Ao Va comment Ac 130 # At most once 131 .It \ Ta Ta 132 .It Ao Va comment Ac Ta ::= Ta Li # Vt string 133 .It Ao Va program Ac Ta ::= Ta Li PROGRAM Ao Va prog-name Ac Ao Va lib-path Ac Op Ao Va args Ac 134 .It Ao Va scaling Ac Ta ::= Ta Li SCALE Vt real 135 # Geometry scaling in ]0, INF) 136 .El 137 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 138 .Ss Media 139 .Bl -column (description-line) (::) () 140 .It Ao Va medium Ac Ta ::= Ta Ao Va fluid Ac | Ao Va solid Ac 141 .It \ Ta Ta 142 .It Ao Va fluid Ac Ta ::= Ta Ao Va fluid-const Ac | Ao Va fluid-prog Ac 143 .It Ao Va fluid-const Ac Ta ::= Ta 144 .Li FLUID Ao Va medium-name Ac Ao Va rho Ac Ao Va cp Ac \e 145 .It Ta Ta Ao Va initial-temp Ac Ao Va imposed-temp Ac \e 146 .It Ta Ta Ao Va triangle-sides Ac ... 147 .It Ao Va fluid-prog Ac Ta ::= Ta Li FLUID_PROG Ao Va medium-name Ac Ao Va prog-desc-sides Ac 148 .It \ Ta Ta 149 .It Ao Va solid Ac Ta ::= Ta Ao Va solid-const Ac | Ao Va solid-prog Ac 150 .It Ao Va solid-const Ac Ta ::= Ta 151 .Li SOLID Ao Va medium-name Ac Ao Va lambda Ac Ao Va rho Ac Ao Va cp Ac \e 152 .It Ta Ta Ao Va delta Ac Ao Va initial-temp Ac Ao Va imposed-temp Ac \e 153 .It Ta Ta Ao Va volumic-power Ac Ao Va triangle-sides Ac No ... 154 .It Ao Va solid-prog Ac Ta ::= Ta Li SOLID_PROG Ao Va medium-name Ac Ao Va prog-desc-sides Ac 155 .It \ Ta Ta 156 .It Ao Va lambda Ac Ta ::= Ta Vt real No # Conductivity > 0 [W/m/K] 157 .It Ao Va rho Ac Ta ::= Ta Vt real No # Volumic mass > 0 [kg/m^3] 158 .It Ao Va cp Ac Ta ::= Ta Vt real No # Capacity > 0 [J/K/kg] 159 .It Ao Va volumic-power Ac Ta ::= Ta Vt real No # [W/m^3] 160 .El 161 .Pp 162 Delta is the numerical parameter that defines the length of a conductive 163 random walk step. 164 The user can define it manually or let Stardis calculate it 165 automatically from the volume of the solid. 166 In the latter case, delta is set to V/(6*A), V and A being the solid's 167 volume and surface respectively: 168 .Bl -column (description-line) (::) () 169 .It Ao Va delta Ac Ta ::= Ta Li AUTO | Vt real 170 .El 171 .Pp 172 Media's descriptions, either solids or fluids, include two possible 173 temperatures: initial and imposed. 174 If imposed temperature is set 175 .Pq that is not Li UNKNOWN , 176 initial temperature must be defined at the same value. 177 In other words, one cannot define a medium with an imposed temperature 178 that changes at 179 .Li t= Ns Ar 0 : 180 .Bl -column (description-line) (::) () 181 .It Ao Va initial-temp Ac Ta ::= Ta Vt real No # Temperature > 0 [K] 182 .It Ao Va imposed-temp Ac Ta ::= Ta Li UNKNOWN No # Temperature has to be solved 183 .It Ta \& \& | Ta Vt real No # Temperature > 0 [K] 184 .El 185 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 186 .Ss Connection 187 .Bl -column (description-line) (::) () 188 .It Ao Va connection Ac Ta ::= Ta Ao Va solid-fluid Ac 189 .It Ta \& \& | Ta Ao Va solid-solid Ac 190 .It Ta \& \& | Ta Ao Va solid-fluid-flux Ac 191 .It \ Ta Ta 192 .\" Solid/fluid connection 193 .It Ao Va solid-fluid Ac Ta ::= Ta Ao Va solid-fluid-const Ac | Ao Va solid-fluid-prog Ac 194 .It Ao Va solid-fluid-const Ac Ta ::= Ta Li SOLID_FLUID_CONNECTION Ao Va connect-name Ac \e 195 .It Ta Ta Ao Va Tref Ac Ao Va emissivity Ac Ao Va specular-fraction Ac \e 196 .It Ta Ta Ao Va hc Ac Ao Va triangles Ac ... 197 .It Ao Va solid-fluid-prog Ac Ta ::= Ta Li SOLID_FLUID_CONNECTION_PROG \e 198 .It Ta Ta Ao Va connect-name Ac Ao Va prog-desc Ac 199 .It \ Ta Ta 200 .\" Solid/solid connection 201 .It Ao Va solid-solid Ac Ta ::= Ta Ao Va solid-solid-const Ac | Ao Va solid-solid-prog Ac 202 .It Ao Va solid-solid-const Ac Ta ::= Ta Li SOLID_SOLID_CONNECTION Ao Va connect-name Ac \e 203 .It Ta Ta Ao Va contact-resistance Ac Ao Va triangles Ac ... 204 .It Ao Va solid-solid-prog Ac Ta ::= Ta Li SOLID_SOLID_CONNECTION_PROG \e 205 .It Ta Ta Ao Va connect-name Ac Ao Va prog-desc Ac 206 .It \ Ta Ta 207 .\" Solid/fluid connection with flux 208 .It Ao Va solid-fluid-flux Ac Ta :: Ta Ao Va sf-flux-const Ac | Ao Va s-flux-prog Ac 209 .It Ao Va sf-flux-const Ac Ta :: Ta Li F_SOLID_FLUID_CONNECTION Ao Va connect-name Ac \e 210 .It Ta Ta Ao Va Tref Ac Ao Va emissivity Ac Ao Va specular-fraction Ac \e 211 .It Ta Ta Ao Va hc Ac Ao Va flux Ac Ao Va triangles Ac ... 212 .It Ao Va sf-flux-prog Ac Ta :: Ta Li F_SOLID_FLUID_CONNECTION_PROG \e 213 .It Ta Ta Ao Va connect-name Ac Ao Va prog-desc Ac 214 .It \ Ta Ta 215 .\" Miscellaneous 216 .It Ao Va emissivity Ac Ta ::= Ta Vt real No # \&In [0,1] 217 .It Ao Va specular-fraction Ac Ta ::= Ta Vt real No # \&In [0,1] 218 .It Ao Va hc Ac Ta ::= Ta Vt real No # Convective coefficient > 0 [W/m^2/K] 219 .It Ao Va contact-resistance Ac Ta ::= Ta Vt real No # > 0 [K/m^-2/W] 220 .El 221 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 222 .Ss Boundary conditions 223 .Bl -column (description-line) (::) () 224 .It Ao Va boundary-condition Ac Ta ::= Ta 225 .Aq Va dirichlet 226 .It Ta \& \& | Ta Aq Va robin 227 .It Ta \& \& | Ta Aq Va neumann 228 .It Ta \& \& | Ta Aq Va robin-neumann 229 .It Ta \& \& | Ta Ao Va rad-env Ac No # \&At most once 230 .It Ta \& \& | Ta Ao Va ext-source Ac No # \&At most once 231 .It \ Ta Ta 232 .\" Dirichlet 233 .It Ao Va dirichlet Ac Ta ::= Ta Ao Va dirichlet-const Ac | Ao Va dirichlet-prog Ac 234 .It Ao Va dirichlet-const Ac Ta ::= Ta Li T_BOUNDARY_FOR_SOLID Ao Va bound-name Ac \e 235 .It Ta Ta Ao Va temp Ac Ao Va triangles Ac ... 236 .It Ao Va dirichlet-prog Ac Ta ::= Ta Li T_BOUNDARY_FOR_SOLID_PROG Ao Va bound-name Ac \e 237 .It Ta Ta Ao Va prog-desc Ac 238 .It \ Ta Ta 239 .\" Robin 240 .It Ao Va robin Ac Ta ::= Ta Ao Va robin-fluid Ac | Ao Va robin-solid Ac 241 .It Ao Va robin-fluid Ac Ta ::= Ta Ao Va robin-fluid-const Ac | Ao Va robin-fluid-prog Ac 242 .It Ao Va robin-solid Ac Ta ::= Ta Ao Va robin-solid-const Ac | Ao Va robin-solid-prog Ac 243 .It Ao Va robin-fluid-const Ac Ta ::= Ta Li H_BOUNDARY_FOR_FLUID Ao Va bound-name Ac \e 244 .It Ta Ta Ao Va robin-const-desc Ac 245 .It Ao Va robin-solid-const Ac Ta ::= Ta Li H_BOUNDARY_FOR_SOLID Ao Va bound-name Ac \e 246 .It Ta Ta Ao Va robin-const-desc Ac 247 .It Ao Va robin-const-desc Ac Ta ::= Ta Ao Va Tref Ac Ao Va emissivity Ac Ao Va specular-fraction Ac 248 .It Ta Ta Ao Va hc Ac Ao Va outside-temp Ac Ao Va triangles Ac ... 249 .It Ao Va robin-fluid-prog Ac Ta ::= Ta Li H_BOUNDARY_FOR_FLUID_PROG Ao Va bound-name Ac \e 250 .It Ta Ta Ao Va prog-desc Ac 251 .It Ao Va robin-solid-prog Ac Ta ::= Ta Li H_BOUNDARY_FOR_SOLID_PROG Ao Va bound-name Ac \e 252 .It Ta Ta Ao Va prog-desc Ac 253 .It \ Ta Ta 254 .\" Neumann 255 .It Ao Va neumann Ac Ta ::= Ta Ao Va neumann-const Ac | Ao Va neumann-prog Ac 256 .It Ao Va neumann-const Ac Ta ::= Ta Li F_BOUNDARY_FOR_SOLID Ao Va bound-name Ac \e 257 .It Ta Ta Ao Va flux Ac Ao Va triangles Ac ... 258 .It Ao Va neumann-prog Ac Ta ::= Ta Li F_BOUNDARY_FOR_SOLID_PROG Ao Va bound-name Ac \e 259 .It Ta Ta Ao Va prog-desc Ac 260 .It \ Ta Ta 261 .\" Robin & Neumann 262 .It Ao Va robin-neumann Ac Ta ::= Ta Ao Va robin-neumann-const Ac 263 .It Ta \& \& | Ta Ao Va robin-neumann-prog Ac 264 .It Ao Va robin-neumann-const Ac Ta ::= Ta Li HF_BOUNDARY_FOR_SOLID Ao Va bound-name Ac \e 265 .It Ta Ta Ao Va Tref Ac Ao Va emissivity Ac Ao Va specular-fraction Ac \e 266 .It Ta Ta Ao Va hc Ac Ao Va outside-temp Ac Ao Va flux Ac Ao Va triangles Ac ... 267 .It Ao Va robin-neumann-prog Ac Ta ::= Ta Li HF_BOUNDARY_FOR_SOLID_PROG Ao Va bound-name Ac \e 268 .It Ta Ta Ao Va prog-desc Ac 269 .It \ Ta Ta 270 .\" Radiative temperature 271 .It Ao Va rad-env Ac Ta ::= Ta Ao Va rad-env-const Ac | Ao Va rad-env-prog Ac 272 .It Ao Va rad-env-const Ac Ta ::= Ta Li TRAD Ao Va temp Ac Ao Va Tref Ac 273 .It Ao Va rad-env-prog Ac Ta ::= Ta Li TRAD_PROG Ao Va prog-name Ac \e 274 .It Ta Ta Op Li PROG_PARAMS Op Ao Va args Ac 275 .It \ Ta Ta 276 .\" External source 277 .It Ao Va ext-source Ac Ta ::= Ta Ao Va ext-source-const Ac | Ao Va ext-source-prog Ac 278 .It Ao Va ext-source-const Ac Ta ::= Ta Li SPHERICAL_SOURCE Ao Va radius Ac Ao Va position Ac \e 279 .It Ta Ta Ao Va power Ac Ao Va diffuse-radiance Ac 280 .It Ao Va ext-source-prog Ac Ta ::= Ta Li SPHERICAL_SOURCE_PROG Ao Va radius Ac \e 281 .It Ta Ta Ao Va prog-name Ac Op Li PROG_PARAMS Op Ao Va args Ac 282 .It \ Ta Ta 283 .\" Miscellaneous 284 .It Ao Va temp Ac Ta ::= Ta Vt real No # Temperature > 0 [K] 285 .It Ao Va Tref Ac Ta ::= Ta Vt real No # Reference temperature > 0 [K] 286 .It Ao Va outside-temp Ac Ta ::= Ta Vt real No # Temperature > 0 [K] 287 .It Ao Va flux Ac Ta ::= Ta Vt real No # [W/m^2] 288 .It Ao Va power Ac Ta ::= Ta Vt real No # [W] 289 .It Ao Va diffuse-radiance Ac Ta ::= Ta Vt real No # [W/m^2/sr] 290 .It Ao Va position Ac Ta ::= Ta Vt real real real 291 .It Ao Va radius Ac Ta ::= Ta Vt real 292 .El 293 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 294 .Ss Miscellaneous 295 Names, either file names or description names 296 .Pq boundary names, medium names, program names, or connection names , 297 are a sequence of one or more ASCII characters, including 298 numbers and special characters like 299 .Ql \&. , 300 .Ql _ , 301 or 302 .Ql - 303 as one may consider using in standard file names. 304 Description names are case-sensitive and two different description 305 lines, either in the same description file or from different description 306 files, cannot use the same name. 307 Additionally, description names cannot be a number, nor be one of the 308 keywords defined by the present grammar and their lowercase 309 counterparts. 310 Finally, description names cannot be longer than 311 @STARDIS_MAX_NAME_LENGTH@ characters. 312 .Bl -column (description-line) (::) () 313 .It Ao Va bound-name Ac Ta ::= Ta Vt string 314 .It Ao Va medium-name Ac Ta ::= Ta Vt string 315 .It Ao Va prog-name Ac Ta ::= Ta Vt string 316 .It Ao Va connect-name Ac Ta ::= Ta Vt string 317 .It \ Ta Ta 318 .It Ao Va stl-path Ac Ta ::= Ta Pa path 319 .It Ao Va lib-path Ac Ta ::= Ta Pa path 320 .It \ Ta Ta 321 .It Ao Va args Ac Ta ::= Ta Vt string No ... 322 .It \ Ta Ta 323 .It Ao Va prog-desc Ac Ta ::= Ta Ao Va prog-name Ac Ao Va triangles Ac ... \e 324 .It Ta Ta Op Li PROG_PARAMS Op Ao Va args Ac 325 .It Ao Va prog-desc-sides Ac Ta ::= Ta Ao Va prog-name Ac Ao Va triangles-sides Ac ... \e 326 .It Ta Ta Op Li PROG_PARAMS Op Ao Va args Ac 327 .It \ Ta Ta 328 .It Ao Va triangles Ac Ta ::= Ta Ao Va stl-path Ac 329 .It Ao Va triangle-sides Ac Ta ::= Ta Ao Va side-specifier Ac Ao Va triangles Ac 330 .El 331 .Pp 332 Side descriptions in side specifiers rely on the following convention: 333 we first consider the direct triangle's normal (right-hand rule), then 334 we define the 335 .Li BACK 336 side of a triangle to be the side this normal comes out from. 337 That means that a closed set of triangles with normals pointing outside 338 should be used with the 339 .Li FRONT 340 side specifier to describe inside medium: 341 .Bl -column (description-line) (::) () 342 .It Ao Va side-specifier Ac Ta ::= Ta Li FRONT | Li BACK | Li BOTH 343 .El 344 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 345 .\" File examples 346 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 347 .Sh EXAMPLES 348 Define a system consisting of a solid cube named 349 .Ql Cube 1 , 350 with a Robin-type boundary condition and radiative exchange with the 351 environment. 352 The cube geometry is read from the file 353 .Pa cube.stl 354 and the solid medium properties are 355 .No lambda= Ns Ar 0.1 No W/m/K , 356 .No rho= Ns Ar 25 No kg/m^3 , 357 .No cp= Ns Ar 2 No J/K/kg . 358 The numerical parameter delta, that is used for solid conductive walks, is 359 .Ar 0.05 . 360 The initial temperature of the cube is 361 .Ar 0 No K , its temperature is unknown 362 .Pq it has to be solved , 363 and its volumic power is 364 .Ar 2.5 No W/m^3 . 365 The boundary properties are 366 .No emissivity= Ns Ar 0 , 367 .No specular-fraction= Ns Ar 0 , 368 .No hc= Ns Ar 10 No W/m^2/K 369 and 370 .No external-temperature= Ns Ar 100 No K . 371 The radiative environment is at 372 .Ar 300 No K . 373 Finally, the linearization of radiative transfer involving Robin's 374 boundary condition uses 375 .Ar 310 No K 376 as reference temperature and is set to 377 .Ar 330 No K 378 when linearisation involves the radiative environment: 379 .Bd -literal -offset Ds 380 SOLID Cube\ 1 0.1 25 2 0.05 0 UNKNOWN 2.5 FRONT cube.stl 381 H_BOUNDARY_FOR_SOLID HdT 310 0 0 10 100 cube.stl 382 TRAD 300 330 383 .Ed 384 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 385 .\" External references 386 .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" 387 .Sh SEE ALSO 388 .Xr stardis 1 , 389 .Xr wordexp 3 390 .Rs 391 .%T The StL Format: Standard Data Format for Fabbers 392 .%A Marshall Burns 393 .%D 1993 394 .%U https://www.fabbers.com/tech/STL_Format 395 .Re