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

stardis-output — output format of stardis(1) results

stardis-output describes the output format of the stardis(1) program. Any stardis(1) result is written to standard output, even though some additional informations can be written in files.

The type of the data that are generated depends on the options used when stardis(1) is invoked. When invoked with one of the basic computation options (-p, -P, -m, -s or -F), stardis(1) outputs a single Monte Carlo result. On the opposite, stardis(1) ouputs compound results when invoked with option -S or -R. Additionally, options -g and -G make stardis(1) compute and output a Green function and possibly information on heat paths' ends. Most of the complex data output is in VTK format.

Note that some special options (-v, -h or -d) that does not involve any computation produce output including information on the stardis(1) software (their ouputs will not be described thereafter) or the provided thermal system.

Any physical quantity in output is in the International System of Units (second, metre, kilogram, kelvin) except the coordinates that are in same system as the geometry.

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 output format is as follows:

⟨output⟩ ::= ⟨mc-estimate⟩
| ⟨green-function⟩
| ⟨geometry-dump⟩
| ⟨infrared-image⟩
| ⟨heat-paths⟩

The following sections describe in detail each of these possible outputs.

When stardis(1) is used to calculate a single Monte Carlo estimate, either a temperature or a flux, the estimate is output first to standard output, possibly followed by some of the heat paths involved in the computation if option -D was used too. Two different formats are possible: a raw, numbers only format (the default) or an extended format that mixes numbers and their descriptions (if option -e is used).

⟨mc-estimate⟩ ::= ⟨probe-temp⟩ # Options -P or -p
| ⟨medium-temp⟩ # Option -m
| ⟨mean-temp⟩ # Option -s
| ⟨mean-flux⟩ # Option -F
 
⟨probe-temp⟩ ::= ⟨probe-temp-raw⟩ | ⟨probe-temp-ext⟩
⟨probe-temp-raw⟩ ::= ⟨estimate⟩ ⟨failures⟩
⟨probe-temp-ext⟩ ::= ⟨position⟩ ⟨time⟩ \
⟨estimate-temp-ext⟩ ⟨failures-ext⟩
 
⟨medium-temp⟩ ::= ⟨medium-temp-raw⟩ | ⟨medium-temp-ext⟩
⟨medium-temp-raw⟩ ::= ⟨estimate⟩ ⟨failures⟩
⟨medium-temp-ext⟩ ::= ⟨medium-name⟩ \
⟨time⟩ ⟨estimate-temp-ext⟩ ⟨failures-ext⟩
 
⟨mean-temp⟩ ::= ⟨mean-temp-raw⟩ | ⟨mean-temp-ext⟩
⟨mean-temp-raw⟩ ::= ⟨estimate⟩ ⟨failures⟩
⟨mean-temp-ext⟩ ::= ⟨stl-path⟩ \
⟨time⟩ ⟨estimate-temp-ext⟩ ⟨failures-ext⟩
 
⟨mean-flux⟩ ::= ⟨mean-flux-raw⟩ | ⟨mean-flux-ext⟩
⟨mean-flux-raw⟩ ::= ⟨estimate⟩ ⟨estimate⟩ ⟨estimate⟩ \
⟨estimate⟩ ⟨estimate⟩ ⟨failures⟩
⟨mean-flux-ext⟩ ::= ⟨stl-path⟩ \
⟨time⟩ ⟨estimate-temp-ext⟩
⟨stl-path⟩ \
⟨time⟩ ⟨estimate-flux-ext⟩
⟨stl-path⟩ \
⟨time⟩ ⟨estimate-flux-ext⟩
⟨stl-path⟩ \
⟨time⟩ ⟨estimate-flux-ext⟩
⟨stl-path⟩ \
⟨time⟩ ⟨estimate-flux-ext⟩
⟨failures-ext⟩
 
⟨estimate⟩ ::= ⟨expected-value⟩ ⟨standard-error⟩
⟨estimate-temp-ext⟩ ::= ⟨expected-value⟩ K +/- ⟨standard-error⟩
⟨estimate-flux-ext⟩ ::= ⟨expected-value⟩ W +/- ⟨standard-error⟩
⟨expected-value⟩ ::= real
⟨standard-error⟩ ::= real
 
