ANL-CEEESA
/
RELOG
mirror of https://github.com/ANL-CEEESA/RELOG.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs

Browse Source
pull/34/head
Alinson S. Xavier 6 months ago
parent f82a1d121d
commit 40947190ad
16 changed files with 1026 additions and 0 deletions
Show Stats Download Patch File Download Diff File

5
docs/Project.toml
Unescape View File

@ -0,0 +1,5 @@
[deps]
BetterFileWatching = "c9fd44ac-77b5-486c-9482-9798bd063cc6"
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
RELOG = "a2afcdf7-cf04-4913-85f9-c0d81ddf2008"
Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"

26
docs/make.jl
Unescape View File

@ -0,0 +1,26 @@
using Documenter
using RELOG
using BetterFileWatching
function make()
makedocs(
sitename="RELOG",
pages=[
"Home" => "index.md",
"User guide" => [
"problem.md",
"format.md",
]
],
format = Documenter.HTML(
assets=["assets/custom.css"],
)
)
end
function watch()
make()
watch_folder("src") do event
make()
end
end

36
docs/src/assets/custom.css
Unescape View File

@ -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);
}

BIN
docs/src/assets/ex_amount_produced.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 52 KiB

BIN
docs/src/assets/ex_emissions.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 37 KiB

BIN
docs/src/assets/ex_plant_cost_per_year.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

BIN
docs/src/assets/ex_plant_locations.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

BIN
docs/src/assets/ex_transportation.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 586 KiB

BIN
docs/src/assets/ex_transportation_amount_distance.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 29 KiB

BIN
docs/src/assets/ex_transportation_emissions.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 32 KiB

BIN
docs/src/assets/relog.png
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 2.0 MiB

217
docs/src/format.md
Unescape View File

