Incorporate Sangam's suggestions

Author: MarJMue

paper/paper.bib

@@ -185,7 +185,7 @@ @article{Berreman72
 }
 
 @misc{byrnes2020multilayer,
-      title={Multilayer optical calculations}, 
+      title={Multilayer optical calculations},
       author={Steven J. Byrnes},
       year={2020},
       eprint={1603.02720},
@@ -324,7 +324,7 @@ @article{Passler19
   abstract = {In our paper J. Opt. Soc. Am. B34, 2128 (2017)JOBPDE0740-322410.1364/JOSAB.34.002128 in Section 2.C, the calculation of the layer-dependent electric field distribution is only valid for media with permittivity tensors that are diagonal in the lab frame, i.e., non-birefringent media. This erratum corrects Section 2.C such that the electric field distribution in birefringent media is calculated correctly. Further, Eqs. (20) and (33)--(36) are corrected. The associated MATLAB implementation has been updated.},
 }
 
-@article{Pearce2021, 
+@article{Pearce2021,
   doi = {10.21105/joss.03460},
   url = {https://doi.org/10.21105/joss.03460},
   year = {2021},
@@ -369,4 +369,19 @@ @article{Bay2022
 Program Title: PyLlama – Python Toolkit for the Electromagnetic Modelling of Multilayered Anisotropic Media CPC Library link to program files: https://doi.org/10.17632/dzw8x5vyrv.1 Developer's repository link: https://github.com/VignoliniLab/PyLlama Licensing provisions: GPLv3 Programming language: Python Supplementary material: User guide and tutorials at https://pyllama.readthedocs.io/ Nature of problem: Computation of the optical reflection and transmission coefficients of arbitrary multilayered linear media, composed of an arbitrary number of layers, possibly mixing isotropic and anisotropic, absorbing and non-absorbing materials, for linearly or circularly polarised light. Solution method: Implementation of both the transfer matrix method (faster) and the scattering matrix method (more robust) relying on a 4×4 matrix formalism. Additional comments including restrictions and unusual features: Integration of a physical model to handle cholesteric structures, blueprint for the integration of user-created custom systems, hassle-free export of spectra for non-programmers even for complex and/or custom systems. External routines include: Numpy [1], Scipy [2], as well as Sympy [3] (optional).
 References
 [1]Numpy, https://numpy.org/.[2]Scipy, https://www.scipy.org/.[3]Sympy, https://www.sympy.org/.}
-}
+}
+
+@book{tompkins2005,
+  title={Handbook of Ellipsometry},
+  author={Tompkins, H. and Irene, E.A.},
+  isbn={9780815517474},
+  year={2005},
+  publisher={William Andrew},
+  address={Norwich}
+}
+
+@book{WVASEguide,
+  title={Guide to Using WVASE},
+  publisher={J. A. Woollam Co., Inc.},
+  address={Lincoln, NE}
+}

paper/paper.md

@@ -23,42 +23,53 @@ bibliography: paper.bib
 
 # Summary
 
-PyElli is an open-source analysis tool for the linear optical interaction of layered materials written in Python.
-It primarily targets spectroscopic ellipsometry but is adaptable to various transmission and reflection experiments.
-
-Spectroscopic ellipsometry (SE) is used throughout various scientific fields to determine the optical constants of layered material stacks.
-SE experiments do not yield directly usable data; numerical analysis is required to deduce actual material parameters.
-This is typically done with the transfer-matrix method (TMM), which associates an interaction matrix with the optical response of each material layer.
-The full optical response of a material system is then determined by matrix multiplication of the layers' matrices.
-
-Proprietary software for such analysis is usually bundled with ellipsometers, with each manufacturer supplying their own adapted version.
-While this suits laboratory workflows, it ties scientists to specific optical models and experiments available in the provided software.
-This makes results hard to reproduce with other systems and data interchange cumbersome.
-If the software does not support a specific kind of analysis, such as calculating anisotropic materials or simultaneous fitting of external experimental parameters, scientists need to use third-party software.
-
-PyElli offers an open-source alternative to existing solutions while remaining as compatible as possible.
-This allows scientists to adapt PyElli to their needs, either for custom experiments not covered by other software [@eberheim2022] or as a full FAIR data [@Wilkinson2016] analysis pipeline for SE measurements.
-It is designed with extensibility and adaptability in mind, enabling scientists to easily develop custom analysis pipelines.
+PyElli is an open-source Python-based analysis tool for the linear optical interaction of layered materials.
+The code primarily targets spectroscopic ellipsometry (SE) but is adaptable to various transmission and reflection experiments featuring spectral and polarization resolution.
+
+Various scientific fields use SE to determine the optical constants of materials and layered material stacks.
+The as-measured SE experimental requires numerical analysis to deduce commonly used, physically meaningful material parameters.
+A typical approach uses transfer-matrix methods (TMM) [@tompkins2005, @WVASEguide].
+Here, an interaction matrix describes the optical response of each individual material layer.
+The full optical response of a multilayer system is then determined by matrix multiplication of the layers' matrices.
+
+The ellipsometer hardware typically supports bundled proprietary software solutions for such analyses.
+Unfortunately, each manufacturer supplies their own adapted tools.
+This promises efficient laboratory workflows if working flawlessly.
+However, it binds scientists to specific optical models and experiments available in the provided software.
+Furthermore, data interchange is cumbersome, and results may be hard to reproduce on competitive systems due to the use of other models or parameters.
+Finally, limitations of the bundled software may stimulate scientists to use third-party software.
+For example, bundled software packages may not support specific kinds of analyses, such as including the response of optically anisotropic materials or simultaneous fitting of external experimental parameters.
+
+PyElli offers an open-source alternative extending the capabilities of existing solutions, while aiming to remain as compatible as possible:
+By providing importers for various manufacturers (Woollam VWASE, Woollam CompleteEASE, Sentech, Accurion), and having dispersion models
+
+Typical examples are implementations of custom experimental geometries not covered by other software [@eberheim2022] or as a full FAIR data [@Wilkinson2016] automated analysis pipeline for SE measurements.
+The code is designed with extensibility and adaptability in mind, enabling scientists to easily develop custom analysis pipelines.
 PyElli also supports recent advances in the standardization of ellipsometry data and models, addressing the need for FAIR data.
 
-The optical models used in PyElli adhere closely to the literature [@Hilfiker2018].
-New dispersions can be added as code, or a generic formula dispersion can be used, which parses a text-based formula into a fittable dispersion.
-
-For analyzing materials, it is helpful to have a database of predefined models.
-PyElli includes the popular public domain database for optical constants [refractiveindex.info](https://refractiveindex.info) [@rii], allowing users to load literature dispersions with a single line of code.
+PyElli aims to provide straight-forward availability of a database of predefined dispersion models for analyzing materials.
+All optical models adhere closely to the literature [@Hilfiker2018].
+Also, the software easily includes the popular public-domain database for optical constants [refractiveindex.info](https://refractiveindex.info) [@rii].
+This allows the inclusion of literature dispersions with a single line of code.
+Additional dispersion relations can be either hard coded, which is more efficient, or parsed from a text-based domain-specific language into a fittable dispersion.
 
 PyElli supports multiple solving algorithms with different characteristics.
-Currently, two algorithms using different formulations are available: a simple but fast algorithm based on a 2x2 matrix formulation [@byrnes2020multilayer] and a more complex 4x4 formulation [@Berreman72; @castany].
-While the 2x2 algorithm splits the light into two perpendicular polarized beams and solves them separately, the 4x4 matrix approach solves the complete electromagnetic field, allowing for the solution of more complex problems, such as anisotropic materials or active media.
-
-For fast processing, PyElli's algorithms are fully vectorized for multiple wavelengths and leverage numerical algebra libraries like [NumPy](https://numpy.org) [@harris2020array] and [SciPy](https://scipy.org) [@2020SciPy-NMeth].
-This allows the use of advanced fitting algorithms, such as global optimizers, within reasonable evaluation times and enables embedded in-situ monitoring of overlayer growth.
-The use of Python and vectorization libraries also facilitates the adoption of artificial intelligence-based analysis of SE data.
+Currently, two algorithms using different formulations are available: a fast algorithm based on a 2x2 matrix formulation [@byrnes2020multilayer] and a more complex 4x4 formulation [@Berreman72; @castany].
+The 2x2 algorithm divides the light into two perpendicular linearly polarized beams, which are solved separately.
+This, for example, eliminates the possibility of including birefringent materials.
+The 4x4 matrix approach solves Maxwell's equations.
+These equations describe the complete electromagnetic field inside each layer of the sample and couple this together using a matrix formalism.
+This allows finding solutions to more complex problems, such as anisotropic materials, active media, or magneto-optic samples.
+
+PyElli's ensures fast processing through fully vectorized algorithms for multiple wavelengths and by leveraging numerical algebra libraries like [NumPy](https://numpy.org) [@harris2020array] and [SciPy](https://scipy.org) [@2020SciPy-NMeth].
+Together, these runtime advantages enable the practical use of advanced fitting algorithms such as global optimizers while maintaining reasonable evaluation times.
+Intriguingly, such advantages enable embedded in-situ monitoring and real-time data analysis of overlayer growth.
+Thus, the use of Python and vectorization libraries also facilitates the adoption of artificial intelligence-based analysis of SE data.
 
 # Statement of need
 
 The importance of publishing data according to the FAIR principles [@Wilkinson2016] is growing.
-Many research journals already require authors to add supporting data, and sponsors are starting to demand data governance from institutes and researchers.
+Many research journals already require authors to add supporting data, and there is a growing expectation from sponsors for institutes and researchers to implement data governance.
 Since reproducing data requires not only the data itself but also the software used to create it, the FAIR principles have recently been extended to apply to research software as well[@Barker2022].
 We believe that producing FAIR data and using a FAIR and open analysis pipeline is especially important for SE, as the results are tightly related and dependent on the algorithms and models used for evaluation.
 
@@ -76,23 +87,23 @@ In summary, we believe and hope that PyElli will contribute to easier analysis,
 
 Other notable Python open-source software for solving transfer-matrices is available, but tends to focus on different aspects:
 
-- [PyGTM](https://pygtm.readthedocs.io) [@Passler17; @Passler19] provides a slower but more extensive general transfer matrix approach. It allows calculation of additional parameters, like the local strength of the electric field at any position in the multilayer stack.
+- [PyGTM](https://pygtm.readthedocs.io) [@Passler17; @Passler19] provides an non-vectorized, extensive general transfer matrix approach. It allows calculation of additional parameters, like the local strength of the electric field at any position in the multilayer stack.
 - [PyLlama](https://pyllama.readthedocs.io) [@Bay2022] focuses on the simulation of liquid crystals and uses non-vectorized TMM and a scattering matrix algorithm (rigorous coupled-wave analysis, RCWA).
 - [RayFlare](https://rayflare.readthedocs.io) [@Pearce2021] is a complete toolkit to simulate the physical and electrical properties of solar cells. It provides the same 2x2 algorithm[@byrnes2020multilayer] and a scattering matrix approach (S4).
-- [tmm_fast](https://github.com/MLResearchAtOSRAM/tmm_fast) [@Luce22] is a fast variant of Byrnes' algorithm for artificial intelligence-based analysis of multilayer stacks.
+- [tmm_fast](https://github.com/MLResearchAtOSRAM/tmm_fast) [@Luce22] is a vectorized variant of Byrnes' algorithm for artificial intelligence-based analysis of multilayer stacks.
 - Additional mentions:
   - [refellips](https://refellips.readthedocs.io/en/latest/)
   - [EMpy](http://lbolla.github.io/EMpy/)
   - [dtmm](https://github.com/IJSComplexMatter/dtmm)
   - [py_matrix](https://github.com/gevero/py_matrix)
 
-# Example: Building a simple model
+# Example: Building a model for an oxide layer on silicon
 
-Building an optical model in PyElli is simple and straightforward.
-Here, we will demonstrate by creating a standard model for SiO2 on Si.
-We will use a Cauchy dispersion function for SiO2 and tabulated literature values for Si loaded from the refractiveindex.info database.
+Building an optical model in PyElli is straightforward.
+Here, we will demonstrate by creating a standard model for SiO$_2$ on Si.
+We will use a Cauchy dispersion function for SiO$_2$ and tabulated literature values for Si loaded from the refractiveindex.info database.
 
-Before building the model, we need to import the necessary libraries.
+We need to import the necessary libraries before building the model:
 PyElli is imported from the module `elli`, and we want to use our parameters wrapper `ParamsHist`, which is imported from `elli.fitting`. `ParamsHist` is a wrapper around the `Parameters` class from [lmfit](https://lmfit.github.io/lmfit-py/index.html) [@matt_newville_2023_7810964], adding history to it so you can revert your model to an earlier set of parameters.
 We also import `linspace` from `numpy` for generating a wavelength axis.
 
@@ -102,32 +113,27 @@ import elli
 from elli.fitting import ParamsHist, fit
 ```
 
-First, we instantiate the parameters.
-We only need `n0` and `n1` for SiO2, so we keep all other values at their default, which is zero in this case.
-Additionally, we introduce the thickness of SiO2 in nanometers.
-Here, you may also add additional settings for lmfit parameters.
+Initially, we define the fit parameters.
+The Cauchy model for SiO$_2$ is defined by the `SiO2_n0` and `SiO2_n1` parameters, along with its layer thickness measured in nanometers.
+Here, additional settings for lmfit parameters like constraints or bounds might be added.
 For a list of parameter arguments, refer to lmfit's documentation or consult our verbose [basic example](https://pyelli.readthedocs.io/en/stable/auto_examples/plot_01_basic_usage.html#sphx-glr-auto-examples-plot-01-basic-usage-py).
 
 ```python
 params = ParamsHist()
-params.add("n0", value=1.452)
-params.add("n1", value=36.0)
-params.add("thickness", value=20)
+params.add("SiO2_n0", value=1.452)
+params.add("SiO2_n1", value=36.0)
+params.add("SiO2_thickness", value=20)
 ```
 
-Now, the Cauchy model is created using the `Cauchy` class.
+Now, the Cauchy model is created using the `Cauchy` class and the defined parameters.
+All other Cauchy coefficients are kept at their default value of zero in this particular case.
 Each dispersion has its own class, and you'll find a list of different dispersions in our [documentation](https://pyelli.readthedocs.io/en/stable/dispersions.html).
-It is important to note that there are two types of parameters for dispersions: **Single parameters**, which only appear once in the formula (e.g., `n0` and `n1`), and **repeated parameters** which represent one element of a sum and may be used in an arbitrary amount.
-Single parameters are added to the class constructor, like `Cauchy(param1, ...)`, and repeated parameters are added via the `.add(...)` method, like `Sellmeier().add(A=param_a, B=param_b)`.
-The available single and repeated parameters are listed in the documentation for each dispersion.
-We are using a Cauchy model here, which only takes single parameters.
-Therefore, we pass all parameters to the class constructor.
-Subsequently, the `.get_mat()` function is called on the created object to automatically convert the dispersion into an isotropic material.
+Subsequently, the `.get_mat()` method is called on the created object to automatically convert the dispersion into an isotropic material.
 
 ```python
 SiO2 = elli.Cauchy(
-  params["n0"],
-  params["n1"],
+  params["SiO2_n0"],
+  params["SiO2_n1"],
 ).get_mat()
 ```
 
@@ -144,22 +150,22 @@ With all materials instantiated, we can build the layered structure.
 The `Structure` class takes three arguments:
 
 - The incident half-space, which is typically air.
-- The layer stack as an array of `Layer` objects. The `Layer` object is created by adding the material and the layer thickness.
+- The layer stack as a list of `Layer` objects. The `Layer` object is created by adding the material and the layer thickness.
 - The lower half-space, which represents the substrate.
 
 The incident and lower half-space are modeled as infinite to terminate the calculation.
-Therfore backside scattering of the substrate cannot be introduced into the calculation.
+Therefore, backside scattering of the substrate cannot be introduced into the calculation.
 
 ```python
 structure = elli.Structure(
     elli.AIR,
-    [elli.Layer(SiO2, params["thickness"])],
+    [elli.Layer(SiO2, params["SiO2_thickness"])],
     Si,
 )
 ```
 
-Finally, we trigger a calculation by calling `evaluate(...)` on the structure.
-We use a `wavelengths` array from $210\;nm$ to $800\;nm$ for the calculation range and an angle of incidence of $70$ degree (second parameter of evaluate).
+Finally, we trigger a calculation by calling the `evaluate(...)` method of the `structure` object.
+We use a `wavelengths` array from $210$ nm to $800$ nm for the calculation range and an angle of incidence of $70°$ degree (second parameter of evaluate).
 
 ```python
 wavelengths = np.linspace(210, 800, 100)
@@ -170,7 +176,9 @@ The calculation is stored in the `result` variable, which is a [`Result` object]
 This object can hold all input parameters and the calculation results. You can call methods like `psi`, `delta`, `R`, etc., to get your desired output.
 We can also use the `@fit` decorator in `elli.fitting` to automatically show a widget-based fitting GUI for Jupyter notebooks.
 Figure \autoref{fig:fit_dec_example} shows the output when used with this example model and some experimental data.
+
 ![The ipywidgets based fitting GUI.\label{fig:fit_dec_example}](fit_decorator_example.png)
+
 You find additional information on how this is done in our [examples](https://pyelli.readthedocs.io/en/stable/auto_examples/index.html).
 
 # Acknowledgements