schiff.md.in (6689B)
1 # Schiff 2 3 The Schiff program computes the *radiative properties* of soft 4 particles. 5 It uses the *Monte-Carlo* method to solve Maxwell's equations 6 within the 7 [L. Schiff's approximation](https://journals.aps.org/pr/abstract/10.1103/PhysRev.104.1481) 8 as presented in 9 [Charon et al. 2025](http://www.sciencedirect.com/science/article/pii/S0022407315003283). 10 The main advantages of using Monte-Carlo are: the possibility to address 11 *any shape* of particle, and the results are provided with a *numerical 12 accuracy*. 13 14 For a mixture of soft particles, Schiff estimates the total 15 *cross-sections* (absorption, scattering and extinction cross-sections) 16 in addition of the *phase function*, its cumulative and its inverse 17 cumulative. 18 19 The set of particles to simulate is defined by its *refractive index* - 20 provided at various wavelengths - and a *geometry distribution* that 21 controls how the particles look like into the mixture. 22 More precisely, this 23 distribution describes the main shapes of the particles (sphere, cylinder, 24 helical pipe, etc.) and their statistical variation according to the 25 distribution of their parameters (gaussian, lognormal, etc.). 26 27 [](images/particles.png) 28 29 > Examples of particle shapes handled by Schiff. 30 31 ## Related articles 32 33 - [Dauchet et al. 2023](https://doi.org/10.1364/OL.50048), 34 "Wave-scattering processes: path-integrals designed for the numerical 35 handling of complex geometries", Optics Letters 36 ([open access](https://arxiv.org/abs/2210.16146)) 37 38 - [Charon et al. 2016](http://www.sciencedirect.com/science/article/pii/S0022407315003283), 39 "Monte Carlo implementation of Schiff׳s approximation for estimating 40 radiative properties of homogeneous, simple-shaped and optically soft 41 particles: Application to photosynthetic micro-organisms", Journal of 42 Quantitative Spectroscopy and Radiative Transfer 43 ([open access](https://hal.science/hal-01599991v1/)) 44 45 - [Weitz et al. 2016](https://www.sciencedirect.com/science/article/abs/pii/S002199911630393X), 46 "Monte Carlo efficiency improvement by multiple sampling of 47 conditioned integration variables", Journal of Computational Physics 48 ([open access](https://hal.science/hal-01599986/)) 49 50 ## A straight interface 51 52 The Schiff program is a *command-line tool* that processes input data, 53 performs computations, write results and that's all. 54 It makes no assumptions on how the input data are created excepted that 55 it has to follow the expected file formats. 56 The simulation results are also provided as is, in a raw ASCII format. 57 58 This thin interface is particularly well suited to be *extended* and 59 *integrated into any toolchain*. 60 According to the user needs, the optical properties of the particles can be 61 entered manually or generated by an external program. 62 In the same way, the output data can either be directly interpreted or 63 post-processed by any script with respect to the targeted toolchain. 64 65 ## Quick start 66 67 Download the desired [archive](schiff-downloads.html) of Schiff and 68 verify its integrity against its PGP signature. 69 Then extract it. 70 Finally 71 source the provided `schiff.profile` file to register the Schiff 72 installation for the current shell priorly to the invocation of the 73 `schiff` program. 74 75 source ~/Schiff-@VERSION@-GNU-Linux64/etc/schiff.profile 76 schiff -h 77 78 The Schiff *reference documentation* is provided trough man pages. 79 Use the `man` command-line to consult it. 80 81 man schiff 82 man schiff-geometry 83 man schiff-output 84 85 ## Build from sources 86 87 Schiff can be built directly from its source tree. 88 The simplest way to do this is to rely on the `schiff` branch of the 89 [Star-Engine](https://gitlab.com/meso-star/star-engine/tree/schiff) 90 project: it provides CMake scripts that automate the download, the compilation 91 and the installation of Schiff and its dependencies. 92 This build procedure assumes the following prerequisites: 93 94 - git source control 95 - GNU Compiler Collection in version 4.9.2 or higher 96 - CMake in version 3.1 or higher 97 98 ### Build 99 100 Assuming that the aforementioned prerequisites are available, the build 101 procedure is summed up to: 102 103 git clone -b Schiff-@VERSION@ \ 104 https://gitlab.com/meso-star/star-engine.git Schiff-@VERSION@ 105 mkdir Schiff-@VERSION@/build 106 cd Schiff-@VERSION@/build 107 cmake ../cmake 108 make 109 110 ### Run 111 112 By default Schiff is installed in the `local` subdirectory of 113 `Schiff-@VERSION@`. Source the provided `schiff.profile` file to 114 register Schiff against the current shell. 115 116 source ~/Schiff-@VERSION@/local/etc/schiff.profile 117 schiff -h 118 119 ### Package 120 121 Once built, the Schiff installation can be packaged in an archive that 122 can then be deployed on compatible systems, i.e. systems whose C 123 library is compatible with the one available on the system used to build 124 Schiff. 125 126 cd Schiff-@VERSION@/build 127 make pkg 128 ls package/Schiff-@VERSION@* # list packages 129 130 ## Post-Process 131 132 The following Bash script illustrates how to post-process the Schiff 133 results. 134 It is an example, provided as is, without additional support. 135 According to your needs, you can study, modify, extend or redistribute 136 it freely : 137 138 139 - [Download](downloads/schiff_pretty_results.sh) the pretty result 140 script 141 142 This script reads an output file generated by the `schiff` command line 143 and split its raw ASCII results in several human readable text files in 144 order to simplify their analysis. 145 146 schiff -i geom.yaml -l 2.3 -w0.5:0.6 -o output properties 147 bash ./schiff_pretty_results.sh output 148 Write xsections.txt 149 Write descs.txt 150 Write func_0.5.txt 151 Write func_0.6.txt 152 Write cumul_0.5.txt 153 Write cumul_0.6.txt 154 Write invcumul_0.5.txt 155 Write invcumul_0.6.txt 156 157 The first generated file, named `xsections.txt`, lists for each 158 wavelength submitted with the `-w` option, its associated 159 absorption, extinction and scattering cross sections. The second file, 160 `descs.txt`, gives overall informations for each simulated 161 wavelengths, like the limit scattering angles from which its phase function was 162 analytically computed. 163 Then for each wavelength, the script generates 3 files named 164 `func_<WLEN>.txt`, `cumul_<WLEN>.txt`, and `invcumul_<WLEN>.txt` that 165 store for the wavelength `<WLEN>`, the value of its associated phase 166 function as well as its cumulative and its inverse cumulative, 167 respectively. 168 169 ## License 170 171 Copyright © 2020, 2021 [|Méso|Star>](mailto:contact@meso-star.com) 172 Copyright © 2015, 2016 Centre National de la Recherche Scientifique (CNRS) 173 174 Schiff is free software released under the GPLv3+ license: GNU GPL 175 version 3 or later. 176 You are welcome to redistribute it under certain conditions; refer to 177 the [license](https://www.gnu.org/licenses/gpl.html) for details.