exo_k.two_stream.two_stream_toon

Created in Jan 2021.

@author: jeremy leconte

Module Contents

exo_k.two_stream.two_stream_toon.solve_2stream_nu_xsec(source_nu, tau_nu, dtau_nu, omega0_nu, g_asym_nu, flux_top_dw_nu, alb_surf_nu, mu0=0.5, flux_at_level=False, mu_star=None, stellar_mode='diffusive', planck_correction_factor=None)[source]

Deals with the spectral axis.

Parameters:

  • source_nu (numpy.ndarray) – \(\pi B(T)\) (Planck function) at each of the Nlay+1 level interfaces. Shape: (Nlev+1, Nw).

  • tau_nu (numpy.ndarray) – Cumulative optical depth of the previous levels, start at 0. The last value tau[-1] is equals to the optical depth of the column. Shape: (Nlev+1, Nw).

  • dtau_nu (numpy.ndarray) – Optical depth of each level, for each band. Shape: (Nlev, Nw).

  • omega0_nu (numpy.ndarray) – Single scattering albedo of each level for each band. Shape: (Nlev, Nw).

  • g_asym_nu (numpy.ndarray) – Asymmetry factor. Shape: (Nlev, Nw).

  • flux_top_dw_nu (numpy.ndarray) – Top down flux, either diffusive or collimated. Shape: (Nw,).

  • alb_surf_nu (numpy.ndarray) – Surface albedo. Emissivity is assumed to be 1.-alb_surf. Shape: (Nw,).

  • mu0 (float) –

    \(\mu_0\) is the incident direction of the observer. It is used as an effective angle.

    • \(\frac{1}{2}\) yields the hemispheric mean approximation.

    • \(\frac{1}{\sqrt(3)}\) yields the quadrature approximation

  • flux_at_level (bool) –

    • If flux_at_level is True, fluxes are calculated at the level surfaces.

    • If False, fluxes are computed at the middle of the layers.

    The top of atmosphere flux is always computed at the top of the uppermost layer (1st level).

  • mu_star (Optional[float]) – \(\mu_*\) is the incident direction of the solar beam. Used when the incoming diffuse flux is treated as a source term.

  • stellar_mode (Literal['diffusive', 'collimated']) –

    When flux_top_dw_nu is provided, set the method to be used to take it into account.

    • diffusive: Incoming diffuse flux at the upper boundary.

    • collimated: Incoming diffuse flux is treated as a source term.

  • planck_correction_factor (Optional[float]) – Allow setting the epsilon used to rewrite the equations , from Chaverot et al. (2022).

Returns:

  • flux_up (np.ndarray) – Shape: (Nlev, Nw).

  • flux_dw (np.ndarray) – Shape: (Nlev, Nw).

  • flux_net (np.ndarray) – Shape: (Nlev, Nw).

  • J4pi (np.ndarray) – Shape: (Nlev, Nw, Ng).

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.solve_2stream_nu_corrk(source_nu, tau_nu, dtau_nu, omega0_nu, g_asym_nu, flux_top_dw_nu, alb_surf_nu, mu0=0.5, flux_at_level=False, mu_star=None, stellar_mode='diffusive', planck_correction_factor=None)[source]

Deals with the spectral axis.

Parameters:

  • source_nu (numpy.ndarray) – \(\pi B(T)\) (Planck function) at each of the Nlay+1 level interfaces. Shape: (Nlev+1, Nw).

  • tau_nu (numpy.ndarray) – Cumulative optical depth of the previous levels, start at 0. The last value tau[-1] is equals to the optical depth of the column. Shape: (Nlev+1, Nw, Ng).

  • dtau_nu (numpy.ndarray) – Optical depth of each level, for each band. Shape: (Nlev, Nw, Ng).

  • omega0_nu (numpy.ndarray) – Single scattering albedo of each level, for each band. Shape: (Nlev, Nw, Ng).

  • g_asym_nu (numpy.ndarray) – Asymmetry factor. Shape: (Nlev, Nw, Ng).

  • flux_top_dw_nu (numpy.ndarray) – Top down flux, either diffusive or collimated. Shape: (Nw,).

  • alb_surf_nu (numpy.ndarray) – Surface albedo. Emissivity is assumed to be 1.-alb_surf. Shape: (Nw,).

  • mu0 (float) –

    \(\mu_0\) is the incident direction of the observer. It is used as an effective angle.

    • \(\frac{1}{2}\) yields the hemispheric mean approximation.

    • \(\frac{1}{\sqrt(3)}\) yields the quadrature approximation

  • flux_at_level (bool) –

    • If flux_at_level is True, fluxes are calculated at the level surfaces.

    • If False, fluxes are computed at the middle of the layers.

    The top of atmosphere flux is always computed at the top of the uppermost layer (1st level).

  • mu_star (Optional[float]) – \(\mu_*\) is the incident direction of the solar beam. Used when the incoming diffuse flux is treated as a source term.

  • stellar_mode (Literal['diffusive', 'collimated']) – Dictate how flux_top_dw_nu is taken it into account. - diffusive: Incoming diffuse flux at the upper boundary. - collimated: Incoming diffuse flux is treated as a source term.

  • planck_correction_factor (Optional[float]) – Allow setting the epsilon used to rewrite the equations , from Chaverot et al. (2022).

