commit 1847773d49615c23bed867b6cd1f0a5953ea2138
parent 1c3bda282bc1361bd1094b66196443538e2de8f4
Author: Vincent Forest <vincent.forest@meso-star.com>
Date: Mon, 23 Jun 2025 09:28:46 +0200
Schiff: begin Markdown translation
Diffstat:
9 files changed, 191 insertions(+), 221 deletions(-)
diff --git a/meso.css b/meso.css
@@ -275,6 +275,7 @@ hr {
******************************************************************************/
table.list {
border-spacing: 0;
+ text-align: center;
width: 100%;
}
diff --git a/schiff/Makefile b/schiff/Makefile
@@ -36,7 +36,7 @@ MAN=\
$(SCHIFF_DIR)/share/man/man5/schiff-geometry.5\
$(SCHIFF_DIR)/share/man/man5/schiff-output.5
-IMG = particles.png
+IMG = images/particles.png thumbs/particles.jpg
HTML = schiff.html schiff-docs.html schiff-downloads.html
build: .sig .man
@@ -69,14 +69,14 @@ schiff_build.sh: ../meso-menu.sh
################################################################################
# Overview
################################################################################
-schiff.html: schiff.html.in $(IMG) schiff_build.sh
+schiff.html: schiff.md.in $(IMG) schiff_build.sh
@echo "Building $@"
- @$(SHELL) schiff_build.sh overview $(SCHIFF_VERSION) > $@
+ @$(SHELL) schiff_build.sh overview $(SCHIFF_VERSION) < schiff.md.in > $@
################################################################################
# Manual pages
################################################################################
-schiff-docs.html: schiff-docs.html.in schiff_build.sh
+schiff-docs.html: schiff-docs.md schiff_build.sh
@echo "Building $@"
@$(SHELL) schiff_build.sh documentations > $@
diff --git a/schiff/particles.png b/schiff/images/particles.png
diff --git a/schiff/schiff-docs.html.in b/schiff/schiff-docs.html.in
@@ -1,13 +0,0 @@
-<header>
- <h1>Schiff
- <span class=subtitle>
- Reference documentation
- </span>
- </h1>
-</header>
-
-<ul>
- <li><a href=man/man1/schiff.1.html>schiff(1)</a></li>
- <li><a href=man/man5/schiff-geometry.5.html>schiff-geometry(5)</a></li>
- <li><a href=man/man5/schiff-output.5.html>schiff-output(5)</a></li>
-</ul>
diff --git a/schiff/schiff-docs.md b/schiff/schiff-docs.md
@@ -0,0 +1,5 @@
+# Reference documentation
+
+- [schiff(1)](man/man1/schiff.1.html)
+- [schiff-geometry(5)](man/man5/schiff-geometry.5.html)
+- [schiff-output(5)](man/man5/schiff-output.5.html)
diff --git a/schiff/schiff.html.in b/schiff/schiff.html.in
@@ -1,202 +0,0 @@
-<header>
- <h1>Schiff
- <span class=subtitle>
- Radiative properties of soft particles
- </span>
- </h1>
-</header>
-
-<div class="news">
- <p><b>Download Schiff ${VERSION}</b></p>
- <ul>
- <li>GNU/Linux:
- <a href="downloads/Schiff-${VERSION}-GNU-Linux64.tar.gz">tarball</a> /
- <a href="downloads/Schiff-${VERSION}-GNU-Linux64.tar.gz.sig">pgp</a></li>
- <li>Sources:
- <a href="downloads/Schiff-${VERSION}-Sources.tar.gz">tarball</a> /
- <a href="downloads/Schiff-${VERSION}-Sources.tar.gz.sig">pgp</a></li>
- </ul>
-</div>
-
-<div class="news">
- <p><b>Related articles</b></p>
- <ul>
- <li>
- <a href="https://doi.org/10.1364/OL.500487">Dauchet et al.</a>
- <br>(Optics Letters 2023)
- </li>
- </ul>
-</div>
-
-<p>The Schiff program computes the <b>radiative properties</b> of soft
-particles. It uses the <b>Monte-Carlo</b> method to solve Maxwell's equations
-within the <a
-href="https://journals.aps.org/pr/abstract/10.1103/PhysRev.104.1481">L. Schiff's
-approximation</a> as presented in <a
-href="http://www.sciencedirect.com/science/article/pii/S0022407315003283">Charon
-et al. 2015</a>.The main advantages of using Monte-Carlo are: the possibility
-to address <b>any shape</b> of particle, and the results are provided with a
-<b>numerical accuracy</b>.</p>
-
-<p>For a mixture of soft particles, Schiff estimates the total
-<b>cross-sections</b> (absorption, scattering and extinction cross-sections) in
-addition of the <b>phase function</b>, its cumulative and its inverse
-cumulative.</p>
-
-<p>The set of particles to simulate is defined by its <b>refractive index</b> -
-provided at various wavelengths - and a <b>geometry distribution</b> that
-controls how the particles look like into the mixture. More precisely, this
-distribution describes the main shapes of the particles (sphere, cylinder,
-helical pipe, <i>etc.</i>) and their statistical variation according to the
-distribution of their parameters (gaussian, lognormal, <i>etc.</i>).</p>
-
-<h2>A straight interface</h2>
-
-<div class="img" style="width: 16em">
- <a href="particles.png">
- <img src="particles.png" alt="Particles">
- </a>
- <div class="caption">
- Examples of particle shapes handled by Schiff.
- </div>
-</div>
-
-<p>The Schiff program is a <b>command-line tool</b> that processes input data,
-performs computations, write results and that's all. It makes no assumptions on
-how the input data are created excepted that it has to follow the expected file
-formats. The simulation results are also provided as is, in a raw ASCII
-format.</p>
-
-<p>This thin interface is particularly
-well suited to be <b>extended</b> and <b>integrated into any toolchain</b>.
-According to the user needs, the optical properties of the particles can be
-entered manually or generated by an external program. In the same way, the
-output data can either be directly interpreted or post-processed by any script
-with respect to the targeted toolchain.</p>
-
-<h2>Quick start</h2>
-
-<p>Download the desired archive of Schiff and verify its integrity against its
-<a href=../misc/pgp_signatures.html>PGP signature</a>. Then extract it. Finally
-source the provided <code>schiff.profile</code> file to register the Schiff
-installation for the current shell priorly to the invocation of the
-<code>schiff</code> program.</p>
-
-<pre class="code">
-$ source ~/Schiff-${VERSION}-GNU-Linux64/etc/schiff.profile
-$ schiff -h
-</pre>
-
-<p>The Schiff <b>reference documentation</b> is provided trough man pages.
-Use the <code>man</code> command-line to consult it.</p>
-
-<pre class="code">
-$ man schiff
-$ man schiff-geometry
-$ man schiff-output
-</pre>
-
-<h2 id=build>Build from sources</h2>
-
-<p>Schiff can be built directly from its source tree. The simplest way to do
-this is to rely on the <code>schiff</code> branch of the <a
-href="https://gitlab.com/meso-star/star-engine/tree/schiff">Star-Engine</a>
-project: it provides CMake scripts that automate the download, the compilation
-and the installation of Schiff and its dependencies. This build procedure
-assumes the following prerequisites:</p>
-
-<ul>
- <li><a href=https://git-scm.com>git</a> source control.</li>
- <li><a href=https://gcc.gnu.org>GNU Compiler Collection</a> in version 4.9.2
- or higher.</li>
- <li><a href="https://cmake.org">CMake</a> in version 3.1 or higher.</li>
-</ul>
-
-<h3>Build</h3>
-
-<p>Assuming that the aforementioned prerequisites are available, the build
-procedure is summed up to:</p>
-
-<pre class="code">
-~ $ git clone -b Schiff-${VERSION} \
- https://gitlab.com/meso-star/star-engine.git Schiff-${VERSION}
-~ $ mkdir Schiff-${VERSION}/build; cd Schiff-${VERSION}/build
-~/Schiff-${VERSION}/build $ cmake ../cmake
-~/Schiff-${VERSION}/build $ make
-</pre>
-
-<h3>Run</h3>
-
-<p>By default Schiff is installed in the <code>local</code> subdirectory of
-<code>Schiff-${VERSION}</code>. Source the provided <code>schiff.profile</code>
-file to register Schiff against the current shell.</p>
-
-<pre class="code">
-$ source ~/Schiff-${VERSION}/local/etc/schiff.profile
-$ schiff -h
-</pre>
-
-<h3>Package</h3>
-
-<p>Once built, the Schiff installation can be packaged in an archive that can
-then be deployed on compatible systems, <i>i.e.</i> systems whose C library is
-compatible with the one available on the system used to build Schiff.</p>
-
-<pre class="code">
-~/Schiff-${VERSION}/build $ make pkg
-~/Schiff-${VERSION}/build $ ls package/Schiff-${VERSION}* # list packages
-</pre>
-
-
-<h2>Post-Process</h2>
-
-<p>The following Bash script illustrates how to post-process the Schiff
-results. It is an example, provided as is, without additional support.
-According to your needs, you can study, modify, extend or redistribute it
-freely.</p>
-
-<table>
- <tr><th>Pretty results</th></tr>
- <tr><td>[<a href='downloads/schiff_pretty_results.sh'>Bash script</a>]</td></tr>
-</table>
-
-<p>This script reads an output file generated by the <code>schiff</code>
-command line and split its raw ASCII results in several human readable text
-files in order to simplify their analysis.</p>
-
-<pre class="code">
-$ schiff -i geom-distrib.yaml -l 2.3 -w0.5:0.6 -o output properties
-$ bash ./schiff_pretty_results.sh output
-Write xsections.txt
-Write descs.txt
-Write func_0.5.txt
-Write func_0.6.txt
-Write cumul_0.5.txt
-Write cumul_0.6.txt
-Write invcumul_0.5.txt
-Write invcumul_0.6.txt
-</pre>
-
-<p>The first generated file, named <code>xsections.txt</code>, lists for each
-wavelength submitted with the <code>-w</code> option, its associated
-absorption, extinction and scattering cross sections. The second file,
-<code>descs.txt</code>, gives overall informations for each simulated
-wavelengths, like the limit scattering angles from which its phase function was
-analytically computed. Then for each wavelength, the script generates 3 files
-named <code>func_<WLEN>.txt</code>, <code>cumul_<WLEN>.txt</code>,
-and <code>invcumul_<WLEN>.txt</code> that store for the wavelength
-<code><WLEN></code>, the value of its associated phase function as well
-as its cumulative and its inverse cumulative, respectively.</p>
-
-<h2>License</h2>
-
-<p>Copyright © 2020, 2021 <a href="mailto:contact@meso-star.com">
-|Méso|Star></a>.<br>
-Copyright © 2015, 2016 Centre National de la Recherche Scientifique
-(CNRS).</p>
-
-<p>Schiff is free software released under the GPLv3+
-license: GNU GPL version 3 or later. You are welcome to redistribute it under
-certain conditions; refer to the <a
-href="https://www.gnu.org/licenses/gpl.html">license</a> for details.</p>
-
diff --git a/schiff/schiff.md.in b/schiff/schiff.md.in
@@ -0,0 +1,177 @@
+# Schiff
+
+The Schiff program computes the *radiative properties* of soft
+particles.
+It uses the *Monte-Carlo* method to solve Maxwell's equations
+within the
+[L. Schiff's approximation](https://journals.aps.org/pr/abstract/10.1103/PhysRev.104.1481)
+as presented in
+[Charon et al. 2025](http://www.sciencedirect.com/science/article/pii/S0022407315003283).
+The main advantages of using Monte-Carlo are: the possibility to address
+*any shape* of particle, and the results are provided with a *numerical
+accuracy*.
+
+For a mixture of soft particles, Schiff estimates the total
+*cross-sections* (absorption, scattering and extinction cross-sections)
+in addition of the *phase function*, its cumulative and its inverse
+cumulative.
+
+The set of particles to simulate is defined by its *refractive index* -
+provided at various wavelengths - and a *geometry distribution* that
+controls how the particles look like into the mixture.
+More precisely, this
+distribution describes the main shapes of the particles (sphere, cylinder,
+helical pipe, etc.) and their statistical variation according to the
+distribution of their parameters (gaussian, lognormal, etc.).
+
+[](images/particles.png)
+
+> Examples of particle shapes handled by Schiff.
+
+## Related articles
+
+- [Dauchet et al. 2023](https://doi.org/10.1364/OL.50048),
+ "Wave-scattering processes: path-integrals designed for the numerical
+ handling of complex geometries", Optics Letters
+ ([open access](https://arxiv.org/abs/2210.16146))
+
+- [Charon et al. 2016](http://www.sciencedirect.com/science/article/pii/S0022407315003283),
+ "Monte Carlo implementation of Schiff׳s approximation for estimating
+ radiative properties of homogeneous, simple-shaped and optically soft
+ particles: Application to photosynthetic micro-organisms", Journal of
+ Quantitative Spectroscopy and Radiative Transfer
+ ([open access](https://hal.science/hal-01599991v1/))
+
+- [Weits et al. 2016](https://www.sciencedirect.com/science/article/abs/pii/S002199911630393X),
+ "Monte Carlo efficiency improvement by multiple sampling of
+ conditioned integration variables", Journal of Computational Physics
+ ([open access](https://hal.science/hal-01599986/))
+
+## A straight interface
+
+The Schiff program is a *command-line tool* that processes input data,
+performs computations, write results and that's all.
+It makes no assumptions on how the input data are created excepted that
+it has to follow the expected file formats.
+The simulation results are also provided as is, in a raw ASCII format.
+
+This thin interface is particularly well suited to be *extended* and
+*integrated into any toolchain*.
+According to the user needs, the optical properties of the particles can be
+entered manually or generated by an external program.
+In the same way, the output data can either be directly interpreted or
+post-processed by any script with respect to the targeted toolchain.
+
+## Quick start
+
+Download the desired [archive](schiff-downloads.html) of Schiff and
+verify its integrity against its PGP signature.
+Then extract it.
+Finally
+source the provided `schiff.profile` file to register the Schiff
+installation for the current shell priorly to the invocation of the
+`schiff` program.
+
+ source ~/Schiff-@VERSION@-GNU-Linux64/etc/schiff.profile
+ schiff -h
+
+The Schiff *reference documentation* is provided trough man pages.
+Use the `man` command-line to consult it.
+
+ man schiff
+ man schiff-geometry
+ man schiff-output
+
+## Build from sources
+
+Schiff can be built directly from its source tree.
+The simplest way to do this is to rely on the `schiff` branch of the
+[Star-Engine](https://gitlab.com/meso-star/star-engine/tree/schiff)
+project: it provides CMake scripts that automate the download, the compilation
+and the installation of Schiff and its dependencies.
+This build procedure assumes the following prerequisites:
+
+- git source control
+- GNU Compiler Collection in version 4.9.2 or higher
+- CMake in version 3.1 or higher
+
+### Build
+
+Assuming that the aforementioned prerequisites are available, the build
+procedure is summed up to:
+
+ git clone -b Schiff-@VERSION@ \
+ https://gitlab.com/meso-star/star-engine.git Schiff-@VERSION@
+ mkdir Schiff-${VERSION}/build
+ cd Schiff-@VERSION@/build
+ cmake ../cmake
+ make
+
+### Run
+
+By default Schiff is installed in the `local` subdirectory of
+`Schiff-@VERSION@`. Source the provided `schiff.profile` file to
+register Schiff against the current shell.
+
+ source ~/Schiff-@VERSION@/local/etc/schiff.profile
+ schiff -h
+
+### Package
+
+Once built, the Schiff 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
+Schiff.
+
+ cd Schiff-@VERSION@/build
+ make pkg
+ ls package/Schiff-${VERSION}* # list packages
+
+## Post-Process
+
+The following Bash script illustrates how to post-process the Schiff
+results.
+It is an example, provided as is, without additional support.
+According to your needs, you can study, modify, extend or redistribute
+it freely :
+
+
+ - [Download](downloads/schiff_pretty_results.sh) the pretty result
+ script
+
+This script reads an output file generated by the `schiff` command line
+and split its raw ASCII results in several human readable text files in
+order to simplify their analysis.
+
+ schiff -i geom.yaml -l 2.3 -w0.5:0.6 -o output properties
+ bash ./schiff_pretty_results.sh output
+ Write xsections.txt
+ Write descs.txt
+ Write func_0.5.txt
+ Write func_0.6.txt
+ Write cumul_0.5.txt
+ Write cumul_0.6.txt
+ Write invcumul_0.5.txt
+ Write invcumul_0.6.txt
+
+The first generated file, named `xsections.txt`, lists for each
+wavelength submitted with the `-w` option, its associated
+absorption, extinction and scattering cross sections. The second file,
+`descs.txt`, gives overall informations for each simulated
+wavelengths, like the limit scattering angles from which its phase function was
+analytically computed.
+Then for each wavelength, the script generates 3 files named
+`func_<WLEN>.txt`, `cumul_<WLEN>.txt`, and `invcumul_<WLEN>.txt` that
+store for the wavelength `<WLEN>`, the value of its associated phase
+function as well as its cumulative and its inverse cumulative,
+respectively.
+
+## License
+
+Copyright © 2020, 2021 [|Méso|Star>](mailto:contact@meso-star.com)
+Copyright © 2015, 2016 Centre National de la Recherche Scientifique (CNRS)
+
+Schiff is free software released under the GPLv3+ license: GNU GPL
+version 3 or later.
+You are welcome to redistribute it under certain conditions; refer to
+the [license](https://www.gnu.org/licenses/gpl.html) for details.
diff --git a/schiff/schiff_build.sh b/schiff/schiff_build.sh
@@ -25,14 +25,14 @@ overview()
fi
print_header -s Schiff -n Overview -r ../
- VERSION=$1 envsubst < schiff.html.in
+ sed "s/@VERSION@/$1/g" | md2html
print_footer
}
documentations()
{
print_header -s Schiff -n Documentations -r ../
- cat schiff-docs.html.in
+ md2html schiff-docs.md
print_footer
}
diff --git a/schiff/thumbs/particles.jpg b/schiff/thumbs/particles.jpg
@@ -0,0 +1 @@
+#$# git-wad 2aafb7d9413d4ca38cbc1d3f26fcb4734407189e944dac1bee2c343758f74196 66201
+\ No newline at end of file
