PythonicDISORT 0.7.0__tar.gz → 0.8.0__tar.gz

{pythonicdisort-0.7.0/src/PythonicDISORT.egg-info → pythonicdisort-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PythonicDISORT
-Version: 0.7.0
+Version: 0.8.0
 Summary: Discrete Ordinates Solver for the (1D) Radiative Transfer Equation in a single or multi-layer atmosphere.
 Author-email: Dion HO Jia Xu <dh3065@columbia.edu>
 Project-URL: Homepage, https://github.com/LDEO-CREW/Pythonic-DISORT
@@ -20,42 +20,43 @@ Requires-Dist: jupyter>1.0.0; extra == "notebook-dependencies"
 Requires-Dist: notebook>6.5.2; extra == "notebook-dependencies"
 
 # Introduction
-The PythonicDISORT package is a Discrete Ordinates Solver for the (1D) Radiative Transfer Equation in a single or multi-layer plane-parallel atmosphere.
+The PythonicDISORT package is a Discrete Ordinates Solver for the (1D) Radiative Transfer Equation 
+in a plane-parallel, horizontally homogeneous atmosphere.
 It is coded entirely in Python 3 and is a reimplementation instead of a wrapper.
 While PythonicDISORT has been optimized for speed, it will naturally be slower than similar FORTRAN algorithms.
 On the other hand, PythonicDISORT should be easier to install, use, and modify than FORTRAN-based Discrete Ordinates Solvers.
 
-PythonicDISORT is based on Stamnes' FORTRAN DISORT (see References, in particular [2, 3, 8]) and has its main features: 
-delta-M scaling, Nakajima-Tanaka (NT) corrections, only flux option, isotropic internal sources (thermal sources), 
+PythonicDISORT is based on Stamnes' FORTRAN DISORT (see References, in particular [2, 3, 8]) and has its main features: multi-layer solver, 
+delta-M scaling, Nakajima-Tanaka (NT) corrections, only flux option, direct beam source, isotropic internal source (blackbody emission), 
 Dirichlet boundary conditions (diffuse flux boundary sources), Bi-Directional Reflectance Function (BDRF) for surface reflection, and more.
-In addition, upon the request of a user, we added a subroutine to calculate actinic fluxes and we are open to further feature requests as well as feedback. 
+In addition, subroutine to calculate actinic fluxes was added to satisfy a user request and further feature requests as well as feedback are welcome.
 
 You may contact me, Dion, through dh3065@columbia.edu.
 
-Our **GitHub repository:** https://github.com/LDEO-CREW/Pythonic-DISORT also includes our F2PY-wrapped Stamnes DISORT (version 4.0.99) in the `disort4.0.99_f2py` directory.
-The original was downloaded from http://www.rtatmocn.com/disort/. The wrapper is inspired by https://github.com/kconnour/pyRT_DISORT.
+The **GitHub repository** is https://github.com/LDEO-CREW/Pythonic-DISORT.
 
 # Documentation
 https://pythonic-disort.readthedocs.io/en/latest/
 
 Also see the accompanying Jupyter Notebook `Pythonic-DISORT.ipynb` in the `docs` directory
 of our GitHub repository.
-The Jupyter Notebook provides comprehensive documentation, suggested inputs, explanations, 
+This Jupyter Notebook provides comprehensive documentation, suggested inputs, explanations, 
 mathematical derivations and verification tests.
-We highly recommend reading the non-optional parts of sections 1 and 2 before use.
+It is highly recommended that new users read the non-optional parts of sections 1 and 2.
 
 ## PyTest and examples of how to use PythonicDISORT
 
-Not only do we have verification tests in the Jupyter Notebook, we have also recreated most of the test problems in Stamnes' `disotest.f90`; 
-`disotest.f90` is included in the `disort4.0.99_f2py` directory of our GitHub repository. In these tests, the solutions from PythonicDISORT are compared 
-against solutions from our F2PY-wrapped Stamnes' DISORT (version 4.0.99). With PyTest installed, execute the console command `pytest` 
-in the `pydisotest` directory to run these tests. The `pydisotest` directory also contains Jupyter Notebooks, one for each test, 
-to show how the tests were implemented. These notebooks double up as examples of how to use PythonicDISORT.
+Not only are there verification tests in `Pythonic-DISORT.ipynb`, 
+most of the test problems in Stamnes' `disotest.f90` (download DISORT 4.0.99 from http://www.rtatmocn.com/disort/) have also been recreated.
+In these tests, the solutions from PythonicDISORT are compared against solutions 
+from a F2PY-wrapped Stamnes' DISORT (version 4.0.99; wrapper inspired by https://github.com/kconnour/pyRT_DISORT). With PyTest installed, execute the console command `pytest` 
+in the `pydisotest` directory to run these tests. The `pydisotest` directory also contains Jupyter Notebooks that correspond to each test
+to show how it was implemented. These notebooks double up as examples of how to use PythonicDISORT.
 
 # Installation
 
 * From PyPI: `pip install PythonicDISORT`
-* From Conda-forge: (TODO: we need to first publish on Conda-forge)
+* From Conda-forge: (TODO: need to first publish on Conda-forge)
 * By cloning repository: `pip install .` in the `Pythonic-DISORT` directory; `pip install -r all_optional_dependencies.txt` to install all optional dependencies (see *Requirements to run PythonicDISORT*)
 
 ## Requirements to run PythonicDISORT
@@ -64,21 +65,18 @@ to show how the tests were implemented. These notebooks double up as examples of
 * `scipy >= 1.8.0`
 * (OPTIONAL) `pytest >= 6.2.5` (Required to use the command `pytest`, see *PyTest and examples of how to use PythonicDISORT*)
 
-## Additional requirements to run the Jupyter Notebook
+## (OPTIONAL) Additional requirements to run the Jupyter Notebook
 * `autograd >= 1.5`
 * `jupyter > 1.0.0`
 * `notebook > 6.5.2`
+* `matplotlib >= 3.6.0`
 
-In addition, our F2PY-wrapped Stamnes' DISORT (in the `disort4.0.99_f2py` directory), or equivalent,
-must be set up to run the last section (section 6).
+In addition, a F2PY-wrapped Stamnes' DISORT, or equivalent, is required to properly run the last section (section 6).
 
 ## Compatibility
 
-The PythonicDISORT package *should* be system agnostic given its minimal dependencies and pure Python code.
-We do not guarantee that our Jupyter Notebook and F2PY-wrapped Stamnes' DISORT will work on other systems though.
-The latter will almost certainly need user edits to work and in any case it requires FORTRAN compilers which
-are not included in our GitHub repository. Everything in the repository was built and tested on Windows 11 but 
-not yet tested on other systems.
+The PythonicDISORT package should be system agnostic given its minimal dependencies and pure Python code.
+Everything in the repository was built and tested on Windows 11.
 
 # Acknowledgements
 
@@ -106,6 +104,8 @@ Science and Technology Center (STC) (Award #2019625) under which this package wa
 
 10) Trefethen, L. N.. 1996. *Finite difference and spectral methods for ordinary and partial differential equations.* https://people.maths.ox.ac.uk/trefethen/pdetext.html.
 
-11) T. Nakajima and M. Tanaka. 1988. *Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation.* https://www.sciencedirect.com/science/article/pii/0022407388900313.
+11) Knut Stamnes. 1982. *On the computation of angular distributions of radiation in planetary atmospheres.* https://www.sciencedirect.com/science/article/pii/0022407382900966.
 
