stardis

Perform coupled heat transfer calculations
git clone git://git.meso-star.fr/stardis.git
Log | Files | Refs | README | LICENSE

commit 1c8a9b77247bf7778944e2fd5e8642f265a4e06b
parent 467a8b62c5fffce1da39566a9c1b623b32cdb595
Author: Christophe Coustet <christophe.coustet@meso-star.com>
Date:   Sun, 29 Mar 2020 17:23:43 +0200

Fix fake doc so that produced output files have expected names

Diffstat:
Mdoc/stardis-input.5.txt | 50+++++++++++++++++++++++++-------------------------
Mdoc/stardis-output.5.txt | 56++++++++++++++++++++++++++++----------------------------
Mdoc/stardis.1.txt.in | 70+++++++++++++++++++++++++++++++++++-----------------------------------
3 files changed, 88 insertions(+), 88 deletions(-)

diff --git a/doc/stardis-input.5.txt b/doc/stardis-input.5.txt @@ -14,30 +14,30 @@ // along with this program. If not, see <http://www.gnu.org/licenses/>. :toc: -solstice-input(5) +stardis-input(5) ================= NAME ---- -solstice-input - solar plant description for solstice(1) +stardis-input - solar plant description for stardis(1) DESCRIPTION ----------- -The *solstice-input* is the format used by the *solstice*(1) program to +The *stardis-input* is the format used by the *stardis*(1) program to represent a solar plant. It relies on the YAML 1.1 data serialization standard -[1]; assuming that the file is compatible with the *solstice-input* semantic, a +[1]; assuming that the file is compatible with the *stardis-input* semantic, a solar plant can be described by using the whole YAML 1.1 functionalities including compact notation and data tagging. A solar plant is composed of a *sun*, an optional *atmosphere* and a collection of *geometries*, i.e. *shapes* with their associated *material*. Beside the raw -description of the aforementioned data, the *solstice-input* format provides +description of the aforementioned data, the *stardis-input* format provides the *entity* item to efficiently structure the geometries in the scene. An entity is a node in a tree data structure where the position of each child entity is relative to the position of its parent. An entity can either encapsulate a *geometry* or a *pivot* that controls the dynamic positioning of its child entities with respect to the pivot constraints and the sun direction -submitted to the *solstice*(1) program. +submitted to the *stardis*(1) program. GRAMMAR ------- @@ -296,16 +296,16 @@ SUN --- The *sun* describes the source of the solar plant. Its direction is not defined -into the *solstice-input*(5) file but is provided by the *solstice*(1) command. -This allows to use the same unmodified *solstice-input*(5) file for several +into the *stardis-input*(5) file but is provided by the *stardis*(1) command. +This allows to use the same unmodified *stardis-input*(5) file for several simulations with different sun directions. The main *sun* property is its direct normal irradiance, or *dni* in W.m\^-2. Its value is a scalar defining the direct irradiance received on a plane perpendicular to the main sun direction. The optional *spectrum* parameter describes the per wavelength distribution of the sun *dni*. Note that this -distribution is automatically normalized by *solstice*(1). If the *spectrum* -attribute is not defined, *solstice*(1) uses a default spectrum computed with +distribution is automatically normalized by *stardis*(1). If the *spectrum* +attribute is not defined, *stardis*(1) uses a default spectrum computed with the SMARTS software [2] between 0.28 and 4 micro-meters. The total *dni* (integrated over the spectral range) was set to 1000 W.m^-2. The standard Mid-Latitude-Summer atmosphere was used with most of gases concentration set @@ -392,7 +392,7 @@ Rp = (n2 * |wi.N| - n1 * |wt.N|) / (n2 * |wi.N| + n1 * |wt.N|) with n1 and n2 the indices of refraction of the incident and transmitted media, and wi and wt the incident and transmitted direction. + -Be careful to ensure the media consistency in the *solstice-input*(5) file; a +Be careful to ensure the media consistency in the *stardis-input*(5) file; a ray travelling in a medium _A_ can only encounter a medium interface whose *medium_i* attribute is _A_. Consequently, a *dielectric* material must be defined as a double sided material whose front and back interfaces are @@ -410,7 +410,7 @@ material: medium_t: *vacuum ....... + -If the media consistency is not ensured, *solstice*(1) will fail to run +If the media consistency is not ensured, *stardis*(1) will fail to run simulations. Note that by default, the surrounding medium is assumed to be the vacuum, i.e. its refractive index and its extinction are scalars whose values are 1 and 0, respectively. If an atmosphere is defined, the refractive @@ -471,10 +471,10 @@ media, and wi and wt the incident and transmitted direction. Note that the underlying scattering function correctly handles the multiple refraction effects into the thin slab. + -Be careful to ensure the media consistency in the *solstice-input*(5) file; a +Be careful to ensure the media consistency in the *stardis-input*(5) file; a ray travelling in a medium _A_ can only encounter a medium interface whose *medium_i* attribute is _A_. If the media consistency is not ensured, -*solstice*(1) will fail to run simulations. Note that by default, the +*stardis*(1) will fail to run simulations. Note that by default, the surrounding medium is assumed to be the vacuum, i.e. its refractive index and its extinction are scalars whose values are 1 and 0, respectively. If an atmosphere is defined, the refractive index of the surrounding medium is still @@ -508,7 +508,7 @@ A *shape* describes a geometric model. It is defined in its local space, i.e. in a coordinate system whose origin is proper to the shape. No space transformation can be introduced through the declaration of a shape: it should be transformed externally through an *object* and/or *entities*. -*solstice-input*(1) provides 2 types of shape: quadric and mesh. The former is +*stardis-input*(1) provides 2 types of shape: quadric and mesh. The former is used to declare parametric surfaces, while the latter describes triangulated surfaces. @@ -519,7 +519,7 @@ A quadric shape is defined from a quadric equation and a set of 2D clipping operations performed in their {X,Y} plane. By convention, the front side of the quadric surface looks toward the positive Z axis. Internally, the clipped quadric surface is discretized in a triangular mesh with respect to the -discretisation parameters of the quadric. This mesh is used by *solstice*(1) +discretisation parameters of the quadric. This mesh is used by *stardis*(1) as a "proxy" to speed up the access toward the quadric shape: the quadric position and its associated normal are in fine computed from the quadric equation. @@ -595,7 +595,7 @@ remove the quadric surface that intersects or does not intersect the *circle-descriptor*:: Circular contour whose size is defined by the *radius* parameter. Actually, -*solstice*(1) discretized the circular contour with respect to the *segments* +*stardis*(1) discretized the circular contour with respect to the *segments* attribute that defines the overall number of segments used to approximate the circle. @@ -603,7 +603,7 @@ circle. Polygonal contour described by a list of 2D vertices. The polygon edges are defined by connecting each vertex to its previous one. To ensure that the polygon is closed, an additional edge is automatically created between the -first and the last vertex. Note that *solstice*(1) assumes that the defined +first and the last vertex. Note that *stardis*(1) assumes that the defined polygon does not overlap itself, i.e. their non consecutive edges are not intersecting. @@ -629,7 +629,7 @@ plane: Triangular mesh ~~~~~~~~~~~~~~~ -Triangular meshes are generated by *solstice*(1) from a shape description or +Triangular meshes are generated by *stardis*(1) from a shape description or loaded from a CAO file. Their normals are defined per triangle and are thus discontinuous even for smooth shapes as spheres. The triangular meshes are not parameterized, i.e. they do not provide a mapping from a 3D position onto its @@ -668,7 +668,7 @@ ENTITY An *entity* is used to declare and position shapes into the solar plant. Actually, the entity is the only item that effectively spawns a *geometry* into the solar plant: if a geometry is declared but not referenced by an entity, it -is ignored by *solstice*(1). An entity is a hierarchical data structure that +is ignored by *stardis*(1). An entity is a hierarchical data structure that can have child entities whose transformation is relative to their parent. If not defined, the *transform* parameter of an entity is assumed to be the identity, i.e. its *rotation* and *translation* are nulls. @@ -679,8 +679,8 @@ the children of a same parent entity. In addition, the name string cannot contain dots, spaces or tabulations. A child entity is identified into the solar plant by successively concatenating, with the \'.' character, the name of its ancestors with its own name. This naming convention is used in the -*solstice-receiver*(5) format to define the entities to track during the -*solstice*(1) computations. For instance, in the following example, the +*stardis-receiver*(5) format to define the entities to track during the +*stardis*(1) computations. For instance, in the following example, the *entity-identifier* of the child entity named *level2* is *level0.level1.level2*: ....... @@ -696,7 +696,7 @@ An entity encapsulates either a *geometry* or a *pivot*. The former is a collection of *objects*, i.e. *shapes* with their associated *material* and an optional *transformation*. The latter is used to control the dynamic positioning of the child entities with respect to some constraints defined by -the pivot type, and the sun directions submitted by *solstice*(1). Each entity +the pivot type, and the sun directions submitted by *stardis*(1). Each entity can also have a list of *anchors*. An anchor is used to define a position relative to the entity into which it is declared. @@ -705,7 +705,7 @@ For a geometric entity one has to define if the encapsulated geometry is a concentrate the solar flux (e.g. a primary mirror). One can define all the solar plant geometric entities as primaries but a well designed solar plant with correctly tagged primary geometries will drastically improve the -convergence speed of the *solstice*(1) simulations. +convergence speed of the *stardis*(1) simulations. Template ~~~~~~~~ @@ -1176,4 +1176,4 @@ NOTES SEE ALSO -------- -*solstice*(1), *solstice-receiver*(5) +*stardis*(1), *stardis-receiver*(5) diff --git a/doc/stardis-output.5.txt b/doc/stardis-output.5.txt @@ -14,28 +14,28 @@ // along with this program. If not, see <http://www.gnu.org/licenses/>. :toc: -solstice-output(5) +stardis-output(5) ================== NAME ---- -solstice-output - output format of solstice(1) results +stardis-output - output format of stardis(1) results DESCRIPTION ----------- -The *solstice-output* describes the output format of the *solstice*(1) program. -All the data generated by a *solstice*(1) invocation are written in a single +The *stardis-output* describes the output format of the *stardis*(1) program. +All the data generated by a *stardis*(1) invocation are written in a single file or on the standard output whether an _output_ file is defined through the *-o* option or not, respectively. Note that submitting several sun directions -to *solstice*(1), through the *-D* option, will produce as many outputs as sun -directions. In other words, invoking *solstice*(1) with _N_ sun directions -looks like calling *solstice*(1) _N_ times and concatenating their associated +to *stardis*(1), through the *-D* option, will produce as many outputs as sun +directions. In other words, invoking *stardis*(1) with _N_ sun directions +looks like calling *stardis*(1) _N_ times and concatenating their associated output. The type of the data that are generated depends on the mode in which -*solstice*(1) is invoked. By default, *solstice*(1) evaluates the power +*stardis*(1) is invoked. By default, *stardis*(1) evaluates the power collected by the submitted solar plant. When invoked with the *-g* option, -*solstice*(1) converts the solar plant geometries in a list of CAO files. The +*stardis*(1) converts the solar plant geometries in a list of CAO files. The *-p* option is used to track the sampled radiative paths while, finally, the *-r* option allows to render an image of the solar facility. @@ -186,7 +186,7 @@ _______ <expected-value> ::= REAL <standard-error> ::= REAL # in [0, INF) -<entity-identifier> # Defined in *solstice-input*(5) +<entity-identifier> # Defined in *stardis-input*(5) _______ SIMULATION @@ -241,12 +241,12 @@ Per receiver results Following global results, the output includes various per-receiver lines, one line per receiver, the exact number of lines being part of the headers. The per-receiver results are sorted according to the order of the receivers as -defined in the submitted *solstice-receiver*(5) file. Each line contains the +defined in the submitted *stardis-receiver*(5) file. Each line contains the following data: - *receiver-name*: name of the receiver, i.e. *entity-identifier* of the entity in which the receiving geometry is defined (see the - *solstice-input*(5) format); + *stardis-input*(5) format); - *receiver-id*: unique integer identifying the receiver; - *area*: area of the receiver; - *front*: estimated results for the front side of the receiver; @@ -285,7 +285,7 @@ part of the headers. Each line contains: - *primary-name*: name of the primary geometry, i.e. *entity-identifier* of the entity in in which the primary geometry is defined (see the - *solstice-input*(5) format); + *stardis-input*(5) format); - *primary-id*: unique integer identifying the primary geometry; - *area*: area of the primary geometry; - *#sample*: number of Monte-Carlo experiments sampled on the primary @@ -334,19 +334,19 @@ meaningless (invalid -1 value). Receiver map ~~~~~~~~~~~~ -A receiver defined in the submitted *solstice-receiver*(5) file, can have a +A receiver defined in the submitted *stardis-receiver*(5) file, can have a per-primitive estimate of its incoming flux density and/or absorbed flux -density if its *per_primitive* flag is active. In this case, *solstice*(1) +density if its *per_primitive* flag is active. In this case, *stardis*(1) generates a *receiver-map* that is actually an ASCII VTK file [2] that stores the triangular mesh of the receiver and, for each triangle, the estimate of its associated incoming flux density and/or absorbed flux density. The "definition" of the receiver map is thus controlled by the discretisation of -the receiver's shape, as described in the *solstice-input*(5) file. Note that +the receiver's shape, as described in the *stardis-input*(5) file. Note that to obtain a good estimate of the per-triangle flux densities, one have to ensure that the number of per-triangle experiments is sufficient regarding the targeted accuracy. Since only a small fraction of the overall sampled radiative paths reach a given triangle, the total number of experiments -required through the *-n* option of *solstice*(1) should be increased +required through the *-n* option of *stardis*(1) should be increased significantly, as 1 or 2 order of magnitude. The number of written per-triangle flux density estimates depends on the @@ -409,21 +409,21 @@ _______ DUMP GEOMETRY ------------- -A *dump-geometry-output* is generated when *solstice*(1) is invoked with the -*-g* option. In this mode, for each submitted sun direction, *solstice*(1) -converts the geometry of the submitted *solstice-input*(5) file in triangular +A *dump-geometry-output* is generated when *stardis*(1) is invoked with the +*-g* option. In this mode, for each submitted sun direction, *stardis*(1) +converts the geometry of the submitted *stardis-input*(5) file in triangular meshes that are then written to the output with respect to the format provided by the *format* parameter of the *-g* option. The only format currently -supported by *solstice*(1) is the Alias Wavefront OBJ [3] format. With no more -sub-option, *solstice*(1) will thus generate one OBJ file containing the whole +supported by *stardis*(1) is the Alias Wavefront OBJ [3] format. With no more +sub-option, *stardis*(1) will thus generate one OBJ file containing the whole mesh of the solar plant. However, the *split* parameter of the *-g* option allows to generate several OBJ files: one description is generated per -*geometry* or per *object*, as defined in the *solstice-input*(5) format, +*geometry* or per *object*, as defined in the *stardis-input*(5) format, whether the *split* sub-option is set to *geometry* or *object*. In this situation, each OBJ description is followed by a line with 3 minus characters in order to identify the end of the current OBJ. -Independently of the *split* strategy, each *solstice-input*(1) geometry is an +Independently of the *split* strategy, each *stardis-input*(1) geometry is an OBJ group whose name is the *entity-identifier* of the entity in which it is encapsulated. Finally, the *dump-geometry-output* uses the *usemtl* directive of the OBJ format to associate to a mesh the name of its material type. The @@ -520,7 +520,7 @@ _______ RENDERING --------- -When invoked with the *-r* option, *solstice*(1) generates an image of the +When invoked with the *-r* option, *stardis*(1) generates an image of the solar facility for each submitted sun direction. Each image is preceded by its associated sun direction and is saved with respect to the ASCII PPM file format [1]. The output images are actually greyscale images whose pixels store @@ -536,6 +536,6 @@ NOTES SEE ALSO -------- -*solstice*(1), -*solstice-input*(5), -*solstice-receiver*(5) +*stardis*(1), +*stardis-input*(5), +*stardis-receiver*(5) diff --git a/doc/stardis.1.txt.in b/doc/stardis.1.txt.in @@ -14,26 +14,26 @@ // along with this program. If not, see <http://www.gnu.org/licenses/>. :toc: -solstice(1) +stardis(1) =========== NAME ---- -solstice - compute the power collected by a concentrated solar plant +stardis - compute the power collected by a concentrated solar plant SYNOPSIS -------- [verse] -*solstice* -*solstice* [_option_]... [_file_] -*solstice* *-g* <__sub-option__[:...]> [_option_]... [_file_] -*solstice* *-p* <__sub-option__[:...]> [_option_]... [_file_] -*solstice* *-r* <__sub-option__[:...]> [_option_]... [_file_] +*stardis* +*stardis* [_option_]... [_file_] +*stardis* *-g* <__sub-option__[:...]> [_option_]... [_file_] +*stardis* *-p* <__sub-option__[:...]> [_option_]... [_file_] +*stardis* *-r* <__sub-option__[:...]> [_option_]... [_file_] DESCRIPTION ----------- -*solstice* computes the total power collected by a concentrated solar plant, as -described in the *solstice-input*(5) _file_. If the _file_ argument is not +*stardis* computes the total power collected by a concentrated solar plant, as +described in the *stardis-input*(5) _file_. If the _file_ argument is not provided, the solar plant is read from standard input. To evaluate various efficiencies for each primary reflector, it computes losses due to cosine effect, shadowing and masking, orientation and surface irregularities, @@ -41,32 +41,32 @@ materials properties and atmospheric extinction. The efficiency for each one of these effects is subsequently computed for each reflector. The entities on which computations must be performed are listed in the -*solstice-receiver*(5) file submitted through the *-R* option. The estimated -results follow the *solstice-output*(5) format and are written to the _output_ +*stardis-receiver*(5) file submitted through the *-R* option. The estimated +results follow the *stardis-output*(5) format and are written to the _output_ file or to the standard output whether the *-o* _output_ option is defined or -not, respectively. Note that the *solstice* algorithm is based on the +not, respectively. Note that the *stardis* algorithm is based on the Monte-Carlo method, which means that every result is provided with its numerical accuracy. -*solstice* is designed to efficiently handle complex solar facilities: several +*stardis* is designed to efficiently handle complex solar facilities: several reflectors can be specified (planes, conics, cylindro-parabolic, etc.) and positioned in 3D space, with a possibility for 1-axis and 2-axis auto-orientation. Multiple materials can be used, as long as the relevant physical properties are provided. Spectral effects are also taken into account: it is possible to define the spectral distribution of any physical property, including the input solar spectrum and the transmissivity of the atmosphere, at -any spectral resolution. Refer to *solstice-input*(5) for more informations. +any spectral resolution. Refer to *stardis-input*(5) for more informations. -In addition of the aforementioned computations, *solstice* provides three +In addition of the aforementioned computations, *stardis* provides three other functionalities. The *-g* option can be used to convert the -*solstice-input*(5) geometries in CAO files. The *-p* option saves the sampled +*stardis-input*(5) geometries in CAO files. The *-p* option saves the sampled radiative paths used by the estimates, allowing to visualise them externally which may be a great help to identify a design issue. Finally, the *-r* option is used to render an image of the submitted solar facility. Note that these three options are mutually exclusives, and once defined, they replace the -default *solstice* behaviour. +default *stardis* behaviour. -Please note that any coordinate-related question in Solstice must be +Please note that any coordinate-related question in Stardis must be considered with the right-handed convention in mind. OPTIONS @@ -78,8 +78,8 @@ OPTIONS Each provided sun direction triggers a new computation whose results are concatenated to the _output_ file. + -Following the right-handed convention, Solstice azimuthal rotation is -counter-clockwise, with 0° on the X axis. Solstice elevation starts from 0° for +Following the right-handed convention, Stardis azimuthal rotation is +counter-clockwise, with 0° on the X axis. Stardis elevation starts from 0° for directions in the XY plane, up to 90° at zenith. Thus -D0,0 -D90,0 -D180,0 and -D270,0 will produce solar vectors {-1,0,0} {0,-1,0} {+1,0,0} and {0,+1,0} respectively, while -D__alpha__,90 will produce {0,0,-1} regardless of _alpha_ @@ -117,7 +117,7 @@ value. *split=*<**geometry**|*object*|*none*>;; Define how the output mesh is split in sub meshes. A sub mesh can be generated for each *geometry* or for each *object* as defined in the - *solstice-input*(5) file format. The *none* option means that only one + *stardis-input*(5) file format. The *none* option means that only one mesh is generated for the whole solar facility. By default, the *split* option is set to *none*. @@ -129,7 +129,7 @@ value. default _experiments-count_ is set to @SOLSTICE_ARGS_DEFAULT_NREALISATIONS@. *-o* _output_:: - Write results to _output_ with respect to the *solstice-output*(5) format. If + Write results to _output_ with respect to the *stardis-output*(5) format. If not defined, write results to standard output. *-p* <__sub-option__:...>:: @@ -151,8 +151,8 @@ value. Do not print the helper message when no _file_ is submitted. *-R* _receivers_:: - *solstice-receiver*(5) file defining the scene receivers, i.e. the solar - plant entities for which *solstice* computes Monte-Carlo estimates. + *stardis-receiver*(5) file defining the scene receivers, i.e. the solar + plant entities for which *stardis* computes Monte-Carlo estimates. *-r* <__sub-option__:...>:: Render an image of the scene through a pinhole camera, for each submitted @@ -204,7 +204,7 @@ value. cores. *-v*:: - Make solstice more verbose. + Make stardis more verbose. *--version*:: Output version information and exit. @@ -219,7 +219,7 @@ declared in the *rcvs.yaml* file. *10000* experiments are used by the Monte-Carlo estimates and the results are written to *output* even though this file already exists: - $ solstice -D45,70:50,75 -R rcvs.yaml -n 10000 -f -o output input.yaml + $ stardis -D45,70:50,75 -R rcvs.yaml -n 10000 -f -o output input.yaml Generate a mesh for each geometry described in *input.yaml*, and save them in the *output* file with respect to the Alias Wavefront OBJ format. The meshes @@ -228,32 +228,32 @@ sun direction whose azimuthal and elevation angles are {*30*,*60*}. Use the *csplit*(1) Unix command to generate an Alias Wavefront OBJ file per geometry stored in *output*. The name of the generated Alias Wavefront OBJ files are *geom*<__NUM__>**.obj** with __NUM__ in [0, N-1] where N is the number of -geometries described in *input.yaml*. Refer to *solstice-output*(5) for +geometries described in *input.yaml*. Refer to *stardis-output*(5) for informations on the regular expression *^---$* used to split the output file: - $ solstice -D30,60 -g format=obj:split=geometry -f -o output input.yaml + $ stardis -D30,60 -g format=obj:split=geometry -f -o output input.yaml $ csplit -f geom -b %02d.obj -z --suppress-matched output /^---$/ {*} Trace 100 radiative paths into the solar plant described in *input.yaml*, with respect to the sun direction whose azimuthal and elevations angles are *0* and -*90* degrees, respectively. Write the *solstice-output*(5) result to the +*90* degrees, respectively. Write the *stardis-output*(5) result to the standard output and postprocess it with the *sed*(1) Unix command to remove the first line that stores the sun direction from which the radiative paths come from. The remaining data that list the radiative paths geometry are redirected into the *paths.vtk* file: - $ solstice -n 100 -D0,90 -R rcvs.yaml -p default input.yaml | sed '1d'>paths.vtk + $ stardis -n 100 -D0,90 -R rcvs.yaml -p default input.yaml | sed '1d'>paths.vtk Use the path-tracing rendering algorithm to draw the solar plant *solplant.yaml* with respect to the sun direction whose azimuthal and elevation angles are *180* and *45* degrees, respectively. Use *64* samples per pixel to estimate the per-pixel radiance and fix the up camera vector to {*0*,*0*,*1*}. -Write the *solstice-output*(5) result to standard output and use the *sed*(1) +Write the *stardis-output*(5) result to standard output and use the *sed*(1) Unix command to remove the first line which stores the sun direction used to draw the image. Finally, visualise the rendered picture by redirecting the remaining data to the *feh*(1) image viewer. - $ solstice -D180,45 -r up=0,0,1:rmode=pt:spp=64 solplant.yaml | sed '1d' | feh - + $ stardis -D180,45 -r up=0,0,1:rmode=pt:spp=64 solplant.yaml | sed '1d' | feh - COPYRIGHT --------- @@ -267,6 +267,6 @@ SEE ALSO *csplit*(1), *feh*(1), *sed*(1), -*solstice-input*(5), -*solstice-output*(5), -*solstice-receiver*(5) +*stardis-input*(5), +*stardis-output*(5), +*stardis-receiver*(5)