@ -0,0 +1,217 @@
# Input data format
RELOG accepts as input a JSON file with four sections: `parameters`, `products`, `centers` and `plants`. Below, we describe each section in more detail.
## Parameters
| 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. |
| `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
```json
{
"parameters": {
"time horizon (years)": 4,
"building period (years)": [1],
"distance metric": "driving"
}
}
```
## Products
| 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. |
#### Example
```json
{
"products": {
"P1": {
"transportation cost ($/km/tonne)": 0.015,
"transportation energy (J/km/tonne)": 0.12,
"transportation emissions (tonne/km/tonne)": {
"CO2": 0.052,
"CH4": 0.003
}
}
}
}
```
## Centers
| Key | Description |
| :------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `latitude (deg)` | The latitude of the center. |
| `longitude (deg)` | The longitude of the center. |
| `input` | The name of the product this center takes as input from the plants. May be `null` if the center accept no input product. |
| `outputs` | List of output products collected by the center. May be `[]` if none. |
| `fixed output (tonne)` | Dictionary mapping the name of each output product to the amount generated by this center each year, regardless of how much input the center receives. For example, if this field equals to `{"P1": [1.0, 2.0, 3.0, 4.0]}`, then this center generates 1.0, 2.0, 3.0 and 4.0 tonnes of P2 in years 1, 2, 3 and 4, respectively. |
| `variable output (tonne/tonne)` | Dictionary mapping the name of each output product to the amount of output generated, for each tonne of input material, and for each year after the input is received. For example, in a 4-year simulation, if this field equals to `{"P1": [0.1, 0.3, 0.6, 0.0]}` and the center receives 1.0, 2.0, 3.0 and 4.0 tonnes of input material in years 1, 2, 3 and 4, then the center will produce $1.0 * 0.1 = 0.1$ of P1 in the first year, $1.0 * 0.3 + 2.0 * 0.1 = 0.5$ the second year, $1.0 * 0.6 + 2.0 * 0.3 + 3.0 * 0.1 = 1.5$ in the third year, and $2.0 * 0.6 + 3.0 * 0.3 + 4.0 * 0.1 = 2.5$ in the final year. |
| `revenue ($/tonne)` | Revenue generated by each tonne of input material sent to the center. If the center accepts no input, this should be `null` |
| `collection cost ($/tonne)` | Dictionary mapping the name of each output product to the cost of collecting one tonne of the product. |
| `operating cost ($)` | Fixed cost to operate the center for one year, regardless of amount of product received or generated. |
| `disposal limit (tonne)` | Dictionary mapping the name of each output product to the maximum disposal amount allower per year of the product at the center. Entry may be `null` if unlimited. |
| `disposal cost ($/tonne)` | Dictionary mapping the name of each output product to the cost to dispose one tonne of the product at the center. |
```json
{
"centers": {
"C1": {
"latitude (deg)": 41.881,
"longitude (deg)": -87.623,
"input": "P1",
"outputs": ["P2", "P3"],
"fixed output (tonne)": {
"P2": [100, 50, 0, 0],
"P3": [20, 10, 0, 0]
},
"variable output (tonne/tonne)": {
"P2": [0.12, 0.25, 0.12, 0.0],
"P3": [0.25, 0.25, 0.25, 0.0]
},
"revenue ($/tonne)": [12.0, 12.0, 12.0, 12.0],
"collection cost ($/tonne)": {
"P2": [0.25, 0.25, 0.25, 0.25],
"P3": [0.37, 0.37, 0.37, 0.37]
},
"operating cost ($)": [150.0, 150.0, 150.0, 150.0],
"disposal limit (tonne)": {
"P2": [0, 0, 0, 0],
"P3": [null, null, null, null]
},
"disposal cost ($/tonne)": {
"P2": [0.23, 0.23, 0.23, 0.23],
"P3": [1.0, 1.0, 1.0, 1.0]
}
},
"C2": {
"latitude (deg)": 41.881,
"longitude (deg)": -87.623,
"input": null,
"outputs": ["P4"],
"variable output (tonne/tonne)": {
"P4": [0, 0, 0, 0]
},
"fixed output (tonne)": {
"P4": [50, 60, 70, 80]
},
"revenue ($/tonne)": null,
"collection cost ($/tonne)": {
"P4": [0.25, 0.25, 0.25, 0.25]
},
"operating cost ($)": [150.0, 150.0, 150.0, 150.0],
"disposal limit (tonne)": {
"P4": [null, null, null, null]
},
"disposal cost ($/tonne)": {
"P4": [0, 0, 0, 0]
}
},
"C3": {
"latitude (deg)": 41.881,
"longitude (deg)": -87.623,
"input": "P1",
"outputs": [],
"variable output (tonne/tonne)": {},
"constant output (tonne)": {},
"revenue ($/tonne)": [12.0, 12.0, 12.0, 12.0],
"collection cost ($/tonne)": {},
"operating cost ($)": [150.0, 150.0, 150.0, 150.0],
"disposal limit (tonne)": {},
"disposal cost ($/tonne)": {}
}
}
}
```
## Plants
| Key | Description |
| :----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `latitude (deg)` | The latitude of the plant, in degrees. |
| `longitude (deg)` | The longitude of the plant, in degrees. |
| `input mix (%)` | Dictionary mapping the name of each input product to the amount required (as a percentage). Must sum to 100%. |
| `output (tonne)` | Dictionary mapping the name of each output product to the amount produced (in tonne) for one tonne of input mix. |
| `processing emissions (tonne)` | A dictionary mapping the name of each greenhouse gas, produced to process each tonne of input, to the amount of gas produced (in tonne). |
| `storage cost ($/tonne)` | Dictionary mapping the name of each input product to the cost of storing the product for one year at the plant for later processing. |
| `storage limit (tonne)` | Dictionary mapping the name of each input product to the maximum amount allowed in storage at any time. May be `null` if unlimited. |
| `disposal cost ($/tonne)` | Dictionary mapping the name of each output product to the cost of disposing it at the plant. |
| `disposal limit (tonne)` | Dictionary mapping the name of each output product to the maximum amount allowed to be disposed of at the plant. May be `null` if unlimited. |
| `capacities` | List describing what plant sizes are allowed, and their characteristics. |
The entries in the `capacities` list should be dictionaries with the following
keys:
| Key | Description |
| :---------------------------------- | :-------------------------------------------------------------------------------------------------- |
| `size (tonne)` | The size of the plant. |
| `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. |
| `initial capacity (tonne)` | Capacity already available. If the plant has not been built yet, this should be `0`. |
```json
{
"plants": {
"L1": {
"latitude (deg)": 41.881,
"longitude (deg)": -87.623,
"input mix (%)": {
"P1": 95.3,
"P2": 4.7
},
"output (tonne)": {
"P3": 0.25,
"P4": 0.12,
"P5": 0.1
},
"processing emissions (tonne)": {
"CO2": 0.1
},
"storage cost ($/tonne)": {
"P1": 0.1,
"P2": 0.1
},
"storage limit (tonne)": {
"P1": 100,
"P2": null
},
"disposal cost ($/tonne)": {
"P3": 0,
"P4": 0.86,
"P5": 0.25,
},
"disposal limit (tonne)": {
"P3": null,
"P4": 1000.0,
"P5": 1000.0
},
"capacities": [
{
"size": 100,
"opening cost ($)": 500,
"fixed operating cost ($)": 300,
"variable operating cost ($/tonne)": 5.0
},
{
"size": 500,
"opening cost ($)": 1000.0,
"fixed operating cost ($)": 400.0,
"variable operating cost ($/tonne)": 5.0.
}
],
"initial capacity (tonne)": 0,
}
}
}
```