-12) K. Connour and A. Stcherbinine. 2022. *pyRT_DISORT.* https://github.com/kconnour/pyRT_DISORT.
+12) T. Nakajima and M. Tanaka. 1988. *Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation.* https://www.sciencedirect.com/science/article/pii/0022407388900313.
+
+13) Connour, Kyle and Wolff, Michael. 2020. *pyRT_DISORT: A pre-processing front-end to help make DISORT simulations easier in Python.* https://github.com/kconnour/pyRT_DISORT.

{pythonicdisort-0.7.0 → pythonicdisort-0.8.0}/README.md

@@ -1,40 +1,41 @@
 # Introduction
-The PythonicDISORT package is a Discrete Ordinates Solver for the (1D) Radiative Transfer Equation in a single or multi-layer plane-parallel atmosphere.
+The PythonicDISORT package is a Discrete Ordinates Solver for the (1D) Radiative Transfer Equation 
+in a plane-parallel, horizontally homogeneous atmosphere.
 It is coded entirely in Python 3 and is a reimplementation instead of a wrapper.
 While PythonicDISORT has been optimized for speed, it will naturally be slower than similar FORTRAN algorithms.
 On the other hand, PythonicDISORT should be easier to install, use, and modify than FORTRAN-based Discrete Ordinates Solvers.
 