Returns:

  • flux_up (np.ndarray) – Shape: (Nlev, Nw, Ng).

  • flux_dw (np.ndarray) – Shape: (Nlev, Nw, Ng).

  • flux_net (np.ndarray) – Shape: (Nlev, Nw, Ng).

  • J4pi (np.ndarray) – Shape: (Nlev, Nw, Ng).

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.solve_2stream(source, tau, dtau, omega0, g_asym, flux_top_dw, alb_surf, mu0, flux_at_level, mu_star, stellar_mode, planck_correction_factor)[source]

Solve the 2-stream equations over a bin.

After Toon et al. (JGR, 1989). Equation numbers refer to this article.

alb_surf = \(R_{sfc}\), emis_surf = \(\varepsilon\) = 1 - alb_surf = \(1 - R_{sfc}\),

Parameters:

  • source (numpy.ndarray) – Shape: (Nlev+1,).

  • tau (numpy.ndarray) – Shape: (Nlev+1,).

  • dtau (numpy.ndarray) – Shape: (Nlev,).

  • omega0 (numpy.ndarray) – Shape: (Nlev,).

  • g_asym (numpy.ndarray) – Shape: (Nlev,).

  • mu0 (float)

  • flux_top_dw (float)

  • alb_surf (float)

  • flux_at_level (bool)

  • mu_star (Optional[float])

  • stellar_mode (Literal['diffusive', 'collimated'])

  • planck_correction_factor (Optional[float]) – Allow setting the epsilon used to rewrite the equations , from Chaverot et al. (2022).

