#!/usr/bin/env python
# coding: utf-8

# # The Location Set Covering Problem (LSCP)
# 
# *Authors:* [Germano Barcelos](https://github.com/gegen07), [James Gaboardi](https://github.com/jGaboardi), [Levi J. Wolf](https://github.com/ljwolf), [Qunshan Zhao](https://github.com/qszhao)
# 
# The Location Set Covering Problem is described by Toregas et al. (1971). There they show that emergency services must be placed according to a response time, since there is a allowable maximum service time for handling emergency activities. Therefore the LSCP model was proprosed whereby _the minimum number of facilities determined and locaten so that every demand area is covered within a predefined maximal service distance or time (Church and Murray, 2018)._ 
# 
# **LSCP can be written as:**
# 
# $\begin{array}
# \displaystyle \textbf{Minimize} & \displaystyle \sum_{j \in J}{Y_j} && (1) \\
# \displaystyle \textbf{Subject to:} & \displaystyle \sum_{j \in N_i}{Y_j} \geq 1 & \forall i \in I & (2) \\
#             & Y_j \in {0,1} & \forall j \in J & (3)
# \\ \end{array}$
#             
# $\begin{array}
# \displaystyle \textbf{Where:}\\ & & \displaystyle i & \small = & \textrm{index of demand points/areas/objects in set } I \\
# & & j & \small = & \textrm{index of potential facility sites in set } J \\
# & & S & \small = & \textrm{maximal acceptable service distance or time standard} \\
# & & d_{ij} & \small = & \textrm{shortest distance or travel time between nodes } i \textrm{ and } j \\
# & & N_i & \small = & \{j | d_{ij} < S\} \\
# & & Y_j & \small = & \begin{cases} 
#           1, \text{if a facility is located at node } j\\
#           0, \text{otherwise} \\
#        \end{cases}
# \end{array}$
#        
# _The formulation above is adapted from Church and Murray (2018)._
# 
# This tutorial generates synthetic demand (clients) and facility sites near a 10x10 lattice representing a gridded urban core. Three LSCP instances are solved while varying parameters:
# 
# * `LSCP.from_cost_matrix()` with network distance as the metric
# * `LSCP.from_geodataframe()` with euclidean distance as the metric
# * `LSCP.from_geodataframe()` with predefined facility locations and euclidean distance as the metric

# In[1]:


get_ipython().run_line_magic('config', 'InlineBackend.figure_format = "retina"')
get_ipython().run_line_magic('load_ext', 'watermark')
get_ipython().run_line_magic('watermark', '')


# In[2]:


import geopandas
import matplotlib.pyplot as plt
from matplotlib.patches import Patch
import matplotlib.lines as mlines
import numpy
import pulp
import shapely
import spopt
from spopt.locate import LSCP, simulated_geo_points

import warnings
with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    # ignore deprecation warning - GH pysal/spaghetti#649
    import spaghetti

get_ipython().run_line_magic('watermark', '-w')
get_ipython().run_line_magic('watermark', '-iv')


# Since the model needs a cost matrix (distance, time, etc.) we should define some variables. First we will assign some the number of clients and facility locations, then the maximum service radius, followed by random seeds in order to reproduce the results. Finally, the solver, assigned below as `pulp.COIN_CMD`, is an interface to optimization solver developed by [COIN-OR](https://github.com/coin-or/Cbc). If you want to use another optimization interface, such as Gurobi or CPLEX, see this [guide](https://coin-or.github.io/pulp/guides/how_to_configure_solvers.html) that explains how to achieve this.

# In[3]:


# quantity demand points
CLIENT_COUNT = 100

# quantity supply points
FACILITY_COUNT = 10

# maximum service radius (in distance units)
SERVICE_RADIUS = 8

# random seeds for reproducibility
CLIENT_SEED = 5
FACILITY_SEED = 6

# set the solver
solver = pulp.COIN_CMD(msg=False, warmStart=True)


# ## Lattice 10x10
# 
# Create a 10x10 lattice with 9 interior lines, both vertical and horizontal.

# In[4]:


with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    # ignore deprecation warning - GH pysal/libpysal#468
    lattice = spaghetti.regular_lattice((0, 0, 10, 10), 9, exterior=True)
ntw = spaghetti.Network(in_data=lattice)


# Transform the `spaghetti` instance into a geodataframe.

# In[5]:


streets = spaghetti.element_as_gdf(ntw, arcs=True)