-PythonicDISORT is based on Stamnes' FORTRAN DISORT (see References, in particular [2, 3, 8]) and has its main features: 
-delta-M scaling, Nakajima-Tanaka (NT) corrections, only flux option, isotropic internal sources (thermal sources), 
+PythonicDISORT is based on Stamnes' FORTRAN DISORT (see References, in particular [2, 3, 8]) and has its main features: multi-layer solver, 
+delta-M scaling, Nakajima-Tanaka (NT) corrections, only flux option, direct beam source, isotropic internal source (blackbody emission), 
 Dirichlet boundary conditions (diffuse flux boundary sources), Bi-Directional Reflectance Function (BDRF) for surface reflection, and more.
-In addition, upon the request of a user, we added a subroutine to calculate actinic fluxes and we are open to further feature requests as well as feedback. 
+In addition, subroutine to calculate actinic fluxes was added to satisfy a user request and further feature requests as well as feedback are welcome.
 
 You may contact me, Dion, through dh3065@columbia.edu.
 
-Our **GitHub repository:** https://github.com/LDEO-CREW/Pythonic-DISORT also includes our F2PY-wrapped Stamnes DISORT (version 4.0.99) in the `disort4.0.99_f2py` directory.
-The original was downloaded from http://www.rtatmocn.com/disort/. The wrapper is inspired by https://github.com/kconnour/pyRT_DISORT.
+The **GitHub repository** is https://github.com/LDEO-CREW/Pythonic-DISORT.
 
 # Documentation
 https://pythonic-disort.readthedocs.io/en/latest/
 
 Also see the accompanying Jupyter Notebook `Pythonic-DISORT.ipynb` in the `docs` directory
 of our GitHub repository.
-The Jupyter Notebook provides comprehensive documentation, suggested inputs, explanations, 
+This Jupyter Notebook provides comprehensive documentation, suggested inputs, explanations, 
 mathematical derivations and verification tests.
-We highly recommend reading the non-optional parts of sections 1 and 2 before use.
+It is highly recommended that new users read the non-optional parts of sections 1 and 2.
 
 ## PyTest and examples of how to use PythonicDISORT
 
-Not only do we have verification tests in the Jupyter Notebook, we have also recreated most of the test problems in Stamnes' `disotest.f90`; 
-`disotest.f90` is included in the `disort4.0.99_f2py` directory of our GitHub repository. In these tests, the solutions from PythonicDISORT are compared 
-against solutions from our F2PY-wrapped Stamnes' DISORT (version 4.0.99). With PyTest installed, execute the console command `pytest` 
-in the `pydisotest` directory to run these tests. The `pydisotest` directory also contains Jupyter Notebooks, one for each test, 
-to show how the tests were implemented. These notebooks double up as examples of how to use PythonicDISORT.
+Not only are there verification tests in `Pythonic-DISORT.ipynb`, 
+most of the test problems in Stamnes' `disotest.f90` (download DISORT 4.0.99 from http://www.rtatmocn.com/disort/) have also been recreated.
+In these tests, the solutions from PythonicDISORT are compared against solutions 
+from a F2PY-wrapped Stamnes' DISORT (version 4.0.99; wrapper inspired by https://github.com/kconnour/pyRT_DISORT). With PyTest installed, execute the console command `pytest` 
+in the `pydisotest` directory to run these tests. The `pydisotest` directory also contains Jupyter Notebooks that correspond to each test
+to show how it was implemented. These notebooks double up as examples of how to use PythonicDISORT.
 
 # Installation
 
 * From PyPI: `pip install PythonicDISORT`
-* From Conda-forge: (TODO: we need to first publish on Conda-forge)
+* From Conda-forge: (TODO: need to first publish on Conda-forge)
 * By cloning repository: `pip install .` in the `Pythonic-DISORT` directory; `pip install -r all_optional_dependencies.txt` to install all optional dependencies (see *Requirements to run PythonicDISORT*)
 
 ## Requirements to run PythonicDISORT