62
docs/src/index.md
Unescape View File

@ -0,0 +1,62 @@
# RELOG -- Supply Chain Design, Analysis and Optimization
**RELOG** is an open-source package designed to optimize supply chains for
forward, reverse and circular manufacturing. Using mixed-integer linear
optimization, RELOG helps users determine strategic decisions such as:
- Where and when to build manufacturing and recycling plants
- The size of these plants, when to expand them, and by how much
- The sources for each plant's input materials and the destinations for their
processed outputs
- Whether to process input materials immediatelly or store them for later use
RELOG has been successully applied in research at various laboratories and
universities, focusing on areas like critical material recovery from spent NiMH
and Li-Ion batteries, biomass processing for hydrogen production, and the
recycling of electronics, plastics and solar PV materials, among others. See
references for more details.
## Screenshots
```@raw html
<center>
<img src="assets/relog.png" width="1000px"/>
</center>
```
## Authors
- **Alinson S. Xavier,** Argonne National Laboratory <axavier@anl.gov>
- **Nwike Iloeje,** Argonne National Laboratory <ciloeje@anl.gov>
- **Kavitha G. Menon,** Argonne National Laboratory
- **John Atkins,** Argonne National Laboratory
- **Kyle Sun,** Argonne National Laboratory
- **Audrey Gallier,** Argonne National Laboratory
## License
```text
RELOG: Reverse Logistics Optimization
Copyright © 2020-2025, UChicago Argonne, LLC. All Rights Reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted
provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of
conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other materials provided
with the distribution.
3. Neither the name of the copyright holder nor the names of its contributors may be used to
endorse or promote products derived from this software without specific prior written
permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
```

257
docs/src/problem.md
Unescape View File