# In[6]:


streets_buffered = geopandas.GeoDataFrame(
    geopandas.GeoSeries(streets["geometry"].buffer(0.5).unary_union),
    crs=streets.crs,
    columns=["geometry"],
)


# Plotting the network created by `spaghetti` we can verify that it mimics a district with quarters and streets.

# In[7]:


streets.plot();


# ## Simulate points in a network
# 
# The `simulated_geo_points` function simulates points near a network. In this case, it uses the 10x10 lattice network created using the `spaghetti` package. Below we use the function defined above and simulate the points near the lattice edges.

# In[8]:


client_points = simulated_geo_points(
    streets_buffered, needed=CLIENT_COUNT, seed=CLIENT_SEED
)
facility_points = simulated_geo_points(
    streets_buffered, needed=FACILITY_COUNT, seed=FACILITY_SEED
)


# Plotting the 100 client and 10 facility points we can see that the function generates dummy points to an area of 10x10, which is the area created by our lattice created on previous cells.

# In[9]:


fig, ax = plt.subplots(figsize=(6, 6))
streets.plot(ax=ax, alpha=0.8, zorder=1, label="streets")
facility_points.plot(
    ax=ax, color="red", zorder=2, label=f"facility candidate sites ($n$={FACILITY_COUNT})"
)
client_points.plot(ax=ax, color="black", label=f"clients sites ($n$={CLIENT_COUNT})")
plt.legend(loc="upper left", bbox_to_anchor=(1.05, 1));


# ## Assign simulated points network locations
# 
# The simulated client and facility points do not adhere to network space. Calculating distances between them without restricting movement to the network results in a euclidean distances,'as the crow flies.' While this is acceptable for some applications, for others it is more realistic to consider network traversal (e.g. Does a mail carrier follow roads to deliver letters or fly from mailbox to mailbox?).
# 
# In our first example we will consider distance along the 10x10 lattice network created above. Therefore, we must first snap the observation points to the network prior to calculating a cost matrix.

# In[10]:


with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    # ignore deprecation warning - GH pysal/libpysal#468
    ntw.snapobservations(client_points, "clients", attribute=True)
clients_snapped = spaghetti.element_as_gdf(ntw, pp_name="clients", snapped=True)
clients_snapped.drop(columns=["id", "comp_label"], inplace=True)

with warnings.catch_warnings():
    warnings.simplefilter("ignore")
    # ignore deprecation warning - GH pysal/libpysal#468
    ntw.snapobservations(facility_points, "facilities", attribute=True)
facilities_snapped = spaghetti.element_as_gdf(ntw, pp_name="facilities", snapped=True)
facilities_snapped.drop(columns=["id", "comp_label"], inplace=True)


# Now the plot seems more organized as the points occupy network space. The network is plotted below with the network locations of the facility points and clients points.

# In[11]:


fig, ax = plt.subplots(figsize=(6, 6))
streets.plot(ax=ax, alpha=0.8, zorder=1, label="streets")
facilities_snapped.plot(
    ax=ax, color="red", zorder=2, label=f"facility candidate sites ($n$={FACILITY_COUNT})"
)
clients_snapped.plot(ax=ax, color="black", label=f"clients sites ($n$={CLIENT_COUNT})")
plt.legend(loc="upper left", bbox_to_anchor=(1.05, 1));


# ## Calculating the (network distance) cost matrix
# Calculate the network distance between clients and facilities.

# In[12]:


cost_matrix = ntw.allneighbordistances(
    sourcepattern=ntw.pointpatterns["clients"],
    destpattern=ntw.pointpatterns["facilities"],
)
cost_matrix.shape


# The expected result here is a network distance between clients and facilities points, in our case a 2D 100x10 array.

# In[13]:


cost_matrix[:5,:]


# In[14]:


cost_matrix[-5:,:]


# With ``LSCP.from_cost_matrix`` we model the LSCP to cover all demand points within `SERVICE_RADIUS` distance units using the network distance cost matrix calculated above.

# In[15]:


lscp_from_cm = LSCP.from_cost_matrix(
    cost_matrix, SERVICE_RADIUS, name="LSCP-network-distance"
)


# The expected result is a solved instance of `LSCP`.

# In[16]:


lscp_from_cm = lscp_from_cm.solve(solver)
lscp_from_cm


# Define the decision variable names used for mapping later.

# In[17]:


facility_points["dv"] = lscp_from_cm.fac_vars
facility_points["dv"] = facility_points["dv"].map(lambda x: x.name.replace("_", ""))
facilities_snapped["dv"] = facility_points["dv"]
facility_points


# ## Calculating euclidean distance from a `GeoDataFrame`
# 
# With ``LSCP.from_geodataframe`` we model the LSCP to cover all demand points within `SERVICE_RADIUS` distance units using geodataframes to calculate a euclidean distance cost matrix.
# 
# Next we will solve the LSCP considering all 10 candidate locations for potential selection.

# In[18]:


distance_metric = "euclidean"
lscp_from_gdf = LSCP.from_geodataframe(
    clients_snapped,
    facilities_snapped,
    "geometry",
    "geometry",
    SERVICE_RADIUS,
    distance_metric=distance_metric,
    name=f"lscp-{distance_metric}-distance"
)


# In[19]:


lscp_from_gdf = lscp_from_gdf.solve(solver)
lscp_from_gdf


# However, in many real world applications there may already be existing facility locations with the goal being to add one or more new facilities. Here we will define facilites $y_4$ and $y_9$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.
# 
# ***Important:*** The facilities in `"predefined_loc"` are a binary array where `1` means the associated location must appear in the solution.

# In[20]:


facility_points["predefined_loc"] = 0
facility_points.loc[(4, 9), "predefined_loc"] = 1
facilities_snapped["predefined_loc"] = facility_points["predefined_loc"]
facility_points


# In[21]:


lscp_from_gdf_pre = LSCP.from_geodataframe(
    clients_snapped,
    facilities_snapped,
    "geometry",
    "geometry",
    SERVICE_RADIUS,
    distance_metric=distance_metric,
    predefined_facility_col="predefined_loc",
    name=f"lscp-{distance_metric}-distance-predefined"
)


# In[22]:


lscp_from_gdf_pre = lscp_from_gdf_pre.solve(solver)
lscp_from_gdf_pre


# ## Plotting the results
# 
# The two cells below describe the plotting of the results. For each method from the `LSCP` class (`.from_cost_matrix()`, `.from_geodataframe()`) there is a plot displaying the facility site that was selected with a star colored and the points covered with the same color. Demand points covered by more than one facility are displayed in overlapping concentric circles.

# In[23]:


dv_colors_arr = [
    "darkcyan",
    "mediumseagreen",
    "saddlebrown",
    "darkslategray",
    "lightskyblue",
    "thistle",
    "lavender",
    "darkgoldenrod",
    "peachpuff",
    "coral",
    "mediumvioletred",
    "blueviolet",
    "fuchsia",
    "cyan",
    "limegreen",
    "mediumorchid",
]
dv_colors = {f"y{i}": dv_colors_arr[i] for i in range(len(dv_colors_arr))}
dv_colors


# In[24]:


def plot_results(model, p, facs, clis=None, ax=None):
    """Visualize optimal solution sets and context."""
    if not ax:
        multi_plot = False
        fig, ax = plt.subplots(figsize=(6, 6))
        markersize, markersize_factor = 4, 4
    else:
        ax.axis("off")
        multi_plot = True
        markersize, markersize_factor = 2, 2
    ax.set_title(model.name, fontsize=15)

    # extract facility-client relationships for plotting (except for p-dispersion)
    plot_clis = isinstance(clis, geopandas.GeoDataFrame)
    if plot_clis:
        cli_points = {}
    fac_sites = {}
    for i, dv in enumerate(model.fac_vars):
        if dv.varValue:
            dv, predef = facs.loc[i, ["dv", "predefined_loc"]]
            fac_sites[dv] = [i, predef]
            if plot_clis:
                geom = clis.iloc[model.fac2cli[i]]["geometry"]
                cli_points[dv] = geom
    
    # study area and legend entries initialization
    streets.plot(ax=ax, alpha=1, color="black", zorder=1)
    legend_elements = [mlines.Line2D([], [], color="black", label="streets")]
    
    if plot_clis:
        # any clients that not asscociated with a facility
        if model.name.startswith("mclp"):
            c = "k"
            if model.n_cli_uncov:
                idx = [i for i, v in enumerate(model.cli2fac) if len(v) == 0]
                pnt_kws = dict(ax=ax, fc=c, ec=c, marker="s", markersize=7, zorder=2)
                clis.iloc[idx].plot(**pnt_kws)
            _label = f"Demand sites not covered ($n$={model.n_cli_uncov})"
            _mkws = dict(marker="s", markerfacecolor=c, markeredgecolor=c, linewidth=0)
            legend_elements.append(mlines.Line2D([], [], ms=3, label=_label, **_mkws))

    # all candidate facilities
    facs.plot(ax=ax, fc="brown", marker="*", markersize=80, zorder=8)
    _label = f"Facility sites ($n$={len(model.fac_vars)})"
    _mkws = dict(marker="*", markerfacecolor="brown", markeredgecolor="brown")
    legend_elements.append(mlines.Line2D([], [], ms=7, lw=0, label=_label, **_mkws))
    
    # facility-(client) symbology and legend entries
    zorder = 4
    for fname, (fac, predef) in fac_sites.items():
        cset = dv_colors[fname]
        if plot_clis:
            # clients
            geoms = cli_points[fname]
            gdf = geopandas.GeoDataFrame(geoms)
            gdf.plot(ax=ax, zorder=zorder, ec="k", fc=cset, markersize=100 * markersize)
            _label = f"Demand sites covered by {fname}"
            _mkws = dict(markerfacecolor=cset, markeredgecolor="k", ms=markersize + 7)
            legend_elements.append(
                mlines.Line2D([], [], marker="o", lw=0, label=_label, **_mkws)
            )
        # facilities
        ec = "k"
        lw = 2
        predef_label = "predefined"
        if model.name.endswith(predef_label) and predef:
            ec = "r"
            lw = 3
            fname += f" ({predef_label})"
        facs.iloc[[fac]].plot(
            ax=ax, marker="*", markersize=1000, zorder=9, fc=cset, ec=ec, lw=lw
        )
        _mkws = dict(markerfacecolor=cset, markeredgecolor=ec, markeredgewidth=lw)
        legend_elements.append(
            mlines.Line2D([], [], marker="*", ms=20, lw=0, label=fname, **_mkws)
        )
        # increment zorder up and markersize down for stacked client symbology
        zorder += 1
        if plot_clis:
            markersize -= markersize_factor / p
    
    if not multi_plot:
        # legend
        kws = dict(loc="upper left", bbox_to_anchor=(1.05, 0.7))
        plt.legend(handles=legend_elements, **kws)


# ### LSCP built from cost matrix (network distance)

# In[25]:


plot_results(
    lscp_from_cm,
    lscp_from_cm.problem.objective.value(),
    facility_points,
    clis=client_points
)


# ### LSCP built from geodataframe (euclidean distance)

# In[26]:


plot_results(
    lscp_from_gdf,
    lscp_from_gdf.problem.objective.value(),
    facility_points,
    clis=client_points
)


# You may notice that the model results are very different. This is expected as the distances between facility and demand points are calculated with different metrics (network vs. euclidean distance).
# 
# But how can just one facility cover all of the demand locations? This can be explained by the nature of the problem. The problem was configured in a synthetic manner, the streets are created as a 10x10 lattice and the `SERVICE_RADIUS` parameter is 8 (distance units). Owing to the central location of facility $y_3$, all demand points can be reached within that (euclidean) distance.
# 
# ### LSCP with preselected facilities (euclidean distance)
# 
# Finally, let's visualize the results of the LSCP when stipulating that facilities $y_4$ and $y_9$ must be included in the final selection.

# In[27]:


plot_results(
    lscp_from_gdf_pre,
    lscp_from_gdf_pre.problem.objective.value(),
    facility_points,
    clis=client_points
)


# -----------------------------------
# 
# ## Comparing solution from varied metrics

# In[28]:


fig, axarr = plt.subplots(1, 3, figsize=(20, 10))
fig.subplots_adjust(wspace=-0.01)
for i, m in enumerate([lscp_from_cm, lscp_from_gdf, lscp_from_gdf_pre]):
    plot_results(
        m, m.problem.objective.value(), facility_points, clis=client_points, ax=axarr[i]
    )


# ## References
# 
# - [Church, R. L., & Murray, A. T. (2018). Location covering models: History, applications and advancements (1st edition 2018). Springer](https://www.springer.com/gb/book/9783319998459)
# - [Toregas, C., Swain, R., ReVelle, C., &amp; Bergman, L. (1971). The location of emergency service facilities. Operations Research, 19(6), 1363–1373.](https://pubsonline.informs.org/doi/abs/10.1287/opre.19.6.1363)