tracts.driver_utils.parse_start_params#

parse_start_params(start_param_bounds, model, repetitions=1, seed=None, sample_param_names=None, fixed_param_values=None)#

Produces starting parameters for optimization in physical units. Only produces starting parameters that are compatible with well-defined migration matrices.

Parameters:

  • start_param_bounds – An object containing attributes corresponding to each parameter in model.model_base_parameters, where the value of each attribute is either a single number (if the starting value for that parameter should be fixed) or a string of the form “min:max” specifying the range from which to sample starting values for that parameter. The parameters specified in start_param_bounds must match those in model.model_base_parameters, and an error will be raised if any parameters are missing or if any extra parameters are included.

  • model (ParametrizedDemography) – The demographic model for which to produce starting parameters.

  • repetitions (int) – The number of sets of starting parameters to produce. Defaults to 1.

  • seed (float | None) – The random seed to use for sampling starting parameters. Defaults to None.

  • sample_param_names (set[str] | None) – Optional subset of parameter names to sample from start_param_bounds. If provided, all other non-ancestry-fixed parameters must be supplied in fixed_param_values.

  • fixed_param_values (dict[str, float] | None) – Optional parameter values to hold fixed while sampling the remaining parameters.

Returns:

list[np.ndarray]

Return type:

A list of arrays of starting parameters in physical units, where each array corresponds to a set of starting parameters for one repetition of the optimization. The parameters are ordered according to their order in model.model_base_parameters.

Notes

Starting-parameter specifications are parsed once per parameter and stored as either ("fixed", value) or ("range", (min, max)). For each candidate vector, independent Uniform(0,1) draws are generated and then transformed per parameter: fixed parameters are assigned directly, while ranged parameters are mapped to Uniform(min, max) via an affine transform. Parameters fixed by ancestry are not sampled from user input and are initialized from the configured ancestry-fixed behavior.

Feasibility is checked by evaluating model.get_violation_score(candidate). Candidates are accepted only when the returned score is non-negative. Any ValueError raised during validation is treated as infeasible, and candidate generation continues until the requested number of feasible starts is collected or the attempt limit is reached.