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)