facloc 0.1.0__py3-none-any.whl

facloc/__init__.py

@@ -0,0 +1,36 @@
+"""facloc - facility location-allocation models for public-service planning.
+
+p-median, p-center, maximal covering (MCLP), location set covering (LSCP) and the
+capacitated p-median, solved by numpy heuristics (greedy + Teitz-Bart vertex
+substitution, greedy + swap, greedy set cover), by exhaustive enumeration for small
+instances, or exactly as integer programmes through the optional PuLP/HiGHS extra.
+"""
+
+from ._version import __version__
+from .distance import distance_matrix, euclidean_matrix, haversine_matrix, manhattan_matrix
+from .errors import FaclocError, InfeasibleError, SolverUnavailableError
+from .exact import solver_available
+from .models import capacitated_p_median, lscp, mclp, p_center, p_median, pmedian_lower_bound
+from .problem import Problem
+from .solution import Solution, evaluate
+
+__all__ = [
+    "FaclocError",
+    "InfeasibleError",
+    "Problem",
+    "Solution",
+    "SolverUnavailableError",
+    "__version__",
+    "capacitated_p_median",
+    "distance_matrix",
+    "euclidean_matrix",
+    "evaluate",
+    "haversine_matrix",
+    "lscp",
+    "manhattan_matrix",
+    "mclp",
+    "p_center",
+    "p_median",
+    "pmedian_lower_bound",
+    "solver_available",
+]

facloc/__main__.py