⟨failures⟩ ::= ⟨error-count⟩ ⟨success-count⟩
⟨error-count⟩ ::= integer
⟨success-count⟩ ::= integer
 
⟨position⟩ ::= [real, real, real]
⟨time⟩ ::= real
| [real, real]
⟨medium-name⟩ ::= string
⟨stl-path⟩ ::= path

The Green function is generated, either in binary or ascii format, when a green-compatible stardis(1) simulation option is used in conjuction with option -G for a binary output, or option -g for an ascii output. For every successful heat path sampled carrying out the simulation, the solver records all the elements of the path history relevant to link the various imposed temperature, flux and volumic power values to the simulation result. The output is made of tables containing the different media and boundaries and their imposed temperature, flux and volumic power values, followed by the heat paths' history. Also, option -G make it possible to output heat paths' end information on an ascii, csv formated file.

⟨green-function⟩ ::= ⟨green-ascii⟩ # Option -g
| ⟨green-binary⟩ [⟨paths⟩] # Option -G

The Monte Carlo estimate and standard deviation for a given set of settings can be computed as the mean and standard deviation of the samples of the Green function computed using these settings. Each sample can be computed as follows:

  • get the temperature of the ending boundary, medium or Trad
  • add the temperature gain of each power term
  • add the temperature gain of each flux term

