site_utilisation_summary

site.SiteProblem.site_utilisation_summary(site_names=None, site_indices=None)

Summarise each candidate site’s real-world current utilisation.

This is a baseline diagnostic, not a solve() output: it reports today’s actual load against capacity, exactly as registered via add_sites(current_load_col=..., capacity_col=...) or add_sites(utilisation_col=...). It works with or without ever calling solve(), and has no SiteSolutionSet counterpart – there is nothing “solved” to select from.

Parameters

Name	Type	Description	Default
site_names	list of str	Restrict the summary to these site names (as they appear in candidate_id_col). Mutually exclusive with site_indices. If neither is given, every registered candidate site is included.	None
site_indices	list of int	Restrict the summary to these canonical_site_index values. Mutually exclusive with site_names.	None

Returns

Name	Type	Description
	pandas.DataFrame	Indexed by site name (index.name == "site"), in canonical_site_index order (or site_names’ given order, if supplied). Columns are included conditionally, depending on which of capacity_col/current_load_col/utilisation_col were registered via add_sites(): - capacity – present iff capacity_col was registered. - current_load – present iff current_load_col was registered (the raw-counts input path only). - utilisation_ratio – always present. Either current_load / capacity (raw-counts path), or utilisation_col’s values as-is (precomputed-ratio path). - headroom – present iff derivable: capacity - current_load (raw-counts path), or capacity * (1 - utilisation_ratio) (precomputed-ratio path, only when capacity_col was also registered). Omitted otherwise.

Raises

Name	Type	Description
	ValueError	If neither current_load_col+capacity_col nor utilisation_col was registered via add_sites(), or if both site_names and site_indices are given.
	IndexError	If site_indices contains a value not in candidate_sites.
	KeyError	If site_names contains a name not in candidate_sites.

Notes

Every requested site appears as an explicit row, but a site with no registered baseline data (typically: not yet built) gets NaN in utilisation_ratio/headroom, not 0.0 – an important distinction to preserve, since 0.0 would instead mean “measured, and currently idle”, an alarming finding for an operating site. Values above 1.0 (genuinely over capacity) are left as-is, not clipped – a negative headroom is itself the finding. This method does not sort its result; use e.g. .sort_values("utilisation_ratio", ascending=False) to rank sites by fullness.