komanawa.gw_age_tools#

created matt_dumont on: 22/09/23

Submodules#

Functions#

`binary_exp_piston_flow`(t, mrt_p1, mrt_p2, frac_p1, ...)	produce a binary exponential piston flow model pdf
`binary_exp_piston_flow_cdf`(t, mrt_p1, mrt_p2, frac_p1, ...)	produce a cdf for a binary exponential piston flow model
`check_age_inputs`(mrt, mrt_p1, mrt_p2, frac_p1, ...)	convenience function to check BEPM age inputs
`exponential_piston_flow`(t, tm, f)	produce an exponential piston flow model pdf
`exponential_piston_flow_cdf`(t, tm, f)	produce a cdf for an exponential piston flow model
`lightweight_predict_future`(source, out_years, ages, ...)	a lightweight version of predict_future_conc_bepm that does not check inputs and does not interpolate the source concentration and does not check the parmeters... use at your own warning
`make_age_dist`(mrt, mrt_p1, mrt_p2, frac_p1, precision, ...)	make an age distribution for the binary exponential piston flow model
`predict_future_conc_bepm`(once_and_future_source_conc, ...)	predict the receptor concentration based on the source concentration time series and the binary piston flow model parameters
`predict_historical_source_conc`(init_conc, mrt, mrt_p1, ...)	Estimate the historical source concentration based on the receptor initial concentration the previous slope and the BEPEM model parameters
`predict_source_future_past_conc_bepm`(initial_conc, ...)	predict the source and receptor concentration in the future and past based on the current concentration the historical observed slope and the future predicted/scenario slope

Package Contents#

binary_exp_piston_flow(t, mrt_p1, mrt_p2, frac_p1, f_p1, f_p2)[source]#

produce a binary exponential piston flow model pdf

Parameters:

t – time steps to calculate pdf for (yrs)
mrt_p1 – mean residence time of the first piston flow component (yrs)
mrt_p2 – mean residence time of the second piston flow component (yrs)
frac_p1 – fraction of the total source that is in the first piston flow component
f_p1 – fraction of the first piston flow component that is in the fast flow component
f_p2 – fraction of the second piston flow component that is in the fast flow component

Returns:

pdf of the binary exponential piston flow model

binary_exp_piston_flow_cdf(t, mrt_p1, mrt_p2, frac_p1, f_p1, f_p2)[source]#

produce a cdf for a binary exponential piston flow model

Parameters:

t – time steps to calculate cdf for (yrs)
mrt_p1 – mean residence time of the first piston flow model (yrs)
mrt_p2 – mean residence time of the second piston flow model (yrs)
frac_p1 – fraction of the total source that is in the first piston flow model
f_p1 – fraction of the first piston flow model that is in the fast flow component
f_p2 – fraction of the second piston flow model that is in the fast flow component

Returns:

cdf of the binary exponential piston flow model

check_age_inputs(mrt, mrt_p1, mrt_p2, frac_p1, precision, f_p1, f_p2)[source]#

convenience function to check BEPM age inputs

Parameters:

mrt – mean residence time of the source (yrs) either mrt or mrt_p2 can be None
mrt_p1 – mean residence time of the first piston flow component (yrs)
mrt_p2 – mean residence time of the second piston flow component (yrs)
frac_p1 – fraction of the total source that is in the first piston flow component
precision – precision of the age distribution (decimal places)
f_p1 – fraction of the first piston flow component that is in the fast flow component
f_p2 – fraction of the second piston flow component that is in the fast flow component

Returns:

exponential_piston_flow(t, tm, f)[source]#

produce an exponential piston flow model pdf

Parameters:

t – time steps to calculate pdf for (yrs)
tm – mean residence time (yrs)
f – fraction of the total source that is in the fast flow component

Returns:

exponential_piston_flow_cdf(t, tm, f)[source]#

produce a cdf for an exponential piston flow model

Parameters:

t – time steps to calculate cdf for (yrs)
tm – mean residence time (yrs)
f – fraction of the total source that is in the fast flow component

Returns:

lightweight_predict_future(source, out_years, ages, age_fractions, precision)[source]#

a lightweight version of predict_future_conc_bepm that does not check inputs and does not interpolate the source concentration and does not check the parmeters… use at your own warning

Parameters:

source
out_years
ages
age_fractions
precision

Returns:

make_age_dist(mrt, mrt_p1, mrt_p2, frac_p1, precision, f_p1, f_p2, start=np.nan)[source]#

make an age distribution for the binary exponential piston flow model

Parameters:

mrt – mean residence time of the source (yrs) either mrt or mrt_p2 can be None
mrt_p1 – mean residence time of the first piston flow component (yrs)
mrt_p2 – mean residence time of the second piston flow component (yrs)
frac_p1 – fraction of the total source that is in the first piston flow component
precision – precision of the age distribution (decimal places)
f_p1 – fraction of the first piston flow component that is in the fast flow component
f_p2 – fraction of the second piston flow component that is in the fast flow component
start – start age for the age distribution (yrs) default is np.nan which will use the maximum of the mrt_p1*5 and mrt_p2*5