Returns:

  • flux_up (np.ndarray) – Shape: (Nlev+1,).

  • flux_dw (np.ndarray) – Shape: (Nlev+1,).

  • flux_net (np.ndarray) – Shape: (Nlev+1,).

  • J4pi (np.ndarray) – Shape: (Nlev+1,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.c_planck(source, dtau, gamma_1, gamma_2)[source]

c_up/dw is for c+/- without direct beam scattering.

_top is for tau equal 0 (top of the layer) _bot is for tau=dtau (bottom of the layer) removed a pi factor because source is pi*B :param source: Shape: (Nlev+1,) :param dtau: Shape: (Nlev,) :param gamma_1: Shape: (Nlev,) :param gamma_2: Shape: (Nlev,)

Returns:

  • c_up_top (np.ndarray) – Shape: (Nlev,)

  • c_dw_top (np.ndarray) – Shape: (Nlev,)

  • c_up_bot (np.ndarray) – Shape: (Nlev,)

  • c_dw_bot (np.ndarray) – Shape: (Nlev,)

Parameters:
Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon._c_star_denominator(l, mu_star, eps_frac=1e-12)[source]

Compute the denominator for equations (23) and (24). We use the following reference: https://github.com/NCAR/iCESM1.2/blob/355f7b2c77f1b49004145f6b975617c0917d18ce/models/atm/cam/src/chemistry/mozart/mo_ps2str.F90#L236C1-L238C47 This allow to properly implement “In practice, if the equality happens to occur, this problem can be eliminated by simply choosing a slightly different value of mu0” (Toon & al 1989)

Parameters:
Return type:

numpy.ndarray

exo_k.two_stream.two_stream_toon.c_star(flux_collimated_top_down, taucum, dtau, gamma_1, gamma_2, gamma_3, gamma_4, omega_0, mu_star)[source]

Compute the values of \(C^{+}(0), C^{-}(0),C^{+}(\tau)\) and \(C^{-}(\tau)\) for the solar radiation part.

Follow the equations (23) and (24).

Parameters:
Returns:

  • $C^```{+}`(0)$ – Shape: (Nlev,).

  • $C^```{-}`(0)$ – Shape: (Nlev,).

  • $C^```{+}`(tau)$ – Shape: (Nlev,).

  • $C^```{-}`(tau)$ – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.c_planck_mid(source, dtau, gamma_1, gamma_2)[source]

Compute \(C^\pm\) at the middle of the layer, i.e. at tau=dtau/2, ie \(C^\pm(\frac{\tau}{2})\).

c_up/dw is for c+/- without direct beam scattering.

Parameters:
Returns:

  • $C^```{+}`(frac```{tau}````{2}`)$ – Shape: (Nlev,).

  • $C^```{-}`(frac```{tau}````{2}`)$ – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.c_star_mid(flux_collimated_top_down, taucum, dtau, gamma_1, gamma_2, gamma_3, gamma_4, omega_0, mu_star)[source]

Compute \(C^\pm\) at the middle of the layer, i.e. at tau=dtau/2, ie \(C^\pm(\frac{\tau}{2})\).

Parameters:
Returns:

  • $C^```{+}`(frac```{tau}````{2}`)$ – Shape: (Nlev,).

  • $C^```{-}`(frac```{tau}````{2}`)$ – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.mid_factor_toon(dtau, gamma_1, gamma_2)[source]

Factors to recover the flux at mid layer.

Parameters:
Returns:

  • \(\text{factor}_{1,\frac{1}{2}}\) (np.ndarray)

  • \(\text{factor}_{2,\frac{1}{2}}\) (np.ndarray)

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.s_planck(omega0, bb_source, planck_correction_factor)[source]

Implement equation (15).

Parameters:
Returns:

  • \(S^+\) (np.ndarray) – Shape: (Nlev,).

  • \(S^-\) (np.ndarray) – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.s_star(omega0, gamma_3, gamma_4, taucum, flux_collimated_top_down, mu_star)[source]

Implement equations (13) and (14).

Parameters:
Returns:

  • \(S^+\) (np.ndarray) – Shape: (Nlev,).

  • \(S^-\) (np.ndarray) – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon._gamma_planck(omega0, g_asym, mu0, planck_correction_factor)[source]

Compute the value for \(\gamma_1\) and \(\gamma_2\) using Table 1.

Parameters:
Returns:

\(\gamma_1\)np.ndarray

Shape: (Nlev,)

\(\gamma_2\)np.ndarray

Shape: (Nlev,)

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon._gamma_star(g_asym, mu0, mu_star)[source]

Compute the value of \(\gamma_{3,4}\), following Toon et al.

At this moment, we made the choice to use the value for the quadrature method and identifying the factor \(\sqrt{3}\) to \(\frac{1}{mu0}\) in our code. Moreover, these factor are not subject to the planck_correction_factor.

Notes

For this function, \(\mu_0\) should have the same meaning as \(\mu_1\) in the article.

Parameters:
Returns:

  • \(\gamma_3\) (np.ndarray) – Shape: (Nlev,).

  • \(\gamma_4\) (np.ndarray) – Shape: (Nlev,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon._gammas_toon(omega0, g_asym, mu0, mu_star, planck_correction_factor, stellar_mode)[source]

Compute the value for \(\gamma_1\), \(\gamma_2\), \(\gamma_3\) and \(\gamma_4\).

Parameters:
Returns:

\(\gamma_1\)np.ndarray

Shape: (Nlev,)

\(\gamma_2\)np.ndarray

Shape: (Nlev,)

\(\gamma_3\)np.ndarray

Shape: (Nlev,)

\(\gamma_4\)np.ndarray

Shape: (Nlev,)

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.lambda_toon2(gamma_1, gamma_2)[source]

Compute \(\lambda^2\) from eq 21 of Toon et al.

Parameters:
Returns:

\(\left( \gamma_1^2 - \gamma_2^2 \right)\) – Shape: (Nlev,).

Return type:

np.ndarray

exo_k.two_stream.two_stream_toon.lambda_toon(gamma_1, gamma_2)[source]

Compute \(\lambda\) from eq 21 of Toon et al.

Parameters:
Returns:

\(\left( \gamma_1^2 - \gamma_2^2 \right)^\frac{1}{2}\) – Shape: (Nlev,).

Return type:

np.ndarray

exo_k.two_stream.two_stream_toon.lambda_GAMMA(gamma_1, gamma_2)[source]

Compute \(\lambda\) and \(\Gamma\) from eq 21 and 22 of Toon et al.

Notes

Toon and al. provide two formulas for \(\Gamma\) at equation (22):

  • \(\frac{\gamma_2}{\gamma_1 + \lambda}\)

  • \(\frac{\gamma_1 - \lambda}{\gamma_2}\)

We choose two use the first one.

Parameters:

  • gamma_1 – \(\gamma_1\) Shape: (Nlev,)

  • gamma_2 – \(\gamma_2\) Shape: (Nlev,)

Returns:

  • \(\lambda\) (np.ndarray) – Shape: (Nlev,)

  • \(\Gamma\) (np.ndarray) – Shape: (Nlev,)

Return type:

Tuple[numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.e_i_toon(dtau, gamma_1, gamma_2)[source]

\(e_i\) factors defined in eq 44.

Parameters:
Returns:

  • \(e_{1}\) (np.ndarray) – Shape: (Nlev,)

  • \(e_{2}\) (np.ndarray) – Shape: (Nlev,)

  • \(e_{3}\) (np.ndarray) – Shape: (Nlev,)

  • \(e_{4}\) (np.ndarray) – Shape: (Nlev,)

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.matrix_toon_tridiag(Nlev, taucum, dtau, omega_0, gamma_1, gamma_2, gamma_3, gamma_4, source, mu0, mu_star, flux_diffuse_top_dw, flux_collimated_top_dw, alb_surf, flux_at_level)[source]

Compute the up/dw/net fluxes and J4pi.

Parameters:

  • Nlev (int) – Number of levels.

  • taucum (numpy.ndarray) – Shape: (Nlev+1,)=(Nlay,).

  • dtau (numpy.ndarray) – Shape: (Nlev,).

  • omega_0 (numpy.ndarray) – Shape: (Nlev,).

  • source (numpy.ndarray) – Shape: (Nlev,).

  • gamma_1 (numpy.ndarray) – Shape: (Nlev,).

  • gamma_2 (numpy.ndarray) – Shape: (Nlev,).

  • gamma_3 (numpy.ndarray) – Shape: (Nlev,). Required in collimated mode.

  • gamma_4 (numpy.ndarray) – Shape: (Nlev,). Required in collimated mode.

  • mu0 (float)

  • mu_star (float)

  • flux_diffuse_top_dw (float) – Top downward flux to be treated as a diffusive flux (ie, boundary condition).

  • flux_collimated_top_dw (Optional[float]) – Top downward flux to be treated as a collimated flux. Can be seen as \(\mu_0\pi Fs\) in toon.

  • alb_surf (float) – Shape: (Nlev,).

  • flux_at_level (bool)

Returns:

\(F_{up}\): np.ndarray

Upper flux at the bottom of the Nlay layers. Shape: (Nlev+1,)=(Nlay,).

\(F_{dw}\): np.ndarray

Down flux at the bottom of the Nlay layers. Shape: (Nlev+1,)=(Nlay,).

\(F_{net}\): np.ndarray

Net flux at the bottom of the Nlay layers. Shape: (Nlev+1,)=(Nlay,).

\(4\pi J_n\): np.ndarray

J4pi at the bottom of the Nlay layers. Take into account the contribution from the incident flux. Shape: (Nlev+1,)=(Nlay,).

Return type:

Tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray, numpy.ndarray]

exo_k.two_stream.two_stream_toon.DTRIDGL(L, AF, BF, CF, DF)[source]

DIMENSION AF(L),BF(L),CF(L),DF(L),XK(L).

DIMENSION AS(2*L),DS(2*L)

!* THIS SUBROUTINE SOLVES A SYSTEM OF TRIDIAGIONAL MATRIX !* EQUATIONS. THE FORM OF THE EQUATIONS ARE: !* A(I)*X(I-1) + B(I)*X(I) + C(I)*X(I+1) = D(I) !======================================================================!

Parameters:
Returns:

Y: np.ndarray

Return type:

numpy.ndarray