# Stardis The Monte-Carlo framework for coupled thermal problems

Stardis is a **thermal simulation** framework for **complex 2D and 3D
environments**, based on new **Monte-Carlo** algorithms built from
reformulations of the main heat transfer phenomena: conduction, convection and
radiation. A set of cross-recursive algorithms have then been derived, and
result in the simulation of "**thermal paths**" that explore space and time
until a boundary condition or an initial condition is found. The key concept
here is that heat transfer phenomena are not considered separately but are
**naturally coupled** via the cross-recursion of the various Monte-Carlo
algorithms.

Beyond its use as a regular thermal simulation tool, the Stardis framework
explicitly targets engineers, researcher, teachers or students wishing to
fully appropriate the **statistical formulation of heat transfer**, from
theoretical concepts to practical implementation. The complete Stardis
framework is thus released under **free licenses**
that guarantee the users the ability to freely use, study, modify or extend
the complete source code according to their needs.

Refer to the Stardis consortium service
offer to **learn** how to use it, **influence** its orientation choices
and **interact** with its developers and other users.

In 2021, Électricité de France R&D became the first member of the Stardis consortium.

Despite its specific advantages, Stardis is not meant to fully replace already well established and highly validated thermal simulation tools. Instead, it can be seen as an additional tool that can be useful for various purposes:

**Probe computation**: Stardis will__not__compute the full temperature field of a system; instead, it can be used to focus on a specific spatial/temporal zone of the system.**Reference method**: the numerical uncertainty is a unique feature of stochastic methods. It can be reduced using a reformulation of the underlying integral for specific problems, and possibly using better suited sampling techniques. Ultimately, the numerical uncertainty can also be reduced by increasing the number of statistical samples. Any value of temperature (or flux) computed by Stardis must agree with the values computed by other tools, within the uncertainty range (and also within the limits of validity of the various assumptions used to derive the Monte-Carlo algorithms used in Stardis). This can prove very useful in order to validate any result obtained by any thermal solver in a case when no analytic solution is available or when a physical intuition is impossible to achieve due to the complexity of the problem.**Educational purposes**: since the various probability sets used by the underlying Monte-Carlo algorithms solely rely on the physics, thermal paths naturally explore the spatial and temporal zones of interest in the system. This can be a drawback in some situations (the paths will have a hard time exiting a highly conductive solid surrounded by non-conductive media) but is a major asset for the direct visualization of what contributes to a given result: the main sources of heat, what transfer modes are dominant, what are the main paths of heat transfer,*etc.***Sensitivity analysis**: the Green functions of the system (estimated and stored during an initial Monte-Carlo computation) can be reused for subsequent (very fast) post-processing computations. This makes possible to explore the sensitivity of any given result to the variations of a boundary or initial condition, or internal power source. This technique is only a small part of a family of so-called "symbolic" Monte-Carlo algorithms that extend the scope of sensitivity analysis to any thermal parameter (for instance: the conductivity of a given solid, a convective exchange coefficient or the emissivity of a solid).

The Stardis framework is structured around **two main components**. The
first one, Stardis-Solver, is the core library that
implements the Monte-Carlo algorithms. The second one is the Stardis application, a command line tool that can be seen as a
reference implementation of a complete workflow relying on Stardis-Solver, from
input data describing the system to simulate (geometry, thermal properties,
limit conditions, *etc.*) to heat transfer simulation and results
post-processing. See below for more information on each of these components.

## Stardis-Solver

Stardis-Solver
is the core library of Stardis: it simulates coupled convecto - conducto -
radiative heat transfers by sampling thermal paths that explore space and time
until a boundary condition or an initial condition is met. Note that this
path formulation does not require **any volumetric mesh**: in addition of
the thermal properties and the limit/boundary conditions, only the geometry
defining the contours of the objects is necessary.

The Stardis-Solver library is currently used in the two following projects:

- Stardis application is the reference implementation of a complete workflow using Stardis-Solver.
- SYRTHES is the general thermal software developed by Électricité de France R&D.

The coupled Monte-Carlo algorithms implemented into Stardis-Solver are based on the following hypothesis:

**Conduction**: the discretization of thermal heat transfer in solids introduces the notion of a conductive**path length**within the Monte-Carlo algorithm. Solutions obtained using this algorithm are formally exact at the limit of a null path length. In practice, this path length has to be adapted, at the individual solid level, so that its value is small compared to the typical length of the solid.**Convection**: fluid media are supposed to be**isothermal**, even if their temperature may vary with time. This hypothesis relies on the assumption of perfectly agitated fluids.**Radiation**: local radiative transfer is solved by an iterative numerical method (Picard algorithm) that requires the knowledge of a reference temperature field. At the basic level (one level of recursion), and using a uniform reference temperature field, this algorithm translates into the hypothesis of a linearized radiative transfer. Using a higher order or recursion makes possible to converge the result closer to the solution of a rigorous spectrally-integrated radiative transfer (a difference of temperatures to the power 4 when integrated over the whole spectrum). The higher the recursion order, the better will be the convergence of the algorithm.

The remaining of this section describes the main functionalities provided by Stardis-Solver upon the aforementioned hypothesis.

### Probe computation

Stardis-Solver computes the temperature at any given position (spatial and
temporal). The main idea is that thermal paths start from this probe position,
and scatter in space while going back in time, until a (spatial) boundary
condition or a (temporal) initial condition is met. In addition to the value of
temperature, using a Monte-Carlo method makes it possible to compute a **numerical
uncertainty** (standard deviation of the weight distribution) over each
result.

### Flux computation

Stardis-Solver can compute the flux over any surface (or group of surfaces) at any time. Alternatively, it can also compute the total energy output from a solid element where an internal source of power must be taken into account.

### Green function

The value of temperature computed at a probe position is no more than the mean of the Monte-Carlo weights of a set of thermal paths. In practice: when no internal power source has to be considered, the weight of any given thermal path is the temperature of the boundary or initial condition that has been reached; when internal power sources or imposed fluxes are taken into account, additional contributions to the weight must be continuously evaluated by the thermal conduction algorithm, but these contributions are proportional to the local dissipated power and imposed flux.

In any case, the position and date at the end of each thermal path (and also accumulation coefficients) can be stored during a first complete Monte-Carlo simulation. This information, known as the Green function, can then be used in a (very fast) post-processing step to compute all required results for different boundary and initial conditions (and also different internal power sources and imposed flux).

### Infrared rendering

Stardis can render a scene in infrared without prior knowledge of the temperature field. Thermal paths that start at the camera in radiative mode propagate through the model, possibly in conductive, convective or radiative mode until reaching a boundary condition (or an initial condition in a non-stationary case).

### Temporal dynamics analysis

Stardis-Solver can output the end of each path sampled during a Monte-Carlo computation, including position, elapsed time, and boundary/medium ID. This not only allows to weight the contribution of each boundary or initial condition to the result, but also gives the temporal dynamics of these contributions.

### Thermal path visualization

Stardis-Solver can output the complete history of a set of thermal paths for later visualization. In addition to positions and dates, physics data is stored along thermal paths, such as the type of heat transfer phenomenon involved at each step, the accumulated power and flux, etc.

## Stardis CLI tools

The stardis framework includes Command Line Interface (CLI) software, namely stardis and sgreen, to use along with Stardis-Solver. Even if these software are intended as reference implementations, they allow to easily exploit some of the functionalities of the solver.

### The stardis CLI

The main CLI tool of the Stardis framework is **stardis**. It can be seen
as a limited but easy-to-use front-end to the stardis solver. Depending on the
provided command line arguments, it simulates a thermal system described
through a simple text file and geometry files and produces various types of
output, from simple Monte-Carlo results to infrared images or Green
functions.

The main limitation that the **stardis** CLI adds to those of
Stardis-Solver is that property descriptions cannot be time or space dependent:
each region of the system, delimited by a boundary, can have its own set of
properties, but these properties must be constant (whereas stardis-solver allows
properties varying in time and space).

### The sgreen CLI

The only purpose of **sgreen** is to post-process binary green-function
files produced by the stardis CLI. It allows to apply a set of values to the
initial and boundary conditions as well as the power and flux sources of the
model to produce the same result a new simulation would produce. The obvious
benefit of using the sgreen post-process instead of a new Monte-Carlo
simulation is the tremendous improvement on computation time.

## Quick start

Pre-compiled versions of Stardis are distributed for the GNU/Linux system
but **to enable distributed parallelism via MPI, you must compile Stardis on the
target machine** (see below). To use a precompiled version, first download the
desired archive of Stardis and check its integrity against its PGP signature. Then extract it:

$ wget https://www.meso-star.com/projects/stardis/downloads/\ Stardis-0.13.1-GNU-Linux64.tar.gz $ wget https://www.meso-star.com/projects/stardis/downloads/\ Stardis-0.13.1-GNU-Linux64.tar.gz.sig $ gpg --verify Stardis-0.13.1-GNU-Linux64.tar.gz.sig $ tar xzf Stardis-0.13.1-GNU-Linux64.tar.gz

We have now to generate the `stardis.profile`

POSIX shell script
that is going to be executed in the running shell to update its environment
variables with the install directories of `stardis`

that, once done,
can be finally be run.

Now we need to generate the `stardis.profile`

POSIX shell script
that we run in the running shell to update its environment variables with the
Stardis installation directory. Once this is done, we can run the
`stardis`

program.

$ sh ~/Stardis-0.13.1-GNU-Linux64/etc/build-stardis-profile.sh $ . ~/Stardis-0.13.1-GNU-Linux64/etc/stardis.profile $ stardis -h # Launch stardis

Note that if the `build-stardis-profile.sh`

script should no
longer be run as long as the Stardis installation directory remains the same,
the `stardis.profile`

script must be run in each new POSIX shell in
which you want to give access to the Stardis installation.

The **reference documentation** of the Stardis CLI and of its associated
tools and fileformats is located in the `share/man`

sub-directory.
To consult it, simply invoke the `man`

command-line.

$ man stardis $ man stardis-input $ man stardis-output $ man sgreen $ man sgreen-input $ man sgreen-output

Refer to the Stardis: Starter Pack to quickly
run a thermal simulation through the `stardis`

CLI; this archive
provides input data and scripts and is a good starting point to begin with the
Stardis framework.

## Build from sources

The Stardis framework can be built directly from its source tree. Note that
it is actually the only way to **enable distributed parallelism** via the
Message Passing Interface specification, precompiled version of Stardis does
not support MPI.

The simplest way to build Stardis from its sources is to rely on the
`stardis`

branch of the Star-Engine
project: it provides CMake scripts that automate the download, the compilation
and the installation of Stardis. This build procedure assumes the following
prerequisites:

- git source control.
- GNU Compiler Collection in version 4.8.4 or higher.
- CMake in version 3 or higher.
- OpenMPI 2 or higher if
distributed memory parallelism is enabled via the
`ENABLE_MPI`

variable of the build system. - Optionally, the AsciiDoc tool suite to generate the man pages of the reference documentation.

### Build

Assuming that the aforementioned prerequisites are available, the build procedure is summed up to:

~ $ git clone -b Stardis-0.13.1 \ https://gitlab.com/meso-star/star-engine.git Stardis-0.13.1 ~ $ mkdir Stardis-0.13.1/build; cd Stardis-0.13.1/build ~/Stardis-0.13.1/build $ cmake ../cmake -DDEPLOY_STARDIS_CLI=ON -DENABLE_MPI=ON ~/Stardis-0.13.1/build $ make

Note that on CMake configuration step, we define the variables
`DEPLOY_STARDIS_CLI`

and `ENABLE_MPI`

to enable the
installation of the Stardis CLI tools and support for distributed parallelism
via MPI.

By default Stardis is installed in the `local`

subdirectory of
`Stardis-0.13.1`

. As the last step of the installation, we need
to generate the `stardis.profile`

POSIX shell script that will be
run in a running shell to update its environment variables with the Stardis
installation directory.

$ sh ~/Stardis-0.13.1/local/etc/build-stardis-profile.sh

### Run

Before running stardis, you must first run the `stardis.profile`

script once in the current POSIX shell to update its environment variables.
Then you can run the stardis program and check out its reference
documentation.

$ . ~/Stardis-0.13.1/local/etc/stardis.profile $ stardis -h

We point out that the `stardis.profile`

script must be run in
each new POSIX shell in which you want to give access to the Stardis
installation.

### Package

Once built, the Stardis installation can be packaged in an archive that can
then be deployed on compatible systems, *i.e.* systems whose C library is
compatible with the one available on the system used to build Stardis.

~/Stardis-0.13.1/build $ make pkg ~/Stardis-0.13.1/build $ ls package/Stardis-0.13.1* # list packages

## License

Stardis is free software released under the GPLv3+ license: GNU GPL version 3 or later. You can freely study, modify or extend it. You are also welcome to redistribute it under certain conditions; refer to the license for details.