Returns:

a tuple

age_step: the step size of the age distribution (yrs)
ages: the ages of the age distribution (yrs)
age_fractions: the fractions of the age distribution (decimal)

predict_future_conc_bepm(once_and_future_source_conc: pandas.Series, predict_start, predict_stop, mrt_p1, frac_p1, f_p1, f_p2, mrt=None, mrt_p2=None, fill_value=1, fill_threshold=0.05, precision=2, pred_step=0.01)[source]#

predict the receptor concentration based on the source concentration time series and the binary piston flow model parameters

Parameters:

once_and_future_source_conc – pd.Series of the source concentration index by age in decimal years the Series can have missing values and will be interpolated onto a 0.01 yr regular index therefore the once_and_future_source_conc may be passed with values only at the start, stop, and inflection points
predict_start – start of the prediction period (decimal years)
predict_stop – end of the prediction period (decimal years)
mrt_p1 – mean residence time of the first piston (yrs)
frac_p1 – fraction of the source that is in the first piston
f_p1 – fraction of exponential flow the first piston
f_p2 – fraction of exponential flow the second piston
mrt – mean residence time of the source (yrs) or None one of mrt or mrt_p2 must be passed
mrt_p2 – mean residence time of the second piston (yrs) or None one of mrt or mrt_p2 must be passed
fill_value – value to prepend to the source concentration to meet the full age distribution needed (e.g. the concentration of very old water), up to the fill_threshold may be filled with the fill_value before an error is raised
fill_threshold – threshold for the source concentration to be filled with the minimum value default is 0.05 (5% of the concentration at the start time)
precision – precision of the age distribution (decimal places)
pred_step – step size for the prediction (yrs) default is 0.01 (approximately monthly), but this can result in longer run times for large prediction periods, so a larger step size can be used. Note that pred_step must be greater or equal to the precision used

Returns:

receptor_conc a pandas series of the receptor concentration indexed by age in years

predict_historical_source_conc(init_conc, mrt, mrt_p1, mrt_p2, frac_p1, f_p1, f_p2, prev_slope, max_conc, min_conc, start_age=np.nan, precision=2, p0=None)[source]#

Estimate the historical source concentration based on the receptor initial concentration the previous slope and the BEPEM model parameters

Parameters:

init_conc – the receptor initial concentration
mrt – mean residence time of the source (yrs)
mrt_p1 – mean residence time of the first piston (yrs)
mrt_p2 – mean residence time of the second piston (yrs)
frac_p1 – fraction of the source that is in the first piston
f_p1 – fraction of exponential flow the first piston
f_p2 – fraction of exponential flow the second piston (use a dummy value if frac_p1 = 1)
prev_slope – slope of the previous trend (conc/yr)
max_conc – maximum concentration of the source (to limit optimisation)
min_conc – minimum concentration of the source (to limit optimisation)
start_age – set a start age for the source concentration (yrs) default is np.nan which will use the maximum of the mrt_p1 and mrt_p2
precision – precision of the age distribution (decimal places) default is 2, approximately monthly
p0 – initial guess for the optimisation (slope, intercept) default is None which will use the previous slope and the initial concentration

Returns:

source_conc_past a pandas series of the source concentration indexed by age in years

predict_source_future_past_conc_bepm(initial_conc, mrt, mrt_p1, frac_p1, f_p1, f_p2, prev_slope, fut_slope, age_range, max_conc, min_conc, max_fut_conc=np.inf, min_fut_conc=0, precision=2)[source]#

predict the source and receptor concentration in the future and past based on the current concentration the historical observed slope and the future predicted/scenario slope

Parameters:

initial_conc – initial concentration (at time = 0 yrs)
mrt – mean residence time of the source (yrs)
mrt_p1 – mean residence time of the first piston (yrs)
frac_p1 – fraction of the source that is in the first piston
f_p1 – fraction of exponential flow the first piston
f_p2 – fraction of exponential flow the second piston
prev_slope – slope of the previous trend (conc/yr)
fut_slope – slope of the future trend (conc/yr)
age_range – range of ages to predict the source concentration for (yrs) (start, stop) where start is negative and stop is positive years from the present time = 0 yrs is the present
max_conc – maximum concentration of the source (to limit optimisation)
min_conc – minimum concentration of the source (to limit optimisation)
max_fut_conc – maximum concentration of the source in the future (to limit the future slope creating crazy numbers)
min_fut_conc – minimum concentration of the source in the future (to limit the slope creating negative numbers)
precision – precision of the age distribution times (decimal places) default is 2, approximately monthly

Returns:

(source_conc, receptor_conc) where source_conc is a pandas series of the source concentration and receptor_conc is a pandas series of the receptor concentration both indexed by age in years relative to the initial concentration at time = 0 yrs (- for past, + for future)