Merge pull request #193 from gegen07/issue-190-add-locate-docs

Update locate docs

README.md

@@ -37,12 +37,54 @@ mexico.plot(column="maxp_new", categorical=True, figsize=(12,8), ec="w");
 <img src="docs/_static/images/maxp.svg" height="350" />
 </p>
 
+### Locate
+```python
+from spopt.locate.coverage import MCLP
+from spopt.locate.util import simulated_geo_points
+import numpy
+import geopandas
+import pulp
+import spaghetti
+
+solver = pulp.PULP_CBC_CMD(msg=False)
+lattice = spaghetti.regular_lattice((0, 0, 10, 10), 9, exterior=True)
+ntw = spaghetti.Network(in_data=lattice)
+street = spaghetti.element_as_gdf(ntw, arcs=True)
+street_buffered = geopandas.GeoDataFrame(
+    geopandas.GeoSeries(street["geometry"].buffer(0.2).unary_union),
+    crs=street.crs,
+    columns=["geometry"],
+)
+client_points = simulated_geo_points(street_buffered, needed=CLIENT_COUNT, seed=CLIENT_SEED)
+facility_points = simulated_geo_points(
+    street_buffered, needed=FACILITY_COUNT, seed=FACILITY_SEED
+)
+ntw.snapobservations(client_points, "clients", attribute=True)
+clients_snapped = spaghetti.element_as_gdf(
+    ntw, pp_name="clients", snapped=True
+)
+
+ntw.snapobservations(facility_points, "facilities", attribute=True)
+facilities_snapped = spaghetti.element_as_gdf(
+    ntw, pp_name="facilities", snapped=True
+)
+cost_matrix = ntw.allneighbordistances(
+    sourcepattern=ntw.pointpatterns["clients"],
+    destpattern=ntw.pointpatterns["facilities"],
+)
+mclp_from_cost_matrix = MCLP.from_cost_matrix(cost_matrix, ai, MAX_COVERAGE, p_facilities=P_FACILITIES)
+mclp_from_cost_matrix = mclp_from_cost_matrix.solve(solver)
+```
+<p align="center">
+<img src="docs/_static/images/mclp.svg" height="350" />
+</p>
 
 ## Examples
 More examples can be found in the [Tutorials](https://pysal.org/spopt/tutorials.html) section of the documentation.
 - [Max-p-regions problem](https://pysal.org/spopt/notebooks/maxp.html)
 - [Skater](https://pysal.org/spopt/notebooks/skater.html)
 - [Region K means](https://pysal.org/spopt/notebooks/reg-k-means.html)
+- [Facility Location Real World Problem](https://pysal.org/spopt/notebooks/facloc-real-world.html)
 
 All examples can be run interactively by launching this repository as a [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/pysal/spopt/main).
 
@@ -54,6 +96,7 @@ All examples can be run interactively by launching this repository as a [![Binde
 - [libpysal](https://pysal.org/libpysal/)
 - [scikit-learn](https://scikit-learn.org/stable/)
 - [geopandas](https://geopandas.org/)
+- [pulp](https://coin-or.github.io/pulp/)
 
 ## Installation
 spopt is available on the [Python Package Index](https://pypi.org/). Therefore, you can either install directly with pip from the command line:

docs/_static/references.bib

@@ -87,4 +87,67 @@ @article{wolf2021
   doi={10.1080/13658816.2021.1934475},
 }
 
+@article{hakimi_1964, 
+  author={Hakimi, S. L.},
+  title={Optimum Locations of Switching Centers and the Absolute Centers and Medians of a Graph}, 
+  journal={Operations Research},
+  volume={12}, 
+  number={3},
+  pages={450–459},
+  year={1964},
+  doi={10.1287/opre.12.3.450},
+}
+
+@article{hakimi_1965, 
+  author={Hakimi, S. L.},
+  title={Optimum Distribution of Switching Centers in a Communication Network and Some Related Graph Theoretic Problems}, 
+  journal={Operations Research},
+  number={3},
+  volume={13},
+  pages={462–475},
+  year={1965},
+  doi={10.1287/opre.13.3.462},
+}
+
+@article{toregas_swain_revelle_bergman_1971, 
+  author={Toregas, Constantine and Swain, Ralph and Revelle, Charles and Bergman, Lawrence}, 
+  title={The Location of Emergency Service Facilities}, volume={19}, 
+  journal={Operations Research}, 
+  number={6},
+  pages={1363–1373},
+  year={1971}, 
+  doi={10.1287/opre.19.6.1363},
+}
+
+@article{calik_labbé_yaman_2015, 
+  author={Calik, Hatice and Labbé, Martine and Yaman, Hande},
+  title={p-Center Problems}, 
+  journal={Location Science},
+  pages={79–92},
+  year={2015},
+  doi={10.1007/978-3-319-13111-5_4},  
+}
+
+@article{chen_murray_jiang_2021,
+  author={Chen, Huanfa and Murray, Alan T. and Jiang, Rui},
+  title={Open-source approaches for location cover models: capabilities and efficiency},
+  journal={Journal of Geographical Systems},
+  doi={10.1007/s10109-021-00350-w},
+  year={2021}
+}
+
+@book{daskin_2013, 
+  author={Daskin, Mark S.},
+  title={Network and discrete location: models, algorithms, and applications}, 
+  publisher={John Wiley & Sons, Inc.}, 
+  year={2013},
+}
+
+@book{church_murray_2018, 
+  author={Church, Richard L. and Murray, Alan T.},
+  title={Location covering models: history, applications and advancements}, 
+  publisher={Springer},  
+  year={2018},
+}
+
 %======

docs/index.rst

@@ -44,6 +44,16 @@ Regionalization, facility location, and transportation-oriented modeling
                 </div>
             </a>
         </div>
+        <div class="col-sm-4 col-xs-14">
+            <a href="https://pysal.org/spopt/notebooks/facloc-real-world.html" class="thumbnail">
+                <img src="_static/images/notebooks-facloc-mclp.png"
+                class="img-responsive center-block">
+                <div class="caption text-center">
+                <h6>Locate Store Sites in San Francisco
+                </h6>
+                </div>
+            </a>
+        </div>
         <div class="col-sm-.5 col-xs-hidden">
         </div>
       </div>