STARDIS-INPUT(5) File Formats Manual STARDIS-INPUT(5)

stardis-input — thermal system description for stardis(1)

stardis-input is the format used by the stardis(1) program to describe a thermal system. It is a line-by-line ASCII syntax.

A thermal system is composed of lines of text, each one describing either a program (an user-provided shared object), a medium frontier (solid or fluid), a boundary condition, a connection between two media, the scale of the whole geometry, or the radiative temperature around the system. In the medium, boundary and connection cases, description lines include a list of file names that constitute the limit, boundary or connection. stardis(1) only accepts triangle mesh geometry files in STL format. If a scale is specified, it defines the scaling factor to apply to the geometry to have it expressed in meters (e.g. 1e-3 if the geometry is in mm).

Any physical quantity involved in descriptions is expected in the International System of Units (second, meter, kilogram, kelvin, watt, joule). However, the geometry provided to stardis(1) can be described in any unit, multiple of meters or not, as long as the scaling factor is provided.

Properties are defined directly as constants in the input file. Several properties can also be defined by programs, i.e. shared objects provided by the user (compiled libraries). The latter allow user-defined variable properties to be supplied to stardis(1). Depending on the type of description they use, programs must export a given list of mandatory functions. They can also export some other optional functions. The exact list with names and types can be found in the public header stardis-prog-properties.h, which is installed together with stardis(1) binary.

A medium limit, a boundary or a connection description can be split across files and a single file or description line can describe more than one frontier (more than one connex region). The main semantic constraint on descriptions is that enclosures must be defined by a single description line, to ensure that every constitutive part of the system is made from a single medium.

Description lines can be submitted to stardis(1) in any order, with the exception of programs that must be defined before use, and can be split across more than one file, through multiple use of option -M.

When a description line is parsed, the first step is to split it in different parts. stardis(1) relies on the wordexp(3) POSIX function for this step. As a consequence the rules that apply at this stage all come from the wordexp rules: environment variables can be used and are substituted, including inside arithmetic expressions, text inside quote pairs is considered a single item, whitespace characters can be escaped so that the current item continues past it (see wordexp(3) for details). Note however that both the use of undefined environment variables and the use of command substitution will be reported as an error as these features are not enabled in stardis(1).