@@ -0,0 +1,7 @@
+"""``python -m facloc``."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

facloc/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

facloc/brute.py

@@ -0,0 +1,111 @@
+"""Exhaustive enumeration for small instances (a reference optimum, mainly for testing).
+
+The p-facility models enumerate all ``C(m_free, p - n_fixed)`` site combinations; the
+LSCP enumerates combinations by increasing size; the capacitated p-median additionally
+enumerates every single-source assignment. ``max_evaluations`` guards against
+accidentally launching an astronomically long run.
+"""
+
+from __future__ import annotations
+
+import itertools
+import math
+from typing import List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from .heuristics import KeyFn, better
+
+__all__ = ["brute_capacitated", "brute_lscp", "brute_nearest"]
+
+DEFAULT_MAX_EVALUATIONS = 2_000_000
+
+
+def _guard(count: int, limit: int) -> None:
+    if count > limit:
+        raise ValueError(
+            f"brute force would evaluate {count:,} configurations (limit {limit:,}); "
+            "use a heuristic or the exact solver"
+        )
+
+
+def brute_nearest(
+    d: np.ndarray,
+    keys: KeyFn,
+    fixed: Sequence[int],
+    free: Sequence[int],
+    p: int,
+    max_evaluations: int = DEFAULT_MAX_EVALUATIONS,
+) -> Tuple[List[int], Tuple[float, float]]:
+    """Best site set for an objective that depends only on nearest-site distances."""
+    k = p - len(fixed)
+    free_l = [int(j) for j in free]
+    _guard(math.comb(len(free_l), k), max_evaluations)
+    base = np.asarray(d[:, list(fixed)].min(axis=1)) if fixed else np.full(d.shape[0], np.inf)
+    best: Optional[Tuple[List[int], Tuple[float, float]]] = None
+    for combo in itertools.combinations(free_l, k):
+        m = np.minimum(base, d[:, list(combo)].min(axis=1)) if combo else base
+        k1, k2 = keys(m[:, None])
+        key = (float(k1[0]), float(k2[0]))
+        if best is None or better(key, best[1]):
+            best = (list(fixed) + list(combo), key)
+    assert best is not None
+    return best
+
+
+def brute_lscp(
+    cover: np.ndarray,
+    fixed: Sequence[int],
+    free: Sequence[int],
+    max_evaluations: int = DEFAULT_MAX_EVALUATIONS,
+) -> List[int]:
+    """Smallest set of new sites that, with ``fixed``, covers every demand point."""
+    n = cover.shape[0]
+    fixed_cov = cover[:, list(fixed)].any(axis=1) if fixed else np.zeros(n, dtype=bool)
+    free_l = [int(j) for j in free]
+    evaluated = 0
+    for k in range(len(free_l) + 1):
+        evaluated += math.comb(len(free_l), k)
+        _guard(evaluated, max_evaluations)
+        for combo in itertools.combinations(free_l, k):
+            cov = fixed_cov | cover[:, list(combo)].any(axis=1) if combo else fixed_cov
+            if cov.all():
+                return list(combo)
+    raise ValueError("no set of sites covers every demand point")
+
+
+def brute_capacitated(
+    cost: np.ndarray,
+    w: np.ndarray,
+    cap: np.ndarray,
+    fixed: Sequence[int],
+    free: Sequence[int],
+    p: int,
+    max_evaluations: int = DEFAULT_MAX_EVALUATIONS,
+) -> Tuple[List[int], np.ndarray, float]:
+    """Exact capacitated p-median (single source) by full enumeration.
+
+    Returns ``(sites, allocation, cost)``; raises ``ValueError`` if infeasible.
+    """
+    n = cost.shape[0]
+    k = p - len(fixed)
+    free_l = [int(j) for j in free]
+    _guard(math.comb(len(free_l), k) * p**n, max_evaluations)
+    eps = 1e-9 * max(1.0, float(w.sum()))
+    best: Optional[Tuple[List[int], np.ndarray, float]] = None
+    for combo in itertools.combinations(free_l, k):
+        cols = list(fixed) + list(combo)
+        for assign in itertools.product(range(len(cols)), repeat=n):
+            a = np.asarray(assign)
+            load = np.bincount(a, weights=w, minlength=len(cols))
+            if np.any(load > cap[cols] + eps):
+                continue
+            alloc = np.asarray(cols)[a]
+            total = float(cost[np.arange(n), alloc].sum())
+            if not np.isfinite(total):
+                continue
+            if best is None or total < best[2] - 1e-9 * max(1.0, abs(best[2])):
+                best = (cols, alloc, total)
+    if best is None:
+        raise ValueError("capacitated problem is infeasible")
+    return best

facloc/cli.py

@@ -0,0 +1,221 @@
+"""Command-line interface: ``facloc solve`` and ``facloc evaluate``."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import List, Optional, Sequence
+
+from . import models
+from ._version import __version__
+from .errors import FaclocError
+from .io import (
+    PointTable,
+    read_matrix_csv,
+    read_points_csv,
+    reorder_matrix,
+    write_allocations_csv,
+    write_json,
+)
+from .problem import Problem
+from .solution import Solution, evaluate
+
+MODELS = ("p-median", "p-center", "mclp", "lscp", "capacitated")
+
+
+def _add_input_args(sp: argparse.ArgumentParser) -> None:
+    g = sp.add_argument_group("input")
+    g.add_argument("--demand", help="demand points CSV (id,x,y,weight)")
+    g.add_argument("--sites", help="candidate sites CSV (id,x,y[,capacity][,existing])")
+    g.add_argument("--matrix", help="distance matrix CSV (rows demand ids, columns site ids)")
+    g.add_argument(
+        "--metric",
+        default="euclidean",
+        choices=("euclidean", "haversine", "manhattan"),
+        help="distance from coordinates when no --matrix (haversine: lon/lat in, metres out)",
+    )
+    g.add_argument("--existing", default="", help="comma-separated ids of existing sites")
+    g.add_argument("--id-col", default="id")
+    g.add_argument("--x-col", default="x")
+    g.add_argument("--y-col", default="y")
+    g.add_argument("--weight-col", default="weight")
+    g.add_argument("--capacity-col", default="capacity")
+    g.add_argument("--existing-col", default="existing")
+
+
+def _add_output_args(sp: argparse.ArgumentParser) -> None:
+    g = sp.add_argument_group("output")
+    g.add_argument("--json", dest="json_out", help="write the full solution as JSON")
+    g.add_argument("--geojson", help="write spider lines + points as GeoJSON")
+    g.add_argument("--allocations", help="write demand -> site allocations as CSV")
+    g.add_argument("-q", "--quiet", action="store_true", help="do not print the summary")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(
+        prog="facloc",
+        description="Facility location-allocation: p-median, p-center, MCLP, LSCP, "
+        "capacitated p-median.",
+    )
+    ap.add_argument("--version", action="version", version=f"facloc {__version__}")
+    sub = ap.add_subparsers(dest="command", required=True)
+
+    sp = sub.add_parser("solve", help="solve a location model")
+    sp.add_argument("model", choices=MODELS)
+    sp.add_argument("-p", type=int, help="number of facilities in total (existing included)")
+    sp.add_argument("--radius", type=float, help="coverage standard (MCLP, LSCP; reporting)")
+    sp.add_argument("--method", default="heuristic", choices=models.METHODS)
+    sp.add_argument("--weighted", action="store_true", help="p-center: minimise max w*d")
+    sp.add_argument("--bound", action="store_true", help="p-median: Lagrangian lower bound")
+    sp.add_argument("--restarts", type=int, default=10, help="extra random starts (heuristic)")
+    sp.add_argument("--seed", type=int, default=0, help="random seed for restarts")
+    sp.add_argument("--solver", default="auto", choices=("auto", "highs", "cbc"))
+    sp.add_argument("--time-limit", type=float, help="exact solver time limit in seconds")
+    _add_input_args(sp)
+    _add_output_args(sp)
+
+    ev = sub.add_parser("evaluate", help="measure a given set of open sites")
+    ev.add_argument("--open", required=True, help="comma-separated ids of open sites")
+    ev.add_argument("--radius", type=float, help="coverage standard for reporting")
+    _add_input_args(ev)
+    _add_output_args(ev)
+    return ap
+
+
+def _read(args: argparse.Namespace, path: str) -> PointTable:
+    return read_points_csv(
+        path,
+        id_col=args.id_col,
+        x_col=args.x_col,
+        y_col=args.y_col,
+        weight_col=args.weight_col,
+        capacity_col=args.capacity_col,
+        existing_col=args.existing_col,
+    )
+
+
+def problem_from_args(args: argparse.Namespace) -> Problem:
+    """Build a :class:`Problem` from parsed CLI arguments."""
+    if not args.demand and not args.matrix:
+        raise ValueError("give --demand (with coordinates) and/or --matrix")
+    dem = _read(args, args.demand) if args.demand else None
+    sit = _read(args, args.sites) if args.sites else None
+    if args.matrix:
+        m_rows, m_cols, mat = read_matrix_csv(args.matrix)
+        d_ids = dem.ids if dem else m_rows
+        s_ids = sit.ids if sit else (dem.ids if dem and m_cols == m_rows else m_cols)
+        dist = reorder_matrix(mat, m_rows, m_cols, d_ids, s_ids)
+    else:
+        if dem is None or dem.xy is None:
+            raise ValueError("--demand needs x/y columns when no --matrix is given")
+        if sit is not None and sit.xy is None:
+            raise ValueError("--sites needs x/y columns when no --matrix is given")
+        d_ids = dem.ids
+        s_ids = sit.ids if sit else dem.ids
+        dist = None
+    site_tab = sit if sit is not None else dem
+    fixed: List[int] = list(sit.existing) if sit is not None else []
+    for tok in (t.strip() for t in args.existing.split(",")):
+        if tok:
+            if tok not in s_ids:
+                raise ValueError(f"--existing: unknown site id {tok!r}")
+            fixed.append(s_ids.index(tok))
+    caps = site_tab.capacities if site_tab is not None and len(site_tab.ids) == len(s_ids) else None
+    weights = dem.weights if dem else None
+    dxy = dem.xy if dem else None
+    sxy = site_tab.xy if site_tab is not None else None
+    if dist is None:
+        assert dem is not None and dem.xy is not None
+        pr = Problem.from_points(
+            dem.xy,
+            None if sit is None else sit.xy,
+            metric=args.metric,
+            weights=weights,
+            fixed=fixed,
+            capacities=caps,
+            demand_ids=d_ids,
+            site_ids=s_ids,
+        )
+        return pr
+    return Problem(
+        dist,
+        weights=weights,
+        fixed=fixed,
+        capacities=caps,
+        demand_ids=d_ids,
+        site_ids=s_ids,
+        demand_xy=dxy if dxy is not None and len(dxy) == len(d_ids) else None,
+        site_xy=sxy if sxy is not None and len(sxy) == len(s_ids) else None,
+        lonlat=args.metric == "haversine",
+    )
+
+
+def _solve(args: argparse.Namespace, pr: Problem) -> Solution:
+    m = args.model
+    if m in ("p-median", "p-center", "mclp", "capacitated") and args.p is None:
+        raise ValueError(f"{m} needs -p")
+    if m in ("mclp", "lscp") and args.radius is None:
+        raise ValueError(f"{m} needs --radius")
+    common = {"method": args.method, "solver": args.solver, "time_limit": args.time_limit}
+    if m == "p-median":
+        return models.p_median(
+            pr,
+            args.p,
+            radius=args.radius,
+            bound=args.bound,
+            restarts=args.restarts,
+            seed=args.seed,
+            **common,
+        )
+    if m == "p-center":
+        return models.p_center(
+            pr,
+            args.p,
+            weighted=args.weighted,
+            radius=args.radius,
+            restarts=args.restarts,
+            seed=args.seed,
+            **common,
+        )
+    if m == "mclp":
+        return models.mclp(
+            pr, args.p, args.radius, restarts=args.restarts, seed=args.seed, **common
+        )
+    if m == "lscp":
+        return models.lscp(pr, args.radius, **common)
+    return models.capacitated_p_median(
+        pr, args.p, radius=args.radius, restarts=args.restarts, seed=args.seed, **common
+    )
+
+
+def _write_outputs(args: argparse.Namespace, sol: Solution) -> None:
+    if args.json_out:
+        write_json(sol.to_dict(), args.json_out)
+    if args.geojson:
+        write_json(sol.to_geojson(), args.geojson)
+    if args.allocations:
+        write_allocations_csv(sol.to_dict(), args.allocations)
+    if not args.quiet:
+        print(sol.summary())
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point; returns the process exit code."""
+    ap = build_parser()
+    args = ap.parse_args(argv)
+    try:
+        pr = problem_from_args(args)
+        if args.command == "solve":
+            sol = _solve(args, pr)
+        else:
+            ids = [t.strip() for t in args.open.split(",") if t.strip()]
+            sol = evaluate(pr, ids, radius=args.radius)
+        _write_outputs(args, sol)
+    except (FaclocError, ValueError, KeyError, OSError) as exc:
+        print(f"facloc: error: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

facloc/distance.py

@@ -0,0 +1,116 @@
+"""Distance matrices between demand points and candidate sites.
+
+Two metrics are built in:
+
+* ``"euclidean"`` - straight-line distance in the units of the input coordinates. Use it with
+  projected coordinates (metres in a UTM zone or a national grid), never with raw degrees.
+* ``"haversine"`` - great-circle distance on a sphere, for longitude/latitude in degrees.
+  The result is in metres. The default radius is the IUGG mean Earth radius
+  R1 = 6 371 008.8 m (Moritz, H. 2000, "Geodetic Reference System 1980",
+  *Journal of Geodesy* 74(1), 128-133). The spherical model errs by up to about 0.5 %
+  against the ellipsoid, which is far below the error of using straight lines instead of
+  travel distances in the first place.
+
+* ``"manhattan"`` - rectilinear (L1) distance in input units, a rough proxy for travel on a
+  grid street network.
+
+For real service planning a network (road or walking) distance matrix is usually better;
+compute it elsewhere (OSRM, pgRouting, a GIS) and pass it to :class:`facloc.Problem` directly.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import numpy as np
+
+__all__ = [
+    "EARTH_RADIUS_M",
+    "METRICS",
+    "distance_matrix",
+    "euclidean_matrix",
+    "haversine_matrix",
+    "manhattan_matrix",
+]
+
+#: IUGG mean Earth radius R1 in metres (Moritz 2000).
+EARTH_RADIUS_M = 6_371_008.8
+
+METRICS = ("euclidean", "haversine", "manhattan")
+
+
+def _as_xy(points: object, name: str) -> np.ndarray:
+    arr = np.asarray(points, dtype=float)
+    if arr.ndim != 2 or arr.shape[1] != 2:
+        raise ValueError(f"{name} must be an (n, 2) array of x/y (or lon/lat) pairs")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError(f"{name} contains NaN or infinite coordinates")
+    return arr
+
+
+def euclidean_matrix(origins: object, destinations: object) -> np.ndarray:
+    """Straight-line distances, shape ``(len(origins), len(destinations))``."""
+    a = _as_xy(origins, "origins")
+    b = _as_xy(destinations, "destinations")
+    diff = a[:, None, :] - b[None, :, :]
+    return np.asarray(np.sqrt((diff**2).sum(axis=2)))
+
+
+def manhattan_matrix(origins: object, destinations: object) -> np.ndarray:
+    """Rectilinear (L1) distances, shape ``(len(origins), len(destinations))``."""
+    a = _as_xy(origins, "origins")
+    b = _as_xy(destinations, "destinations")
+    return np.asarray(np.abs(a[:, None, :] - b[None, :, :]).sum(axis=2))
+
+
+def haversine_matrix(
+    origins: object, destinations: object, radius: float = EARTH_RADIUS_M
+) -> np.ndarray:
+    """Great-circle distances in metres between lon/lat points given in degrees.
+
+    Uses the haversine formula
+    ``d = 2 R asin(sqrt(sin^2(dphi/2) + cos phi1 cos phi2 sin^2(dlambda/2)))``.
+    """
+    a = _as_xy(origins, "origins")
+    b = _as_xy(destinations, "destinations")
+    for arr, name in ((a, "origins"), (b, "destinations")):
+        if np.any(np.abs(arr[:, 1]) > 90.0) or np.any(np.abs(arr[:, 0]) > 360.0):
+            raise ValueError(
+                f"{name} are not lon/lat degrees (|lat| must be <= 90); "
+                "pass coordinates as (lon, lat) or use metric='euclidean' for projected data"
+            )
+    lon1 = np.radians(a[:, 0])[:, None]
+    lat1 = np.radians(a[:, 1])[:, None]
+    lon2 = np.radians(b[:, 0])[None, :]
+    lat2 = np.radians(b[:, 1])[None, :]
+    h = (
+        np.sin((lat2 - lat1) / 2.0) ** 2
+        + np.cos(lat1) * np.cos(lat2) * np.sin((lon2 - lon1) / 2.0) ** 2
+    )
+    return np.asarray(2.0 * radius * np.arcsin(np.sqrt(np.clip(h, 0.0, 1.0))))
+
+
+def distance_matrix(
+    origins: object,
+    destinations: Optional[object] = None,
+    metric: str = "euclidean",
+) -> np.ndarray:
+    """Distance matrix from ``origins`` (rows) to ``destinations`` (columns).
+
+    Parameters
+    ----------
+    origins, destinations:
+        ``(n, 2)`` coordinate arrays. For ``metric="haversine"`` the columns are
+        longitude, latitude in degrees. ``destinations`` defaults to ``origins``.
+    metric:
+        ``"euclidean"``, ``"haversine"`` or ``"manhattan"``.
+    """
+    if destinations is None:
+        destinations = origins
+    if metric == "euclidean":
+        return euclidean_matrix(origins, destinations)
+    if metric == "haversine":
+        return haversine_matrix(origins, destinations)
+    if metric == "manhattan":
+        return manhattan_matrix(origins, destinations)
+    raise ValueError(f"unknown metric {metric!r}; choose one of {', '.join(METRICS)}")

facloc/errors.py

@@ -0,0 +1,17 @@
+"""Exceptions raised by facloc."""
+
+from __future__ import annotations
+
+__all__ = ["FaclocError", "InfeasibleError", "SolverUnavailableError"]
+
+
+class FaclocError(Exception):
+    """Base class for facloc errors."""
+
+
+class InfeasibleError(FaclocError, ValueError):
+    """The instance has no feasible solution (e.g. demand that no site can reach or cover)."""
+
+
+class SolverUnavailableError(FaclocError, ImportError):
+    """The optional exact solver (PuLP / HiGHS) is not installed."""