Beyond the file format described below, stardis(1) could write comments (characters behind the hash mark (#)) or blank lines (lines without any characters or composed only of spaces and tabs). These are not part of the file format and should be ignored.

The ASCII file format of a Green function is as follows:

⟨green-ascii⟩ ::=
⟨time-range⟩
⟨#solids⟩ ⟨#fluids⟩ \
⟨#dirichlet-boundaries⟩ \
⟨#robin-boundaries⟩ \
⟨#neumann-boundaries⟩ \
⟨#successes⟩ ⟨#failures⟩
⟨solid⟩
...
⟨fluid⟩
...
⟨dirichlet-boundary⟩
...
⟨robin-boundary⟩
...
⟨neumann-boundary⟩
...
⟨rad-temp⟩
⟨samples⟩
 
⟨time-rad⟩ ::= real real
⟨#solids⟩ ::= integer
⟨#fluids⟩ ::= integer
⟨#dirichlet-boundaries⟩ ::= integer
⟨#robin-boundaries⟩ ::= integer
⟨#neumann-boundaries⟩ ::= integer
⟨#successes⟩ ::= integer
⟨#failures⟩ ::= integer
 
⟨solid⟩ ::= ⟨green-id⟩ ⟨name⟩ ⟨lambda⟩ ⟨rho⟩ ⟨cp⟩ \
⟨power⟩ ⟨initial-temp⟩ ⟨imposed-temp⟩
⟨fluid⟩ ::= ⟨green-id⟩ ⟨name⟩ ⟨rho⟩ ⟨cp⟩ \
⟨initial-temp⟩ ⟨imposed-temp⟩
⟨lambda⟩ ::= real # Conductivity > 0 [W/m/K]
⟨rho⟩ ::= real # Volumic mass > 0 [kg/m^3]
⟨cp⟩ ::= real # Capacity > 0 [J/K/kg]
⟨power⟩ ::= real # Volumic power [W/m^3]
⟨initial-temp⟩ ::= real # Temperature [K]
⟨imposed-temp⟩ ::= real # Temperature [K]
 
⟨dirichlet-boundary⟩ ::= ⟨green-id⟩ ⟨name⟩ ⟨temp⟩
⟨robin-boundary⟩ ::= ⟨green-id⟩ ⟨name⟩ ⟨temp-ref⟩ \
⟨emissivity⟩ ⟨specular-fraction⟩ ⟨hc⟩ \
⟨temp⟩
⟨neumann-boundary⟩ ::= ⟨green-id⟩ ⟨name⟩ ⟨flux⟩
⟨emissivity⟩ ::= real # In [0,1]
⟨specular-fraction⟩ ::= real # In [0,1]
⟨hc⟩ ::= real # Convective coefficient [W/m^2/K]
⟨temp⟩ ::= real # Temperature [K]
⟨temp-ref⟩ ::= real # Reference temperature [K]
⟨flux⟩ ::= real # [W/m^2]
 
⟨rad-temp⟩ ::= ⟨green-id⟩ ⟨Trad⟩ ⟨Trad-ref⟩
⟨Trad⟩ ::= real # Radiative temperature [K]
⟨Trad-ref⟩ ::= real # Reference temperature [K]
 
⟨sample⟩ ::= ⟨end-type⟩ ⟨green-id⟩ \
⟨#power-terms⟩ ⟨#flux-terms⟩ \
⟨power-term⟩ ... ⟨flux-term⟩ ...
⟨end-type⟩ ::= ⟨end-dirichlet⟩
| ⟨end-robin⟩
| ⟨end-Trad⟩
| ⟨end-fluid⟩ # Fluid temperature
| ⟨end-solid⟩ # Solid temperature
⟨end-dirichlet⟩ ::=
⟨end-robin⟩ ::=
⟨end-Trad⟩ ::=
⟨end-fluid⟩ ::=
⟨end-solid⟩ ::=
⟨#power-terms⟩ ::= integer
⟨#flux-terms⟩ ::= integer
⟨power-term⟩ ::= ⟨green-id⟩ ⟨factor⟩
⟨flux-term⟩ ::= ⟨green-id⟩ ⟨factor⟩
⟨factor⟩ ::= real
 
⟨green-id⟩ ::= integer
⟨name⟩ ::= string

Binary Green outputs are formated according to the various C types from the stardis-green.h header file. The output begins with a header (of type struct green_file_header) that includes counts, followed by descriptions (of type struct green_description) and samples. Thereafter is the format of binary Green outputs. This output is produced by calls and does not take care of endianness.

The binary file format of a Green function is as follows:

⟨green-binary⟩ ::=
⟨file_format_version⟩
⟨#descriptions⟩
⟨#solids⟩
⟨#fluids⟩
⟨#robin-boundaries⟩
⟨#dirichlet-boundaries⟩
⟨#neumann-boundaries⟩
⟨#solid-fluid-connects⟩
⟨#solid-solid-connects⟩
⟨#successes⟩
⟨#failures⟩
⟨Trad⟩
⟨Trad-ref⟩
⟨time-range⟩
⟨description⟩ ...
⟨sample⟩ ...
 
⟨file_format_version⟩ ::= unsigned
⟨#descriptions⟩ ::= unsigned
⟨#solids⟩ ::= unsigned
⟨#fluids⟩ ::= unsigned
⟨#robin-boundaries⟩ ::= unsigned
⟨#dirichlet-boundaries⟩ ::= unsigned
⟨#neumann-boundaries⟩ ::= unsigned
⟨#solid-fluid-connects⟩ ::= unsigned
⟨#solid-solid-connects⟩ ::= unsigned
⟨#successes⟩ ::= size_t
⟨#failures⟩ ::= size_t
⟨Trad⟩ ::= double # Radiative temperature
⟨Trad-ref⟩ ::= double # Reference radiative temperature
⟨time-range⟩ ::= double[2]
 
⟨description⟩ ::= struct green_description
 
⟨sample⟩ ::= ⟨sample-header⟩
⟨power-id⟩ ...
⟨flux-id⟩ ...
⟨power-weight⟩ ...
⟨flux-weight⟩ ...
⟨sample-header⟩ ::= struct green_sample_header
⟨power-id⟩ ::= unsigned
⟨flux-id⟩ ::= unsigned
⟨power-weight⟩ ::= double
⟨flux-weight⟩ ::= double

Binary Green function can be followed by partial information on the sampled paths. The output data are restricted to paths' ends.

⟨paths⟩ ::=
⟨path-end⟩
...
 
⟨path-end⟩ ::= ⟨end-name⟩, ⟨end-id⟩, ⟨x⟩, ⟨y⟩, ⟨z⟩, \
⟨elapsed-time⟩
⟨end-name⟩ ::= string # Boundary name or TRAD
⟨end-id⟩ ::= integer
⟨x⟩ ::= real
⟨y⟩ ::= real
⟨z⟩ ::= real
⟨elapsed-time⟩ ::= real # [s]

A ⟨geometry-dump⟩ is generated when stardis(1) is invoked with option -d. In this mode, stardis(1) outputs the system geometry, as submitted in stardis-input(5) description, to standard output in VTK format. The output geometry is the concatenation of the various geometry files used in stardis-input(5) description. It is the result of a deduplication process that removes duplicate and degenerated triangles from the submited geometry. Additionaly, as permitted by the VTK format, the output geometry is decorated with many different properties provided to help users understand the description processing, including possible errors.

If errors are detected, some optional error-related data fields are included in the geometry file. Some errors report a by-triangle error status, other errors report a by-enclosure error status.

Also, holes in the geometry, if any, are reported in geometry dumps. A hole is defined by its frontier that is a collection of triangles surrounding the hole. Such triangles are detected as having their 2 sides in the same enclosure, but with a different medium on each side.

Media information is provided in two different flavours. First the medium on front and back sides of triangles can be found through the Front_medium and Back_medium fields. These fields use the special value INT_MAX for sides with no defined medium, as one can expect on boundary triangles. On the other hand, medium information provided by the Enclosures_internal_media field displays the id of the medium created to hold boundary information for boundary triangles. In either case, media numbering information can be found in log messages if option -V 3 is used in conjunction with the -d dump option.

The VTK layout is as follows:

⟨geometry-dump⟩ ::=
⟨description⟩
⟨vertices⟩
⟨triangles⟩
⟨#triangles⟩
⟨front-media⟩
⟨back-media⟩
⟨interfaces⟩
⟨unique-ids⟩
⟨user-ids⟩
[⟨merge-conflicts⟩]
[⟨property-conflicts⟩]
⟨file-ids⟩
⟨boundaries⟩
[⟨compute-region⟩]
⟨encl-or-overlaps⟩
 
⟨description⟩ ::= string # Up to 256 characters

⟨vertices⟩ ::= ⟨#vertices⟩ double
⟨x⟩ ⟨y⟩ ⟨z⟩
...
⟨triangles⟩ ::= ⟨#triangles⟩ ⟨#triangles*4⟩
⟨vertex-id⟩ ⟨vertex-id⟩ ⟨vertex-id⟩
...

List triangle indices stardis(1) deduplication:

⟨unique-ids⟩ ::=
⟨triangle-id⟩ # In [0, ⟨#triangles⟩]
... # Up to ⟨#triangles⟩

List triangle indices deduplication to let the caller indentify his geometry as submitted to stardis(1):

⟨user-ids⟩ ::=
⟨triangle-id⟩
... # Up to ⟨#triangles⟩

List the file identifier in which each triangle first appeared:

⟨file-ids⟩ ::=
⟨file-rank⟩
... # Up to ⟨#triangles⟩
 
⟨#vertices⟩ ::= integer
⟨#triangles⟩ ::= integer
⟨#triangles*4⟩ ::= integer
⟨vertex-id⟩ ::= integer # In [0, ⟨#vertices⟩]
⟨triangle-id⟩ ::= integer
⟨x⟩ ::= real
⟨y⟩ ::= real
⟨z⟩ ::= real
⟨file-rank⟩ ::= integer

⟨front-media⟩ ::=
⟨medium-id⟩ | ⟨undef-medium⟩
... # Up to ⟨#triangles⟩
⟨back-media⟩ ::=
⟨medium-id⟩ | ⟨undef-medium⟩
... # Up to ⟨#triangles⟩
⟨interfaces-media⟩ ::=
⟨interface-id⟩
... # Up to ⟨#triangles⟩
⟨boundaries⟩ ::=
⟨boundary-id⟩
... # Up to ⟨#triangles⟩
 
⟨medium-id⟩ ::= integer
⟨undef-medium⟩ ::=
⟨interface-id⟩ ::= integer
⟨boundary-id⟩ ::= integer

Define which triangles are members of the surface on which stardis(1) performs the calculation (options -F, -S or -s):

⟨compute-region⟩ ::=
⟨region-membership⟩
... # Up to ⟨#triangles⟩
⟨region-membership⟩ ::= # Not member
| # The front side is member
| # The back side is member
| # Both sides are members
| # Error: must not be member

Define which triangles have an invalid media definition when merging partitions:

⟨merge-conflicts⟩ ::=
⟨merge-conflict-id⟩
... # Up to ⟨#triangles⟩
⟨merge-conflict-id⟩ ::= # No conflict
| # Conflict

Define which triangles have an invalid limit condition or an invalid connection and report what is wrong:

⟨property-conflicts⟩ ::=
⟨prop-conflict-id⟩
...
⟨prop-conflict-id⟩ ::= # No conflict
| # Robin btw 2 defined fluids
| # Robin btw 2 undefined fluids
| # Robin on fluid applied to solid
| # Robin btw 2 defined solids
| # Robin btw 2 undefined solids
| # Robin on solid applied to fluid
| # Robin&Neumann btw 2 defined media
| # Robin&Neumann btw 2 undefined media
| # Robin&Neumann applied to fluid
| # Dirichlet btw 2 defined solids
| # Dirichlet btw 2 undefined solids
| # Dirichlet on solid applied to fluid
| # Neumann btw 2 defined media
| # Neumann btw 2 undefined media
| # Neumann applied to fluid
| # Solid/fluid btw 2 solids
| # Solid/fluid btw 2 fluids
| # Solid/fluid used as boundary
| # Solid/fluid btw 2 undefined media
| # No connection btw fluid/fluid
| # No connection btw solid/fluid
| # No boundary around fluid
| # No boundary around solid
| # Invalid part of a compute surface

⟨encl-or-overlaps⟩ ::= ⟨encl-information⟩
| ⟨overlappings⟩
 
⟨encl-information⟩ ::= [⟨holes⟩] # If any
⟨enclosures⟩
 
⟨enclosures⟩ ::=
⟨enclosures-geoms⟩
⟨enclosures-media⟩

Report which triangles surround a hole:

⟨holes⟩ ::=
⟨hole-membership⟩
... # Up to ⟨#triangles⟩
⟨hole-membership⟩ ::= # Not surrounding a hole
# Surrounding a hole

List the enclosures to which the triangle belongs and report the validity status of the enclosures:

⟨enclosures-geoms⟩ ::= ⟨#enclosures⟩ \
⟨#triangles⟩ unsigned_char
⟨encl-status⟩ ... # Up to ⟨#enclosures⟩
... # Up to ⟨#triangles⟩
⟨encl-status⟩ ::= # Not part of the enclosure
| # Enclosure is valid
| # More than 1 medium
| # Triangles with undef medium
| # More than 1 medium including undef

List the media that the triangle surrounds for each enclosure and report media description problems:

⟨enclosures-media⟩ ::= ⟨#enclosures⟩ \
⟨#triangles⟩ unsigned_char
⟨encl-media⟩ ... # Up to ⟨#enclosures⟩
... # Up to ⟨#triangles⟩
⟨encl-media⟩ ::= ⟨medium-id⟩ # Medium of the enclosure
| # Not part of the enclosure
| -1 # Error: in the enclosure
| -2 # Error: medium missing

Report problems of triangle overlap:

⟨overlappings⟩ ::=
unsigned_int 1
⟨overlapping-status⟩
... # Up to ⟨#triangles⟩
⟨overlapping-status⟩ ::= # Doesn't overlap another triangle
| # Error: overlaps another triangle
⟨#enclosures⟩ ::= integer

When invoked with option -R, stardis(1) calculates an infrared image of the system and write it to standard output. Depending on the fmt sub-option, this file can be either in htrdr-image(5) format or in VTK format.

⟨infrared-image⟩ ::= ⟨infrared-image-ht⟩ # Option -R fmt=HT
| ⟨infrared-image-vtk⟩ # Option -R fmt=VTK

The htrdr-image(5) layout of an infrared image is as follows:

⟨infrared-image-ht⟩ ::= ⟨definition⟩
⟨pixel⟩
... # Up to number of pixels
 
⟨definition⟩ ::= ⟨width⟩ ⟨height⟩
⟨width⟩ ::= integer
⟨height⟩ ::= integer
 
⟨pixel⟩ ::= ⟨temperature⟩ 0 0 0 0 ⟨time⟩
⟨temperature⟩ ::= ⟨estimate⟩
⟨time⟩ ::= ⟨estimate⟩ # Time per realisation
 
⟨estimate⟩ ::= ⟨expected-value⟩ ⟨standard-error⟩
⟨expected-value⟩ ::= real
⟨standard-error⟩ ::= real

See htpp(1) to convert images in htrdr-image(5) format into a regular image.

An infrared VTK image is an XY plane. By convention, the origin (0,0) pixel is at the top-left corner of the image. The result not only includes the computed temperature image, but also includes a per-pixel computation time image as well as a per-pixel path error count image and per-pixel standard deviation images for both temperature and computation time.

The VTK layout of an infrared image is as follows:

⟨infrared-image-vtk⟩ ::=
⟨description⟩
⟨width⟩ ⟨height⟩ 1
⟨#pixels⟩
⟨temp⟩
⟨temp-stderr⟩
⟨time⟩
⟨time-stderr⟩
⟨failures-count⟩
 
⟨temp⟩ ::=
real
... # Up to ⟨#pixels⟩
 
⟨temp-stderr⟩ ::=
real
... # Up to ⟨#pixels⟩
 
⟨time⟩ ::=
real
... # Up to ⟨#pixels⟩
 
⟨time-stderr⟩ ::=
real
... # Up to ⟨#pixels⟩
 
⟨failures-count⟩ ::=
integer
... # Up to ⟨#pixels⟩
 
⟨#pixels⟩ ::= integer # = ⟨width⟩ * ⟨height⟩
⟨width⟩ ::= integer
⟨height⟩ ::= integer
⟨description⟩ ::= string # Up to 256 characters

When the stardis(1) option -D is used in conjunction with an option that computes a result, some of the heat paths (successful paths, erroneous paths, or both) sampled during the simulation are written to files. Each path is written in VTK format, one VTK file per path. The path description can include vertices' time if it makes sense, that is if the computation time is not .

Due to the branching nature of non-linear Monte Carlo algorithms, paths are made of strips. With a Picard order of 1 (option -o 1), there is only a single strip. With higher orders, the number of strips can be greater than 1. As a result, the whole path is a tree: past the first strip, each strip can start from any vertex of one of the previous strips. This tree, when displaying the Branch_id field, starts with id 0, then increments each time a non-linearity leads to the creation of a new strip (to fetch a temperature).

The VTK layout of a path is as follows:

⟨heat-path⟩ ::=
⟨description⟩
⟨vertices⟩
⟨strips⟩
⟨#strips⟩
⟨status⟩
⟨#vertices⟩
⟨segment-types⟩
⟨weights⟩
⟨branch-ids⟩
[⟨vertices-time⟩] # If not steady
 
⟨description⟩ ::= string # Up to 256 characters
⟨#vertices⟩ ::= integer
⟨#strips⟩ ::= integer

List the vertices of the main trajectory and its branches:

⟨vertices⟩ ::= ⟨#vertices⟩ double
⟨x⟩ ⟨y⟩ ⟨z⟩
... # Up to ⟨#vertices⟩
⟨x⟩ ::= real
⟨y⟩ ::= real
⟨z⟩ ::= real

List the main trajectory and branches of the path:

⟨strips⟩ ::= ⟨#strips⟩ ⟨strip-list-size⟩
⟨#strip-vertices⟩ ⟨vertex-id⟩ ...
... # Up to ⟨#strips⟩
⟨strip-list-size⟩ ::= integer # vertices per strip + ⟨#strips⟩
⟨vertex-id⟩ ::= integer # In [0, ⟨#vertices⟩[

Status of the path:

⟨status⟩ ::=
| # 0: Success; 1: Failure
... # Up to ⟨#strips⟩

List the type of heat transfert to which each path vertex belongs:

⟨segment-types⟩ ::=
⟨segment-type⟩
... # Up to ⟨#vertices⟩
⟨segment-type⟩ ::= # Conduction
| # Convection
| # Radiative

Monte Carlo weight along the path:

⟨weights⟩ ::=
real
... # Up to ⟨#vertices⟩

List the identifier of the main path and its branches with respect to the branch depth:

⟨branch-ids⟩ ::=
integer # In [0, Picard_order[
... # Up to ⟨#vertices⟩

Rewinded time along the path:

⟨vertices-time⟩ ::=
real # Time [s]
... # Up to ⟨#vertices⟩

htpp(1), stardis(1), htrdr-image(5), stardis-input(5)

The VTK User's Guide, Kitware, Inc, 11, 470--482, 2010, Simple Legacy Formats.

April 12, 2024 UNIX