commit 0103104e167c9078be367f7f495ed93e6d050220
parent 80d4207d8e37130b02fa8c772b6d4c9e567f72c9
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 17 Mar 2025 12:04:05 +0100
planets: update the manual of the -V option
Update of the -V option to configure how acceleration structures are
built. Currently, only the manual is updated. The code remains
unchanged. In other words, the documentation is ahead of the expected
behaviour of the code.
This option must also allow to control the processes that build the
acceleration structures. When using MPI, the common case on a
supercomputer is to use shared disk space between processes. So, when
storing acceleration structures on disk, all processes build their own
set of acceleration structures and save them in the same file, since
this space is the same for all processes. And although no errors were
reported by users, this was only by chance since, depending on MPI
scheduling, a process could open a non-empty storage space. In such a
situation, it would have expected a valid storage space and would have
returned an error because the octrees were actually under construction.
In the best-case scenario, there were no errors reported, and all the
processes were writing the same data to the same file. This
considerably increased pressure on the disk and reduced construction
performance. In fact, in such a situation, the user would not have had
to store the accelerator structures to force all the processes to build
their own set of structures in memory.
To avoid these problems, the acceleration structure will now only be
built by the master process, assuming that the same disk space is shared
by all processes. If this is not the case, the user must explicitly
activate the build for all processes.
Diffstat:
1 file changed, 53 insertions(+), 5 deletions(-)
diff --git a/doc/htrdr-planets.1.in b/doc/htrdr-planets.1.in
@@ -20,7 +20,7 @@
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with this program. If not, see <http://www.gnu.org/licenses/>.
-.Dd February 14, 2025
+.Dd March 17, 2025
.Dt HTRDR-PLANETS 1
.Os
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
@@ -46,7 +46,7 @@
.Op Fl s Ar spectral_opt Ns Op : Ns Ar spectral_opt No ...
.Op Fl T Ar optical_thickness
.Op Fl t Ar threads_count
-.Op Fl V Ar accel_struct_definition
+.Op Fl V Ar accel_struct_opt Ns Op : Ns Ar accel_struct_opt No ...
.Fl g Ar gas_opt Ns Op : Ns Ar gas_opt No ...
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\" Detailed description
@@ -433,9 +433,57 @@ Advice on the number of threads to use.
By default,
.Nm
uses many threads as processor cores.
-.It Fl V Ar accel_struct_definition
+.It Fl V Ar accel_struct_opt Ns Op : Ns Ar accel_struct_opt No ...
+Configure the building of the acceleration structures.
+.Pp
+The acceleration structures building options are as follows:
+.Bl -tag -width Ds
+.It Cm def= Ns Ar definition
Advice on the definition of the atmospheric acceleration structures.
Default is @HTRDR_PLANETS_ARGS_DEFAULT_GRID_DEFINITION_HINT@.
+.It Cm nthreads= Ns Ar threads_count
+Advice on the number of threads to use.
+This number is different from that defined by the
+.Fl t
+option, as the construction of acceleration structures is not based on
+the same parallelization model as Monte Carlo integration.
+This construction may not benefit from too many threads, on the
+contrary.
+.Pp
+The default value is 8, i.e. a maximum of 8 threads are used to build
+acceleration structures.
+.It Cm proc= Ns Ar processes
+This option is only used when
+.Nm
+is run with multiple processes
+.Pq see Xr mpirun 1 .
+It defines the processes that must build the acceleration structures.
+.Pp
+The value
+.Cm all
+means that all processes build their own set of acceleration structures.
+This is the de facto configuration when no storage is used
+.Po
+i.e. the
+.Fl O
+option is not set
+.Pc .
+.Pp
+If acceleration structure storage is defined
+.Pq Fl O No option ,
+a value of
+.Cm all
+should only be used if each process has its own disk space on which its
+own set of acceleration structures is stored.
+If processes share a common disk space, the value should be
+.Cm master .
+This means that only the main process builds the acceleration
+structures, which are in fine shared with the other processes by
+storing the saved acceleration structures on a common disk space.
+.Pp
+The default value is
+.Cm master .
+.El
.It Fl v
Make
.Nm
@@ -651,7 +699,7 @@ htrdr-planets -v -N \\
:mesh=ground_triangles.smsh\\
:prop=ground_properties.rnsp\\
:brdf=ground_brdfs.rnsl \\
- -V 512 -T 10 -O storage_cie.bin \\
+ -V def=512 -T 10 -O storage_cie.bin \\
-fo image_CIE_XYZ.ht
.Ed
.Pp
@@ -693,7 +741,7 @@ htrdr-planets -v -N \\
:mesh=ground_triangles.smsh\\
:prop=ground_properties.rnsp\\
:brdf=ground_brdfs.rnsl \\
- -V 512 -T 10 -O storage_lw.bin \\
+ -V def=512 -T 10 -O storage_lw.bin \\
-fo image_infrared.ht
.Ed
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