@@ -43,21 +44,18 @@ to show how the tests were implemented. These notebooks double up as examples of
 * `scipy >= 1.8.0`
 * (OPTIONAL) `pytest >= 6.2.5` (Required to use the command `pytest`, see *PyTest and examples of how to use PythonicDISORT*)
 
-## Additional requirements to run the Jupyter Notebook
+## (OPTIONAL) Additional requirements to run the Jupyter Notebook
 * `autograd >= 1.5`
 * `jupyter > 1.0.0`
 * `notebook > 6.5.2`
+* `matplotlib >= 3.6.0`
 
-In addition, our F2PY-wrapped Stamnes' DISORT (in the `disort4.0.99_f2py` directory), or equivalent,
-must be set up to run the last section (section 6).
+In addition, a F2PY-wrapped Stamnes' DISORT, or equivalent, is required to properly run the last section (section 6).
 
 ## Compatibility
 
-The PythonicDISORT package *should* be system agnostic given its minimal dependencies and pure Python code.
-We do not guarantee that our Jupyter Notebook and F2PY-wrapped Stamnes' DISORT will work on other systems though.
-The latter will almost certainly need user edits to work and in any case it requires FORTRAN compilers which
-are not included in our GitHub repository. Everything in the repository was built and tested on Windows 11 but 
-not yet tested on other systems.
+The PythonicDISORT package should be system agnostic given its minimal dependencies and pure Python code.
+Everything in the repository was built and tested on Windows 11.
 
 # Acknowledgements
 
@@ -85,6 +83,8 @@ Science and Technology Center (STC) (Award #2019625) under which this package wa
 
 10) Trefethen, L. N.. 1996. *Finite difference and spectral methods for ordinary and partial differential equations.* https://people.maths.ox.ac.uk/trefethen/pdetext.html.
 
-11) T. Nakajima and M. Tanaka. 1988. *Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation.* https://www.sciencedirect.com/science/article/pii/0022407388900313.
+11) Knut Stamnes. 1982. *On the computation of angular distributions of radiation in planetary atmospheres.* https://www.sciencedirect.com/science/article/pii/0022407382900966.
 
-12) K. Connour and A. Stcherbinine. 2022. *pyRT_DISORT.* https://github.com/kconnour/pyRT_DISORT.
+12) T. Nakajima and M. Tanaka. 1988. *Algorithms for radiative intensity calculations in moderately thick atmospheres using a truncation approximation.* https://www.sciencedirect.com/science/article/pii/0022407388900313.
+
+13) Connour, Kyle and Wolff, Michael. 2020. *pyRT_DISORT: A pre-processing front-end to help make DISORT simulations easier in Python.* https://github.com/kconnour/pyRT_DISORT.

{pythonicdisort-0.7.0 → pythonicdisort-0.8.0}/pyproject.toml

@@ -8,7 +8,7 @@ dependencies = [
   "scipy>=1.8.0",
 ]
 name = "PythonicDISORT"
-version = "0.7.0"
+version = "0.8.0"
 authors = [
   { name="Dion HO Jia Xu", email="dh3065@columbia.edu" },
 ]

{pythonicdisort-0.7.0 → pythonicdisort-0.8.0}/src/PythonicDISORT/_assemble_intensity_and_fluxes.py

@@ -28,9 +28,9 @@ def _assemble_intensity_and_fluxes(
     NLayers_to_use_sparse,              # Number of layers above or equal which to use sparse matrices
     _autograd_compatible,               # Should the output functions be compatible with autograd?
 ):  
-    """In this function the solution functions: intensity `u`, upward flux `flux_up`, downward flux `flux_down` 
-    are assembled from the eigenpairs and the coefficients which have been solved from the boundary conditions. 
-    These solution functions are then returned.
+    """Assembles the solution functions: intensity `u`, upward flux `flux_up`, downward flux `flux_down` 
+    from the previously solved eigenpairs and coefficients from the boundary conditions. 
+    Returns these solution functions.
     This function is wrapped by the `pydisort` function.
     It should be called through `pydisort` and never directly.
     It has many seemingly redundant arguments, which are described below,
