Hapke functions
The module contains all the various functions defined and used for the Hapke model.
|
Henyey-Greenstein single lobe Single particle phase function as defined in Hapke [1] |
|
Henyey-Greenstein double conjugated lobes Single particle phase function, with conjugated forward and backward lobes, as defined in Hapke [1] and in McGuire and Hapke [39] |
|
Hapke shadow hiding opposition effect (SHOE) function. |
|
2nd order approximation of the Ambartzumian-Chandrasekhar H function. |
Compute the A$_{n}$ coefficients for the Legendre polynomial expansion in the case of an anisotropic multiple scattering. |
|
|
Compute the B$_{n}$ coefficients for the Legendre polynomial expansion of the single lobe Henyey-Greenstein phase function. |
|
Compute the B$_{n}$ coefficients for the Legendre polynomial expansion of the two-term Henyey-Greenstein phase function. |
|
Compute the first n Legendre polynomials Pn(x) using the Bonnet’s recursion formula. |
|
Computes the roughness function as defined in Hapke [8]. |
- photmodels.phot_hapke.henyey_greenstein_1(phase_angle, b)[source]
Henyey-Greenstein single lobe Single particle phase function as defined in Hapke [1]
(15)\[P_{HG,1}(g, b) = \frac{(1 - b^2)}{(1 + 2\cdot b\cdot \cos(g) + b^2)^{3/2}}\]- Parameters:
phase_angle (
float|ndarray) – Phase angle array in radians, noted as gb (
float) – Asymmetry parameter (-1 \(\leq\) b \(\leq\) 1).
- Returns:
Henyey-Greenstein phase function values.
- Return type:
ndarray
- photmodels.phot_hapke.henyey_greenstein_2(phase_angle, b, c)[source]
Henyey-Greenstein double conjugated lobes Single particle phase function, with conjugated forward and backward lobes, as defined in Hapke [1] and in McGuire and Hapke [39]
(16)\[P_{HG,2}(g, b, c) = \frac{(1 + c)}{2}\cdot P_{HG,1}(g, -b) + \frac{(1 - c)}{2}\cdot P_{HG,1}(g, b)\]- Parameters:
phase_angle (
ndarray) – Phase angle array in radians, noted as gb (
float) – Asymmetry parameter (0 \(\leq\) b \(\leq\) 1).c (
float) – Backscattering fraction (-1 \(\leq\) c \(\leq\) 1).
- Returns:
Two-term Henyey-Greenstein phase function values.
- Return type:
ndarray
- photmodels.phot_hapke.henyey_greenstein_3(phase_angle, b1, b2, c)[source]
Henyey-Greenstein with two independant lobes. Single particle phase function, with two independant forward and backward lobes, as defined in Hapke [1] and in McGuire and Hapke [39].
(17)\[P_{HG,3}(g, b_1, b_2, c) = \frac{(1 + c)}{2}\cdot P_{HG,1}(g, b_1) + \frac{(1 - c)}{2}\cdot P_{HG,1}(g, -b_2)\]- Parameters:
phase_angle (
ndarray) – Phase angle array in radians, noted as gb1 (
float) – Asymmetry parameter for backward-scattering lobe (0 \(\leq\) bm \(\leq\) 1).b2 (
float) – Asymmetry parameter for forward-scattering lobe (0 \(\leq\) bp \(\leq\) 1).c (
float) – Relative lobe strength (-1 \(\leq\) c \(\leq\) 1).
- Returns:
Three-term Henyey-Greenstein phase function values.
- Return type:
ndarray
- photmodels.phot_hapke.hapke_shoe(phase_angle, bsh, hsh)[source]
Hapke shadow hiding opposition effect (SHOE) function. This function is an approximation of the exact Hapke SHOE integral, corresponding to the case of a particulate medium with either a step distribution of matter or a hyperbolic distribution.
(18)\[B_{SH}(g) = \frac{1}{1 + \frac{1}{h_{sh}} \tan(\frac{g}{2})}\]- Parameters:
phase_angle (
ndarray) – Phase angle array in radians, noted as gbsh (
float) – Amplitude of the shadow hiding opposition effect (0 \(\leq\) bsh \(\leq\) 1).hsh (
float) – Angular width of the shadow hiding opposition effect (hsh > 0).
- Returns:
Hapke shadow hiding opposition effect function values.
- Return type:
ndarray
Note
Using this function implies a porous particulate medium, thus any model using this function should also include the porosity parameter (K) as defined in Hapke [8].
- photmodels.phot_hapke.hapke_shoe_erf(phase_angle, bsh, hsh)[source]
Hapke shadow hiding opposition effect (SHOE) function using error function. This function is the exact expression of the SHOE when considering a slab of particles, which a step distribution of matter.
(19)\[ B_{SH}(g) = 1 + b_{sh} \biggl[ \exp{\left(-3 y^2\right)} - 1 + 2 \sqrt{\pi} \cdot y \cdot \exp{(y^2)} \cdot \bigl[\erf{(2y)} - \erf{(y)}\bigr] \biggr]\]where \(y = \sqrt{\frac{h_{sh}}{\tan{\left(\frac{g}{2}\right)}}}\)
- Parameters:
phase_angle (
ndarray) – Phase angle array in radians, noted as gbsh (
float) – Amplitude of the shadow hiding opposition effect (0 \(\leq\) bsh \(\leq\) 1).hsh (
float) – Angular width of the shadow hiding opposition effect (hsh > 0).
- Returns:
Hapke shadow hiding opposition effect function values.
- Return type:
ndarray
- photmodels.phot_hapke.hapke_shoe_retro(phase_angle, bsh, hsh)[source]
Hapke’s initial analytic model for the opposition effect. This function is referred to as the retrodirective function in the 1963, 1981 papers.
(20)\[B_{SH}(g, h) = 1+B_{0} \cdot \Biggl[ 1-\frac{ \tan{\left(g\right)} }{ 2\cdot h }\cdot \left(3-e^{ -\frac{h}{ \tan{\left(g\right)} } } \right)\cdot \left(1-e^{ -\frac{h}{ \tan{\left(g\right)} } } \right) \Biggr]\]where \(B_{0}\) is the amplitude of the opposition effect, and \(h\) is the angular width of the opposition effect. This expression is valid for phase angles |g| <= 90 degrees, beyond which \(B_{SH}(g)\) = 1.
- Parameters:
phase_angle (
ndarray) – Phase angle array in radians, noted as gbsh (
float) – Amplitude of the shadow hiding opposition effect (0 \(\leq\) bsh \(\leq\) 1).hsh (
float) – Angular width of the shadow hiding opposition effect (hsh > 0).
- Return type:
ndarray- Returns:
array[float] – Evaluation of the retrodirective function.
.. note:: – This function is deprecated and should not be used in new models.
- photmodels.phot_hapke.h_function_o1(w, x)[source]
1st order approximation of the Ambartzumian-Chandrasekhar H function.
(21)\[H(x) = \frac{1+2\cdot x}{1 - 2\cdot x\cdot \sqrt{1 - w}}\]- Parameters:
w (
float) – Single scattering albedo (0 \(\leq\) w \(\leq\) 1).x (
ndarray) – Cosine of incidence or emergence angle (mu0 or mu).
- Returns:
1st order approximation of Ambartsumian-Chandrasekhar H function values.
- Return type:
ndarray
Note
This function is an approximation of the exact H function, supposedly with relative errors less than 4% over the single scattering albedo range 0 < w < 1, and for all x values between 0 and 1.
The use of the 2nd order approximation should preferred in all cases, in due of its better accuracy.
- photmodels.phot_hapke.h_function_o2(w, x)[source]
2nd order approximation of the Ambartzumian-Chandrasekhar H function.
(22)\[H(x) = \biggl[1 - w \cdot x \cdot \left(r_{0} + \frac{1 - 2\cdot x\cdot r_{0}}{2} \cdot \log\left(1 + \frac{1}{x}\right) \right)\biggr]^{-1}\]- Parameters:
w (
float) – Single scattering albedo (0 \(\leq\) w \(\leq\) 1).x (
ndarray) – Cosine of incidence or emergence angle (mu0 or mu).
- Return type:
ndarray- Returns:
array[float] – 2nd order approximation of Ambartsumian-Chandrasekhar H function values.
.. note:: – This function is an approximation of the exact H function, supposedly with relative errors less than 1% up to w ~ 1.
- photmodels.phot_hapke.pg_legendre_an(n)[source]
Compute the A$_{n}$ coefficients for the Legendre polynomial expansion in the case of an anisotropic multiple scattering. Using the expression from Hapke [9]
(23)\[\]- Parameters:
n (
int) – Number of coefficients to compute.- Returns:
An coefficients array.
- Return type:
array[float]
- photmodels.phot_hapke.pg_legendre_bn_isotropic(n)[source]
Sets to one the B$_{n}$ coefficients for the Legendre polynomial expansion in the case of an isotropic phase function.
(24)\[B_{n} = 1, \forall n \in \mathbb{N}\]- Parameters:
n (
int) – Number of coefficients to compute.- Returns:
Array set to one.
- Return type:
array[float]
- photmodels.phot_hapke.pg_legendre_bn_hg1(n, b)[source]
Compute the B$_{n}$ coefficients for the Legendre polynomial expansion of the single lobe Henyey-Greenstein phase function. Using the expression from Hapke [9]:
(25)\[\]- Parameters:
n (
int) – Number of coefficients to compute.b (
float) – Asymmetry parameter (-1 \(\leq\) b \(\leq\) 1).
- Returns:
Bn coefficients array.
- Return type:
array[float]
- photmodels.phot_hapke.pg_legendre_bn_hg2(n, b, c)[source]
Compute the B$_{n}$ coefficients for the Legendre polynomial expansion of the two-term Henyey-Greenstein phase function. Using the expression from Hapke [9]:
(26)\[\]- Parameters:
n (
int) – Number of coefficients to compute.b (
float) – Asymmetry parameter (0 \(\leq\) b \(\leq\) 1).c (
float) – Backscattering fraction (0 \(\leq\) c \(\leq\) 1).
- Returns:
Bn coefficients array.
- Return type:
array[float]
- photmodels.phot_hapke.pg_legendre_pn(n, x)[source]
Compute the first n Legendre polynomials Pn(x) using the Bonnet’s recursion formula.
(27)\[\]- Parameters:
n (
int) – Number of polynomials to compute.x (
ndarray) – Input x values array (in the case of the Hapke model x = cos(incidence/emergence angle)).
- Returns:
2D array containing the first n Legendre polynomials evaluated at each x value.
- Return type:
array[float]
- photmodels.phot_hapke.roughness_dxs(*, inc, emi, phi, theta)[source]
Computes the disk function modulated by the roughness function, as defined in Hapke [7] and Hapke [1].
- Parameters:
inc (
ndarray) – the array of incidence angle values (in radians)emi (
ndarray) – the array of emergence angle values (in radians)azi (array[float]) – the array of azimuth angle values (in radians)
theta (
float) – The photometric roughness value (in radians)
- Returns:
the evaluated product of the roughness function per the roughness-modulated disk function.
- Return type:
ndarray
Notes
The function is valid only for azimuth angles between 0 and pi, in due of the ‘f’ function, approximation chosen by Hapke (see Hapke [1], chap 12).
Benchmarking against PH’s implementation for 10k runs on an i9-9900K via jupyter NB and VScode.
old implementation : 0.0422771990 ± 0.0033080535 (s)
this implementation : 0.0191985337 ± 0.0014033128 (s)
- photmodels.phot_hapke.hapke_roughness(inc, emi, azi, theta)[source]
Computes the roughness function as defined in Hapke [8]. It returns the ratio of the reflectance masked by mutual shadows.
- Parameters:
inc (
ndarray) – the array of incidence angle values (in radians)emi (
ndarray) – the array of emergence angle values (in radians)azi (
ndarray) – the array of azimuth angle values (in radians)theta (
float) – The photometric roughness value (in radians)
- Returns:
the evaluated roughness function
- Return type:
ndarray