tracts.driver_utils.check_optimal_params_near_bounds#

check_optimal_params_near_bounds(demographic_model, optimal_params, tol)#

Checks whether any of the final optimal parameters is close to a user-narrowed admissible bound (see bounds/parse_param_bounds), which may indicate that the true optimum lies outside the range the user specified. If so, prints/logs a message recommending a re-run starting from these optimal values (see start_params) with the admissible range widened for the affected parameter(s) (see bounds).

Only bounds that the user explicitly narrowed below their default (type-determined) value are checked, and only on the narrowed side: a parameter sitting at its natural type boundary (e.g. a sex-bias parameter landing at +-1, or a time parameter at its default lower bound) is not flagged, since that boundary was not something the user restricted. (A sex-bias parameter at a +-1 boundary is instead handled by the boundary re-optimization, see check_optimal_sex_bias_parameters_at_boundaries.) Closeness is relative to the parameter’s (narrowed) admissible range (upper - lower), not absolute, since parameters can differ by orders of magnitude in scale.

Parameters:

  • demographic_model (ParametrizedDemography | ParametrizedDemographySexBiased) – The demographic model whose parameters’ bounds are checked against.

  • optimal_params (ndarray) – The final optimal parameters in physical units, as returned by the optimization process, in the order given by demographic_model.model_base_params.

  • tol (float) – Relative tolerance, as a fraction of a parameter’s admissible range, within which a value counts as “close” to a bound. See OptimizationConfig.bounds_proximity_tol.

Returns:

The names of the parameters found close to a user-narrowed bound (possibly empty).

Return type:

list[str]