@ -0,0 +1,257 @@
# Mathematical problem definition
## Overview and assumptions
The mathematical model employed by RELOG is based on three main components:
1. **Products and Materials:** Inputs and outputs for both manufacturing and
recycling plants. This include raw materials, wheter virgin or recovered, and
final products, whether new or at their end-of-life. Each product has
associated transportation parameters, such as costs, energy and emissions.
2. **Manufacturing and Recycling Plants:** Facilities that take in specific
materials and produce certain products. The outputs can be sent to another
plant for further processing, to a collection & distribution center for
customer sale, or simply disposed of at landfill. Plants have associated
costs (capital, fixed and operating), as well as various limits (processing
capacity, storage and disposal limits).
3. **Collection and Distribution Centers:** Facilities that receive final
products from the plants, sell them to customers, and then collect them back
once they reach their end-of-life. Collected products can either be sent to a
plant for recycling or disposed of at a local landfill. Centers have
associated revenue and various costs, such as operating cost, collection cost
and disposal cost. The amount of material collected by a center can either be
a fixed rate per year, or depend on the amount of product sold at the center
in previous years.
!!! note
- We assume that transportation costs, energy and emissions scale linearly with transportation distance and amount being transported. Distances between locations are calculated using either approximated driving distances (continental U.S. only) or straight-line distances.
- Once a plant is opened, we assume that it remains open until the end of the planning horizon. Similarly, once a plant is expanded, its size cannot be reduced at a later time.
- In addition to serving as a source of end-of-life products, centers can also serve as a souce for virgin materials. In this case, the center does not receive any inputs from manufacturing or recycling plants, and it generates the desired material at a fixed rate. Collection cost, in this case, refers to the cost to produce the virgin material.
- We assume that centers accept either no input product, or a single input product.
## Sets
| Symbol | Description |
| :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| $C$ | Set of collection and distribution centers |
| $P$ | Set of manufacturing and recycling plants |
| $M$ | Set of products and materials |
| $M^+_u$ | Set of output products of plant/center $u$. |
| $M^-_u$ | Set of input products of plant/center $u$. |
| $T$ | Set of time periods in the planning horizon. We assume $T=\{1,\ldots,t^{max}\}.$ |
| $E$ | Set of transportation edges. Specifically, $(u,v,m) \in E$ if $m$ is an output of $u$ and an input of $v$, where $m \in M$ and $u, v \in P \cup C$. |
| $E^-(v)$ | Set of incoming edges for plant/center v. Specifically, edges $(u,m)$ such that $(u,v,m) \in E$. |
| $E^+(u)$ | Set of outgoing edges for plant/center u. Specifically, edges $(v,m)$ such that $(u,v,m) \in E$. |
## Constants
| Symbol | Description | Unit |
| :-------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------ |
| $K^{\text{dist}}_{uv}$ | Distance between plants/centers $u$ and $v$ | km |
| $K^\text{cap}_{p}$ | Capacity of plant $p$, if the plant is open | tonne |
| $K^\text{disp-limit}_{pmt}$ | Maximum amount of material $m$ that can be disposed of at plant $p$ at time $t$ | tonne |
| $K^\text{mix}_{pmt}$ | If plant $p$ receives one tonne of input material at time $t$, then $K^\text{mix}_{pmt}$ is the amount of product $m$ in this mix. Must be between zero and one, and the sum of these amounts must equal to one. | tonne |
| $K^\text{output}_{pmt}$ | Amount of material $m$ produced by plant $p$ at time $t$ for each tonne of input material processed | tonne |
| $R^\text{tr}_{mt}$ | Cost to send material $m$ at time $t$ | \$/km-tonne |
| $R^\text{collect}_{cmt}$ | Cost of collecting material $m$ at center $c$ at time $t$ | \$/tonne |
| $R^\text{disp}_{umt}$ | Cost to dispose of material at plant/center $u$ at time $t$ | \$/tonne |
| $R^\text{fix}_{ut}$ | Fixed operating cost for plant/center $u$ at time $t$ | \$ |
| $R^\text{open}_{pt}$ | Cost to open plant $p$ at time $t$ | \$ |
| $R^\text{rev}_{ct}$ | Revenue for selling the input product of center $c$ at this center at time $t$ | \$/tonne |
| $R^\text{var}_{pt}$ | Cost to process one tonne of input material at plant $p$ at time $t$ | \$/tonne |
| $K^\text{out-fix}_{cmt}$ | Fixed amount of material $m$ collected at center $m$ at time $t$ | \$/tonne |
| $K^\text{out-var}_{c,m,i}$ | Factor used to calculate variable amount of material $m$ collected at center $m$. See `eq_z_collected` for more details. | -- |
| $K^\text{out-var-len}_{cm}$ | Length of the $K^\text{out-var}_{c,m,*}$ vector. | -- |
## Decision variables
| Symbol | JuMP name | Description | Unit |
| :--------------------------- | :------------------------------- | :------------------------------------------------------------------------------- | :----- |
| $x_{pt}$ | `x[p.name, t]` | One if plant $p$ is operational at time $t$ | binary |
| $y_{uvmt}$ | `y[u.name, v.name, m.name, t]` | Amount of product $m$ sent from plant/center $u$ to plant/center $v$ at time $t$ | tonne |
| $z^{\text{collected}}_{cmt}$ | `z_collected[c.name, m.name, t]` | Amount of material $m$ collected by center $c$ at time $t$ | tonne |
| $z^{\text{disp}}_{umt}$ | `z_disp[u.name, m.name, t]` | Amount of product $m$ disposed of at plant/center $u$ at time $t$ | tonne |
| $z^{\text{input}}_{ut}$ | `z_input[u.name, t]` | Total plant/center input at time $t$ | tonne |
| $z^{\text{prod}}_{umt}$ | `z_prod[u.name, m.name, t]` | Amount of product $m$ produced by plant/center $u$ at time $t$ | tonne |
## Objective function
The goals is to minimize a linear objective function with the following terms:
- Transportation costs, which depend on transportation distance
$K^{\text{dist}}_{uv}$ and product-specific factor $R^\text{tr}_{mt}$:
```math
\sum_{(u, v, m) \in E} \sum_{t \in T} K^{\text{dist}}_{uv} R^\text{tr}_{mt} y_{uvmt}
```
- Center revenue, obtained by selling products received from manufacturing and
recycling plants:
```math
- \sum_{c \in C} \sum_{(p,m) \in E^-(c)} \sum_{t \in T} R^\text{rev}_{ct} y_{pcmt}
```
- Center collection cost, incurred for each tonne of output material sent to a
plant:
```math
\sum_{c \in C} \sum_{(p,m) \in E^+(c)} \sum_{t \in T} R^\text{collect}_{cmt} y_{cpmt}
```
- Center disposal cost, incurred when disposing of output material, instead of
sending it to a plant:
```math
\sum_{c \in C} \sum_{m \in M^+_c} \sum_{t \in T} R^\text{disp}_{cmt} z^\text{disp}_{cmt}
```
- Center fixed operating cost, incurred for every time period, regardless of
input or output amounts:
```math
\sum_{c \in C} \sum_{t \in T} R^\text{fix}_{ct}
```
- Plant disposal cost, incurred for each tonne of product discarded at the
plant:
```math
\sum_{p \in P} \sum_{m \in M^+_p} \sum_{t \in T} R^\text{disp}_{pmt} z^\text{disp}_{pmt}
```
- Plant opening cost:
```math
\sum_{p \in P} \sum_{t \in T} R^\text{open}_{pt} \left(
x_{pt} - x_{p,t-1}
\right)
```
- Plant fixed operating cost, incurred for every time period, regardless of
input or output amounts, as long as the plant is operational:
```math
\sum_{p \in P} \sum_{t \in T} R^\text{fix}_{pt} x_{pt}
```
- Plant variable operating cost, incurred for each tonne of input material
received by the plant:
```math
\sum_{p \in P} \sum_{(u,m) \in E^-(p)} \sum_{t \in T} R^\text{var}_{pt} y_{upmt}
```
## Constraints
- Definition of plant input (`eq_z_input[p.name, t]`):
```math
\begin{align*}
& z^{\text{input}}_{pt} = \sum_{(u,m) \in E^-(p)} y_{upmt}
& \forall p \in P, t \in T
\end{align*}
```
- Plant input mix must have correct proportion
(`eq_input_mix[p.name, m.name, t]`):
```math
\begin{align*}
& \sum_{u : (u,m) \in E^-(p)} y_{upmt}
= K^\text{mix}_{pmt} z^{\text{input}}_{pt}
& \forall p \in P, m \in M^-_p, t \in T
\end{align*}
```
- Definition of amount produced by a plant (`eq_z_prod[p.name, m.name, t]`):
```math
\begin{align*}
& z^\text{prod}_{pmt} = K^\text{output}_{pmt} z^\text{input}_{pt}
& \forall p \in P, m \in M^+_p, t \in T
\end{align*}
```
- Material produced by a plant must be sent somewhere or disposed of
(`eq_balance[p.name, m.name, t]`):
```math
\begin{align*}
& z^\text{prod}_{pmt} = \sum_{v : (v,m) \in E^+(p)} y_{pvmt} + z^\text{disp}_{pmt}
& \forall p \in P, m \in M^+_p, t \in T
\end{align*}
```
- Plants have a maximum capacity; furthermore, if the plant is not open, its
capacity is zero (`eq_capacity[p.name,t]`)
```math
\begin{align*}
& z^\text{input}_{pt} \leq K^\text{cap}_p x_{pt}
& \forall p \in P, t \in T
\end{align*}
```
- Disposal limit at the plants (`eq_keep_open[p.name, t]`):
```math
\begin{align*}
& z^\text{disp}_{pmt} \leq K^\text{disp-limit}_{pmt}
& \forall p \in P, m \in M^+_p, t \in T
\end{align*}
```
- Once a plant is built, it must remain open until the end of the planning
horizon (`eq_keep_open[p.name, t]`):
```math
\begin{align*}
& x_{pt} \geq x_{p,t-1}
& \forall p \in P, t \in T
\end{align*}
```
- Definition of center input (`eq_z_input[c.name, t]`):
```math
\begin{align*}
& z^\text{input}_{ct} = \sum_{u : (u,m) \in E^-(c)} y_{ucmt}
& \forall c \in C, t \in T
\end{align*}
```
- Calculation of amount collected by the center
(`eq_z_collected[c.name, m.name, t]`). In the equation below,
$K^\text{out-var-len}$ is the length of the $K^\text{out-var}_{c,m,*}$ vector.
```math
\begin{align*}
& z^\text{collected}_{cmt}
= \sum_{i=0}^{\min\{K^\text{out-var-len}_{cm}-1,t-1\}} K^\text{out-var}_{c,m,i+1} z^\text{input}_{c,t-i}
+ K^\text{out-fix}_{cmt}
& \forall c \in C, m \in M^+_c, t \in T
\end{align*}
```
- Products collected at centers must be sent somewhere or disposed of
(`eq_balance[c.name, m.name, t]`):
```math
\begin{align*}
& z^\text{collected}_{cmt} = \sum_{v : (v,m) \in E^+(c)} y_{cvmt} + z^\text{disp}_{cmt}
& \forall c \in C, m \in M^+_c, t \in T
\end{align*}
```
- Disposal limit at the centers (`eq_disposal_limit[c.name, m.name, t]`):
```math
\begin{align*}
& z^\text{disp}_{cmt} \leq K^\text{disp-limit}_{cmt}
& \forall c \in C, m \in M^+_c, t \in T
\end{align*}
```

