predefined explanation (#384)

notebooks/facloc-disperse-real-world.ipynb

@@ -844,7 +844,9 @@
    "metadata": {},
    "source": [
     "## P-Dispersion with selection of predefined candidate facilities\n",
-    "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_{11}$ and $y_{15}$ as*** already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_{11}$ and $y_{15}$ as*** already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1647,9 +1649,9 @@
    "hash": "56b72aab97c5d88c22a6bf5872989e2e65e9296dc12395fbfb8350007c775deb"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1661,7 +1663,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/facloc-lscpb-real-world.ipynb

@@ -1694,7 +1694,9 @@
    "metadata": {},
    "source": [
     "## LSCP & LSCP-B with selection of predefined candidate facilities\n",
-    "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_{11}$ and $y_{15}$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_{11}$ and $y_{15}$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -2619,9 +2621,9 @@
    "hash": "56b72aab97c5d88c22a6bf5872989e2e65e9296dc12395fbfb8350007c775deb"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -2633,7 +2635,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/facloc-real-world.ipynb

@@ -2270,9 +2270,9 @@
    "hash": "958eb214114e08f71b7ebc4a2a14e16b7e5a4d56e75cf94b50c30e8e940fafb5"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -2284,7 +2284,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/lscp.ipynb

@@ -773,7 +773,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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."
+    "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.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1311,9 +1313,9 @@
    "hash": "56b72aab97c5d88c22a6bf5872989e2e65e9296dc12395fbfb8350007c775deb"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1325,7 +1327,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/lscp_capacity.ipynb

@@ -1555,7 +1555,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Stipulate that facility $y_5$ must be a member of the solution set"
+    "### Stipulate that facility $y_5$ must be a member of the solution set\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1929,9 +1931,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1943,7 +1945,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   },
   "vscode": {
    "interpreter": {

notebooks/lscp_gis.ipynb

@@ -15590,9 +15590,9 @@
    "hash": "31b88bb145573cdebdaa7fd72fef7949ecb3dda26d5e10d4ccc660a5d07787a7"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -15604,7 +15604,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/lscpb.ipynb

@@ -895,7 +895,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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."
+    "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.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1631,9 +1633,9 @@
    "hash": "56b72aab97c5d88c22a6bf5872989e2e65e9296dc12395fbfb8350007c775deb"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1645,7 +1647,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/mclp.ipynb

@@ -924,7 +924,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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_0$, $y_1$, and $y_3$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_0$, $y_1$, and $y_3$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1443,9 +1445,9 @@
    "hash": "31b88bb145573cdebdaa7fd72fef7949ecb3dda26d5e10d4ccc660a5d07787a7"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1457,7 +1459,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/p-center.ipynb

@@ -811,7 +811,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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_0$ and $y_1$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_0$ and $y_1$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1338,9 +1340,9 @@
    "hash": "958eb214114e08f71b7ebc4a2a14e16b7e5a4d56e75cf94b50c30e8e940fafb5"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1352,7 +1354,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/p-dispersion.ipynb

@@ -853,7 +853,9 @@
    "id": "d53d6bfe",
    "metadata": {},
    "source": [
-    "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_{11}$ and $y_{12}$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_{11}$ and $y_{12}$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1447,9 +1449,9 @@
    "hash": "56b72aab97c5d88c22a6bf5872989e2e65e9296dc12395fbfb8350007c775deb"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1461,7 +1463,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.8"
+   "version": "3.11.4"
   }
  },
  "nbformat": 4,

notebooks/p-median.ipynb

@@ -928,7 +928,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "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_0$ and $y_1$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution."
+    "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_0$ and $y_1$ as already existing (they must be present in the model solution). This will lead to a sub-optimal solution.\n",
+    "\n",
+    "***Important:*** The facilities in `\"predefined_loc\"` are a binary array where `1` means the associated location must appear in the solution."
    ]
   },
   {
@@ -1452,9 +1454,9 @@
    "hash": "958eb214114e08f71b7ebc4a2a14e16b7e5a4d56e75cf94b50c30e8e940fafb5"
   },
   "kernelspec": {
-   "display_name": "Python [conda env:py310_spopt]",
+   "display_name": "Python [conda env:py311_spopt]",
    "language": "python",
-   "name": "conda-env-py310_spopt-py"
+   "name": "conda-env-py311_spopt-py"
   },
   "language_info": {
    "codemirror_mode": {

spopt/locate/base.py

@@ -467,7 +467,10 @@ def add_predefined_facility_constraint(
         obj : T_FacModel
             A bounded type of the ``LocateSolver`` class.
         predefined_fac : numpy.array
-            Indexes of facilities that are already located (zero-indexed).
+            A binary 1D array of service facilities that must appear in the
+            solution. For example, consider 3 facilites ``['A', 'B', 'C']``.
+            If facility ``'B'`` must be in the model solution, then the passed
+            in array should be ``[0, 1, 0]``.
         demand : numpy.array (default None)
             A 1D array of service load or population demand.
         facility_capacity : numpy.array (default None)

spopt/locate/coverage.py

@@ -141,7 +141,10 @@ def from_cost_matrix(
         service_radius : float
             Maximum acceptable service distance.
         predefined_facilities_arr : numpy.array (default None)
-            Predefined facilities that must appear in the solution.
+            A binary 1D array of service facilities that must appear in the
+            solution. For example, consider 3 facilites ``['A', 'B', 'C']``.
+            If facility ``'B'`` must be in the model solution, then the passed
+            in array should be ``[0, 1, 0]``.
         demand_quantity_arr : numpy.array (default None)
             Amount of demand at each client location.
         facility_capacity_arr : numpy.array (default None)
@@ -315,6 +318,9 @@ def from_geodataframe(
              Maximum acceptable service distance.
         predefined_facility_col : str (default None)
             Column name representing facilities are already defined.
+            This a binary assignment per facility. For example, consider 3 facilites
+            ``['A', 'B', 'C']``. If facility ``'B'`` must be in the model solution,
+            then the column should be ``[0, 1, 0]``.
         demand_quantity_col : str
             Column name representing amount of demand at each client location.
         facility_capacity_arr : str
@@ -622,7 +628,10 @@ def from_cost_matrix(
         solver : pulp.LpSolver
             A solver supported by ``pulp``.
         predefined_facilities_arr : numpy.array (default None)
-            Predefined facilities that must appear in the solution.
+            A binary 1D array of service facilities that must appear in the
+            solution. For example, consider 3 facilites ``['A', 'B', 'C']``.
+            If facility ``'B'`` must be in the model solution, then the passed
+            in array should be ``[0, 1, 0]``.
         name : str (default 'LSCP-B')
             The problem name.
 
@@ -769,6 +778,9 @@ def from_geodataframe(
             A solver supported by ``pulp``.
         predefined_facility_col : str (default None)
             Column name representing facilities are already defined.
+            This a binary assignment per facility. For example, consider 3 facilites
+            ``['A', 'B', 'C']``. If facility ``'B'`` must be in the model solution,
+            then the column should be ``[0, 1, 0]``.
         distance_metric : str (default 'euclidean')
             A metric used for the distance calculations supported by
             `scipy.spatial.distance.cdist <https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.cdist.html>`_.
@@ -1055,7 +1067,10 @@ def from_cost_matrix(
         p_facilities : int
             The number of facilities to be located.
         predefined_facilities_arr : numpy.array (default None)
-            Predefined facilities that must appear in the solution.
+            A binary 1D array of service facilities that must appear in the
+            solution. For example, consider 3 facilites ``['A', 'B', 'C']``.
+            If facility ``'B'`` must be in the model solution, then the passed
+            in array should be ``[0, 1, 0]``.
         name : str (default 'MCLP')
             The problem name.
 
@@ -1206,6 +1221,9 @@ def from_geodataframe(
            The number of facilities to be located.
         predefined_facility_col : str (default None)
             Column name representing facilities are already defined.
+            This a binary assignment per facility. For example, consider 3 facilites
+            ``['A', 'B', 'C']``. If facility ``'B'`` must be in the model solution,
+            then the column should be ``[0, 1, 0]``.
         distance_metric : str (default 'euclidean')
             A metric used for the distance calculations supported by
             `scipy.spatial.distance.cdist <https://docs.scipy.org/doc/scipy/reference/generated/scipy.spatial.distance.cdist.html>`_.