Skip to content

neptoon.corrections.theory

neutrons_to_soil_moisture

Functions:

grav_soil_moisture_to_neutrons_desilets_etal_2010 

grav_soil_moisture_to_neutrons_desilets_etal_2010(gravimetric_sm, n0, additional_gravimetric_water=0.0, a0=0.0808, a1=0.372, a2=0.115)

Convert gravimetric soil moisture to neutron counts based on Eq. (A1) in Desilets et al. (2010). $$ N = N_0 \,\Big(\frac{a_0}{\theta_\mathrm{grv} + \theta_\mathrm{add} + a_2} + a_1\Big) $$

References

Parameters:

Name Type Description Default
gravimetric_sm float

Gravimetric soil moisture, \(\theta_\mathrm{grv}\) (g/g)

 required
n0 float

Neutron scaling parameter, \(N_0\) (cph)

 required
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools, \(\theta_\mathrm{add}\) (g/g), from lattice water or soil organic carbon, for instance.

 0.0
a0 float

Numerical constant

 0.0808
a1 float

Numerical constant

 0.372
a2 float

Numerical constant

 0.115

Returns:

Name Type Description
neutron_count float

Neutron count, \(N\) (cph)

neutrons_to_grav_soil_moisture_desilets_etal_2010 

neutrons_to_grav_soil_moisture_desilets_etal_2010(neutron_count, n0, additional_gravimetric_water=0.0, a0=0.0808, a1=0.372, a2=0.115)

Convert corrected neutron counts to gravimetric soil moisture based on Eq. (A1) in Desilets et al. (2010). $$ \theta_\mathrm{grv}(N) = \frac{a_0}{N/N_0 - a_1} - a_2 - \theta_\mathrm{add} $$

References

Parameters:

Name Type Description Default
neutron_count float

Neutron count \(N\) (cph)

 required
n0 float

Neutron scaling parameter, \(N_0\) (cph)

 required
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools, \(\theta_\mathrm{add}\) (g/g), from lattice water or soil organic carbon, for instance.

 0.0
a0 float

Numerical constant

 0.0808
a1 float

Numerical constant

 0.372
a2 float

Numerical constant

 0.115

Returns:

Name Type Description
gravimetric_sm float

Gravimetric soil moisture, \(\theta_\mathrm{grv}\) (g/g)

neutrons_to_grav_soil_moisture_desilets_etal_2010_reformulated 

neutrons_to_grav_soil_moisture_desilets_etal_2010_reformulated(neutron_count, n0=None, n_max=None, additional_gravimetric_water=0.0, a0=0.0808, a1=0.372, a2=0.115)

Convert corrected neutron counts to gravimetric soil moisture based on Eq. (A1) in Desilets et al. (2010) and the reformulation suggested by Eq. (12) in Köhli et al. (2021). $$ \theta_\mathrm{grv}(N) = p_0\,\frac{1 - N/N_\mathrm{max}}{p_1 - N/N_\mathrm{max}} - \theta_\mathrm{add} $$

References

Parameters:

Name Type Description Default
neutron_count float

Neutron count \(N\) (cph)

 required
n0 float

Neutron scaling parameter, \(N_0\) (in cph), if \(N_\mathrm{max}\) is not defined.

 None
n_max float

Neutron scaling parameter, \(N_\mathrm{max}\) (in cph), if \(N_0\) is not defined.

 None
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools, \(\theta_\mathrm{add}\) (g/g), from lattice water or soil organic carbon, for instance.

 0.0
a0 float

Numerical constant

 0.0808
a1 float

Numerical constant

 0.372
a2 float

Numerical constant

 0.115

Returns:

Name Type Description
gravimetric_sm float

Gravimetric soil moisture, \(\theta_\mathrm{grv}\) (g/g)

neutrons_to_grav_soil_moisture_koehli_etal_2021 

neutrons_to_grav_soil_moisture_koehli_etal_2021(neutron_count, n0, abs_air_humidity, additional_gravimetric_water=0.0, koehli_parameters='Mar21_mcnp_drf')

Convert corrected neutron counts and air humidity to gravimetric soil moisture based on the UTS function, Eq. (15) in Köhli et al. (2021). Note that this is a numerical inversion of the UTS function, developed by Prof. Ulrich Schmidt (University of Heidelberg). $$ \theta_\mathrm{grv} = f(N, h) - \theta_\mathrm{add},\quad\mathrm{where}\quad f=\mathrm{UTS}^{-1} $$

References

Parameters:

Name Type Description Default
neutron_count float

Neutron count \(N\) (cph)

 required
n0 float

Neutron scaling parameter (\(N_0\) or \(N_\mathrm{D}\))

 required
abs_air_humidity float

Absolute air humidity, \(h\) (g/cm³)

 required
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools, \(\theta_\mathrm{add}\) (g/g), from lattice water or soil organic carbon, for instance.

 0.0
koehli_parameters str

Parameter set to use.

 'Mar21_mcnp_drf'

Returns:

Name Type Description
gravimetric_sm float

Gravimetric soil moisture, \(\theta_\mathrm{grv}\) (g/g)

Examples:

With scalars:

>>> soil_moisture_grv = neutrons_to_grav_soil_moisture_koehli_etal_2021(
...     neutron_count=1000,
...     n0=3000,
...     abs_air_humidity=5.0,
...     additional_gravimetric_water = 0.05,
... )
0.292

With Pandas:

>>> data = pandas.DataFrame()
>>> data["N"] = [1600, 1400, 1200, 1000]
>>> data["h"] = [2, 3, 4, 5]
>>> data["sm_grv"] = [
...     neutrons_to_grav_soil_moisture_koehli_etal_2021(
...         neutron_count=N,
...         n0=3000,
...         abs_air_humidity=h,
...         additional_gravimetric_water = 0.05,
...     )
...     for N, h in zip(data["N"].values, data["h"].values)
... ]

grav_soil_moisture_to_neutrons_koehli_etal_2021 

grav_soil_moisture_to_neutrons_koehli_etal_2021(gravimetric_sm, abs_air_humidity, n0, additional_gravimetric_water=0.0, koehli_parameters='Mar21_mcnp_drf')

Convert gravimetric soil moisture and air humidity to neutrons based on the UTS function, Eq. (15) in Köhli et al. (2021). Note that the UTS implementation here includes bulk density scaling, \(\theta_\mathrm{vol}\cdot1.43/\varrho_\mathrm{s}=\theta_\mathrm{grv}\cdot1.43\) (see Appendix). $$ N = \mathrm{UTS}(\theta_\mathrm{grv} + \theta_\mathrm{add}, h) $$

References

Parameters:

Name Type Description Default
gravimetric_sm float

Gravimetric soil moisture, \(\theta_\mathrm{grv}\) (g/g)

 required
abs_air_humidity float

Aabsolute air humidity at the site, \(h\) (g/cm³)

 required
n0 float

Neutron scaling parameter (\(N_0\) or \(N_\mathrm{D}\))

 required
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools, \(\theta_\mathrm{add}\) (g/g), from lattice water or soil organic carbon, for instance.

 0.0
koehli_parameters str

Parameter set to use

 'Mar21_mcnp_drf'

Returns:

Name Type Description
neutron_count float

Neutron count \(N\) (cph)

Examples:

>>> N_cph = grav_soil_moisture_to_neutrons_koehli_etal_2021(
...     gravimetric_sm=0.292,
...     n0=3000,
...     abs_air_humidity=5.0,
...     additional_gravimetric_water=0.05,
... )
1000

find_n0 

find_n0(gravimetric_sm, neutron_count, abs_air_humidity=0.0, additional_gravimetric_water=0.0, conversion_theory='desilets_etal_2010', desilets_parameters=[0.0808, 0.372, 0.115], koehli_parameters='Mar21_mcnp_drf', metric='rmse', return_error=False)

Finds the neutron scaling parameter, \(N_0\) for Desilets et al. (2010) or \(N_\mathrm{D}\) for Köhli et al. (2021). The function works with scalar input (single calibration day) or vectorized input (multiple days).

References

Parameters:

Name Type Description Default
gravimetric_sm float

gravimetric water content (g/cm3)

 required
neutron_count float

Neutron count in counts per hour (cph)

 required
abs_air_humidity float

absolute air humidity (g/cm³)

 0.0
additional_gravimetric_water float

Gravimetric water equivalent of additional hydrogen pools (g/g), from lattice water or soil organic carbon, for instance.

 0.0
desilets_parameters ArrayLike

Parameter set for the Desilets Eq., [a0, a1, a2],

 [0.0808, 0.372, 0.115]
koehli_parameters Literal['Jan23_uranos', 'Jan23_mcnpfull', 'Mar12_atmprof', 'Mar21_mcnp_drf', 'Mar21_mcnp_ewin', 'Mar21_uranos_drf', 'Mar21_uranos_ewin', 'Mar22_mcnp_drf_Jan', 'Mar22_mcnp_ewin_gd', 'Mar22_uranos_drf_gd', 'Mar22_uranos_ewin_chi2', 'Mar22_uranos_drf_h200m', 'Aug08_mcnp_drf', 'Aug08_mcnp_ewin', 'Aug12_uranos_drf', 'Aug12_uranos_ewin', 'Aug13_uranos_atmprof', 'Aug13_uranos_atmprof2']

Parameter set for the Köhli Eq.

 'Mar21_mcnp_drf'
metric Literal['rmse', 'mae', 'mse', 'mape', 'rmspe', 'log_mse', 'log_mse', 'relative_rmse']

Error metric to optimize, one of: 'rmse', 'mae', 'mse', 'mape', 'rmspe', 'log_mse', 'log_mse', 'relative_rmse'

 'rmse'
return_error bool

If true, return a second value representing the RMSE

 False

Examples:

>>> N0, rmse = find_n0(
...    gravimetric_sm=[0.292, 0.032],
...    abs_air_humidity=[5,4],
...    neutron_count=[1000,1650],
...    additional_gravimetric_water=[0.05,0.05],
...    conversion_theory='koehli_etal_2021',
...    return_error = True
... )
>>> print(f"N0 = {N0:.0f} ± {rmse:.0f}")
3165 ± 46