PythonicDISORT 1.0.0__tar.gz → 1.0.1__tar.gz

{pythonicdisort-1.0.0/src/PythonicDISORT.egg-info → pythonicdisort-1.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PythonicDISORT
-Version: 1.0.0
+Version: 1.0.1
 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

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/pyproject.toml

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

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/src/PythonicDISORT/_assemble_intensity_and_fluxes.py

@@ -592,6 +592,6 @@ def _assemble_intensity_and_fluxes(
         # --------------------------------------------------------------------------------------------------------------------------
 
     if only_flux:
-        return flux_up, flux_down, u0#, GC_collect_0, K_collect_0
+        return flux_up, flux_down, u0#, GC_collect_0, K_collect_0, B_collect_0
     else:
         return flux_up, flux_down, u0, u

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/src/PythonicDISORT/_solve_for_coeffs.py

@@ -82,12 +82,12 @@ def _solve_for_coeffs(
     GC_collect = np.empty((NFourier, NLayers, NQuad, NQuad))
     use_banded_solver = (NLayers >= use_banded_solver_NLayers)
     if use_banded_solver:
-        sym_offset = 3 * N - 1
+        Nsupsubdiags = 3 * N - 1 # The number of super-diagonals equals the number of sub-diagonals
     
     # The following loops can easily be parallelized, but the speed-up is unlikely to be worth the overhead
     for m in range(NFourier):
         m_equals_0 = (m == 0)
-        BDRF_bool = (NBDRF > m) 
+        there_is_BDRF_mode = (NBDRF > m) 
         
         G_collect_m = G_collect[m, :, :, :]
         K_collect_m = K_collect[m, :, :]
@@ -97,7 +97,7 @@ def _solve_for_coeffs(
         # Generate mathscr_D and mathscr_X (BDRF terms)
         # Just for this part, refer to section 3.4.2 of the Comprehensive Documentation 
         # --------------------------------------------------------------------------------------------------------------------------
-        if BDRF_bool:
+        if there_is_BDRF_mode:
             mathscr_D_neg = (1 + m_equals_0 * 1) * BDRF_Fourier_modes[m](mu_arr_pos, mu_arr_pos)
             R = mathscr_D_neg * mu_arr_pos_times_W[None, :]
 
@@ -212,7 +212,7 @@ def _solve_for_coeffs(
                     * np.exp(-scaled_tau_arr_with_0 / mu0)[l_range, None]
                 ).ravel()
                 
-            if BDRF_bool:
+            if there_is_BDRF_mode:
                 RHS = (
                     np.concatenate(
                         [
@@ -260,7 +260,7 @@ def _solve_for_coeffs(
             G_0_np
             * np.exp(K_collect_m[0, :N] * scaled_tau_arr_with_0[1])[None, :]
         )
-        if BDRF_bool:
+        if there_is_BDRF_mode:
             LHS[-N:, -NQuad : -N] = (G_L_pn - R @ G_L_nn) * E_Lm1L[None, :]
             LHS[-N:, -N:] = G_L_pp - R @ G_L_np
         else:
@@ -298,8 +298,8 @@ def _solve_for_coeffs(
         # Solve the system
         if use_banded_solver:
             C_m = sc.linalg.solve_banded(
-                (sym_offset, sym_offset),
-                to_diag_ordered_form(LHS, sym_offset),
+                (Nsupsubdiags, Nsupsubdiags),
+                to_diag_ordered_form(LHS, Nsupsubdiags, Nsupsubdiags),
                 RHS,
                 True,
                 True,

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/src/PythonicDISORT/_solve_for_gen_and_part_sols.py

@@ -153,7 +153,7 @@ def _solve_for_gen_and_part_sols(
                 alpha_arr[ind, :, :] = alpha
                 beta_arr[ind, :, :] = beta
                 no_shortcut_indices.append(ind)
-                if m_equals_0 and there_is_iso_source:
+                if m_equals_0 and there_is_iso_source: # Keep the list empty if there is no isotropic source
                     no_shortcut_indices_0.append(l)
                 
             else:
@@ -192,7 +192,7 @@ def _solve_for_gen_and_part_sols(
             / K_arr[:, None, :]
         )
 
-        # Eigenvector matrix
+        # Eigenvector matrices
         G_arr = np.concatenate(
             (
                 (eigenvecs_GpG_arr - eigenvecs_GmG_arr) / 2,
@@ -203,7 +203,7 @@ def _solve_for_gen_and_part_sols(
         
         G_collect[no_shortcut_indices, :, :] = G_arr
         K_collect[no_shortcut_indices, :] = K_arr
-        if len(no_shortcut_indices_0) > 0:
+        if len(no_shortcut_indices_0) > 0: # If there is no isotropic source this list will be empty
             G_inv_collect_0[no_shortcut_indices_0, :, :] = np.linalg.inv(
                 G_collect[: len(no_shortcut_indices_0), :, :]
             )

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/src/PythonicDISORT/pydisort.py

@@ -44,7 +44,7 @@ def pydisort(
     omega_arr : array or float
         Single-scattering albedo of each atmospheric layer.
     NQuad : int
-        Number of ``mu`` quadrature nodes.
+        Number of ``mu`` quadrature nodes, i.e. number of streams.
     Leg_coeffs_all : 2darray
         All available unweighted phase function Legendre coefficients.
         Each row pertains to an atmospheric layer (from top to bottom).
@@ -61,10 +61,10 @@ def pydisort(
     NFourier : optional, int
         Number of Fourier modes to use to construct the intensity function.
     b_pos : optional, 2darray or float
-        Dirichlet boundary condition for the upward direction.
+        Dirichlet condition at the bottom boundary for the upward direction.
         Each column pertains to a Fourier mode (ascending order).
     b_neg : optional, 2darray or float
-        Dirichlet boundary condition for the downward direction.
+        Dirichlet condition at the top boundary for the downward direction.
         Each column pertains to a Fourier mode (ascending order).
     only_flux : optional, bool
         Do NOT compute the intensity function?
@@ -86,7 +86,7 @@ def pydisort(
         At or above how many atmospheric layers should ``scipy.linalg.solve_banded`` be used?
     autograd_compatible : optional, bool
         If ``True``, the autograd package: https://github.com/HIPS/autograd can be used to compute
-        the tau-derivatives of the output functions but ``pydisort`` will be less efficient.  
+        the ``tau``-derivatives of the output functions but ``pydisort`` will be less efficient.  
 
     Returns
     -------
@@ -97,9 +97,7 @@ def pydisort(
         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``.
-        For example, ``Fp(1, is_antiderivative_wrt_tau=True) - Fp(0, is_antiderivative_wrt_tau=True)`` 
-        will produce the tau-integral over ``[1, 0]`` assuming both values belong to the same layer, and
-        ``Fp(tau_arr, is_antiderivative_wrt_tau = True) - Fp(np.insert(tau_arr[:-1] + 1e-15, 0, 0), is_antiderivative_wrt_tau = True)``
+        For example, ``Fp(tau_arr, is_antiderivative_wrt_tau = True) - Fp(np.insert(tau_arr[:-1] + 1e-15, 0, 0), is_antiderivative_wrt_tau = True)``
         will produce an array of the tau-integral over each layer.
         Pass ``return_tau_arr`` to return ``tau_arr`` (defaults to ``False``).
     Fm(tau) : function
@@ -234,8 +232,8 @@ def pydisort(
         raise ValueError("The number of phase function Legendre coefficients must be positive.") 
     if not np.all(omega_arr * Leg_coeffs_all[:, 0] == omega_arr):
         raise ValueError("The first phase function Legendre coefficient must equal 1.") 
-    if not (np.all(0 <= Leg_coeffs_all) and np.all(Leg_coeffs_all <= 1)):
-        raise ValueError("The phase function Legendre coefficients must all be between 0 and 1.") 
+    if not (np.all(-1 <= Leg_coeffs_all) and np.all(Leg_coeffs_all <= 1)):
+        raise ValueError("The phase function Legendre coefficients must all be between -1 and 1.") 
     if not NLeg <= NLeg_all:
         raise ValueError("`NLeg` cannot be larger than the number of phase function Legendre coefficients provided.")
     # Ensure that the first dimension of the following inputs corresponds to the number of layers
@@ -265,9 +263,9 @@ def pydisort(
     if I0 < 0:
         raise ValueError("The incident beam must have positive intensity.")
     if there_is_beam_source:
-        if not 0 < mu0 and mu0 <= 1:
+        if not (0 < mu0 and mu0 <= 1):
             raise ValueError("The cosine of the polar angle of the incident beam must be between 0 and 1, excluding 0.")
-        if not 0 <= phi0 and phi0 < 2 * pi:
+        if not (0 <= phi0 and phi0 < 2 * pi):
             raise ValueError("Provide the principal azimuthal angle for the incident beam (must be between 0 and 2pi, excluding 2pi).")
     # Ensure that the BC inputs are of the correct shape
     if len(np.atleast_1d(b_pos)) == 1:

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1}/src/PythonicDISORT/subroutines.py

@@ -299,14 +299,14 @@ def Planck(T, WVNM):
 
     Parameters
     ----------
-    T : float or 1darray
+    T : float or array
         Temperatures in kelvin.
     WVNM : float
         Wavenumber with units m^-1.
 
     Returns
     -------
-    float or 1darray
+    float or array
         Emitted power per unit area from a blackbody surface with units W / m^2.
 
     """
@@ -325,14 +325,15 @@ def Planck(T, WVNM):
     
 
 def blackbody_contrib_to_BCs(T, WVNMLO, WVNMHI, **kwargs):
-    """Compute blackbody contribution to the BCs (``b_pos`` or ``b_neg``).
+    """Compute blackbody contribution to each BC (``b_pos`` or ``b_neg``), 
+    i.e. the blackbody emission of that boundary, with units W / m^2.
     This convenience function is provided to help match the inputs for Stamnes' DISORT to those for PythonicDISORT.
     Users will have to manually adjust emissivities but ``PythonicDISORT.subroutines.generate_emissivity_from_BDRF``
     can help with that.
     
     Parameters
     ----------
-    T : float or 1darray
+    T : float or array
         Temperatures in kelvin.
     WVNMLO : float
         Lower bound of wavenumber interval with units m^-1. This variable is identically named in Stamnes' DISORT.
@@ -341,6 +342,10 @@ def blackbody_contrib_to_BCs(T, WVNMLO, WVNMHI, **kwargs):
     **kwargs
         Keyword arguments to pass to ``scipy.integrate.quad_vec``.
         
+    Returns
+    -------
+    float or array
+        The blackbody emission of each boundary with units W / m^2.
     """ 
     return np.squeeze(sc.integrate.quad_vec(lambda WVNM: Planck(T, WVNM), WVNMLO, WVNMHI, **kwargs)[0])
 
@@ -351,15 +356,15 @@ def linear_spline_coefficients(x, y, check_inputs=True):
 
     Parameters
     ----------
-    x : 1darray
+    x : array
         Array of `x` data points.
-    y : 1darray
+    y : array
         Array of `y` data points.
 
     Returns
     -------
     2darray
-        The coefficients with axes (segment, ascending polynomial order), as required by ``pydisort``.
+        The coefficients with axes (segment, ascending polynomial order) which is required by ``pydisort``.
 
     """
     # Input checks
@@ -379,15 +384,16 @@ def linear_spline_coefficients(x, y, check_inputs=True):
 
 
 def generate_s_poly_coeffs(tau_arr, TEMPER, WVNMLO, WVNMHI, **kwargs):
-    """Generate ``s_poly_coeffs`` as required by ``pydisort``.
-    This convenience function is provided to help match the inputs for Stamnes' DISORT to those for PythonicDISORT,
-    however, users will have to manually adjust emissivities.
+    """Generate DISORT-equivalent ``s_poly_coeffs`` for input into ``pydisort``.
+    This convenience function is provided to help match the inputs for Stamnes' DISORT to those for PythonicDISORT.
+    Users will have to manually adjust emissivities, however, and they should note that PythonicDISORT allows much
+    more flexibility in choosing blackbody emission profiles than DISORT.
     
     Parameters
     ----------
     tau_arr : array or float
         Optical depth of the lower boundary of each atmospheric layer.
-    TEMPER : 1darray
+    TEMPER : array
         Temperature in kelvin at each boundary / interface from top to bottom.
         This variable is identically named in Stamnes' DISORT.
     WVNMLO : float
@@ -419,7 +425,7 @@ def generate_s_poly_coeffs(tau_arr, TEMPER, WVNMLO, WVNMHI, **kwargs):
 def generate_emissivity_from_BDRF(N, zeroth_BDRF_Fourier_mode):
     """Use Kirchoff's law of thermal radiation to determine the (directional) emissivity 
     of the surface given the zeroth Fourier mode of the Bi-Directional Reflectance Function (BDRF).
-    This computation is internal to Stamnes' DISORT.
+    This computation is automatic and internal to Stamnes' DISORT.
     This function supplements ``PythonicDISORT.subroutines.blackbody_contrib_to_BCs``.
     
     Parameters
@@ -432,8 +438,8 @@ def generate_emissivity_from_BDRF(N, zeroth_BDRF_Fourier_mode):
 
     Returns
     -------
-    1darray
-        Emissivity for the blackbody contribution to the lower boundary source `b_neg``.
+    array
+        Emissivity for the blackbody contribution to the lower boundary source ``b_neg``.
     """
     mu_arr_pos, W = Gauss_Legendre_quad(N)
     return 1 - 2 * zeroth_BDRF_Fourier_mode(mu_arr_pos, mu_arr_pos) * mu_arr_pos[None, :] @ W
@@ -488,9 +494,9 @@ def affine_transform_poly_coeffs(poly_coeffs, a_arr, b_arr):
     poly_coeffs : 2darray
         Array with columns [C_0, C_1, ..., C_n]. 
         The rows correspond to different affine transformations.
-    a_arr : 1darray
+    a_arr : array
         Scale factors.
-    b_arr : 1darray
+    b_arr : array
         Translations.
 
     Returns
@@ -518,10 +524,11 @@ def affine_transform_poly_coeffs(poly_coeffs, a_arr, b_arr):
     return np.einsum("lij, lj -> li", T, poly_coeffs, optimize=True)
 
 
+
 def interpolate(u):
-    """Polynomial (Barycentric) interpolation with respect to mu. The output 
-    is a function that is continuous and variable in all three arguments: mu, tau and phi.
-    Discussed in sections 3.7 and 6.3 in the Comprehensive Documentation.
+    """Polynomial (Barycentric) interpolation with respect to ``mu``. The output 
+    is a function that is continuous and variable in all three arguments: ``mu``, ``tau`` and ``phi``.
+    Discussed in sections 3.7 and 6.3 of the Comprehensive Documentation.
 
     Parameters
     ----------
@@ -611,22 +618,23 @@ def interpolate(u):
          
 
 
-def to_diag_ordered_form(A, sym_offset):
+def to_diag_ordered_form(A, Nsuperdiags, Nsubdiags):
     """
-    Convert a matrix A to the diagonal ordered form required by ``scipy.linalg.solve_banded``.
-    We assume that the matrix has the same number of super- and sub-diagonals.
+    Convert some matrix A to the diagonal ordered form required by ``scipy.linalg.solve_banded``.
 
     Parameters
     ----------
     A : 2darray
         The square matrix to be converted.
-    sym_offset : int
-        The number of super- or sub-diagonals (assumed to be equal)
+    Nsuperdiags : int
+        The number of super-diagonals.
+    Nsubdiags : int
+        The number of sub-diagonals.
 
     Returns
     -------
     2darray
-        The diagonal ordered form matrix as required by solve_banded.
+        The diagonal ordered form matrix as required by ``scipy.linalg.solve_banded``.
     """
     n = A.shape[0]
     indices = np.arange(n)
@@ -634,28 +642,29 @@ def to_diag_ordered_form(A, sym_offset):
     return np.concatenate(
         [
             A[
-                indices - np.arange(sym_offset, -1, -1)[:, None],
+                indices - np.arange(Nsuperdiags, -1, -1)[:, None],
                 indices[None, :],
             ],
             A[
-                indices - np.arange(n - 1, n - sym_offset - 1, -1)[:, None],
+                indices - np.arange(n - 1, n - Nsubdiags - 1, -1)[:, None],
                 indices[None, :],
             ],
         ],
         axis=0,
     )
 
+
     
-def _mathscr_v(tau,                             # Input optical depths
-                l,                              # Layer index of each input optical depth
-                Nscoeffs,                       # Number of isotropic source polynomial coefficients
-                s_poly_coeffs,                  # Polynomial coefficients of isotropic source
-                G,                              # Eigenvector matrices
-                K,                              # Eigenvalues
-                G_inv,                          # Inverse of eigenvector matrix
-                mu_arr,                         # Quadrature nodes for both hemispheres
+def _mathscr_v(tau,                              # Input optical depths
+                l,                               # Layer index of each input optical depth
+                Nscoeffs,                        # Number of isotropic source polynomial coefficients
+                s_poly_coeffs,                   # Polynomial coefficients of isotropic source
+                G,                               # Eigenvector matrices
+                K,                               # Eigenvalues
+                G_inv,                           # Inverse of eigenvector matrix
+                mu_arr,                          # Quadrature nodes for both hemispheres
                 is_antiderivative_wrt_tau=False, # Switch to an antiderivative of the function?
-                autograd_compatible=False,      # Should the output functions be compatible with autograd?
+                autograd_compatible=False,       # Should the output functions be compatible with autograd?
                 ):
     """Particular solution for isotropic internal sources.
     Refer to section 3.6.1 of the Comprehensive Documentation.
@@ -664,22 +673,22 @@ def _mathscr_v(tau,                             # Input optical depths
     and ``_solve_for_coeffs`` functions which call it.
     
     Arguments of _mathscr_v
-    |          Variable           |                 Shape                 |
-    | --------------------------- | ------------------------------------- |
-    | ``tau``                       | ``Ntau``                                |
-    | ``l``                         | ``Ntau``                                |
-    | ``Nscoeffs``                  | scalar                                |
-    | ``s_poly_coeffs``             | ``NLayers x Nscoeffs`` or ``Nscoeffs``    |
-    | ``G``                         | ``NLayers<= x NQuad x NQuad``           |
-    | ``K``                         | ``NLayers<= x NQuad``                   |
+    |          Variable             |                   Shape                   |
+    | ----------------------------- | ----------------------------------------- |
+    | ``tau``                       | ``Ntau``                                  |
+    | ``l``                         | ``Ntau``                                  |
+    | ``Nscoeffs``                  | scalar                                    |
+    | ``s_poly_coeffs``             | ``NLayers x Nscoeffs``                    |
+    | ``G``                         | ``NLayers<= x NQuad x NQuad``             |
+    | ``K``                         | ``NLayers<= x NQuad``                     |
     | ``G_inv``                     | ``NLayers<= x NQuad x NQuad`` or ``None`` |
-    | ``mu_arr``                    | ``NQuad``                               |
-    | ``is_antiderivative_wrt_tau`` | boolean                               |
-    | ``autograd_compatible``      | boolean                               |
+    | ``mu_arr``                    | ``NQuad``                                 |
+    | ``is_antiderivative_wrt_tau`` | boolean                                   |
+    | ``autograd_compatible``       | boolean                                   |
     
     Notable internal variables of _mathscr_v
-    |     Variable     |                Shape                | 
-    | ---------------- | ----------------------------------- |
+    |     Variable     |                Shape                  | 
+    | ---------------- | ------------------------------------- |
     | i_arr            | ``Nscoeffs``                          |
     | i_arr_repeat     | ``Nscoeffs*(Nscoeffs+1)/2``           | Using triangular number formula
     | j_arr            | ``Nscoeffs*(Nscoeffs+1)/2``           | Using triangular number formula
@@ -694,8 +703,8 @@ def _mathscr_v(tau,                             # Input optical depths
         def mathscr_b(i):
             """
             Notable internal variables of mathscr_b
-            |     Variable     |                 Shape                 |
-            | ---------------- | ------------------------------------- |
+            |     Variable     |                  Shape                  |
+            | ---------------- | --------------------------------------- |
             | j_arr            | ``i + 1``                               |
             | s_poly_coeffs_nj | ``i + 1``                               |
             | OUTPUT           | ``Nscoeffs x (i + 1) x NQuad``          |
@@ -716,7 +725,7 @@ def _mathscr_v(tau,                             # Input optical depths
         shape = np.shape(K)
         i_arr = np.arange(Nscoeffs)
         i_arr_repeat = np.repeat(i_arr, i_arr + 1)
-        j_arr = np.concatenate([np.arange(i + 1) for i in range(Nscoeffs)])
+        j_arr = np.concatenate([i_arr[:i] for i in range(1, Nscoeffs + 1)])
         s_poly_coeffs_nj = s_poly_coeffs[:, n - j_arr]
 
         mathscr_v_coeffs = np.zeros((Nscoeffs, shape[0], shape[1]))
@@ -752,7 +761,7 @@ def _mathscr_v(tau,                             # Input optical depths
 
 def _compare(results, mu_to_compare, reorder_mu, flux_up, flux_down, u=None):
     """Performs pointwise comparisons between results from Stamnes' DISORT,
-    which are stored in .npz files, against results from PythonicDISORT. Used in our PyTests.
+    which are stored in ``.npz`` files, against results from PythonicDISORT. Used in our PyTests.
 
     """
     # Load saved results from Stamnes' DISORT

{pythonicdisort-1.0.0 → pythonicdisort-1.0.1/src/PythonicDISORT.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: PythonicDISORT
-Version: 1.0.0
+Version: 1.0.1
 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