@@ -161,7 +161,15 @@ def _assemble_intensity_and_fluxes(
  
         # Construct the intensity function (refer to Section 3.7 of the Comprehensive Documentation)
         # --------------------------------------------------------------------------------------------------------------------------
-        def u(tau, phi, return_Fourier_error=False):
+        def u(tau, phi, return_Fourier_error=False, is_antiderivative_wrt_tau=False):
+            """
+            Intensity function with arguments `(tau, phi)` of types `(array or float, array or float)`.
+            Returns an ndarray with axes corresponding to variation with `mu, tau, phi` respectively.
+            Pass `return_Fourier_error = True` (defaults to `False`) to return the 
+            Cauchy / Fourier convergence evaluation (type: float) for the last Fourier term.
+            Pass `is_antiderivative_wrt_tau = True` (defaults to `False`)
+            to switch to an antiderivative of the function with respect to `tau`.
+            """
             tau = np.atleast_1d(tau)
             phi = np.atleast_1d(phi)
             assert np.all(tau >= 0)
@@ -179,7 +187,7 @@ def _assemble_intensity_and_fluxes(
                 scaled_tau = scaled_tau_arr_l - scaled_tau_dist_from_top
             else:
                 scaled_tau = tau
-
+            
             exponent = np.concatenate(
                 [
                     K_collect[:, l, :N] * (scaled_tau - scaled_tau_arr_lm1)[None, :, None],
@@ -187,14 +195,33 @@ def _assemble_intensity_and_fluxes(
                 ],
                 axis=-1,
             )
-            if there_is_beam_source:
-                um = np.einsum(
-                    "mtij, mtj -> mti", GC_collect[:, l, :, :], np.exp(exponent), optimize=True
-                ) + B_collect[:, l, :] * np.exp(-scaled_tau[None, :, None] / mu0)
+            
+            if is_antiderivative_wrt_tau:
+                if there_is_beam_source:
+                    um = np.einsum(
+                        "mtij, mtj -> mti",
+                        GC_collect[:, l, :, :],
+                        np.exp(exponent) / (scale_tau[None, l, None] * K_collect[:, l, :]),
+                        optimize=True,
+                    ) + B_collect[:, l, :] * np.exp(-scaled_tau[None, :, None] / mu0) / (
+                        -scale_tau[None, l, None] / mu0
+                    )
+                else:
+                    um = np.einsum(
+                        "mtij, mtj -> mti",
+                        GC_collect[:, l, :, :],
+                        np.exp(exponent) / (scale_tau[None, l, None] * K_collect[:, l, :]),
+                        optimize=True,
+                    )
             else:
-                um = np.einsum(
-                    "mtij, mtj -> mti", GC_collect[:, l, :, :], np.exp(exponent), optimize=True
-                )
+                if there_is_beam_source:
+                    um = np.einsum(
+                        "mtij, mtj -> mti", GC_collect[:, l, :, :], np.exp(exponent), optimize=True
+                    ) + B_collect[:, l, :] * np.exp(-scaled_tau[None, :, None] / mu0)
+                else:
+                    um = np.einsum(
+                        "mtij, mtj -> mti", GC_collect[:, l, :, :], np.exp(exponent), optimize=True
+                    )
             
             # Contribution from particular solution for isotropic internal sources
             if there_is_iso_source:
@@ -207,6 +234,7 @@ def _assemble_intensity_and_fluxes(
                     G_inv_collect_0,
                     mu_arr,
                     _autograd_compatible,
+                    is_antiderivative_wrt_tau
                 )
                 
                 if _autograd_compatible:
@@ -229,20 +257,43 @@ def _assemble_intensity_and_fluxes(
                     ],
                     axis=-1,
                 )
-                if there_is_beam_source:
-                    ulast = np.einsum(
-                        "tij, tj -> it", GC_collect[-1, l, :, :], np.exp(exponent), optimize=True
-                    ) + B_collect[-1, l, :].T * np.exp(-scaled_tau[None, :] / mu0)
+                if is_antiderivative_wrt_tau:
+                    if there_is_beam_source:
+                        ulast = np.einsum(
+                            "tij, tj -> it",
+                            GC_collect[-1, l, :, :],
+                            np.exp(exponent) / (scale_tau[l, None] * K_collect[-1, l, :]),
+                            optimize=True,
+                        ) + B_collect[-1, l, :].T * np.exp(-scaled_tau[None, :] / mu0) / (
+                            -scale_tau[None, l] / mu0
+                        )
+                    else:
+                        ulast = np.einsum(
+                            "tij, tj -> it",
+                            GC_collect[-1, l, :, :],
+                            np.exp(exponent) / (scale_tau[l, None] * K_collect[-1, l, :]),
+                            optimize=True,
+                        )
                 else:
-                    ulast = np.einsum(
-                        "tij, tj -> it", GC_collect[-1, l, :, :], np.exp(exponent), optimize=True
-                    )
+                    if there_is_beam_source:
+                        ulast = np.einsum(
+                            "tij, tj -> it", GC_collect[-1, l, :, :], np.exp(exponent), optimize=True
+                        ) + B_collect[-1, l, :].T * np.exp(-scaled_tau[None, :] / mu0)
+                    else:
+                        ulast = np.einsum(
+                            "tij, tj -> it", GC_collect[-1, l, :, :], np.exp(exponent), optimize=True
+                        )
+                        
                 intensities_abs = np.abs(intensities)
                 Fourier_error = np.max(
-                    np.abs(ulast[:, :, None] * np.cos((NFourier - 1) * (phi0 - phi))[None, None, :]),
-                    intensities_abs,
-                    out=np.zeros_like(intensities_abs),
-                    where=intensities_abs > 1e-8,
+                    np.divide(
+                        np.abs(
+                            ulast[:, :, None] * np.cos((NFourier - 1) * (phi0 - phi))[None, None, :]
+                        ),
+                        intensities_abs,
+                        out=np.zeros_like(intensities_abs),
+                        where=intensities_abs > 1e-8,
+                    )
                 )
                 return I0_orig * np.squeeze(intensities), Fourier_error
             else:
@@ -251,7 +302,16 @@ def _assemble_intensity_and_fluxes(
     
     # Construct u0
     # --------------------------------------------------------------------------------------------------------------------------
-    def u0(tau, return_act_dscale_reclassification=False):
+    def u0(tau, is_antiderivative_wrt_tau=False, _return_act_dscale_for_reclass=False):
+        """        
+        Zeroth Fourier mode of the intensity with argument `tau` (type: array or float).
+        Returns an ndarray with axes corresponding to variation with `mu` and `tau` respectively.
+        This function is useful for calculating actinic fluxes and other quantities of interest,
+        but reclassification of delta-scaled flux and other corrections must be done manually
+        (for actinic flux `generate_diff_act_flux_funcs` will automatically perform the reclassification).
+        Pass `is_antiderivative_wrt_tau = True` (defaults to `False`)
+        to switch to an antiderivative of the function with respect to `tau`.
+        """
         tau = np.atleast_1d(tau)
         assert np.all(tau >= 0)
         assert np.all(tau <= tau_arr[-1])
@@ -268,11 +328,14 @@ def _assemble_intensity_and_fluxes(
             scaled_tau = scaled_tau_arr_l - scaled_tau_dist_from_top
             # The following complements the function `subroutines.generate_diff_act_flux_funcs`
             # in performing the reclassification of delta-scaled actinic flux
-            if return_act_dscale_reclassification: 
-                act_dscale_reclassification = I0 * np.exp(-scaled_tau / mu0) - I0 * np.exp(-tau / mu0)
+            if _return_act_dscale_for_reclass: 
+                if is_antiderivative_wrt_tau:
+                    act_dscale_reclassification = I0 * np.exp(-scaled_tau / mu0) / (-scale_tau[l] / mu0) - I0 * np.exp(-tau / mu0) * -mu0
+                else:
+                    act_dscale_reclassification = I0 * np.exp(-scaled_tau / mu0) - I0 * np.exp(-tau / mu0)
         else:
             scaled_tau = tau
-            if return_act_dscale_reclassification:
+            if _return_act_dscale_for_reclass:
                 act_dscale_reclassification = 0
 
         exponent = np.concatenate(
@@ -282,14 +345,33 @@ def _assemble_intensity_and_fluxes(
             ],
             axis=-1,
         )
-        if there_is_beam_source:
-            u0 = np.einsum(
-                "tij, tj -> it", GC_collect_0[l, :, :], np.exp(exponent), optimize=True
-            ) + B_collect_0[l, :].T * np.exp(-scaled_tau[None, :] / mu0)
+        
+        if is_antiderivative_wrt_tau:
+            if there_is_beam_source:
+                u0 = np.einsum(
+                    "tij, tj -> it",
+                    GC_collect_0[l, :, :],
+                    np.exp(exponent) / (scale_tau[l, None] * K_collect_0[l, :]),
+                    optimize=True,
+                ) + B_collect_0[l, :].T * np.exp(-scaled_tau[None, :] / mu0) / (
+                    -scale_tau[None, l] / mu0
+                )
+            else:
+                u0 = np.einsum(
+                    "tij, tj -> it",
+                    GC_collect_0[l, :, :],
+                    np.exp(exponent) / (scale_tau[l, None] * K_collect_0[l, :]),
+                    optimize=True,
+                )
         else:
-            u0 = np.einsum(
-                "tij, tj -> it", GC_collect_0[l, :, :], np.exp(exponent), optimize=True
-            )
+            if there_is_beam_source:
+                u0 = np.einsum(
+                    "tij, tj -> it", GC_collect_0[l, :, :], np.exp(exponent), optimize=True
+                ) + B_collect_0[l, :].T * np.exp(-scaled_tau[None, :] / mu0)
+            else:
+                u0 = np.einsum(
+                    "tij, tj -> it", GC_collect_0[l, :, :], np.exp(exponent), optimize=True
+                )
         
         # Contribution from particular solution for isotropic internal sources
         if there_is_iso_source:
@@ -302,10 +384,11 @@ def _assemble_intensity_and_fluxes(
                 G_inv_collect_0,
                 mu_arr,
                 _autograd_compatible,
+                is_antiderivative_wrt_tau
             )
-            u0 += _mathscr_v_contribution
+            u0 = u0 + _mathscr_v_contribution
         
-        if return_act_dscale_reclassification:
+        if _return_act_dscale_for_reclass:
             return I0_orig * np.squeeze(u0), act_dscale_reclassification
         else:
             return I0_orig * np.squeeze(u0)
@@ -320,7 +403,13 @@ def _assemble_intensity_and_fluxes(
         B_neg = B_collect_0[:, N:].T
 
 
-    def flux_up(tau):
+    def flux_up(tau, is_antiderivative_wrt_tau=False):
+        """    
+        (Energetic) Flux function with argument `tau` (type: array or float) for positive (upward) `mu` values.
+        Returns the diffuse flux magnitudes (same type and size as `tau`).
+        Pass `is_antiderivative_wrt_tau = True` (defaults to `False`)
+        to switch to an antiderivative of the function with respect to `tau`.
+        """
         tau = np.atleast_1d(tau)
         assert np.all(tau >= 0)
         assert np.all(tau <= tau_arr[-1])
@@ -348,12 +437,18 @@ def _assemble_intensity_and_fluxes(
                 G_inv_collect_0,
                 mu_arr,
                 _autograd_compatible,
+                is_antiderivative_wrt_tau
             )[:N, :]
         else:
             _mathscr_v_contribution = 0
-
+        
         if there_is_beam_source:
-            direct_beam_contribution = B_pos[:, l] * np.exp(-scaled_tau[None, :] / mu0)
+            if is_antiderivative_wrt_tau:
+                direct_beam_contribution = (
+                    B_pos[:, l] * np.exp(-scaled_tau[None, :] / mu0) / (-scale_tau[None, l] / mu0)
+                )
+            else:
+                direct_beam_contribution = B_pos[:, l] * np.exp(-scaled_tau[None, :] / mu0)
         else:
             direct_beam_contribution = 0
 
@@ -364,17 +459,36 @@ def _assemble_intensity_and_fluxes(
             ],
             axis=-1,
         )
-        u0_pos = (
-            np.einsum("tij, tj -> it", GC_pos[l, :, :], np.exp(exponent))
-            + direct_beam_contribution
-            + _mathscr_v_contribution
-        )
+        
+        if is_antiderivative_wrt_tau:
+            u0_pos = (
+                np.einsum(
+                    "tij, tj -> it",
+                    GC_pos[l, :, :],
+                    np.exp(exponent) / (scale_tau[l, None] * K_collect_0[l, :]),
+                )
+                + direct_beam_contribution
+                + _mathscr_v_contribution
+            )
+        else:
+            u0_pos = (
+                np.einsum("tij, tj -> it", GC_pos[l, :, :], np.exp(exponent))
+                + direct_beam_contribution
+                + _mathscr_v_contribution
+            )
         
         flux = 2 * pi * (mu_arr_pos * W) @ u0_pos
         return I0_orig * np.squeeze(flux)[()]
 
 
-    def flux_down(tau):
+    def flux_down(tau, is_antiderivative_wrt_tau=False):
+        """
+        (Energetic) Flux function with argument `tau` (type: array or float) for negative (downward) `mu` values.
+        Returns a tuple of the diffuse and direct flux magnitudes respectively where each entry is of the
+        same type and size as `tau`.
+        Pass `is_antiderivative_wrt_tau = True` (defaults to `False`)
+        to switch to an antiderivative of the function with respect to `tau`.
+        """
         tau = np.atleast_1d(tau)
         assert np.all(tau >= 0)
         assert np.all(tau <= tau_arr[-1])
@@ -402,14 +516,20 @@ def _assemble_intensity_and_fluxes(
                 G_inv_collect_0,
                 mu_arr,
                 _autograd_compatible,
+                is_antiderivative_wrt_tau
             )[N:, :]
         else:
             _mathscr_v_contribution = 0
         
         if there_is_beam_source:
-            direct_beam_contribution = B_neg[:, l] * np.exp(-scaled_tau[None, :] / mu0)
-            direct_beam = I0 * mu0 * np.exp(-tau / mu0)
-            direct_beam_scaled = I0 * mu0 * np.exp(-scaled_tau / mu0)
+            if is_antiderivative_wrt_tau:
+                direct_beam_contribution = B_neg[:, l] * np.exp(-scaled_tau[None, :] / mu0) / (-scale_tau[None, l] / mu0)
+                direct_beam = I0 * mu0 * np.exp(-tau / mu0) * -mu0
+                direct_beam_scaled = I0 * mu0 * np.exp(-scaled_tau / mu0) / (-scale_tau[None, l] / mu0)
+            else:
+                direct_beam_contribution = B_neg[:, l] * np.exp(-scaled_tau[None, :] / mu0)
+                direct_beam = I0 * mu0 * np.exp(-tau / mu0)
+                direct_beam_scaled = I0 * mu0 * np.exp(-scaled_tau / mu0)
         else:
             direct_beam_contribution = 0
             direct_beam = 0
@@ -422,11 +542,19 @@ def _assemble_intensity_and_fluxes(
             ],
             axis=-1,
         )
-        u0_neg = (
-            np.einsum("tij, tj -> it", GC_neg[l, :, :], np.exp(exponent))
-            + direct_beam_contribution
-            + _mathscr_v_contribution
-        )
+        
+        if is_antiderivative_wrt_tau:
+            u0_neg = (
+                np.einsum("tij, tj -> it", GC_neg[l, :, :], np.exp(exponent) / (scale_tau[l, None] * K_collect_0[l, :]))
+                + direct_beam_contribution
+                + _mathscr_v_contribution
+            )
+        else:
+            u0_neg = (
+                np.einsum("tij, tj -> it", GC_neg[l, :, :], np.exp(exponent))
+                + direct_beam_contribution
+                + _mathscr_v_contribution
+            )
         
         diffuse_flux = 2 * pi * (mu_arr_pos * W) @ u0_neg + direct_beam_scaled - direct_beam
         return (

{pythonicdisort-0.7.0 → pythonicdisort-0.8.0}/src/PythonicDISORT/_solve_for_coeffs.py

@@ -29,9 +29,9 @@ def _solve_for_coeffs(
     NLayers_to_use_sparse,                  # Number of layers above or equal which to use sparse matrices
 ):
     """
-    In this function the unknown coefficients of the general solution to the system
-    of ODEs for each Fourier mode is solved using the boundary conditions 
-    and the product of the coefficients and the eigenvectors is returned.
+    Uses the boundary conditions to solve for the unknown coefficients 
+    of the general solution to the system of ordinary differential equations for each Fourier mode. 
+    Returns the product of the coefficients and the eigenvectors.
     This function is wrapped by the `_assemble_intensity_and_fluxes` function.
     It has many seemingly redundant arguments to maximize precomputation in the `pydisort` function.
     See the Jupyter Notebook, especially section 3, for documentation, explanation and derivation.