evaluate_single_solution_single_objective

site.SiteProblem.evaluate_single_solution_single_objective(
    objective='p_median',
    weights=None,
    site_names=None,
    site_indices=None,
    capacitated=False,
    threshold_for_coverage=None,
    baseline_costs=None,
    meaningful_change_threshold=0.0,
    beyond_thresholds=None,
    unreachable_cost=None,
)

Evaluate a specific set of facility sites against a single objective.

This method calculates the performance of a given facility configuration (a ‘solution’). It determines which demand points are assigned to which sites based on minimum travel cost and calculates coverage metrics if a threshold is provided.

Parameters

Name Type Description Default
objective str The name of the objective function to evaluate. Must be a value defined in SUPPORTED_OBJECTIVES. "p_median"
site_names list of str A list of site identifiers (column names in the travel matrix) representing the chosen solution. None
site_indices list of int A list of integer positions (column indices) representing the chosen solution. None
capacitated bool Whether to consider site capacity constraints. Currently, only False is supported. False
threshold_for_coverage float or int A distance or time value. Demand points with a minimum travel cost lower than this value are flagged as ‘covered’. The resulting proportion_within_coverage_threshold metric is weighted by the demand registered via add_demand(); the unweighted share of regions is reported alongside it as proportion_regions_within_coverage_threshold. None
baseline_costs dict[str, pandas.Series] Internal/advanced: forwarded to EvaluatedCombination to compute population-impact-vs-baseline metrics. Most callers should use evaluate_baseline() and SolutionComparator.population_impact_summary(), or solve(baseline=...), rather than passing this directly. None
meaningful_change_threshold float Only used when baseline_costs is given – see lokigi.utils._population_impact_metrics. 0.0
beyond_thresholds float or sequence of float One or more “left behind” travel-cost thresholds – forwarded to EvaluatedCombination, see its beyond_thresholds parameter for the resulting demand_beyond_threshold_<t> / regions_beyond_threshold_<t> columns. Deliberately distinct from threshold_for_coverage: “covered” (good) and “beyond” (bad) cross the threshold in opposite directions, and this parameter accepts more than one value at once. None
unreachable_cost float Forwarded to EvaluatedCombination – see its parameter of the same name. Produces weighted_average_for_ranking/ unweighted_average_for_ranking/max_for_ranking on the returned combination, identical to their honest counterparts unless this is set. Most callers should use solve( unreachable_cost=...) rather than passing this directly; passing it here alone has no effect beyond that combination’s own reported numbers, since a direct call doesn’t rank/prune against other combinations at all. None

Returns

Name Type Description
EvaluatedCombination A results container containing the objective type, resolved site indices/names, and a detailed DataFrame of the demand assignments.

Raises

Name Type Description
ValueError If an unsupported objective is passed, or if neither (or both) site_names and site_indices are provided.
KeyError If provided site_names do not exist in the travel matrix columns.
IndexError If provided site_indices are out of the bounds of the travel matrix.
NotImplementedError If capacitated=True is requested.

Warnings

A UserWarning is emitted if an equity band has no reachable region under the primary or any secondary travel matrix. That band is excluded from the disparity metrics (gap_*_weighted, inter_tertile_ratio, the tertile averages), which then describe the remaining bands.

Notes

The method assumes an uncapacitated assignment logic where every demand point is assigned to its nearest (lowest cost) active facility.

If self.travel_and_demand_df has not been generated via a merge yet, this method calls _create_joined_demand_travel_df automatically.

See Also

EvaluatedCombination : The class used to wrap the output of this method.

Back to top