From 92d30460b9f2c227770dd426415c1ee34dac5300 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 3 Sep 2021 18:07:40 -0500 Subject: [PATCH 01/14] Update README.md --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3ab0be6..57dfb12 100644 --- a/README.md +++ b/README.md @@ -26,8 +26,10 @@ ### Authors -* **Alinson S. Xavier,** Argonne National Laboratory <> -* **Nwike Iloeje,** Argonne National Laboratory <> +* **Alinson S. Xavier** <> +* **Nwike Iloeje** <> +* **John Atkins** +* **Kyle Sun** ### License From 19a34fb5d29a61d1ceb2c281008c20cc48878623 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 26 Aug 2022 13:04:47 -0500 Subject: [PATCH 02/14] Update dependencies; switch to Documenter.jl --- Makefile | 29 ++-- Project.toml | 30 ++--- deps/formatter/Project.toml | 5 + deps/formatter/format.jl | 8 ++ docs/Project.toml | 4 + docs/make.jl | 19 +++ docs/src/assets/custom.css | 36 +++++ .../src/assets}/ex_amount_produced.png | Bin .../src/assets}/ex_emissions.png | Bin .../src/assets}/ex_plant_cost_per_year.png | Bin .../src/assets}/ex_plant_locations.png | Bin .../src/assets}/ex_transportation.png | Bin .../ex_transportation_amount_distance.png | Bin .../assets}/ex_transportation_emissions.png | Bin {src/docs => docs/src}/format.md | 16 +-- {src/docs => docs/src}/index.md | 20 +-- {src/docs => docs/src}/model.md | 127 +++++++++++------- {src/docs => docs/src}/reports.md | 41 ++++-- {src/docs => docs/src}/usage.md | 41 +++--- juliaw | 75 +++++++++++ src/docs/css/custom.css | 28 ---- src/docs/js/mathjax.js | 8 -- src/graph/build.jl | 2 +- 23 files changed, 319 insertions(+), 170 deletions(-) create mode 100644 deps/formatter/Project.toml create mode 100644 deps/formatter/format.jl create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/assets/custom.css rename {src/docs/images => docs/src/assets}/ex_amount_produced.png (100%) rename {src/docs/images => docs/src/assets}/ex_emissions.png (100%) rename {src/docs/images => docs/src/assets}/ex_plant_cost_per_year.png (100%) rename {src/docs/images => docs/src/assets}/ex_plant_locations.png (100%) rename {src/docs/images => docs/src/assets}/ex_transportation.png (100%) rename {src/docs/images => docs/src/assets}/ex_transportation_amount_distance.png (100%) rename {src/docs/images => docs/src/assets}/ex_transportation_emissions.png (100%) rename {src/docs => docs/src}/format.md (96%) rename {src/docs => docs/src}/index.md (86%) rename {src/docs => docs/src}/model.md (57%) rename {src/docs => docs/src}/reports.md (92%) rename {src/docs => docs/src}/usage.md (92%) create mode 100755 juliaw delete mode 100644 src/docs/css/custom.css delete mode 100644 src/docs/js/mathjax.js diff --git a/Makefile b/Makefile index e86d416..0b8ace3 100644 --- a/Makefile +++ b/Makefile @@ -1,28 +1,19 @@ -JULIA := julia --color=yes --project=@. -SRC_FILES := $(wildcard src/*.jl test/*.jl) VERSION := 0.5 -all: docs test - -build/sysimage.so: src/sysimage.jl Project.toml Manifest.toml - mkdir -p build - $(JULIA) src/sysimage.jl - -build/test.log: $(SRC_FILES) build/sysimage.so - cd test; $(JULIA) --sysimage ../build/sysimage.so runtests.jl - clean: - rm -rf build/* + rm -rfv build Manifest.toml test/Manifest.toml deps/formatter/build deps/formatter/Manifest.toml docs: - mkdocs build -d ../docs/$(VERSION)/ - + cd docs; julia --project=. make.jl; cd .. + rsync -avP --delete-after docs/build/ ../docs/$(VERSION)/ + format: - julia -e 'using JuliaFormatter; format(["src", "test"], verbose=true);' + cd deps/formatter; ../../juliaw format.jl -test: build/test.log +test: test/Manifest.toml + ./juliaw test/runtests.jl -test-watch: - bash -c "while true; do make test --quiet; sleep 1; done" +test/Manifest.toml: test/Project.toml + julia --project=test -e "using Pkg; Pkg.instantiate()" -.PHONY: docs test +.PHONY: docs test format diff --git a/Project.toml b/Project.toml index f4b5119..6a4eab8 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "RELOG" uuid = "a2afcdf7-cf04-4913-85f9-c0d81ddf2008" authors = ["Alinson S Xavier "] -version = "0.5.1" +version = "0.5.2" [deps] CRC = "44b605c4-b955-5f2b-9b6d-d2bd01d3d205" @@ -19,7 +19,6 @@ JuMP = "4076af6c-e467-56ae-b986-b466b2749572" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee" OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d" -PackageCompiler = "9b87118b-4619-50d2-8e1e-99f35a4d4d9d" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" ProgressBars = "49802e3a-d2f1-5c88-81d8-b72133a6f568" Shapefile = "8e980c4a-a4fe-5da2-b3a7-4b4b0353a2f4" @@ -29,20 +28,19 @@ ZipFile = "a5390f91-8eb1-5f08-bee0-b1d1ffed6cea" [compat] CRC = "4" -CSV = "0.7" -Cbc = "0.6" -Clp = "0.8" -DataFrames = "0.21" -DataStructures = "0.17" +CSV = "0.10" +Cbc = "1" +Clp = "1" +DataFrames = "1" +DataStructures = "0.18" GZip = "0.5" -Geodesy = "0.5" +Geodesy = "1" JSON = "0.21" -JSONSchema = "0.3" -JuMP = "0.21" -MathOptInterface = "0.9" -OrderedCollections = "1.4" -PackageCompiler = "1" -ProgressBars = "0.6" -Shapefile = "0.7" -ZipFile = "0.9" +JSONSchema = "1" +JuMP = "1" +MathOptInterface = "1" +OrderedCollections = "1" +ProgressBars = "1" +Shapefile = "0.8" +ZipFile = "0.10" julia = "1" diff --git a/deps/formatter/Project.toml b/deps/formatter/Project.toml new file mode 100644 index 0000000..4bc5f25 --- /dev/null +++ b/deps/formatter/Project.toml @@ -0,0 +1,5 @@ +[deps] +JuliaFormatter = "98e50ef6-434e-11e9-1051-2b60c6c9e899" + +[compat] +JuliaFormatter = "0.14.4" diff --git a/deps/formatter/format.jl b/deps/formatter/format.jl new file mode 100644 index 0000000..9f9d965 --- /dev/null +++ b/deps/formatter/format.jl @@ -0,0 +1,8 @@ +using JuliaFormatter +format( + [ + "../../src", + "../../test", + ], + verbose=true, +) diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..8db0c61 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,4 @@ +[deps] +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" +RELOG = "a2afcdf7-cf04-4913-85f9-c0d81ddf2008" +Revise = "295af30f-e4ad-537b-8983-00126c2a3abe" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..9a44440 --- /dev/null +++ b/docs/make.jl @@ -0,0 +1,19 @@ +using Documenter, RELOG + +function make() + makedocs( + sitename="RELOG", + pages=[ + "Home" => "index.md", + "usage.md", + "format.md", + "reports.md", + "model.md", + ], + format = Documenter.HTML( + assets=["assets/custom.css"], + ) + ) +end + +make() \ No newline at end of file diff --git a/docs/src/assets/custom.css b/docs/src/assets/custom.css new file mode 100644 index 0000000..07214a3 --- /dev/null +++ b/docs/src/assets/custom.css @@ -0,0 +1,36 @@ +@media screen and (min-width: 1056px) { + #documenter .docs-main { + max-width: 65rem !important; + } +} + + +tbody, thead, pre { + border: 1px solid rgba(0, 0, 0, 0.25); +} + +table td, th { + padding: 8px; +} + +table p { + margin-bottom: 0; +} + +table td code { + white-space: nowrap; +} + +table tr, +table th { + border-bottom: 1px solid rgba(0, 0, 0, 0.1); +} + +table tr:last-child { + border-bottom: 0; +} + +code { + background-color: transparent; + color: rgb(232, 62, 140); +} \ No newline at end of file diff --git a/src/docs/images/ex_amount_produced.png b/docs/src/assets/ex_amount_produced.png similarity index 100% rename from src/docs/images/ex_amount_produced.png rename to docs/src/assets/ex_amount_produced.png diff --git a/src/docs/images/ex_emissions.png b/docs/src/assets/ex_emissions.png similarity index 100% rename from src/docs/images/ex_emissions.png rename to docs/src/assets/ex_emissions.png diff --git a/src/docs/images/ex_plant_cost_per_year.png b/docs/src/assets/ex_plant_cost_per_year.png similarity index 100% rename from src/docs/images/ex_plant_cost_per_year.png rename to docs/src/assets/ex_plant_cost_per_year.png diff --git a/src/docs/images/ex_plant_locations.png b/docs/src/assets/ex_plant_locations.png similarity index 100% rename from src/docs/images/ex_plant_locations.png rename to docs/src/assets/ex_plant_locations.png diff --git a/src/docs/images/ex_transportation.png b/docs/src/assets/ex_transportation.png similarity index 100% rename from src/docs/images/ex_transportation.png rename to docs/src/assets/ex_transportation.png diff --git a/src/docs/images/ex_transportation_amount_distance.png b/docs/src/assets/ex_transportation_amount_distance.png similarity index 100% rename from src/docs/images/ex_transportation_amount_distance.png rename to docs/src/assets/ex_transportation_amount_distance.png diff --git a/src/docs/images/ex_transportation_emissions.png b/docs/src/assets/ex_transportation_emissions.png similarity index 100% rename from src/docs/images/ex_transportation_emissions.png rename to docs/src/assets/ex_transportation_emissions.png diff --git a/src/docs/format.md b/docs/src/format.md similarity index 96% rename from src/docs/format.md rename to docs/src/format.md index cef0537..01fdc7d 100644 --- a/src/docs/format.md +++ b/docs/src/format.md @@ -11,7 +11,7 @@ RELOG accepts as input a JSON file with three sections: `parameters`, `products` The **parameters** section describes details about the simulation itself. | Key | Description -|:--------------------------|---------------| +|:--------------------------|:---------------| |`time horizon (years)` | Number of years in the simulation. |`building period (years)` | List of years in which we are allowed to open new plants. For example, if this parameter is set to `[1,2,3]`, we can only open plants during the first three years. By default, this equals `[1]`; that is, plants can only be opened during the first year. | @@ -31,7 +31,7 @@ The **parameters** section describes details about the simulation itself. The **products** section describes all products and subproducts in the simulation. The field `instance["Products"]` is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys: | Key | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| |`transportation cost ($/km/tonne)` | The cost to transport this product. Must be a time series. |`transportation energy (J/km/tonne)` | The energy required to transport this product. Must be a time series. Optional. |`transportation emissions (tonne/km/tonne)` | A dictionary mapping the name of each greenhouse gas, produced to transport one tonne of this product along one kilometer, to the amount of gas produced (in tonnes). Must be a time series. Optional. @@ -40,7 +40,7 @@ The **products** section describes all products and subproducts in the simulatio Each product may have some amount available at the beginning of each time period. In this case, the key `initial amounts` maps to a dictionary with the following keys: | Key | Description -|:------------------------|---------------| +|:------------------------|:---------------| | `latitude (deg)` | The latitude of the location. | `longitude (deg)` | The longitude of the location. | `amount (tonne)` | The amount of the product initially available at the location. Must be a time series. @@ -93,7 +93,7 @@ Each product may have some amount available at the beginning of each time period The **plants** section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field `instance["Plants"]` is a dictionary mapping the name of the plant to a dictionary with the following keys: | Key | Description -|:------------------------|---------------| +|:------------------------|:---------------| | `input` | The name of the product that this plant takes as input. Only one input is accepted per plant. | `outputs (tonne/tonne)` | A dictionary specifying how many tonnes of each product is produced for each tonnes of input. For example, if the plant outputs 0.5 tonnes of P2 and 0.25 tonnes of P3 for each tonnes of P1 provided, then this entry should be `{"P2": 0.5, "P3": 0.25}`. If the plant does not output anything, this key may be omitted. |`energy (GJ/tonne)` | The energy required to process 1 tonne of the input. Must be a time series. Optional. @@ -113,14 +113,14 @@ Each type of plant is associated with a set of potential locations where it can The `storage` dictionary should contain the following keys: | Key | Description -|:------------------------|---------------| +|:------------------------|:---------------| | `cost ($/tonne)` | The cost to store a tonne of input product for one time period. Must be a time series. | `limit (tonne)` | The maximum amount of input product this plant can have in storage at any given time. The keys in the `disposal` dictionary should be the names of the products. The values are dictionaries with the following keys: | Key | Description -|:------------------------|---------------| +|:------------------------|:---------------| | `cost ($/tonne)` | The cost to dispose of the product. Must be a time series. | `limit (tonne)` | The maximum amount that can be disposed of. If an unlimited amount can be disposed, this key may be omitted. Must be a time series. @@ -128,7 +128,7 @@ The keys in the `disposal` dictionary should be the names of the products. The v The keys in the `capacities (tonne)` dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys: | Key | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `opening cost ($)` | The cost to open a plant of this size. | `fixed operating cost ($)` | The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series. | `variable operating cost ($/tonne)` | The cost that the plant incurs to process each tonne of input. Must be a time series. @@ -210,7 +210,7 @@ is is possible to write: Location names follow the format `db:id`, where `db` is the name of the database and `id` is the identifier for a specific location. RELOG currently includes the following databases: Database | Description | Examples ----------|-------------|---------- +:--------|:------------|:--------- `us-state`| List of states of the United States. | `us-state:IL` (State of Illinois) `2018-us-county` | List of United States counties, as of 2018. IDs are 5-digit FIPS codes. | `2018-us-county:17043` (DuPage county in Illinois) diff --git a/src/docs/index.md b/docs/src/index.md similarity index 86% rename from src/docs/index.md rename to docs/src/index.md index c25c173..ad1397f 100644 --- a/src/docs/index.md +++ b/docs/src/index.md @@ -1,25 +1,29 @@ # RELOG: Reverse Logistics Optimization - **RELOG** is an open-source supply chain optimization package focusing on reverse logistics and reverse manufacturing. The package uses Mixed-Integer Linear Programming to determine where to build recycling plants, what size should these plants have and which customers should be served by which plants. The package supports custom reverse logistics pipelines, with multiple types of plants, multiple types of product and multiple time periods. - +```@raw html +
+ +
+``` ### Table of Contents - * [Usage](usage.md) - * [Input and Output Data Formats](format.md) - * [Simplified Solution Reports](reports.md) - * [Optimization Model](model.md) + ```@contents +Pages = ["usage.md", "format.md", "reports.md", "model.md"] +Depth = 3 +``` + ### Source Code * [https://github.com/ANL-CEEESA/RELOG](https://github.com/ANL-CEEESA/RELOG) ### Authors -* **Alinson S. Xavier,** Argonne National Laboratory <> -* **Nwike Iloeje,** Argonne National Laboratory <> +* **Alinson S. Xavier,** Argonne National Laboratory +* **Nwike Iloeje,** Argonne National Laboratory ### License diff --git a/src/docs/model.md b/docs/src/model.md similarity index 57% rename from src/docs/model.md rename to docs/src/model.md index dfc1bca..7098e34 100644 --- a/src/docs/model.md +++ b/docs/src/model.md @@ -6,53 +6,65 @@ In this page, we describe the precise mathematical optimization model used by RE ### Sets -* $L$ - Set of locations holding the original material to be recycled -* $M$ - Set of materials recovered during the reverse manufacturing process -* $P$ - Set of potential plants to open -* $T = \{ 1, \ldots, t^{max} \} $ - Set of time periods +Symbol | Description +:-------|:------------ +$L$ | Set of locations holding the original material to be recycled +$M$ | Set of materials recovered during the reverse manufacturing process +$P$ | Set of potential plants to open +$T = \{ 1, \ldots, t^{max} \}$ | Set of time periods ### Constants -**Plants:** +#### Plants -* $c^\text{disp}_{pmt}$ - Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ (`$/tonne/km`) -* $c^\text{exp}_{pt}$ - Cost of adding one tonne of capacity to plant $p$ at time $t$ (`$/tonne`) -* $c^\text{open}_{pt}$ - Cost of opening plant $p$ at time $t$, at minimum capacity (`$`) -* $c^\text{f-base}_{pt}$ - Fixed cost of keeping plant $p$ open during time period $t$ (`$`) -* $c^\text{f-exp}_{pt}$ - Increase in fixed cost for each additional tonne of capacity (`$/tonne`) -* $c^\text{var}_{pt}$ - Variable cost of processing one tonne of input at plant $p$ at time $t$ (`$/tonne`) -* $c^\text{store}_{pt}$ - Cost of storing one tonne of original material at plant $p$ at time $t$ (`$/tonne`) -* $m^\text{min}_p$ - Minimum capacity of plant $p$ (`tonne`) -* $m^\text{max}_p$ - Maximum capacity of plant $p$ (`tonne`) -* $m^\text{disp}_{pmt}$ - Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ (`tonne`) -* $m^\text{store}_p$ - Maximum amount of original material that plant $p$ can store for later processing. +Symbol | Description | Unit +:-------|:------------|:--- +$c^\text{disp}_{pmt}$ | Cost of disposing one tonne of material $m$ at plant $p$ during time $t$ | \$/tonne/km +$c^\text{exp}_{pt}$ | Cost of adding one tonne of capacity to plant $p$ at time $t$ | \$/tonne +$c^\text{open}_{pt}$ | Cost of opening plant $p$ at time $t$, at minimum capacity | $ +$c^\text{f-base}_{pt}$ | Fixed cost of keeping plant $p$ open during time period $t$ | $ +$c^\text{f-exp}_{pt}$ | Increase in fixed cost for each additional tonne of capacity | \$/tonne +$c^\text{var}_{pt}$ | Variable cost of processing one tonne of input at plant $p$ at time $t$ | \$/tonne +$c^\text{store}_{pt}$ | Cost of storing one tonne of original material at plant $p$ at time $t$ | \$/tonne +$m^\text{min}_p$ | Minimum capacity of plant $p$ | tonne +$m^\text{max}_p$ | Maximum capacity of plant $p$ | tonne +$m^\text{disp}_{pmt}$ | Maximum amount of material $m$ that plant $p$ can dispose of during time $t$ | tonne +$m^\text{store}_p$ | Maximum amount of original material that plant $p$ can store for later processing. | tonne -**Products:** +#### Products -* $\alpha_{pm}$ - Amount of material $m$ recovered by plant $t$ for each tonne of original material (`tonne/tonne`) -* $m^\text{initial}_{lt}$ - Amount of original material to be recycled at location $l$ during time $t$ (`tonne`) +Symbol | Description | Unit +:-------|:------------|:--- +$\alpha_{pm}$ | Amount of material $m$ recovered by plant $t$ for each tonne of original material | tonne/tonne +$m^\text{initial}_{lt}$ | Amount of original material to be recycled at location $l$ during time $t$ | tonne -**Transportation:** +#### Transportation -* $c^\text{tr}_{t}$ - Transportation cost during time $t$ (`$/tonne/km`) -* $d_{lp}$ - Distance between plant $p$ and location $l$ (`km`) +Symbol | Description | Unit +:-------|:------------|:--- +$c^\text{tr}_{t}$ | Transportation cost during time $t$ | \$/tonne/km +$d_{lp}$ | Distance between plant $p$ and location $l$ | km ### Decision variables -* $q_{mpt}$ - Amount of material $m$ recovered by plant $p$ during time $t$ (`tonne`) -* $u_{pt}$ - Binary variable that equals 1 if plant $p$ starts operating at time $t$ (`bool`) -* $w_{pt}$ - Extra capacity (amount above the minimum) added to plant $p$ during time $t$ (`tonne`) -* $x_{pt}$ - Binary variable that equals 1 if plant $p$ is operational at time $t$ (`bool`) -* $y_{lpt}$ - Amount of product sent from location $l$ to plant $p$ during time $t$ (`tonne`) -* $z^{\text{disp}}_{mpt}$ - Amount of material $m$ disposed of by plant $p$ during time $t$ (`tonne`) -* $z^{\text{store}}_{pt}$ - Amount of original material in storage at plant $p$ by the end of time period $t$ (`tonne`) -* $z^{\text{proc}}_{mpt}$ - Amount of original material processed by plant $p$ during time period $t$ (`tonne`) + +Symbol | Description | Unit +:-------|:------------|:--- +$q_{mpt}$ | Amount of material $m$ recovered by plant $p$ during time $t$ | tonne +$u_{pt}$ | Binary variable that equals 1 if plant $p$ starts operating at time $t$ | Boolean +$w_{pt}$ | Extra capacity (amount above the minimum) added to plant $p$ during time $t$ | tonne +$x_{pt}$ | Binary variable that equals 1 if plant $p$ is operational at time $t$ | Boolean +$y_{lpt}$ | Amount of product sent from location $l$ to plant $p$ during time $t$ | tonne +$z^{\text{disp}}_{mpt}$ | Amount of material $m$ disposed of by plant $p$ during time $t$ | tonne +$z^{\text{store}}_{pt}$ | Amount of original material in storage at plant $p$ by the end of time period $t$ | tonne +$z^{\text{proc}}_{mpt}$ | Amount of original material processed by plant $p$ during time period $t$ | tonne ### Objective function RELOG minimizes the overall capital, production and transportation costs: +```math \begin{align*} \text{minimize} \;\; & \sum_{t \in T} \sum_{p \in P} \left[ @@ -73,6 +85,7 @@ RELOG minimizes the overall capital, production and transportation costs: & \sum_{t \in T} \sum_{p \in P} \sum_{m \in M} c^{\text{disp}}_{pmt} z_{pmt} \end{align*} +``` In the first line, we have (i) opening costs, if plant starts operating at time $t$, (ii) fixed operating costs, if plant is operational, (iii) additional fixed operating costs coming from expansion performed in all previous time periods up to the current one, and finally (iv) the expansion costs during the current time period. In the second line, we have storage and variable processing costs. @@ -83,14 +96,17 @@ In the fourth line, we have the disposal costs. * All original materials must be sent to a plant: -\begin{align} +```math +\begin{align*} & \sum_{p \in P} y_{lpt} = m^\text{initial}_{lt} & \forall l \in L, t \in T -\end{align} +\end{align*} +``` * Amount received equals amount processed plus stored. Furthermore, all original material should be processed by the end of the simulation. -\begin{align} +```math +\begin{align*} & \sum_{l \in L} y_{lpt} + z^{\text{store}}_{p,t-1} = z^{\text{proc}}_{pt} + z^{\text{store}}_{p,t} & \forall p \in P, t \in T \\ @@ -98,56 +114,70 @@ In the fourth line, we have the disposal costs. & \forall p \in P \\ & z^{\text{store}}_{p,t^{\max}} = 0 & \forall p \in P -\end{align} +\end{align*} +``` * Plants have a limited processing capacity. Furthermore, if a plant is closed, it has zero processing capacity: -\begin{align} +```math +\begin{align*} & z^{\text{proc}}_{pt} \leq m^\text{min}_p x_p + \sum_{i=1}^t w_p & \forall p \in P, t \in T -\end{align} +\end{align*} +``` * Plants have limited storage capacity. Furthermore, if a plant is closed, is has zero storage capacity: -\begin{align} +```math +\begin{align*} & z^{\text{store}}_{pt} \leq m^\text{store}_p x_p & \forall p \in P, t \in T -\end{align} +\end{align*} +``` * Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded: -\begin{align} +```math +\begin{align*} & \sum_{i=1}^t w_p \leq m^\text{max}_p x_p & \forall p \in P, t \in T -\end{align} +\end{align*} +``` * Amount of recovered material is proportional to amount processed: -\begin{align} +```math +\begin{align*} & q_{mpt} = \alpha_{pm} z^{\text{proc}}_{pt} & \forall m \in M, p \in P, t \in T -\end{align} +\end{align*} +``` * Because we only consider a single type of plant, all recovered material must be immediately disposed of. In RELOG's full model, recovered materials may be sent to another plant for further processing. -\begin{align} +```math +\begin{align*} & q_{mpt} = z_{mpt} & \forall m \in M, p \in P, t \in T -\end{align} +\end{align*} +``` * A plant is operational at time $t$ if it was operational at time $t-1$ or it was built at time $t$. This constraint also prevents a plant from being built multiple times. -\begin{align} +```math +\begin{align*} & x_{pt} = x_{p,t-1} + u_{pt} & \forall p \in P, t \in T \setminus \{1\} \\ & x_{p,1} = u_{p,1} & \forall p \in P -\end{align} +\end{align*} +``` * Variable bounds: -\begin{align} +```math +\begin{align*} & q_{mpt} \geq 0 & \forall m \in M, p \in P, t \in T \\ & u_{pt} \in \{0,1\} @@ -162,4 +192,5 @@ In the fourth line, we have the disposal costs. & p \in P, t \in T \\ & z^{\text{disp}}_{mpt}, z^{\text{proc}}_{mpt} \geq 0 & \forall m \in M, p \in P, t \in T -\end{align} +\end{align*} +``` diff --git a/src/docs/reports.md b/docs/src/reports.md similarity index 92% rename from src/docs/reports.md rename to docs/src/reports.md index 8f7090d..4cda24d 100644 --- a/src/docs/reports.md +++ b/docs/src/reports.md @@ -9,7 +9,7 @@ In this page, we also illustrate what types of charts and visualizations can be Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by `RELOG.write_plants_report(solution, filename)`. | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `plant type` | Plant type. | `location name` | Location name. | `year` | What year this row corresponds to. This reports includes one row for each year. @@ -45,7 +45,9 @@ sns.barplot(x="year", .reset_index()); ``` - +```@raw html + +``` * Map showing plant locations (in Python): ```python @@ -65,8 +67,9 @@ points = gp.points_from_xy(data["longitude (deg)"], gp.GeoDataFrame(data, geometry=points).plot(ax=ax); ``` - - +```@raw html + +``` ## Plant outputs report @@ -74,7 +77,7 @@ Report showing amount of products produced, sent and disposed of by each plant, | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `plant type` | Plant type. | `location name` | Location name. | `year` | What year this row corresponds to. This reports includes one row for each year. @@ -101,7 +104,9 @@ sns.barplot(x="amount produced (tonne)", .reset_index()); ``` - +```@raw html + +``` ## Plant emissions report @@ -109,7 +114,7 @@ sns.barplot(x="amount produced (tonne)", Report showing amount of emissions produced by each plant. Generated by `RELOG.write_plant_emissions_report(solution, filename)`. | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `plant type` | Plant type. | `location name` | Location name. | `year` | Year. @@ -133,14 +138,16 @@ sns.barplot(x="plant type", .reset_index()); ``` - +```@raw html + +``` ## Products report Report showing primary product amounts, locations and marginal costs. Generated by `RELOG.write_products_report(solution, filename)`. | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `product name` | Product name. | `location name` | Name of the collection center. | `latitude (deg)` | Latitude of the collection center. @@ -156,7 +163,7 @@ Report showing amount of product sent from initial locations to plants, and from | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `source type` | If product is being shipped from an initial location, equals `Origin`. If product is being shipped from a plant, equals plant type. | `source location name` | Name of the location where the product is being shipped from. | `source latitude (deg)` | Latitude of the source location. @@ -190,7 +197,9 @@ sns.barplot(x="product", .reset_index()); ``` - +```@raw html + +``` * Map of transportation lines (in Python): @@ -233,7 +242,9 @@ gp.GeoDataFrame(data, geometry=points).plot(ax=ax, markersize=50); ``` - +```@raw html + +``` ## Transportation emissions report @@ -241,7 +252,7 @@ gp.GeoDataFrame(data, geometry=points).plot(ax=ax, Report showing emissions for each trip between initial locations and plants, and between pairs of plants. Generated by `RELOG.write_transportation_emissions_report(solution, filename)`. | Column | Description -|:--------------------------------------|---------------| +|:--------------------------------------|:---------------| | `source type` | If product is being shipped from an initial location, equals `Origin`. If product is being shipped from a plant, equals plant type. | `source location name` | Name of the location where the product is being shipped from. | `source latitude (deg)` | Latitude of the source location. @@ -275,4 +286,6 @@ sns.barplot(x="emission type", .reset_index()); ``` - +```@raw html + +``` diff --git a/src/docs/usage.md b/docs/src/usage.md similarity index 92% rename from src/docs/usage.md rename to docs/src/usage.md index b2b864a..9c1e384 100644 --- a/src/docs/usage.md +++ b/docs/src/usage.md @@ -3,22 +3,17 @@ Usage ## 1. Installation -To use RELOG, the first step is to install the [Julia programming language](https://julialang.org/) on your machine. Note that RELOG was developed and tested with Julia 1.5 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, type `]` to switch to package manger mode, then run: +To use RELOG, the first step is to install the [Julia programming language](https://julialang.org/) on your machine. Note that RELOG was developed and tested with Julia 1.8 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, then run: -```text -(@v1.5) pkg> add https://github.com/ANL-CEEESA/RELOG.git +```julia +using Pkg +Pkg.add(name="RELOG", version="0.5") ``` After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: -```text -(@v1.5) pkg> test RELOG -``` - -To update the package to a newer version, type `]` to enter the package manager mode, then run: - -```text -(@v1.5) pkg> update RELOG +```julia +Pkg.test("RELOG") ``` ## 2. Modeling the problem @@ -111,13 +106,17 @@ By default, RELOG internally uses [Cbc](https://github.com/coin-or/Cbc), an open ```julia using RELOG, Gurobi, JuMP -gurobi = optimizer_with_attributes(Gurobi.Optimizer, - "TimeLimit" => 3600, - "MIPGap" => 0.001) - -RELOG.solve("instance.json", - output="solution.json", - optimizer=gurobi) +gurobi = optimizer_with_attributes( + Gurobi.Optimizer, + "TimeLimit" => 3600, + "MIPGap" => 0.001, +) + +RELOG.solve( + "instance.json", + output="solution.json", + optimizer=gurobi, +) ``` ### 5.2 Multi-period heuristics @@ -133,6 +132,8 @@ To solve an instance using this heuristic, use the option `heuristic=true`, as s ```julia using RELOG -solution = RELOG.solve("/home/user/instance.json", - heuristic=true) +solution = RELOG.solve( + "/home/user/instance.json", + heuristic=true, +) ``` diff --git a/juliaw b/juliaw new file mode 100755 index 0000000..b78bc72 --- /dev/null +++ b/juliaw @@ -0,0 +1,75 @@ +#!/bin/bash +# UnitCommitment.jl: Optimization Package for Security-Constrained Unit Commitment +# Copyright (C) 2020-2021, UChicago Argonne, LLC. All rights reserved. +# Released under the modified BSD license. See COPYING.md for more details. + +if [ ! -e Project.toml ]; then + echo "juliaw: Project.toml not found" + exit 1 +fi + +if [ ! -e Manifest.toml ]; then + julia --project=. -e 'using Pkg; Pkg.instantiate()' || exit 1 +fi + +if [ ! -e build/sysimage.so -o Project.toml -nt build/sysimage.so ]; then + echo "juliaw: rebuilding system image..." + + # Generate temporary project folder + rm -rf $HOME/.juliaw + mkdir -p $HOME/.juliaw/src + cp Project.toml Manifest.toml $HOME/.juliaw + NAME=$(julia -e 'using TOML; toml = TOML.parsefile("Project.toml"); "name" in keys(toml) && print(toml["name"])') + if [ ! -z $NAME ]; then + cat > $HOME/.juliaw/src/$NAME.jl << EOF +module $NAME +end +EOF + fi + + # Add PackageCompiler dependencies to temporary project + julia --project=$HOME/.juliaw -e 'using Pkg; Pkg.add(["PackageCompiler", "TOML", "Logging"])' + + # Generate system image scripts + cat > $HOME/.juliaw/sysimage.jl << EOF +using PackageCompiler +using TOML +using Logging + +Logging.disable_logging(Logging.Info) +mkpath("$PWD/build") + +println("juliaw: generating precompilation statements...") +run(\`julia --project="$PWD" --trace-compile="$PWD"/build/precompile.jl \$(ARGS)\`) + +println("juliaw: finding dependencies...") +project = TOML.parsefile("Project.toml") +manifest = TOML.parsefile("Manifest.toml") +deps = Symbol[] +for dep in keys(project["deps"]) + if dep in keys(manifest) + # Up to Julia 1.6 + dep_entry = manifest[dep][1] + else + # Julia 1.7+ + dep_entry = manifest["deps"][dep][1] + end + if "path" in keys(dep_entry) + println(" - \$(dep) [skip]") + else + println(" - \$(dep)") + push!(deps, Symbol(dep)) + end +end + +println("juliaw: building system image...") +create_sysimage( + deps, + precompile_statements_file = "$PWD/build/precompile.jl", + sysimage_path = "$PWD/build/sysimage.so", +) +EOF + julia --project=$HOME/.juliaw $HOME/.juliaw/sysimage.jl $* +else + julia --project=. --sysimage build/sysimage.so $* +fi diff --git a/src/docs/css/custom.css b/src/docs/css/custom.css deleted file mode 100644 index 366aa46..0000000 --- a/src/docs/css/custom.css +++ /dev/null @@ -1,28 +0,0 @@ -.navbar-default { - border-bottom: 0px; - background-color: #fff; - box-shadow: 0px 0px 15px rgba(0, 0, 0, 0.2); -} - -a, .navbar-default a { - color: #06a !important; - font-weight: normal; -} - -.disabled > a { - color: #999 !important; -} - -.navbar-default a:hover, -.navbar-default .active, -.active > a { - background-color: #f0f0f0 !important; -} - -.icon-bar { - background-color: #666 !important; -} - -.navbar-collapse { - border-color: #fff !important; -} \ No newline at end of file diff --git a/src/docs/js/mathjax.js b/src/docs/js/mathjax.js deleted file mode 100644 index bfc06b8..0000000 --- a/src/docs/js/mathjax.js +++ /dev/null @@ -1,8 +0,0 @@ -MathJax.Hub.Config({ - "tex2jax": { inlineMath: [ [ '$', '$' ] ] } -}); -MathJax.Hub.Config({ - config: ["MMLorHTML.js"], - jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"], - extensions: ["MathMenu.js", "MathZoom.js"] -}); \ No newline at end of file diff --git a/src/graph/build.jl b/src/graph/build.jl index ee28413..dc274e7 100644 --- a/src/graph/build.jl +++ b/src/graph/build.jl @@ -7,7 +7,7 @@ using Geodesy function calculate_distance(source_lat, source_lon, dest_lat, dest_lon)::Float64 x = LLA(source_lat, source_lon, 0.0) y = LLA(dest_lat, dest_lon, 0.0) - return round(distance(x, y) / 1000.0, digits = 2) + return round(euclidean_distance(x, y) / 1000.0, digits = 2) end function build_graph(instance::Instance)::Graph From 8f52c047025b8876a5e70888b79deade608acc30 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 26 Aug 2022 13:08:22 -0500 Subject: [PATCH 03/14] Fix broken image link --- docs/src/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/index.md b/docs/src/index.md index ad1397f..bb485e3 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -4,7 +4,7 @@ ```@raw html
- +
``` From 19bec961bd356fc3eab33cc3978b45f4d9c66136 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 26 Aug 2022 13:12:20 -0500 Subject: [PATCH 04/14] GH Actions: Update Julia versions --- .github/workflows/test.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 28624e0..5aa8f86 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -10,7 +10,7 @@ jobs: runs-on: ${{ matrix.os }} strategy: matrix: - version: ['1.3', '1.4', '1.5', '1.6'] + version: ['1.6', '1.7', '1.8'] os: - ubuntu-latest arch: From e7eec937cb164f579c6b4831244f8cfd46c4dce4 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 26 Aug 2022 13:21:42 -0500 Subject: [PATCH 05/14] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 57dfb12..0eff1c1 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ - + ### Documentation From da158eb961dd85daecd397a518f571567fcd514f Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 26 Aug 2022 13:26:15 -0500 Subject: [PATCH 06/14] Update CHANGELOG --- CHANGELOG.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f038847..f3776ff 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,39 +11,43 @@ All notable changes to this project will be documented in this file. [semver]: https://semver.org/spec/v2.0.0.html [pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0 +## [0.5.2] -- 2022-08-26 +### Changed +- Update to JuMP 1.x + ## [0.5.1] -- 2021-07-23 -## Added +### Added - Allow user to specify locations as unique identifiers, instead of latitude and longitude (e.g. `us-state:IL` or `2018-us-county:17043`) - Add what-if scenarios. - Add products report. ## [0.5.0] -- 2021-01-06 -## Added +### Added - Allow plants to store input material for processing in later years ## [0.4.0] -- 2020-09-18 -## Added +### Added - Generate simplified solution reports (CSV) ## [0.3.3] -- 2020-10-13 -## Added +### Added - Add option to write solution to JSON file in RELOG.solve - Improve error message when instance is infeasible - Make output file more readable ## [0.3.2] -- 2020-10-07 -## Added +### Added - Add "building period" parameter ## [0.3.1] -- 2020-07-17 -## Fixed +### Fixed - Fix expansion cost breakdown ## [0.3.0] -- 2020-06-25 -## Added +### Added - Track emissions and energy (transportation and plants) -## Changed +### Changed - Minor changes to input file format: - Make all dictionary keys lowercase - Rename "outputs (tonne)" to "outputs (tonne/tonne)" From 23b3b33146561fc5e967cd9e135467b0ede76042 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 28 Oct 2022 14:05:53 -0500 Subject: [PATCH 07/14] Update README.md --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 0eff1c1..1d66f57 100644 --- a/README.md +++ b/README.md @@ -30,6 +30,7 @@ * **Nwike Iloeje** <> * **John Atkins** * **Kyle Sun** +* **Audrey Gallier** ### License From 48bd3c403f88ea4fe56bbd938f4f358c010eaea9 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Thu, 15 Dec 2022 09:49:38 -0600 Subject: [PATCH 08/14] Switch from Euclidean to approximate driving distance --- CHANGELOG.md | 4 +++ Project.toml | 3 +- docs/src/usage.md | 2 +- src/RELOG.jl | 6 ++-- src/graph/build.jl | 12 ++----- src/graph/dist.jl | 69 ++++++++++++++++++++++++++++++++++++++++ test/graph/build_test.jl | 2 +- test/graph/dist_test.jl | 25 +++++++++++++++ test/runtests.jl | 1 + 9 files changed, 109 insertions(+), 15 deletions(-) create mode 100644 src/graph/dist.jl create mode 100644 test/graph/dist_test.jl diff --git a/CHANGELOG.md b/CHANGELOG.md index f3776ff..5f45517 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,10 @@ All notable changes to this project will be documented in this file. [semver]: https://semver.org/spec/v2.0.0.html [pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0 +# [0.6.0] -- 2022-12-15 +### Changed +- Switch from Euclidean distance to approximate driving distance + ## [0.5.2] -- 2022-08-26 ### Changed - Update to JuMP 1.x diff --git a/Project.toml b/Project.toml index 6a4eab8..038f3c2 100644 --- a/Project.toml +++ b/Project.toml @@ -1,7 +1,7 @@ name = "RELOG" uuid = "a2afcdf7-cf04-4913-85f9-c0d81ddf2008" authors = ["Alinson S Xavier "] -version = "0.5.2" +version = "0.6.0" [deps] CRC = "44b605c4-b955-5f2b-9b6d-d2bd01d3d205" @@ -18,6 +18,7 @@ JSONSchema = "7d188eb4-7ad8-530c-ae41-71a32a6d4692" JuMP = "4076af6c-e467-56ae-b986-b466b2749572" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee" +NearestNeighbors = "b8a86587-4115-5ab1-83bc-aa920d37bbce" OrderedCollections = "bac558e1-5e72-5ebc-8fee-abe8a469f55d" Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7" ProgressBars = "49802e3a-d2f1-5c88-81d8-b72133a6f568" diff --git a/docs/src/usage.md b/docs/src/usage.md index 9c1e384..7a2fe25 100644 --- a/docs/src/usage.md +++ b/docs/src/usage.md @@ -7,7 +7,7 @@ To use RELOG, the first step is to install the [Julia programming language](http ```julia using Pkg -Pkg.add(name="RELOG", version="0.5") +Pkg.add(name="RELOG", version="0.6") ``` After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed: diff --git a/src/RELOG.jl b/src/RELOG.jl index d8d4226..0f39e32 100644 --- a/src/RELOG.jl +++ b/src/RELOG.jl @@ -5,19 +5,19 @@ module RELOG include("instance/structs.jl") - include("graph/structs.jl") +include("instance/geodb.jl") +include("graph/dist.jl") include("graph/build.jl") include("graph/csv.jl") include("instance/compress.jl") -include("instance/geodb.jl") include("instance/parse.jl") include("instance/validate.jl") include("model/build.jl") include("model/getsol.jl") -include("model/solve.jl") include("model/resolve.jl") +include("model/solve.jl") include("reports/plant_emissions.jl") include("reports/plant_outputs.jl") include("reports/plants.jl") diff --git a/src/graph/build.jl b/src/graph/build.jl index dc274e7..12640d6 100644 --- a/src/graph/build.jl +++ b/src/graph/build.jl @@ -2,14 +2,6 @@ # Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved. # Released under the modified BSD license. See COPYING.md for more details. -using Geodesy - -function calculate_distance(source_lat, source_lon, dest_lat, dest_lon)::Float64 - x = LLA(source_lat, source_lon, 0.0) - y = LLA(dest_lat, dest_lon, 0.0) - return round(euclidean_distance(x, y) / 1000.0, digits = 2) -end - function build_graph(instance::Instance)::Graph arcs = [] next_index = 0 @@ -48,13 +40,15 @@ function build_graph(instance::Instance)::Graph end # Build arcs from collection centers to plants, and from one plant to another + metric = _KnnDrivingDistance() for source in [collection_shipping_nodes; plant_shipping_nodes] for dest in process_nodes_by_input_product[source.product] - distance = calculate_distance( + distance = _calculate_distance( source.location.latitude, source.location.longitude, dest.location.latitude, dest.location.longitude, + metric, ) values = Dict("distance" => distance) arc = Arc(source, dest, values) diff --git a/src/graph/dist.jl b/src/graph/dist.jl new file mode 100644 index 0000000..abaecc0 --- /dev/null +++ b/src/graph/dist.jl @@ -0,0 +1,69 @@ +# RELOG: Reverse Logistics Optimization +# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved. +# Released under the modified BSD license. See COPYING.md for more details. + +using Geodesy +using NearestNeighbors +using DataFrames + +Base.@kwdef mutable struct _KnnDrivingDistance + tree = nothing + ratios = nothing +end + +mutable struct _EuclideanDistance end + +function _calculate_distance( + source_lat, + source_lon, + dest_lat, + dest_lon, + ::_EuclideanDistance, +)::Float64 + x = LLA(source_lat, source_lon, 0.0) + y = LLA(dest_lat, dest_lon, 0.0) + return round(euclidean_distance(x, y) / 1000.0, digits = 3) +end + +function _calculate_distance( + source_lat, + source_lon, + dest_lat, + dest_lon, + metric::_KnnDrivingDistance, +)::Float64 + if metric.tree === nothing + basedir = joinpath(dirname(@__FILE__), "..", "..", "data") + csv_filename = joinpath(basedir, "dist_driving.csv") + + # Download pre-computed driving data + if !isfile(csv_filename) + _download_zip( + "https://axavier.org/RELOG/0.6/data/dist_driving_0b9a6ad6.zip", + basedir, + csv_filename, + 0x0b9a6ad6, + ) + end + + # Fit kNN model + df = DataFrame(CSV.File(csv_filename)) + coords = Matrix(df[!, [:source_lat, :source_lon, :dest_lat, :dest_lon]])' + metric.ratios = Matrix(df[!, [:ratio]]) + metric.tree = KDTree(coords) + end + + # Compute Euclidean distance + dist_euclidean = _calculate_distance( + source_lat, + source_lon, + dest_lat, + dest_lon, + _EuclideanDistance(), + ) + + # Predict ratio + idxs, _ = knn(metric.tree, [source_lat, source_lon, dest_lat, dest_lon], 5) + ratio_pred = mean(metric.ratios[idxs]) + return round(dist_euclidean * ratio_pred, digits = 3) +end diff --git a/test/graph/build_test.jl b/test/graph/build_test.jl index 1b52f58..9df3cab 100644 --- a/test/graph/build_test.jl +++ b/test/graph/build_test.jl @@ -21,7 +21,7 @@ using RELOG @test node.outgoing_arcs[1].source.location.name == "C1" @test node.outgoing_arcs[1].dest.location.plant_name == "F1" @test node.outgoing_arcs[1].dest.location.location_name == "L1" - @test node.outgoing_arcs[1].values["distance"] == 1095.62 + @test node.outgoing_arcs[1].values["distance"] == 1695.364 node = process_node_by_location_name["L1"] @test node.location.plant_name == "F1" diff --git a/test/graph/dist_test.jl b/test/graph/dist_test.jl new file mode 100644 index 0000000..cce8b6a --- /dev/null +++ b/test/graph/dist_test.jl @@ -0,0 +1,25 @@ +# RELOG: Reverse Logistics Optimization +# Copyright (C) 2020, UChicago Argonne, LLC. All rights reserved. +# Released under the modified BSD license. See COPYING.md for more details. + +using RELOG + +@testset "KnnDrivingDistance" begin + # Euclidean distance between Chicago and Indianapolis + @test RELOG._calculate_distance( + 41.866, + -87.656, + 39.764, + -86.148, + RELOG._EuclideanDistance(), + ) == 265.818 + + # Approximate driving distance between Chicago and Indianapolis + @test RELOG._calculate_distance( + 41.866, + -87.656, + 39.764, + -86.148, + RELOG._KnnDrivingDistance(), + ) == 316.43 +end diff --git a/test/runtests.jl b/test/runtests.jl index 3fcf070..1da75c7 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -11,6 +11,7 @@ using Test end @testset "Graph" begin include("graph/build_test.jl") + include("graph/dist_test.jl") end @testset "Model" begin include("model/build_test.jl") From 841fbf16fb6c9696246655d19f37a3844ca60105 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Thu, 15 Dec 2022 10:21:21 -0600 Subject: [PATCH 09/14] Make distance metric configurable; fix building period bug --- CHANGELOG.md | 7 +++++-- docs/src/format.md | 5 ++++- instances/s1.json | 3 ++- src/graph/build.jl | 3 +-- src/graph/dist.jl | 20 ++++---------------- src/instance/parse.jl | 26 +++++++++++++++++++++++--- src/instance/structs.jl | 11 +++++++++++ src/schemas/input.json | 3 +++ test/graph/dist_test.jl | 4 ++-- 9 files changed, 55 insertions(+), 27 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5f45517..6aa093c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,8 +12,11 @@ All notable changes to this project will be documented in this file. [pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0 # [0.6.0] -- 2022-12-15 -### Changed -- Switch from Euclidean distance to approximate driving distance +### Added +- Allow RELOG to calculate approximate driving distances, instead of just straight-line distances between points. + +### Fixed +- Fix bug that caused building period parameter to be ignored ## [0.5.2] -- 2022-08-26 ### Changed diff --git a/docs/src/format.md b/docs/src/format.md index 01fdc7d..4164370 100644 --- a/docs/src/format.md +++ b/docs/src/format.md @@ -14,6 +14,7 @@ The **parameters** section describes details about the simulation itself. |:--------------------------|:---------------| |`time horizon (years)` | Number of years in the simulation. |`building period (years)` | List of years in which we are allowed to open new plants. For example, if this parameter is set to `[1,2,3]`, we can only open plants during the first three years. By default, this equals `[1]`; that is, plants can only be opened during the first year. | +|`distance metric` | Metric used to compute distances between pairs of locations. Valid options are: `"Euclidean"`, for the straight-line distance between points; or `"driving"` for an approximated driving distance. If not specified, defaults to `"Euclidean"`. #### Example @@ -21,7 +22,8 @@ The **parameters** section describes details about the simulation itself. { "parameters": { "time horizon (years)": 2, - "building period (years)": [1] + "building period (years)": [1], + "distance metric": "driving", } } ``` @@ -220,6 +222,7 @@ Database | Description | Examples * Plants can be expanded at any time, even long after they are open. * All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next. * Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes. +* Accurate driving distances are only available for the continental United States. ## Output Data Format (JSON) diff --git a/instances/s1.json b/instances/s1.json index e88e8c5..279f1ae 100644 --- a/instances/s1.json +++ b/instances/s1.json @@ -1,6 +1,7 @@ { "parameters": { - "time horizon (years)": 2 + "time horizon (years)": 2, + "distance metric": "driving" }, "products": { "P1": { diff --git a/src/graph/build.jl b/src/graph/build.jl index 12640d6..418ac5e 100644 --- a/src/graph/build.jl +++ b/src/graph/build.jl @@ -40,7 +40,6 @@ function build_graph(instance::Instance)::Graph end # Build arcs from collection centers to plants, and from one plant to another - metric = _KnnDrivingDistance() for source in [collection_shipping_nodes; plant_shipping_nodes] for dest in process_nodes_by_input_product[source.product] distance = _calculate_distance( @@ -48,7 +47,7 @@ function build_graph(instance::Instance)::Graph source.location.longitude, dest.location.latitude, dest.location.longitude, - metric, + instance.distance_metric, ) values = Dict("distance" => distance) arc = Arc(source, dest, values) diff --git a/src/graph/dist.jl b/src/graph/dist.jl index abaecc0..777ad87 100644 --- a/src/graph/dist.jl +++ b/src/graph/dist.jl @@ -6,19 +6,12 @@ using Geodesy using NearestNeighbors using DataFrames -Base.@kwdef mutable struct _KnnDrivingDistance - tree = nothing - ratios = nothing -end - -mutable struct _EuclideanDistance end - function _calculate_distance( source_lat, source_lon, dest_lat, dest_lon, - ::_EuclideanDistance, + ::EuclideanDistance, )::Float64 x = LLA(source_lat, source_lon, 0.0) y = LLA(dest_lat, dest_lon, 0.0) @@ -30,7 +23,7 @@ function _calculate_distance( source_lon, dest_lat, dest_lon, - metric::_KnnDrivingDistance, + metric::KnnDrivingDistance, )::Float64 if metric.tree === nothing basedir = joinpath(dirname(@__FILE__), "..", "..", "data") @@ -54,13 +47,8 @@ function _calculate_distance( end # Compute Euclidean distance - dist_euclidean = _calculate_distance( - source_lat, - source_lon, - dest_lat, - dest_lon, - _EuclideanDistance(), - ) + dist_euclidean = + _calculate_distance(source_lat, source_lon, dest_lat, dest_lon, EuclideanDistance()) # Predict ratio idxs, _ = knn(metric.tree, [source_lat, source_lon, dest_lat, dest_lon], 5) diff --git a/src/instance/parse.jl b/src/instance/parse.jl index 5720393..d105aee 100644 --- a/src/instance/parse.jl +++ b/src/instance/parse.jl @@ -23,10 +23,23 @@ function parse(json)::Instance validate(json, Schema(json_schema)) building_period = [1] - if "building period (years)" in keys(json) - building_period = json["building period (years)"] + if "building period (years)" in keys(json["parameters"]) + building_period = json["parameters"]["building period (years)"] end + distance_metric = EuclideanDistance() + if "distance metric" in keys(json["parameters"]) + metric_name = json["parameters"]["distance metric"] + if metric_name == "driving" + distance_metric = KnnDrivingDistance() + elseif metric_name == "Euclidean" + # nop + else + error("Unknown distance metric: $metric_name") + end + end + @show distance_metric + plants = Plant[] products = Product[] collection_centers = CollectionCenter[] @@ -176,5 +189,12 @@ function parse(json)::Instance @info @sprintf("%12d collection centers", length(collection_centers)) @info @sprintf("%12d candidate plant locations", length(plants)) - return Instance(T, products, collection_centers, plants, building_period) + return Instance( + T, + products, + collection_centers, + plants, + building_period, + distance_metric, + ) end diff --git a/src/instance/structs.jl b/src/instance/structs.jl index 190ae9b..692fbca 100644 --- a/src/instance/structs.jl +++ b/src/instance/structs.jl @@ -48,10 +48,21 @@ mutable struct Plant storage_cost::Vector{Float64} end + +abstract type DistanceMetric end + +Base.@kwdef mutable struct KnnDrivingDistance <: DistanceMetric + tree = nothing + ratios = nothing +end + +mutable struct EuclideanDistance <: DistanceMetric end + mutable struct Instance time::Int64 products::Vector{Product} collection_centers::Vector{CollectionCenter} plants::Vector{Plant} building_period::Vector{Int64} + distance_metric::DistanceMetric end diff --git a/src/schemas/input.json b/src/schemas/input.json index fd46ec0..1cafb71 100644 --- a/src/schemas/input.json +++ b/src/schemas/input.json @@ -14,6 +14,9 @@ "properties": { "time horizon (years)": { "type": "number" + }, + "distance metric": { + "type": "string" } }, "required": [ diff --git a/test/graph/dist_test.jl b/test/graph/dist_test.jl index cce8b6a..d643602 100644 --- a/test/graph/dist_test.jl +++ b/test/graph/dist_test.jl @@ -11,7 +11,7 @@ using RELOG -87.656, 39.764, -86.148, - RELOG._EuclideanDistance(), + RELOG.EuclideanDistance(), ) == 265.818 # Approximate driving distance between Chicago and Indianapolis @@ -20,6 +20,6 @@ using RELOG -87.656, 39.764, -86.148, - RELOG._KnnDrivingDistance(), + RELOG.KnnDrivingDistance(), ) == 316.43 end From 9191474df83df1e618a74b66c6609c2af78e9117 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Thu, 15 Dec 2022 10:36:44 -0600 Subject: [PATCH 10/14] Bump version to 0.6 --- Makefile | 2 +- README.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Makefile b/Makefile index 0b8ace3..e95cd0a 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -VERSION := 0.5 +VERSION := 0.6 clean: rm -rfv build Manifest.toml test/Manifest.toml deps/formatter/build deps/formatter/Manifest.toml diff --git a/README.md b/README.md index 1d66f57..a581688 100644 --- a/README.md +++ b/README.md @@ -15,14 +15,14 @@ - + ### Documentation - * [Usage](https://anl-ceeesa.github.io/RELOG/0.5/usage) - * [Input and Output Data Formats](https://anl-ceeesa.github.io/RELOG/0.5/format) - * [Simplified Solution Reports](https://anl-ceeesa.github.io/RELOG/0.5/reports) - * [Optimization Model](https://anl-ceeesa.github.io/RELOG/0.5/model) + * [Usage](https://anl-ceeesa.github.io/RELOG/0.6/usage) + * [Input and Output Data Formats](https://anl-ceeesa.github.io/RELOG/0.6/format) + * [Simplified Solution Reports](https://anl-ceeesa.github.io/RELOG/0.6/reports) + * [Optimization Model](https://anl-ceeesa.github.io/RELOG/0.6/model) ### Authors From 51ff8eb1301af38229f30c62380387fb1ada2b17 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Thu, 15 Dec 2022 11:03:44 -0600 Subject: [PATCH 11/14] Restrict NearestNeighbors version; remove debug statement --- Project.toml | 1 + src/instance/parse.jl | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/Project.toml b/Project.toml index 038f3c2..baacbfd 100644 --- a/Project.toml +++ b/Project.toml @@ -45,3 +45,4 @@ ProgressBars = "1" Shapefile = "0.8" ZipFile = "0.10" julia = "1" +NearestNeighbors = "0.4" diff --git a/src/instance/parse.jl b/src/instance/parse.jl index d105aee..255af28 100644 --- a/src/instance/parse.jl +++ b/src/instance/parse.jl @@ -38,7 +38,6 @@ function parse(json)::Instance error("Unknown distance metric: $metric_name") end end - @show distance_metric plants = Plant[] products = Product[] From d1f6796c96a56ed84dce41d748dedb8bc82fb1fa Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Fri, 16 Dec 2022 15:33:16 -0600 Subject: [PATCH 12/14] Update CHANGELOG.md --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6aa093c..a257a56 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ All notable changes to this project will be documented in this file. [semver]: https://semver.org/spec/v2.0.0.html [pkjjl]: https://pkgdocs.julialang.org/v1/compatibility/#compat-pre-1.0 -# [0.6.0] -- 2022-12-15 +## [0.6.0] -- 2022-12-15 ### Added - Allow RELOG to calculate approximate driving distances, instead of just straight-line distances between points. From 79748e3c13390e39306be7373c0536c43bf8b117 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Tue, 24 Jan 2023 10:27:41 -0600 Subject: [PATCH 13/14] Dist: Drop NaN in training dataset --- src/graph/dist.jl | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/src/graph/dist.jl b/src/graph/dist.jl index 777ad87..a5e1abf 100644 --- a/src/graph/dist.jl +++ b/src/graph/dist.jl @@ -40,7 +40,8 @@ function _calculate_distance( end # Fit kNN model - df = DataFrame(CSV.File(csv_filename)) + df = DataFrame(CSV.File(csv_filename, missingstring="NaN")) + dropmissing!(df) coords = Matrix(df[!, [:source_lat, :source_lon, :dest_lat, :dest_lon]])' metric.ratios = Matrix(df[!, [:ratio]]) metric.tree = KDTree(coords) @@ -53,5 +54,7 @@ function _calculate_distance( # Predict ratio idxs, _ = knn(metric.tree, [source_lat, source_lon, dest_lat, dest_lon], 5) ratio_pred = mean(metric.ratios[idxs]) - return round(dist_euclidean * ratio_pred, digits = 3) + dist_pred = round(dist_euclidean * ratio_pred, digits = 3) + isfinite(dist_pred) || error("non-finite distance detected: $dist_pred") + return dist_pred end From 50d53f628fb979f28c28d52a86f20f0db2a797f4 Mon Sep 17 00:00:00 2001 From: "Alinson S. Xavier" Date: Tue, 24 Jan 2023 10:31:40 -0600 Subject: [PATCH 14/14] Reformat source code --- src/graph/dist.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/graph/dist.jl b/src/graph/dist.jl index a5e1abf..05fe687 100644 --- a/src/graph/dist.jl +++ b/src/graph/dist.jl @@ -40,7 +40,7 @@ function _calculate_distance( end # Fit kNN model - df = DataFrame(CSV.File(csv_filename, missingstring="NaN")) + df = DataFrame(CSV.File(csv_filename, missingstring = "NaN")) dropmissing!(df) coords = Matrix(df[!, [:source_lat, :source_lon, :dest_lat, :dest_lon]])' metric.ratios = Matrix(df[!, [:ratio]])