292
docs/src/reports.md
Unescape View File

@ -0,0 +1,292 @@
# Solution reports
In addition to the full output format described in [data formats](format.md), RELOG can also generate a number of simplified reports in tabular data format (CSV), which can be more easily processed by spreadsheet software (such as Microsoft Excel), by data analysis libraries (such as Pandas) or by relational databases (such as SQLite).
In this page, we also illustrate what types of charts and visualizations can be produced from these tabular data files. The sample charts have been produced using Python, matplotlib, seaborn and geopandas.
## Plants report
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.
| `latitude (deg)` | Latitude of the plant.
| `longitude (deg)` | Longitude of the plant.
| `capacity (tonne)` | Capacity of the plant at this point in time.
| `amount received (tonne)` | Amount of input material received by the plant this year.
| `amount processed (tonne)` | Amount of input material processed by the plant this year.
| `amount in storage (tonne)` | Amount of input material in storage at the end of the year.
| `utilization factor (%)` | Amount processed by the plant this year divided by current plant capacity.
| `energy (GJ)` | Amount of energy expended by the plant this year.
| `opening cost ($)` | Amount spent opening the plant. This value is only positive if the plant became operational this year.
| `expansion cost ($)` | Amount spent this year expanding the plant capacity.
| `fixed operating cost ($)` | Amount spent for keeping the plant operational this year.
| `variable operating cost ($)` | Amount spent this year to process the input material.
| `storage cost ($)` | Amount spent this year on storage.
| `total cost ($)` | Sum of all previous plant costs.
### Sample charts
* Bar plot with total plant costs per year, grouped by plant type (in Python):
```python
import pandas as pd
import seaborn as sns; sns.set()
data = pd.read_csv("plants_report.csv")
sns.barplot(x="year",
y="total cost ($)",
hue="plant type",
data=data.groupby(["plant type", "year"])
.sum()
.reset_index());
```
```@raw html
<img src="../assets/ex_plant_cost_per_year.png" width="500px"/>
```
* Map showing plant locations (in Python):
```python
import pandas as pd
import geopandas as gp
# Plot base map
world = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))
ax = world.plot(color='white', edgecolor='50', figsize=(13,6))
ax.set_ylim([23, 50])
ax.set_xlim([-128, -65])
# Plot plant locations
data = pd.read_csv("nimh_plants.csv")
points = gp.points_from_xy(data["longitude (deg)"],
data["latitude (deg)"])
gp.GeoDataFrame(data, geometry=points).plot(ax=ax);
```
```@raw html
<img src="../assets/ex_plant_locations.png" width="1000px"/>
```
## Plant outputs report
Report showing amount of products produced, sent and disposed of by each plant, as well as disposal costs. Generated by `RELOG.write_plant_outputs_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.
| `product name` | Product being produced.
| `amount produced (tonne)` | Amount of product produced this year.
| `amount sent (tonne)` | Amount of product produced by this plant and sent to another plant for further processing this year.
| `amount disposed (tonne)` | Amount produced produced by this plant and immediately disposed of locally this year.
| `disposal cost ($)` | Disposal cost for this year.
### Sample charts
* Bar plot showing total amount produced for each product, grouped by year (in Python):
```python
import pandas as pd
import seaborn as sns; sns.set()
data = pd.read_csv("plant_outputs_report.csv")
sns.barplot(x="amount produced (tonne)",
y="product name",
hue="year",
data=data.groupby(["product name", "year"])
.sum()
.reset_index());
```
```@raw html
<img src="../assets/ex_amount_produced.png" width="500px"/>
```
## Plant emissions report
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.
| `emission type` | Type of emission.
| `amount (tonne)` | Amount of emission produced by the plant this year.
### Sample charts
* Bar plot showing total emission by plant type, grouped type of emissions (in Python):
```python
import pandas as pd
import seaborn as sns; sns.set()
data = pd.read_csv("plant_emissions_report.csv")
sns.barplot(x="plant type",
y="emission amount (tonne)",
hue="emission type",
data=data.groupby(["plant type", "emission type"])
.sum()
.reset_index());
```
```@raw html
<img src="../assets/ex_emissions.png" width="500px"/>
```
## 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.
| `longitude (deg)` | Longitude of the collection center.
| `year` | What year this row corresponds to. This reports includes one row for each year.
| `amount (tonne)` | Amount of product available at this collection center.
| `amount disposed (tonne)` | Amount of product disposed of at this collection center.
| `marginal cost ($/tonne)` | Cost to process one additional tonne of this product coming from this collection center.
## Transportation report
Report showing amount of product sent from initial locations to plants, and from one plant to another. Includes the distance between each pair of locations, amount-distance shipped, transportation costs and energy expenditure. Generated by `RELOG.write_transportation_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.
| `source longitude (deg)` | Longitude of the source location.
| `destination type`| Type of plant the product is being shipped to.
| `destination location name`| Name of the location where the product is being shipped to.
| `destination latitude (deg)` | Latitude of the destination location.
| `destination longitude (deg)` | Longitude of the destination location.
| `product`| Product being shipped.
| `year`| Year.
| `distance (km)`| Distance between source and destination.
| `amount (tonne)`| Total amount of product being shipped between the two locations this year.
| `amount-distance (tonne-km)`| Total amount being shipped this year times distance.
| `transportation cost ($)`| Cost to transport this amount of product between the two locations for this year.
| `transportation energy (GJ)`| Energy expended transporting this amount of product between the two locations.
### Sample charts
* Bar plot showing total amount-distance for each product type, grouped by year (in Python):
```python
import pandas as pd
import seaborn as sns; sns.set()
data = pd.read_csv("transportation_report.csv")
sns.barplot(x="product",
y="amount-distance (tonne-km)",
hue="year",
data=data.groupby(["product", "year"])
.sum()
.reset_index());
```
```@raw html
<img src="../assets/ex_transportation_amount_distance.png" width="500px"/>
```
* Map of transportation lines (in Python):
```python
import pandas as pd
import geopandas as gp
from shapely.geometry import Point, LineString
import matplotlib.pyplot as plt
from matplotlib import collections
# Plot base map
world = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))
ax = world.plot(color='white', edgecolor='50', figsize=(14,7))
ax.set_ylim([23, 50])
ax.set_xlim([-128, -65])
# Draw transportation lines
data = pd.read_csv("transportation_report.csv")
lines = [[(row["source longitude (deg)"], row["source latitude (deg)"]),
(row["destination longitude (deg)"], row["destination latitude (deg)"])
] for (index, row) in data.iterrows()]
ax.add_collection(collections.LineCollection(lines,
linewidths=0.25,
zorder=1,
alpha=0.5,
color="50"))
# Draw source points
points = gp.points_from_xy(data["source longitude (deg)"],
data["source latitude (deg)"])
gp.GeoDataFrame(data, geometry=points).plot(ax=ax,
color="0.5",
markersize=1);
# Draw destination points
points = gp.points_from_xy(data["destination longitude (deg)"],
data["destination latitude (deg)"])
gp.GeoDataFrame(data, geometry=points).plot(ax=ax,
color="red",
markersize=50);
```
```@raw html
<img src="../assets/ex_transportation.png" width="1000px"/>
```
## Transportation emissions report
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.
| `source longitude (deg)` | Longitude of the source location.
| `destination type`| Type of plant the product is being shipped to.
| `destination location name`| Name of the location where the product is being shipped to.
| `destination latitude (deg)` | Latitude of the destination location.
| `destination longitude (deg)` | Longitude of the destination location.
| `product`| Product being shipped.
| `year`| Year.
| `distance (km)`| Distance between source and destination.
| `shipped amount (tonne)`| Total amount of product being shipped between the two locations this year.
| `shipped amount-distance (tonne-km)`| Total amount being shipped this year times distance.
| `emission type` | Type of emission.
| `emission amount (tonne)` | Amount of emission produced by transportation segment this year.
### Sample charts
* Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python):
```python
import pandas as pd
import seaborn as sns; sns.set()
data = pd.read_csv("transportation_emissions_report.csv")
sns.barplot(x="emission type",
y="emission amount (tonne)",
hue="product",
data=data.groupby(["product", "emission type"])
.sum()
.reset_index());
```
```@raw html
<img src="../assets/ex_transportation_emissions.png" width="500px"/>
```