In what follows, some lines end with a backslash (\). This is used as a convenience to continue a description next line. However, this trick cannot be used in actual description files and actual description lines must be kept single-line. Text introduced by the sharp character (#) in descriptions is a comment and is not part of the description.

The file format is as follows:

⟨thermal-system⟩ ::= ⟨description-line⟩
...
⟨description-line⟩ ::= ⟨comment⟩
| ⟨program⟩ [⟨comment⟩]
| ⟨medium⟩ [⟨comment⟩]
| ⟨connection⟩ [⟨comment⟩]
| ⟨boundary-condition⟩ [⟨comment⟩]
| ⟨scaling⟩ [⟨comment⟩] # At most once
 
⟨comment⟩ ::= string
⟨program⟩ ::= ⟨prog-name⟩ ⟨lib-path⟩ [⟨args⟩]
⟨scaling⟩ ::= real # Geometry scaling in ]0, INF)

⟨medium⟩ ::= ⟨fluid⟩ | ⟨solid⟩
 
⟨fluid⟩ ::= ⟨fluid-const⟩ | ⟨fluid-prog⟩
⟨fluid-const⟩ ::= ⟨medium-name⟩ ⟨rho⟩ ⟨cp⟩ \
⟨initial-temp⟩ ⟨imposed-temp⟩ \
⟨triangle-sides⟩ ...
⟨fluid-prog⟩ ::= ⟨medium-name⟩ ⟨prog-desc-sides⟩
 
⟨solid⟩ ::= ⟨solid-const⟩ | ⟨solid-prog⟩
⟨solid-const⟩ ::= ⟨medium-name⟩ ⟨lambda⟩ ⟨rho⟩ ⟨cp⟩ \
⟨delta⟩ ⟨initial-temp⟩ ⟨imposed-temp⟩ \
⟨volumic-power⟩ ⟨triangle-sides⟩ ...
⟨solid-prog⟩ ::= ⟨medium-name⟩ ⟨prog-desc-sides⟩
 
⟨lambda⟩ ::= real # Conductivity > 0 [W/m/K]
⟨rho⟩ ::= real # Volumic mass > 0 [kg/m^3]
⟨cp⟩ ::= real # Capacity > 0 [J/K/kg]
⟨volumic-power⟩ ::= real # [W/m^3]

Delta is the numerical parameter that defines the length of a conductive random walk step. The user can define it manually or let Stardis calculate it automatically from the volume of the solid. In the latter case, delta is set to V/(6*A), V and A being the solid's volume and surface respectively:

⟨delta⟩ ::= | real

Media's descriptions, either solids or fluids, include two possible temperatures: initial and imposed. If imposed temperature is set (that is not UNKNOWN), initial temperature must be defined at the same value. In other words, one cannot define a medium with an imposed temperature that changes at t=0:

⟨initial-temp⟩ ::= real # Temperature > 0 [K]
⟨imposed-temp⟩ ::= # Temperature has to be solved
| real # Temperature > 0 [K]

⟨connection⟩ ::= ⟨solid-fluid⟩ | ⟨solid-solid⟩
 
⟨solid-fluid⟩ ::= ⟨solid-fluid-const⟩ | ⟨solid-fluid-prog⟩
⟨solid-fluid-const⟩ ::= ⟨connect-name⟩ \
⟨Tref⟩ ⟨emissivity⟩ ⟨specular-fraction⟩ \
⟨hc⟩ ⟨triangles⟩ ...
⟨solid-fluid-prog⟩ ::=
⟨connect-name⟩ ⟨prog-desc⟩
 
⟨solid-solid⟩ ::= ⟨solid-solid-const⟩ | ⟨solid-solid-prog⟩
⟨solid-solid-const⟩ ::= ⟨connect-name⟩ \
⟨contact-resistance⟩ ⟨triangles⟩ ...
⟨solid-solid-prog⟩ ::=
⟨connect-name⟩ ⟨prog-desc⟩
 
⟨emissivity⟩ ::= real # In [0,1]
⟨specular-fraction⟩ ::= real # In [0,1]
⟨hc⟩ ::= real # Convective coefficient > 0 [W/m^2/K]
⟨contact-resistance⟩ ::= real # > 0 [K/m^-2/W]

⟨boundary-condition⟩ ::= ⟨dirichlet⟩
| ⟨robin⟩
| ⟨neumann⟩
| ⟨robin-neumann⟩
| ⟨rad-env⟩ # At most once
| ⟨ext-source⟩ # At most once
 
⟨dirichlet⟩ ::= ⟨dirichlet-const⟩ | ⟨dirichlet-prog⟩
⟨dirichlet-const⟩ ::= ⟨bound-name⟩ \
⟨temp⟩ ⟨triangles⟩ ...
⟨dirichlet-prog⟩ ::= ⟨bound-name⟩ \
⟨prog-desc⟩
 
⟨robin⟩ ::= ⟨robin-fluid⟩ | ⟨robin-solid⟩
⟨robin-fluid⟩ ::= ⟨robin-fluid-const⟩ | ⟨robin-fluid-prog⟩
⟨robin-solid⟩ ::= ⟨robin-solid-const⟩ | ⟨robin-solid-prog⟩
⟨robin-fluid-const⟩ ::= ⟨bound-name⟩ \
⟨robin-const-desc⟩
⟨robin-solid-const⟩ ::= ⟨bound-name⟩ \
⟨robin-const-desc⟩
⟨robin-const-desc⟩ ::= ⟨Tref⟩ ⟨emissivity⟩ ⟨specular-fraction⟩
⟨hc⟩ ⟨outside-temp⟩ ⟨triangles⟩ ...
⟨robin-fluid-prog⟩ ::= ⟨bound-name⟩ \
⟨prog-desc⟩
⟨robin-solid-prog⟩ ::= ⟨bound-name⟩ \
⟨prog-desc⟩
 
⟨neumann⟩ ::= ⟨neumann-const⟩ | ⟨neumann-prog⟩
⟨neumann-const⟩ ::= ⟨bound-name⟩ \
⟨flux⟩ ⟨triangles⟩ ...
⟨neumann-prog⟩ ::= ⟨bound-name⟩ \
⟨prog-desc⟩
 
⟨robin-neumann⟩ ::= ⟨robin-neumann-const⟩
| ⟨robin-neumann-prog⟩
⟨robin-neumann-const⟩ ::= ⟨bound-name⟩ \
⟨Tref⟩ ⟨emissivity⟩ ⟨specular-fraction⟩ \
⟨hc⟩ ⟨outside-temp⟩ ⟨flux⟩ ⟨triangles⟩ ...
⟨robin-neumann-prog⟩ ::= ⟨bound-name⟩ \
⟨prog-desc⟩
 
⟨rad-env⟩ ::= ⟨rad-env-const⟩ | ⟨rad-env-prog⟩
⟨rad-env-const⟩ ::= ⟨temp⟩ ⟨Tref⟩
⟨rad-env-prog⟩ ::= ⟨prog-name⟩ \
[PROG_PARAMS [⟨args⟩]]
 
⟨ext-source⟩ ::= ⟨ext-source-const⟩ | ⟨ext-source-prog⟩
⟨ext-source-const⟩ ::= ⟨radius⟩ ⟨position⟩ \
⟨power⟩ ⟨diffuse-radiance⟩
⟨ext-source-prog⟩ ::= ⟨radius⟩ \
⟨prog-name⟩ [PROG_PARAMS [⟨args⟩]]
 
⟨temp⟩ ::= real # Temperature > 0 [K]
⟨Tref⟩ ::= real # Reference temperature > 0 [K]
⟨outside-temp⟩ ::= real # Temperature > 0 [K]
⟨flux⟩ ::= real # [W/m^2]
⟨power⟩ ::= real # [W]
⟨diffuse-radiance⟩ ::= real # [W/m^2/sr]
⟨position⟩ ::= real real real
⟨radius⟩ ::= real

Names, either file names or description names (boundary names, medium names, program names, or connection names), are a sequence of one or more ASCII characters, including numbers and special characters like ‘.’, ‘_’, or ‘-’ as one may consider using in standard file names. Description names are case-sensitive and two different description lines, either in the same description file or from different description files, cannot use the same name. Additionally, description names cannot be a number, nor be one of the keywords defined by the present grammar and their lowercase counterparts. Finally, description names cannot be longer than 63 characters.

⟨bound-name⟩ ::= string
⟨medium-name⟩ ::= string
⟨prog-name⟩ ::= string
⟨connect-name⟩ ::= string
 
⟨stl-path⟩ ::= path
⟨lib-path⟩ ::= path
 
⟨args⟩ ::= string ...
 
⟨prog-desc⟩ ::= ⟨prog-name⟩ ⟨triangles⟩ ... \
[PROG_PARAMS [⟨args⟩]]
⟨prog-desc-sides⟩ ::= ⟨prog-name⟩ ⟨triangles-sides⟩ ... \
[PROG_PARAMS [⟨args⟩]]
 
⟨triangles⟩ ::= ⟨stl-path⟩
⟨triangle-sides⟩ ::= ⟨side-specifier⟩ ⟨triangles⟩

Side descriptions in side specifiers rely on the following convention: we first consider the direct triangle's normal (right-hand rule), then we define the BACK side of a triangle to be the side this normal comes out from. That means that a closed set of triangles with normals pointing outside should be used with the FRONT side specifier to describe inside medium:

⟨side-specifier⟩ ::= | |

Define a system consisting of a solid cube named ‘Cube 1’, with a Robin-type boundary condition and radiative exchange with the environment. The cube geometry is read from the file cube.stl and the solid medium properties are lambda=0.1 W/m/K, rho=25 kg/m^3, cp=2 J/K/kg. The numerical parameter delta, that is used for solid conductive walks, is 0.05. The initial temperature of the cube is 0 K, its temperature is unknown (it has to be solved), and its volumic power is 2.5 W/m^3. The boundary properties are emissivity=0, specular-fraction=0, hc=10 W/m^2/K and external-temperature=100 K. The radiative environment is at 300 K. Finally, the linearization of radiative transfer involving Robin's boundary condition uses 310 K as reference temperature and is set to 330 K when linearisation involves the radiative environment:

SOLID Cube 1 0.1 25 2 0.05 0 UNKNOWN 2.5 FRONT cube.stl
H_BOUNDARY_FOR_SOLID HdT 310 0 0 10 100 cube.stl
TRAD 300 330

stardis(1), wordexp(3)

Marshall Burns, The StL Format: Standard Data Format for Fabbers, https://www.fabbers.com/tech/STL_Format, 1993.

April 18, 2024 UNIX