commit 15e12609d3fd0952da3365b174e1d188296aa26c
parent 4eee7d51b35756924d30a167666122a7404d30b3
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date: Thu, 9 Apr 2020 10:10:25 +0200
Documentation improvement; fix spelling
Diffstat:
11 files changed, 88 insertions(+), 85 deletions(-)
diff --git a/cmake/CMakeLists.txt b/cmake/CMakeLists.txt
@@ -35,7 +35,7 @@ set_property(CACHE STARDIS_DOC PROPERTY STRINGS
###############################################################################
# Generate files
###############################################################################
-set(STARDIS_ARGS_DEFAULT_AMBIANT_TEMP "300")
+set(STARDIS_ARGS_DEFAULT_AMBIENT_TEMP "300")
set(STARDIS_ARGS_DEFAULT_COMPUTE_TIME "INF")
set(STARDIS_ARGS_DEFAULT_RENDERING_FOV "70") # degrees
set(STARDIS_ARGS_DEFAULT_RENDERING_IMG_HEIGHT "480")
diff --git a/doc/stardis-input.5.txt b/doc/stardis-input.5.txt
@@ -28,28 +28,30 @@ DESCRIPTION
thermal system. It relies on a line-based ad-hoc syntax.
A thermal system is composed of lines of text, each one describing either a
-medium (solid or fluid) frontier, or a boundary (limit condition or connection
-between two media). In either case, the description line includes a list of
-file names that constitute the limit or boundary. The current version of
-*stardis* only accepts triangle mesh geometry files in *VTK* format.
+medium (solid or fluid) a frontier, or a boundary (limit condition or
+connection between two media). In either case, the description line includes a
+list of file names that constitute the limit or boundary. The current version
+of *stardis* only accepts triangle mesh geometry files in *VTK* format.
There are no constraints on triangle partitions: a medium limit or a boundary
description can be split accross files and description lines, and a single
file or description line can describe more than one frontier (more than one
connex region).
-Any physical quantity involved in descriptions is expected in the
-International System of Units (second, metre, kilogram, kelvin); the same
-applies to *stardis(1)* outputs as described in *stardis-output(5)*.
-
Finally, description lines can be submitted to the *stardis*(1) program in
any order and can be split accross more than one file, through multiple use
of the *-M* option.
+UNITS
+-----
+Any physical quantity involved in descriptions is expected in the
+International System of Units (second, metre, kilogram, kelvin); the same
+applies to *stardis(1)* outputs as described in *stardis-output(5)*.
+
GRAMMAR
-------
In what follows, some lines end in *\*. This is used as a convenience to
-continue a description next line. However, this character cannot be used in
+continue a description next line. However, this trick cannot be used in
actual description files and actual description lines must be kept single-line.
Also, text appearing between quote marks has to be used verbatim in the input,
except the quote characters. Finally, text following the *#* character in
@@ -152,7 +154,6 @@ ______________
TRIANGLE SIDES
--------------
-
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
@@ -161,20 +162,18 @@ used with the FRONT side specifier to describe inside medium.
NAMES
-----
-
Names, either file names, medium names or boundary names, are a sequence of
one or ore ASCII characters, including numbers and special characters like
*.* *_* *-* as one may consider using in standard file names, *without any
spacing* either escaped or not.
-Two different description lines can use the same name. However, computating
+Two different description lines can use the same name. However, computing
mean temperature in a given medium (*-m* option of *stardis*) has an undefined
behaviour when the medium name has been used more than once in the system
description.
EXAMPLES
--------
-
Define a solid cube with a h boundary. The cube geometry is read from the file
cube.stl and the solid medium properties are lambda=0.1, rho=25, cp=2. The
numerical parameter delta, that is used for solid conductive walks, is 0.05.
diff --git a/doc/stardis-output.5.txt b/doc/stardis-output.5.txt
@@ -25,21 +25,26 @@ stardis-output - output format of stardis(1) results
DESCRIPTION
-----------
The *stardis-output* describes the output format of the *stardis*(1) program.
-All the data generated by a *stardis*(1) invocation are written to the standard
-output.
+All the data generated by a *stardis*(1) invocation are written to _standard
+output_.
The type of the data that are generated depends on the option used when
*stardis*(1) is invoked. When invoked with one of the basic computation options
(*-p*, *-P*, *-m*, *-s* or *-F*), *stardis*(1) output a single Monte-Carlo
result. On the opposite, *stardis*(1) ouputs compound results when invoked with
option *-S* or *-R*. Additionally, options *-g* and *-D* are output modifiers.
+
Finaly, some special options (*-v*, *-h* or *-d*) that does not involve any
computation produce output including information on the *stardis*(1) software
(their ouput will not be described thereafter) or the provided thermal system.
+UNITS
+-----
+As for values in *stardis-input*(5), any physical quantity in output is in the
+International System of Units (second, metre, kilogram, kelvin).
+
OPTIONS
-------
-
Every top-level item of the output listed below is produced by one or more
specific options of the *stardis*(1) program. The following list gives the
correspondance:
@@ -63,7 +68,7 @@ correspondance:
GRAMMAR
-------
In what follows, some lines end in *\*. This is used as a convenience to
-continue a description next line. However, this character is not part of the
+continue a description next line. However, this trick is not part of the
actual output, that continues on a single line. On the other hand, multiple
lines not using the *\* convenience in multi-lines descriptions are truly
different lines of output. Also, text appearing between quote marks is a
@@ -82,7 +87,7 @@ _______
SINGLE MONTE CARLO
------------------
When *stardis*(1) is used to produce a single Monte-Carlo result, either
-temperature or flux, this result is output first to standard output, possibly
+temperature or flux, this result is output first to _standard output_, possibly
followed by some of the heat paths involved in the computation if option *-D*
was used too.
@@ -145,7 +150,6 @@ _______
GREEN
-----
-
The green function is generated when a green-compatible *stardis*(1) simulation
option is used in conjuction with the *-g* option. For every successful heat
path sampled carrying out the simulation, the solver records all the elements
@@ -158,10 +162,9 @@ by the paths' history.
DUMP GEOMETRY
-------------
-
A *geometry-file* is generated when *stardis*(1) is invoked with the *-d*
option. In this mode, *stardis*(1) outputs the system geometry, as submitted
-in *stardis-input*(5) description, to standard output in the VTK [1] format.
+in *stardis-input*(5) description, to _standard output_ in the VTK [1] format.
The output geometry is not 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.
@@ -174,9 +177,9 @@ DUMP HEAT PATHS
---------------
When the *stardis*(1) option *-D* is used some of the termal paths (either
successful paths, erroneous paths, or both) sampled carrying out the simulation
-are written to standard output after to the computation result. The various path
-are written in VTK[1] format, one VTK file per path separated by a special text
-line.
+are written to _standard output_ after to the computation result. The various
+path are written in VTK [1] format, one VTK file per path separated by a
+special text line.
[verse]
_______
@@ -248,7 +251,8 @@ _______
RENDERING
---------
When invoked with the *-R* option, *stardis*(1) generates an infrared image
-file of the system and write it to standard output in the VTK file format [1].
+file of the system and write it to _standard output_ in the VTK [1] file
+format.
NOTES
-----
diff --git a/doc/stardis.1.txt.in b/doc/stardis.1.txt.in
@@ -51,13 +51,13 @@ information on the system in an unbiased and very-fast statistical model.
In addition of the aforementioned computations, *stardis* provides three
other functionalities. The *-d* option can be used to convert the
*stardis-input*(5) geometry into a VTK file. The *-D* option saves the sampled
-heat paths used by the estimates, allowing to visualise them externally
+heat paths used to build the estimate, allowing to visualise them externally
which may be of a great help to identify issues. Finally, the *-R* option
can be used to render an infrared image of the submitted system.
-The provided system should be described in the *stardis-input*(5) format
-and can be split over any number of files, each being submited through the
-*-M* option.
+The provided system description should comply with the *stardis-input*(5)
+format and can be split over any number of files, each being submited through
+the *-M* option.
Stardis' algorithms are based on state-of-the-art Monte-Carlo method applied
to radiative transfer physics (Delatorre [1]) combined with conduction's
@@ -88,9 +88,9 @@ Transactions of the American Mathematical Society, 1956.
MANDATORY OPTIONS
-----------------
*-M* _file_::
- Read a text file containing a (partial) description of the system.
+ Read a text file containing a possibly partial description of the system.
Can include both media enclosures and boundary conditions, in any order.
- Can be used more than once if the description is splited across different
+ Can be used more than once if the description is split across different
files.
EXCLUSIVE OPTIONS
@@ -103,35 +103,35 @@ EXCLUSIVE OPTIONS
*-P* _x,y,z[,time]_::
Compute the temperature at the given probe on an interface at a given time.
By default compute time is @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The probe is
- suposed to be on an interface and is moved to the closest point of the
- closest interface.
+ supposed to be on an interface and is moved to the closest point of the
+ closest interface before the computation start.
*-m* _medium_name[,time]_::
Compute the mean temperature in a given medium at a given time. The medium
name must be part of the system description. By default compute time is
- @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The medium doesn't need to be connex.
+ @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The medium does not need to be connex.
*-s* _file[,time]_::
Compute the mean temperature on a given 2D region at a given time, the
region being defined as the front sides of the triangles in the provided
*STL* file. By default compute time is @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@.
These triangles are not added to the geometry, but must be part of it. The
- region doesn't need to be connex.
+ region does not need to be connex.
*-S* _file[,time]_::
Compute the by-triangle mean temperature on a given 2D region at a given
time, the region being defined as the front sides of the triangles in the
- provided *VTK* file. By default compute time is
- @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. These triangles are not added to the
- geometry, but must be part of it. The region doesn't need to be connex.
+ provided *VTK* file. These triangles are not added to the geometry, but must
+ be part of it. By default compute time is
+ @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@. The region does not need to be connex.
*-F* _file[,time]_::
Compute the mean flux on a given 2D region at a given time, the region
being defined as the front sides of the triangles in the provided *VTK* file.
- By default compute time is @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@.
- Flux is accounted positive when going from the front side to the back side,
- at a single-triangle level. These triangles are not added to the geometry,
- but must be part of it. The region doesn't need to be connex.
+ These triangles are not added to the geometry, but must be part of it. Flux
+ is accounted positive when going from the front side to the back side, at a
+ single-triangle level. By default compute time is
+ @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@.The region does not need to be connex.
*-R* [__sub-option__:...]::
Render an infrared image of the system through a pinhole camera and write it
@@ -147,7 +147,9 @@ EXCLUSIVE OPTIONS
**pos=**_x_**,**_y_**,**_z_;;
Position of the camera. By default it is set to
- {@STARDIS_ARGS_DEFAULT_RENDERING_POS@}.
+ {@STARDIS_ARGS_DEFAULT_RENDERING_POS@} or it is automatically computed to
+ ensure that the whole scene is visible, whether *tgt* is set or not,
+ respectively.
**spp=**_samples-count_;;
Number of samples per pixel.
@@ -164,16 +166,14 @@ EXCLUSIVE OPTIONS
respectively.
**up=**_x_**,**_y_**,**_z_;;
- Up vector of the camera. If *rmode* is *pt*, this vector also defines the
- direction toward the top of the skydome. By default, *up* is set to
+ Up vector of the camera. By default, it is set to
{@STARDIS_ARGS_DEFAULT_RENDERING_UP@}.
OTHER OPTIONS
-------------
-
-*-a* _ambiant_::
- Set *ambiant* as the ambient radiative temperature for the whole system.
- By default *ambiant* is @STARDIS_ARGS_DEFAULT_AMBIANT_TEMP@.
+*-a* _ambient_::
+ Set the ambient radiative temperature for the whole system. By default
+ *ambient* is @STARDIS_ARGS_DEFAULT_AMBIANT_TEMP@.
*-d*::
Write the geometry to _standard output_ in VTK format along with various
@@ -183,16 +183,16 @@ OTHER OPTIONS
Using this option in conjunction with an option that
specifies a compute region (-s, -S, -F) has the effect to include the
region in the output. This option cannot be used in conjunction with other
-options that write to _standard output_ (-R, -g, -D, -h, -v).
+options that write to _standard output_ (-R, -g, -D, -h, -v).
*-D* _type_::
Write heat paths of the given *type* to _standard output_ in VTK format.
Possible values are *error* (write paths ending in error), *success*
- (write successful paths),*all* (write all paths).
+ (write successful paths), and *all* (write all paths).
+
This option can only be used in conjuction with an option that runs a
computation (-p, -P, -m, -s, -R, -S, -F) and cannot be used in conjunction
-with other options that write to _standard output_ (-R, -d, -g, -h, -v).
+with some other options that write to _standard output_ (-R, -d, -g, -h, -v).
**-f** _factor_::
Rescale the geometry by the given *factor* before sending it to the solver,
@@ -200,57 +200,57 @@ with other options that write to _standard output_ (-R, -d, -g, -h, -v).
is @STARDIS_ARGS_DEFAULT_SCALE_FACTOR@.
*-g*::
- Write the green function at a steady state to _standard output_ after the
+ Write the green function at steady state to _standard output_ after the
specified computation.
+
This option can only be used in conjonction with one these options: -p, -P,
--m, -s. Any provided compute time is silently ignored.
+-m, -s. Any compute time provided through one of these options is silently
+ignored.
*-h*::
Output short help and exit.
*-n* _samples-count_::
- Number of Monte-Carlo samples. By default _samples-count_ is set to
+ Number of Monte-Carlo samples. By default *samples-count* is set to
@STARDIS_ARGS_DEFAULT_SAMPLES_COUNT@.
*-r* _reference_::
- Set *reference* as the temperature used for the linearization of the
- radiative transfer. By default *reference* is
- @STARDIS_ARGS_DEFAULT_REFERENCE_TEMP@.
+ Set the reference temperature used for the linearization of the radiative
+ transfer. By default *reference* is @STARDIS_ARGS_DEFAULT_REFERENCE_TEMP@.
*-t* _threads-count_::
Hint on the number of threads to use. By default use as many threads as CPU
cores.
*-V* _level_::
- Set the verbosity level according to the following list. Default verbosity
- *level* is @STARDIS_ARGS_DEFAULT_VERBOSE_LEVEL@.
+ Set the verbosity level. Possible values are:
* *0*: (write no message to _standard error_),
* *1*: (write error messages only to _standard error_),
* *2*: (write error and warning messages to _standard error_),
* *3*: (write error, warning and informative messages to _standard error_).
++
+Default verbosity *level* is @STARDIS_ARGS_DEFAULT_VERBOSE_LEVEL@.
*-v*::
Output version information and exit.
EXAMPLES
--------
-
-Pre-process the system as described in *scene.txt* when intending to compute
+Preprocess the system as described in *scene.txt* when intending to compute
the mean flux on the triangles from the file *edge.stl*, and write its geometry
in the file *scene.vtk*. Verbosity level is set to *3*:
$ stardis -M scene.txt -F edge.stl -d -V 3 > scene.vtk
-Compute the temperature at the probe point *0, 0.5, 0* at the steady state. The
-system is read from the 2 files *media.txt* and *bound.txt* and the number of
+Compute the temperature at the probe point *0, 0.5, 0* at steady state. The
+system is read from the 2 files *media.txt* and *bounds.txt* and the number of
samples is set to *1000000*:
$ stardis -M media.txt -M bounds.txt -p 0,0.5,0 -n 1000000
Compute the mean temperature in the medium *med05* at *t=100* s. The system is
-read from the 2 files *media.txt* and *bound.txt*:
+read from the 2 files *media.txt* and *bounds.txt*:
$ stardis -M media.txt -M bounds.txt -m med05,100
diff --git a/src/stardis-app.c b/src/stardis-app.c
@@ -504,7 +504,7 @@ stardis_init
stardis->samples = args->samples;
stardis->nthreads = args->nthreads;
stardis->scale_factor = args->scale_factor;
- stardis->ambiant_temp = args->ambiant_temp;
+ stardis->ambient_temp = args->ambient_temp;
stardis->ref_temp = args->ref_temp;
stardis->dump_paths = SDIS_HEAT_PATH_NONE;
if(args->dump_paths & DUMP_ERROR)
diff --git a/src/stardis-app.h b/src/stardis-app.h
@@ -738,7 +738,7 @@ struct stardis {
size_t samples;
unsigned nthreads;
double scale_factor;
- double ambiant_temp, ref_temp;
+ double ambient_temp, ref_temp;
struct mem_allocator* allocator;
struct logger* logger;
struct sdis_device* dev;
diff --git a/src/stardis-compute.c b/src/stardis-compute.c
@@ -175,7 +175,7 @@ compute_probe(struct stardis* stardis)
stardis->samples,
pos,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
&green));
ERR(dump_green(green, stardis, stdout));
@@ -187,7 +187,7 @@ compute_probe(struct stardis* stardis)
pos,
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
stardis->dump_paths,
&estimator));
@@ -222,7 +222,7 @@ compute_probe_on_interface(struct stardis* stardis)
uv,
SDIS_FRONT,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
&green));
ERR(dump_green(green, stardis, stdout));
@@ -236,7 +236,7 @@ compute_probe_on_interface(struct stardis* stardis)
time,
SDIS_FRONT,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
stardis->dump_paths,
&estimator));
@@ -279,7 +279,7 @@ compute_camera(const struct stardis* stardis)
cam,
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
width,
height,
@@ -324,7 +324,7 @@ compute_medium(struct stardis* stardis)
stardis->samples,
medium,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
&green));
ERR(dump_green(green, stardis, stdout));
@@ -336,7 +336,7 @@ compute_medium(struct stardis* stardis)
medium,
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
stardis->dump_paths,
&estimator));
@@ -417,7 +417,7 @@ compute_boundary(struct stardis* stardis)
darray_sides_cdata_get(&stardis->compute_surface.sides),
darray_size_t_size_get(&stardis->compute_surface.primitives),
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
&green));
ERR(dump_green(green, stardis, stdout));
@@ -430,7 +430,7 @@ compute_boundary(struct stardis* stardis)
darray_size_t_size_get(&stardis->compute_surface.primitives),
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
stardis->dump_paths,
&estimator));
@@ -462,7 +462,7 @@ compute_flux_boundary(struct stardis* stardis)
darray_size_t_size_get(&stardis->compute_surface.primitives),
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
&estimator));
ERR(print_single_MC_result(estimator, stardis, stdout));
@@ -504,7 +504,7 @@ compute_map(struct stardis* stardis)
1,
time,
stardis->scale_factor,
- stardis->ambiant_temp,
+ stardis->ambient_temp,
stardis->ref_temp,
stardis->dump_paths,
darray_estimators_data_get(&estimators) + p));
diff --git a/src/stardis-default.h.in b/src/stardis-default.h.in
@@ -16,7 +16,7 @@
#ifndef STARDIS_DEFAULT_H
#define STARDIS_DEFAULT_H
-#define STARDIS_DEFAULT_AMBIANT_TEMP @STARDIS_ARGS_DEFAULT_AMBIANT_TEMP@
+#define STARDIS_DEFAULT_AMBIENT_TEMP @STARDIS_ARGS_DEFAULT_AMBIENT_TEMP@
#define STARDIS_DEFAULT_COMPUTE_TIME @STARDIS_ARGS_DEFAULT_COMPUTE_TIME@
#define STARDIS_DEFAULT_RENDERING_FOV @STARDIS_ARGS_DEFAULT_RENDERING_FOV@
#define STARDIS_DEFAULT_RENDERING_IMG_HEIGHT @STARDIS_ARGS_DEFAULT_RENDERING_IMG_HEIGHT@
diff --git a/src/stardis-output.c b/src/stardis-output.c
@@ -505,7 +505,7 @@ dump_green
fprintf(stream, "# Radiative Temperatures\n");
fprintf(stream, "# ID Rad_Temp Lin_Temp\n");
fprintf(stream, "%u\t%g\t%g\n",
- szd, stardis->ambiant_temp, stardis->ref_temp);
+ szd, stardis->ambient_temp, stardis->ref_temp);
fprintf(stream, "# Samples\n");
fprintf(stream,
diff --git a/src/stardis-parsing.c b/src/stardis-parsing.c
@@ -291,7 +291,7 @@ init_args
args->nthreads = DEFAULT_NTHREADS;
args->probe[3] = STARDIS_DEFAULT_COMPUTE_TIME;
args->scale_factor = STARDIS_DEFAULT_SCALE_FACTOR;
- args->ambiant_temp = STARDIS_DEFAULT_AMBIANT_TEMP;
+ args->ambient_temp = STARDIS_DEFAULT_AMBIENT_TEMP;
args->ref_temp = STARDIS_DEFAULT_REFERENCE_TEMP;
args->verbose = STARDIS_DEFAULT_VERBOSE_LEVEL;
@@ -488,9 +488,9 @@ re_switch:
}
case 'a':
- res = cstr_to_double(optarg, &args->ambiant_temp);
+ res = cstr_to_double(optarg, &args->ambient_temp);
if(res != RES_OK
- || args->ambiant_temp < 0)
+ || args->ambient_temp < 0)
{
if(res == RES_OK) res = RES_BAD_ARG;
logger_print(args->logger, LOG_ERROR,
diff --git a/src/stardis-parsing.h b/src/stardis-parsing.h
@@ -94,7 +94,7 @@ struct args {
double probe[4];
enum stardis_mode mode;
double scale_factor;
- double ambiant_temp, ref_temp;
+ double ambient_temp, ref_temp;
char* camera;
enum dump_path_type dump_paths;
int verbose;