131
docs/src/usage.md
Unescape View File

@ -0,0 +1,131 @@
# 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.8 and may not be compatible with newer versions. After Julia is installed, launch the Julia console, then run:
```julia
using Pkg
Pkg.add(name="RELOG", version="0.7")
```
## 2. Modeling the problem
The two main model components in RELOG are **products** and **plants**.
A **product** is any material that needs to be recycled, any intermediary product produced during the recycling process, or any product recovered at the end of the process. For example, in a NiMH battery recycling study case, products could include (i) the original batteries to be recycled; (ii) the cathode and anode parts of the battery; (iii) rare-earth elements and (iv) scrap metals.
- The model assumes that some products are initially available at user-specified locations (described by their latitude, longitude and the amount available), while other products only become available during the recycling process.
- Products that are initially available must be sent to a plant for processing during the same time period they became available.
- Transporting products from one location to another incurs a transportation cost (`$/km/tonne`), spends some amount of energy (`J/km/tonne`) and may generate multiple types of emissions (`tonne/tonne`). All these parameters are user-specified and may be product- and time-specific.
A **plant** is a facility that converts one type of product to another. RELOG assumes that each plant receives a single type of product as input and converts this input into multiple types of products. Multiple types of plants, with different inputs, outputs and performance characteristics, may be specified. In the NiMH battery recycling study case, for example, one type of plant could be a _disassembly plant_, which converts _batteries_ into _cathode_ and _anode_. Another type of plant could be _anode recycling plant_, which converts _anode_ into _rare-earth elements_ and _scrap metals_.
- To process each tonne of input material, plants incur a variable operating cost (`$/tonne`), spend some amount of energy (`GJ/tonne`), and produce multiple types of emissions (`tonne/tonne`). Plants also incur a fixed operating cost (`$`) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific.
- Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost (`$`) which may be region- and time-specific. Plants also have a limited capacity (in `tonne`), which indicates the maximum amount of input material they are able to process per year. When specifying potential locations for each type of plant, it is also possible to specify the minimum and maximum capacity of the plants that can be built at that particular location. Different plants sizes may have different opening costs and fixed operating costs. After a plant is built, it can be further expanded in the following years, up to its maximum capacity.
- Products received by a plant can be either processed immediately or stored for later processing. Plants have a maximum storage capacity (`tonne`). Storage costs (`$/tonne`) can also be specified.
- All products generated by a plant can either be sent to another plant for further processing, or disposed of locally for either a profit or a loss (`$/tonne`). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location.
All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the [data format page](format.md).
## 3. Running the optimization
After creating a JSON file describing the reverse manufacturing process and the input data, the following example illustrates how to use the package to find the optimal set of decisions:
```julia
# Import package
using RELOG
# Solve optimization problem
solution = RELOG.solve("/home/user/instance.json")
# Write full solution in JSON format
RELOG.write(solution, "solution.json")
# Write simplified reports in CSV format
RELOG.write_plants_report(solution, "plants.csv")
RELOG.write_transportation_report(solution, "transportation.csv")
```
For a complete description of the file formats above, and for a complete list of available reports, see the [data format page](format.md).
## 4. What-If Analysis
Fundamentally, RELOG decides when and where to build plants based on a deterministic optimization problem that minimizes costs for a particular input file provided by the user. In practical situations, it may not be possible to perfectly estimate some (or most) entries in this input file in advance, such as costs, demands and emissions. In this situation, it may be interesting to evaluate how well does the facility location plan produced by RELOG work if costs, demands and emissions turn out to be different.
To simplify this what-if analysis, RELOG provides the `resolve` method, which updates a previous solution based on a new scenario, but keeps some of the previous decisions fixed. More precisely, given an optimal solution produced by RELOG and a new input file describing the new scenario, the `resolve` method reoptimizes the supply chain and produces a new solution which still builds the same set of plants as before, in exactly the same locations and with the same capacities, but that may now utilize the plants differently, based on the new data. For example, in the new solution, plants that were previously used at full capacity may now be utilized at half-capacity instead. As another example, regions that were previously served by a certain plant may now be served by a different one.
The following snippet shows how to use the method:
```julia
# Import package
using RELOG
# Optimize for the average scenario
solution_avg, model_avg = RELOG.solve("input_avg.json", return_model=true)
# Write reports for the average scenario
RELOG.write_plants_report(solution_avg, "plants_avg.csv")
RELOG.write_transportation_report(solution_avg, "transportation_avg.csv")
# Re-optimize for the high-demand scenario, keeping plants fixed
solution_high = RELOG.resolve(model_avg, "input_high.json")
# Write reports for the high-demand scenario
RELOG.write_plants_report(solution_high, "plants_high.csv")
RELOG.write_transportation_report(solution_high, "transportation_high.csv")
```
To use the `resolve` method, the new input file should be very similar to the original one. Only the following entries are allowed to change:
- **Products:** Transportation costs, energy, emissions and initial amounts (latitude, longitude and amount).
- **Plants:** Energy and emissions.
- **Plant's location:** Latitude and longitude.
- **Plant's storage:** Cost.
- **Plant's capacity:** Opening cost, fixed operating cost and variable operating cost.
## 5. Advanced options
### 5.1 Changing the solver
By default, RELOG internally uses [HiGHS](https://github.com/ERGO-Code/HiGHS), an open-source and freely-available Mixed-Integer Linear Programming solver. For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch to Gurobi, for example:
```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,
)
```
### 5.2 Multi-period heuristics
For large-scale instances, it may be too time-consuming to find an exact optimal solution to the multi-period version of the problem. For these situations, RELOG includes a heuristic solution method, which proceeds as follows:
1. First, RELOG creates a single-period version of the problem, in which most values are replaced by their averages. This single-period problem is typically much easier to solve.
2. After solving the simplified problem, RELOG resolves the multi-period version of the problem, but considering only candidate plant locations that were selected by the optimal solution to the single-period version of the problem. All remaining candidate plant locations are removed.
To solve an instance using this heuristic, use the option `heuristic=true`, as shown below.
```julia
using RELOG
solution = RELOG.solve(
"/home/user/instance.json",
heuristic=true,
)
```
Write Preview
Loading…
Cancel
Save