diff --git a/0.7/format/index.html b/0.7/format/index.html index 3a49966..ace9fce 100644 --- a/0.7/format/index.html +++ b/0.7/format/index.html @@ -103,4 +103,4 @@ "amount (tonne)": [934.56, 934.56] } } -}

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:

DatabaseDescriptionExamples
us-stateList of states of the United States.us-state:IL (State of Illinois)
2018-us-countyList of United States counties, as of 2018. IDs are 5-digit FIPS codes.2018-us-county:17043 (DuPage county in Illinois)

Current limitations

Output Data Format (JSON)

To be documented.

+}

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:

DatabaseDescriptionExamples
us-stateList of states of the United States.us-state:IL (State of Illinois)
2018-us-countyList of United States counties, as of 2018. IDs are 5-digit FIPS codes.2018-us-county:17043 (DuPage county in Illinois)

Current limitations

Output Data Format (JSON)

To be documented.

diff --git a/0.7/index.html b/0.7/index.html index 8b97f71..06ed2b8 100644 --- a/0.7/index.html +++ b/0.7/index.html @@ -1,7 +1,7 @@ Home · RELOG
Edit on GitHub

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.

-

Table of Contents

Source Code

Authors

  • Alinson S. Xavier, Argonne National Laboratory <axavier@anl.gov>
  • Nwike Iloeje, Argonne National Laboratory <ciloeje@anl.gov>

License

RELOG: Reverse Logistics Optimization
+
Table of Contents
Source Code
Authors
  • Alinson S. Xavier, Argonne National Laboratory <axavier@anl.gov>
  • Nwike Iloeje, Argonne National Laboratory <ciloeje@anl.gov>
  • John Atkins
  • Kyle Sun
  • Audrey Gallier
License
RELOG: Reverse Logistics Optimization
 Copyright © 2020, UChicago Argonne, LLC. All Rights Reserved.
 
 Redistribution and use in source and binary forms, with or without modification, are permitted
@@ -24,4 +24,4 @@ CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
 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.
+POSSIBILITY OF SUCH DAMAGE. diff --git a/0.7/model/index.html b/0.7/model/index.html index 2d08041..669e61c 100644 --- a/0.7/model/index.html +++ b/0.7/model/index.html @@ -78,4 +78,4 @@ & p \in P, t \in T \\ & z^{\text{p-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/0.7/reports/index.html b/0.7/reports/index.html index 8631f15..deff64b 100644 --- a/0.7/reports/index.html +++ b/0.7/reports/index.html @@ -92,4 +92,4 @@ sns.barplot(x="emission type", hue="product", data=data.groupby(["product", "emission type"]) .sum() - .reset_index()); + .reset_index()); diff --git a/0.7/search/index.html b/0.7/search/index.html index dbcd8ad..dfbe103 100644 --- a/0.7/search/index.html +++ b/0.7/search/index.html @@ -1,2 +1,2 @@ -Search · RELOG

Loading search...

    +Search · RELOG

    Loading search...

      diff --git a/0.7/search_index.js b/0.7/search_index.js index 77e573e..f5be731 100644 --- a/0.7/search_index.js +++ b/0.7/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"reports/#Simplified-Solution-Reports","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"In addition to the full output format described in data formats, 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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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.","category":"page"},{"location":"reports/#Plants-report","page":"Simplified Solution Reports","title":"Plants report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear What year this row corresponds to. This reports includes one row for each year.\nlatitude (deg) Latitude of the plant.\nlongitude (deg) Longitude of the plant.\ncapacity (tonne) Capacity of the plant at this point in time.\namount received (tonne) Amount of input material received by the plant this year.\namount processed (tonne) Amount of input material processed by the plant this year.\namount in storage (tonne) Amount of input material in storage at the end of the year.\nutilization factor (%) Amount processed by the plant this year divided by current plant capacity.\nenergy (GJ) Amount of energy expended by the plant this year.\nopening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year.\nexpansion cost ($) Amount spent this year expanding the plant capacity.\nfixed operating cost ($) Amount spent for keeping the plant operational this year.\nvariable operating cost ($) Amount spent this year to process the input material.\nstorage cost ($) Amount spent this year on storage.\ntotal cost ($) Sum of all previous plant costs.","category":"page"},{"location":"reports/#Sample-charts","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot with total plant costs per year, grouped by plant type (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plants_report.csv\")\nsns.barplot(x=\"year\",\n y=\"total cost ($)\",\n hue=\"plant type\",\n data=data.groupby([\"plant type\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Map showing plant locations (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport geopandas as gp\n\n# Plot base map\nworld = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))\nax = world.plot(color='white', edgecolor='50', figsize=(13,6))\nax.set_ylim([23, 50])\nax.set_xlim([-128, -65])\n\n# Plot plant locations\ndata = pd.read_csv(\"nimh_plants.csv\")\npoints = gp.points_from_xy(data[\"longitude (deg)\"],\n data[\"latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax);","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Plant-outputs-report","page":"Simplified Solution Reports","title":"Plant outputs report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear What year this row corresponds to. This reports includes one row for each year.\nproduct name Product being produced.\namount produced (tonne) Amount of product produced this year.\namount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year.\namount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year.\ndisposal cost ($) Disposal cost for this year.","category":"page"},{"location":"reports/#Sample-charts-2","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total amount produced for each product, grouped by year (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plant_outputs_report.csv\")\nsns.barplot(x=\"amount produced (tonne)\",\n y=\"product name\",\n hue=\"year\",\n data=data.groupby([\"product name\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Plant-emissions-report","page":"Simplified Solution Reports","title":"Plant emissions report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear Year.\nemission type Type of emission.\namount (tonne) Amount of emission produced by the plant this year.","category":"page"},{"location":"reports/#Sample-charts-3","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total emission by plant type, grouped type of emissions (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plant_emissions_report.csv\")\nsns.barplot(x=\"plant type\",\n y=\"emission amount (tonne)\",\n hue=\"emission type\",\n data=data.groupby([\"plant type\", \"emission type\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Products-report","page":"Simplified Solution Reports","title":"Products report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing primary product amounts, locations and marginal costs. Generated by RELOG.write_products_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nproduct name Product name.\nlocation name Name of the collection center.\nlatitude (deg) Latitude of the collection center.\nlongitude (deg) Longitude of the collection center.\nyear What year this row corresponds to. This reports includes one row for each year.\namount (tonne) Amount of product available at this collection center.\namount disposed (tonne) Amount of product disposed of at this collection center.\nmarginal cost ($/tonne) Cost to process one additional tonne of this product coming from this collection center.","category":"page"},{"location":"reports/#Transportation-report","page":"Simplified Solution Reports","title":"Transportation report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nsource type If product is being shipped from an initial location, equals Origin. If product is being shipped from a plant, equals plant type.\nsource location name Name of the location where the product is being shipped from.\nsource latitude (deg) Latitude of the source location.\nsource longitude (deg) Longitude of the source location.\ndestination type Type of plant the product is being shipped to.\ndestination location name Name of the location where the product is being shipped to.\ndestination latitude (deg) Latitude of the destination location.\ndestination longitude (deg) Longitude of the destination location.\nproduct Product being shipped.\nyear Year.\ndistance (km) Distance between source and destination.\namount (tonne) Total amount of product being shipped between the two locations this year.\namount-distance (tonne-km) Total amount being shipped this year times distance.\ntransportation cost ($) Cost to transport this amount of product between the two locations for this year.\ntransportation energy (GJ) Energy expended transporting this amount of product between the two locations.","category":"page"},{"location":"reports/#Sample-charts-4","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total amount-distance for each product type, grouped by year (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"transportation_report.csv\")\nsns.barplot(x=\"product\",\n y=\"amount-distance (tonne-km)\",\n hue=\"year\",\n data=data.groupby([\"product\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Map of transportation lines (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport geopandas as gp\nfrom shapely.geometry import Point, LineString\nimport matplotlib.pyplot as plt\nfrom matplotlib import collections\n\n# Plot base map\nworld = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))\nax = world.plot(color='white', edgecolor='50', figsize=(14,7))\nax.set_ylim([23, 50])\nax.set_xlim([-128, -65])\n\n# Draw transportation lines\ndata = pd.read_csv(\"transportation_report.csv\")\nlines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]),\n (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"])\n ] for (index, row) in data.iterrows()]\nax.add_collection(collections.LineCollection(lines,\n linewidths=0.25,\n zorder=1,\n alpha=0.5,\n color=\"50\"))\n\n# Draw source points\npoints = gp.points_from_xy(data[\"source longitude (deg)\"],\n data[\"source latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax,\n color=\"0.5\",\n markersize=1);\n\n# Draw destination points\npoints = gp.points_from_xy(data[\"destination longitude (deg)\"],\n data[\"destination latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax,\n color=\"red\",\n markersize=50);","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Transportation-emissions-report","page":"Simplified Solution Reports","title":"Transportation emissions report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nsource type If product is being shipped from an initial location, equals Origin. If product is being shipped from a plant, equals plant type.\nsource location name Name of the location where the product is being shipped from.\nsource latitude (deg) Latitude of the source location.\nsource longitude (deg) Longitude of the source location.\ndestination type Type of plant the product is being shipped to.\ndestination location name Name of the location where the product is being shipped to.\ndestination latitude (deg) Latitude of the destination location.\ndestination longitude (deg) Longitude of the destination location.\nproduct Product being shipped.\nyear Year.\ndistance (km) Distance between source and destination.\nshipped amount (tonne) Total amount of product being shipped between the two locations this year.\nshipped amount-distance (tonne-km) Total amount being shipped this year times distance.\nemission type Type of emission.\nemission amount (tonne) Amount of emission produced by transportation segment this year.","category":"page"},{"location":"reports/#Sample-charts-5","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"transportation_emissions_report.csv\")\nsns.barplot(x=\"emission type\",\n y=\"emission amount (tonne)\",\n hue=\"product\",\n data=data.groupby([\"product\", \"emission type\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"usage/#Usage","page":"Usage","title":"Usage","text":"","category":"section"},{"location":"usage/#.-Installation","page":"Usage","title":"1. Installation","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"To use RELOG, the first step is to install the Julia programming language 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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using Pkg\nPkg.add(name=\"RELOG\", version=\"0.6\")","category":"page"},{"location":"usage/#.-Modeling-the-problem","page":"Usage","title":"2. Modeling the problem","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"The two main model components in RELOG are products and plants.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nProducts that are initially available must be sent to a plant for processing during the same time period they became available.\nTransporting 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nPlants 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.\nProducts 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.\nAll 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page.","category":"page"},{"location":"usage/#.-Running-the-optimization","page":"Usage","title":"3. Running the optimization","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"# Import package\nusing RELOG\n\n# Solve optimization problem\nsolution = RELOG.solve(\"/home/user/instance.json\")\n\n# Write full solution in JSON format\nRELOG.write(solution, \"solution.json\")\n\n# Write simplified reports in CSV format\nRELOG.write_plants_report(solution, \"plants.csv\")\nRELOG.write_transportation_report(solution, \"transportation.csv\")","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"For a complete description of the file formats above, and for a complete list of available reports, see the data format page.","category":"page"},{"location":"usage/#.-What-If-Analysis","page":"Usage","title":"4. What-If Analysis","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"The following snippet shows how to use the method:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"# Import package\nusing RELOG\n\n# Optimize for the average scenario\nsolution_avg, model_avg = RELOG.solve(\"input_avg.json\", return_model=true)\n\n# Write reports for the average scenario\nRELOG.write_plants_report(solution_avg, \"plants_avg.csv\")\nRELOG.write_transportation_report(solution_avg, \"transportation_avg.csv\")\n\n# Re-optimize for the high-demand scenario, keeping plants fixed\nsolution_high = RELOG.resolve(model_avg, \"input_high.json\")\n\n# Write reports for the high-demand scenario\nRELOG.write_plants_report(solution_high, \"plants_high.csv\")\nRELOG.write_transportation_report(solution_high, \"transportation_high.csv\")","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"Products: Transportation costs, energy, emissions and initial amounts (latitude, longitude and amount).\nPlants: Energy and emissions.\nPlant's location: Latitude and longitude.\nPlant's storage: Cost.\nPlant's capacity: Opening cost, fixed operating cost and variable operating cost.","category":"page"},{"location":"usage/#.-Advanced-options","page":"Usage","title":"5. Advanced options","text":"","category":"section"},{"location":"usage/#.1-Changing-the-solver","page":"Usage","title":"5.1 Changing the solver","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"By default, RELOG internally uses 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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using RELOG, Gurobi, JuMP\n\ngurobi = optimizer_with_attributes(\n Gurobi.Optimizer,\n \"TimeLimit\" => 3600,\n \"MIPGap\" => 0.001,\n)\n\nRELOG.solve(\n \"instance.json\",\n output=\"solution.json\",\n optimizer=gurobi,\n)","category":"page"},{"location":"usage/#.2-Multi-period-heuristics","page":"Usage","title":"5.2 Multi-period heuristics","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nAfter 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"To solve an instance using this heuristic, use the option heuristic=true, as shown below.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using RELOG\n\nsolution = RELOG.solve(\n \"/home/user/instance.json\",\n heuristic=true,\n)","category":"page"},{"location":"model/#Optimization-Model","page":"Optimization Model","title":"Optimization Model","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant.","category":"page"},{"location":"model/#Mathematical-Description","page":"Optimization Model","title":"Mathematical Description","text":"","category":"section"},{"location":"model/#Sets","page":"Optimization Model","title":"Sets","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description\nL Set of collection centers holding the primary material to be recycled\nM Set of materials recovered during the reverse manufacturing process\nP Set of potential plants to open\nT = 1 ldots t^max Set of time periods","category":"page"},{"location":"model/#Constants","page":"Optimization Model","title":"Constants","text":"","category":"section"},{"location":"model/#Plants","page":"Optimization Model","title":"Plants","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nc^textexp_pt Cost of adding one tonne of capacity to plant p at time t $/tonne\nc^textf-base_pt Fixed cost of keeping plant p open during time period t $\nc^textf-exp_pt Increase in fixed cost for each additional tonne of capacity $/tonne\nc^textopen_pt Cost of opening plant p at time t, at minimum capacity $\nc^textp-disp_pmt Cost of disposing recovered material m at plant p during time t $/tonne/km\nc^textstore_pt Cost of storing primary material at plant p at time t $/tonne\nc^textproc_pt Variable cost of processing primary material at plant p at time t $/tonne\nm^textmax_p Maximum capacity of plant p tonne\nm^textmin_p Minimum capacity of plant p tonne\nm^textinit_p Initial capacity of plant p tonne\nm^textp-disp_pmt Maximum amount of recovered material m that plant p can dispose of during time t tonne\nm^textstore_p Maximum amount of primary material that plant p can store for later processing. tonne","category":"page"},{"location":"model/#Products","page":"Optimization Model","title":"Products","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nalpha_pm Amount of material m recovered by plant t for each tonne of primary material tonne/tonne\nc^textacq_lt Cost of acquiring primary material at collection center l during time t $/tonne\nc^textc-disp_lt Cost of disposing primary material at collection center l during time t $/tonne\nm^textc-disp_t Maximum amount of primary material that can be disposed of across all collection centers during time t tonne\nm^textinitial_lt Amount of primary material available to be recycled at collection center l during time t tonne","category":"page"},{"location":"model/#Transportation","page":"Optimization Model","title":"Transportation","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nc^texttr_t Cost to transport primary material during time t $/tonne/km\nd_lp Distance between plant p and collection center l km","category":"page"},{"location":"model/#Decision-variables","page":"Optimization Model","title":"Decision variables","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nq_mpt Amount of material m recovered by plant p during time t tonne\nu_pt Binary variable that equals 1 if plant p starts operating at time t Boolean\nw_pt Extra capacity (amount above the minimum) added to plant p during time t tonne\nx_pt Binary variable that equals 1 if plant p is operational at time t Boolean\ny_lpt Amount of primary material sent from collection center l to plant p during time t tonne\nz^textp-disp_mpt Amount of recovered material m disposed of by plant p during time t tonne\nz^textc-disp_lt Amount of primary material disposed of at collection center l during time t tonne\nz^textstore_pt Amount of primary material in storage at plant p by the end of time period t tonne\nz^textproc_mpt Amount of primary material processed by plant p during time period t tonne","category":"page"},{"location":"model/#Objective-function","page":"Optimization Model","title":"Objective function","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"RELOG minimizes the overall capital, production and transportation costs:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n textminimize \n sum_t in T sum_p in P left\n c^textopen_pt u_pt +\n c^textf-base_pt x_pt +\n c^textf-exp_pt left( sum_i=0^t w_pi right) +\n c^textexp_pt w_pt\n right + \n \n sum_t in T sum_p in P left\n c^textstore_pt z^textstore_pt +\n c^textproc_pt z^textproc_pt\n right + \n \n sum_t in T sum_l in L sum_p in P\n c^texttr_t d_lp y_lpt +\n \n \n sum_t in T sum_p in P sum_m in M c^textp-disp_pmt z_pmt +\n \n \n sum_t in T sum_l in L c^textacq_lt left(\n m^textinitial_lt - z^textc-disp_lt\n right) + c^textc-disp_lt z^textc-disp_lt\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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. In the third line, we have transportation costs. In the fourth line, we have disposal costs at the plants. In the fifth line, we have acquisition and disposal cost at the collection centers.","category":"page"},{"location":"model/#Constraints","page":"Optimization Model","title":"Constraints","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"All primary material must either be sent to a plant for processing or disposed of at the collection center:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_p in P y_lpt + z^textc-disp_lt = m^textinitial_lt\n forall l in L t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"There is a limit on how much primary material can be disposed of at the collection centers:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_l in L z^textc-disp_lt leq m^textc-disp_t\n t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Amount received equals amount processed plus stored. Furthermore, all primary material should be processed by the end of the simulation.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_l in L y_lpt + z^textstore_pt-1\n = z^textproc_pt + z^textstore_pt\n forall p in P t in T \n z^textstore_p0 = 0\n forall p in P \n z^textstore_pt^max = 0\n forall p in P\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants have a limited processing capacity. Furthermore, if a plant is closed, it has zero processing capacity:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n z^textproc_pt leq m^textmin_p x_p + sum_i=0^t w_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants have limited storage capacity. Furthermore, if a plant is closed, is has zero storage capacity:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n z^textstore_pt leq m^textstore_p x_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_i=0^t w_p leq left( m^textmax_p - m^textmin_p right) x_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Amount of recovered material is proportional to amount processed:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt = alpha_pm z^textproc_pt\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt = z^textp-disp_mpt\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n x_pt = x_pt-1 + u_pt\n forall p in P t in T \nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Boundary constants:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n x_p0 = begincases\n 0 text if m^textinit_p = 0 \n 1 text otherwise \n endcases \n w_p0 = maxleft0 m^textinit_p - m^textmin_p right\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Variable bounds:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt geq 0\n forall m in M p in P t in T \n u_pt in 01\n forall p in P t in T \n w_pt geq 0\n forall p in P t in T \n x_pt in 01\n forall p in P t in T \n y_lpt geq 0\n forall l in L p in P t in T \n z^textc-disp_lt geq 0\n l in L t in T \n z^textstore_pt geq 0\n p in P t in T \n z^textp-disp_mpt z^textproc_mpt geq 0\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"format/#Input-and-Output-Data-Formats","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format.","category":"page"},{"location":"format/#Input-Data-Format-(JSON)","page":"Input and Output Data Formats","title":"Input Data Format (JSON)","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"RELOG accepts as input a JSON file with three sections: parameters, products and plants. Below, we describe each section in more detail.","category":"page"},{"location":"format/#Parameters","page":"Input and Output Data Formats","title":"Parameters","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The parameters section describes details about the simulation itself.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ntime horizon (years) Number of years in the simulation.\nbuilding 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.\ndistance 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\".","category":"page"},{"location":"format/#Example","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"parameters\": {\n \"time horizon (years)\": 2,\n \"building period (years)\": [1],\n \"distance metric\": \"driving\"\n }\n}","category":"page"},{"location":"format/#Products","page":"Input and Output Data Formats","title":"Products","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ntransportation cost ($/km/tonne) The cost to transport this product. Must be a time series.\ntransportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional.\ntransportation 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.\ninitial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series.\ndisposal limit (tonne) Total amount of product that can be disposed of across all collection centers. If omitted, all product must be processed. This parameter has no effect on product disposal at plants.\ndisposal cost ($/tonne) Cost of disposing one tonne of this product at a collection center. If omitted, defaults to zero. This parameter has no effect on product disposal costs at plants.\nacquisition cost ($/tonne) Cost of acquiring one tonne of this product at a collection center. If omitted, defaults to zero.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nlatitude (deg) The latitude of the location.\nlongitude (deg) The longitude of the location.\namount (tonne) The amount of the product initially available at the location. Must be a time series.","category":"page"},{"location":"format/#Example-2","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"products\": {\n \"P1\": {\n \"initial amounts\": {\n \"C1\": {\n \"latitude (deg)\": 7.0,\n \"longitude (deg)\": 7.0,\n \"amount (tonne)\": [934.56, 934.56]\n },\n \"C2\": {\n \"latitude (deg)\": 7.0,\n \"longitude (deg)\": 19.0,\n \"amount (tonne)\": [198.95, 198.95]\n },\n \"C3\": {\n \"latitude (deg)\": 84.0,\n \"longitude (deg)\": 76.0,\n \"amount (tonne)\": [212.97, 212.97]\n }\n },\n \"transportation cost ($/km/tonne)\": [0.015, 0.015],\n \"transportation energy (J/km/tonne)\": [0.12, 0.11],\n \"transportation emissions (tonne/km/tonne)\": {\n \"CO2\": [0.052, 0.05],\n \"CH4\": [0.003, 0.002]\n },\n \"disposal cost ($/tonne)\": [-10.0, -12.0],\n \"disposal limit (tonne)\": [1.0, 1.0],\n \"acquisition cost ($/tonne)\": [1.0, 1.0]\n },\n \"P2\": {\n \"transportation cost ($/km/tonne)\": [0.022, 0.02]\n },\n \"P3\": {\n \"transportation cost ($/km/tonne)\": [0.0125, 0.0125]\n },\n \"P4\": {\n \"transportation cost ($/km/tonne)\": [0.0175, 0.0175]\n }\n }\n}","category":"page"},{"location":"format/#Processing-plants","page":"Input and Output Data Formats","title":"Processing plants","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ninput The name of the product that this plant takes as input. Only one input is accepted per plant.\noutputs (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.\nenergy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional.\nemissions (tonne/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). Must be a time series. Optional.\nlocations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below).","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nlatitude (deg) The latitude of the location, in degrees.\nlongitude (deg) The longitude of the location, in degrees.\ndisposal A dictionary describing what products can be disposed locally at the plant.\nstorage A dictionary describing the plant's storage.\ncapacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics.\ninitial capacity (tonne) Capacity already available at this location. Optional.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The storage dictionary should contain the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ncost ($/tonne) The cost to store a tonne of input product for one time period. Must be a time series.\nlimit (tonne) The maximum amount of input product this plant can have in storage at any given time.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ncost ($/tonne) The cost to dispose of the product. Must be a time series.\nlimit (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.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nopening cost ($) The cost to open a plant of this size.\nfixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series.\nvariable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series.","category":"page"},{"location":"format/#Example-3","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"plants\": {\n \"F1\": {\n \"input\": \"P1\",\n \"outputs (tonne/tonne)\": {\n \"P2\": 0.2,\n \"P3\": 0.5\n },\n \"energy (GJ/tonne)\": [0.12, 0.11],\n \"emissions (tonne/tonne)\": {\n \"CO2\": [0.052, 0.05],\n \"CH4\": [0.003, 0.002]\n },\n \"locations\": {\n \"L1\": {\n \"latitude (deg)\": 0.0,\n \"longitude (deg)\": 0.0,\n \"disposal\": {\n \"P2\": {\n \"cost ($/tonne)\": [-10.0, -12.0],\n \"limit (tonne)\": [1.0, 1.0]\n }\n },\n \"storage\": {\n \"cost ($/tonne)\": [5.0, 5.3],\n \"limit (tonne)\": 100.0\n },\n \"capacities (tonne)\": {\n \"100\": {\n \"opening cost ($)\": [500, 530],\n \"fixed operating cost ($)\": [300.0, 310.0],\n \"variable operating cost ($/tonne)\": [5.0, 5.2]\n },\n \"500\": {\n \"opening cost ($)\": [750, 760],\n \"fixed operating cost ($)\": [400.0, 450.0],\n \"variable operating cost ($/tonne)\": [5.0, 5.2]\n }\n }\n }\n }\n }\n }\n}","category":"page"},{"location":"format/#Geographic-database","page":"Input and Output Data Formats","title":"Geographic database","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Instead of specifying locations using latitudes and longitudes, it is also possible to specify them using unique identifiers, such as the name of a US state, or the county FIPS code. This works anywhere latitude (deg) and longitude (deg) are expected. For example, instead of:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"initial amounts\": {\n \"C1\": {\n \"latitude (deg)\": 37.27182,\n \"longitude (deg)\": -119.2704,\n \"amount (tonne)\": [934.56, 934.56]\n }\n }\n}","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"is is possible to write:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"initial amounts\": {\n \"C1\": {\n \"location\": \"us-state:CA\",\n \"amount (tonne)\": [934.56, 934.56]\n }\n }\n}","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Database Description Examples\nus-state List of states of the United States. us-state:IL (State of Illinois)\n2018-us-county List of United States counties, as of 2018. IDs are 5-digit FIPS codes. 2018-us-county:17043 (DuPage county in Illinois)","category":"page"},{"location":"format/#Current-limitations","page":"Input and Output Data Formats","title":"Current limitations","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation.\nPlants can be expanded at any time, even long after they are open.\nAll 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.\nUp to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes.\nAccurate driving distances are only available for the continental United States.","category":"page"},{"location":"format/#Output-Data-Format-(JSON)","page":"Input and Output Data Formats","title":"Output Data Format (JSON)","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"To be documented.","category":"page"},{"location":"#RELOG:-Reverse-Logistics-Optimization","page":"Home","title":"RELOG: Reverse Logistics Optimization","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"},{"location":"","page":"Home","title":"Home","text":"
      \n \n
      ","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\"usage.md\", \"format.md\", \"reports.md\", \"model.md\"]\nDepth = 3","category":"page"},{"location":"#Source-Code","page":"Home","title":"Source Code","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"https://github.com/ANL-CEEESA/RELOG","category":"page"},{"location":"#Authors","page":"Home","title":"Authors","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Alinson S. Xavier, Argonne National Laboratory \nNwike Iloeje, Argonne National Laboratory ","category":"page"},{"location":"#License","page":"Home","title":"License","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RELOG: Reverse Logistics Optimization\nCopyright © 2020, UChicago Argonne, LLC. All Rights Reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted\nprovided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this list of\n conditions and the following disclaimer.\n2. Redistributions in binary form must reproduce the above copyright notice, this list of\n conditions and the following disclaimer in the documentation and/or other materials provided\n with the distribution.\n3. Neither the name of the copyright holder nor the names of its contributors may be used to\n endorse or promote products derived from this software without specific prior written\n permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR\nIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR\nCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\nTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR\nOTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.","category":"page"}] +[{"location":"reports/#Simplified-Solution-Reports","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"In addition to the full output format described in data formats, 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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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.","category":"page"},{"location":"reports/#Plants-report","page":"Simplified Solution Reports","title":"Plants report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing plant costs, capacities, energy expenditure and utilization factors. Generated by RELOG.write_plants_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear What year this row corresponds to. This reports includes one row for each year.\nlatitude (deg) Latitude of the plant.\nlongitude (deg) Longitude of the plant.\ncapacity (tonne) Capacity of the plant at this point in time.\namount received (tonne) Amount of input material received by the plant this year.\namount processed (tonne) Amount of input material processed by the plant this year.\namount in storage (tonne) Amount of input material in storage at the end of the year.\nutilization factor (%) Amount processed by the plant this year divided by current plant capacity.\nenergy (GJ) Amount of energy expended by the plant this year.\nopening cost ($) Amount spent opening the plant. This value is only positive if the plant became operational this year.\nexpansion cost ($) Amount spent this year expanding the plant capacity.\nfixed operating cost ($) Amount spent for keeping the plant operational this year.\nvariable operating cost ($) Amount spent this year to process the input material.\nstorage cost ($) Amount spent this year on storage.\ntotal cost ($) Sum of all previous plant costs.","category":"page"},{"location":"reports/#Sample-charts","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot with total plant costs per year, grouped by plant type (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plants_report.csv\")\nsns.barplot(x=\"year\",\n y=\"total cost ($)\",\n hue=\"plant type\",\n data=data.groupby([\"plant type\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Map showing plant locations (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport geopandas as gp\n\n# Plot base map\nworld = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))\nax = world.plot(color='white', edgecolor='50', figsize=(13,6))\nax.set_ylim([23, 50])\nax.set_xlim([-128, -65])\n\n# Plot plant locations\ndata = pd.read_csv(\"nimh_plants.csv\")\npoints = gp.points_from_xy(data[\"longitude (deg)\"],\n data[\"latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax);","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Plant-outputs-report","page":"Simplified Solution Reports","title":"Plant outputs report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear What year this row corresponds to. This reports includes one row for each year.\nproduct name Product being produced.\namount produced (tonne) Amount of product produced this year.\namount sent (tonne) Amount of product produced by this plant and sent to another plant for further processing this year.\namount disposed (tonne) Amount produced produced by this plant and immediately disposed of locally this year.\ndisposal cost ($) Disposal cost for this year.","category":"page"},{"location":"reports/#Sample-charts-2","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total amount produced for each product, grouped by year (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plant_outputs_report.csv\")\nsns.barplot(x=\"amount produced (tonne)\",\n y=\"product name\",\n hue=\"year\",\n data=data.groupby([\"product name\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Plant-emissions-report","page":"Simplified Solution Reports","title":"Plant emissions report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing amount of emissions produced by each plant. Generated by RELOG.write_plant_emissions_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nplant type Plant type.\nlocation name Location name.\nyear Year.\nemission type Type of emission.\namount (tonne) Amount of emission produced by the plant this year.","category":"page"},{"location":"reports/#Sample-charts-3","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total emission by plant type, grouped type of emissions (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"plant_emissions_report.csv\")\nsns.barplot(x=\"plant type\",\n y=\"emission amount (tonne)\",\n hue=\"emission type\",\n data=data.groupby([\"plant type\", \"emission type\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Products-report","page":"Simplified Solution Reports","title":"Products report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Report showing primary product amounts, locations and marginal costs. Generated by RELOG.write_products_report(solution, filename).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nproduct name Product name.\nlocation name Name of the collection center.\nlatitude (deg) Latitude of the collection center.\nlongitude (deg) Longitude of the collection center.\nyear What year this row corresponds to. This reports includes one row for each year.\namount (tonne) Amount of product available at this collection center.\namount disposed (tonne) Amount of product disposed of at this collection center.\nmarginal cost ($/tonne) Cost to process one additional tonne of this product coming from this collection center.","category":"page"},{"location":"reports/#Transportation-report","page":"Simplified Solution Reports","title":"Transportation report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nsource type If product is being shipped from an initial location, equals Origin. If product is being shipped from a plant, equals plant type.\nsource location name Name of the location where the product is being shipped from.\nsource latitude (deg) Latitude of the source location.\nsource longitude (deg) Longitude of the source location.\ndestination type Type of plant the product is being shipped to.\ndestination location name Name of the location where the product is being shipped to.\ndestination latitude (deg) Latitude of the destination location.\ndestination longitude (deg) Longitude of the destination location.\nproduct Product being shipped.\nyear Year.\ndistance (km) Distance between source and destination.\namount (tonne) Total amount of product being shipped between the two locations this year.\namount-distance (tonne-km) Total amount being shipped this year times distance.\ntransportation cost ($) Cost to transport this amount of product between the two locations for this year.\ntransportation energy (GJ) Energy expended transporting this amount of product between the two locations.","category":"page"},{"location":"reports/#Sample-charts-4","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total amount-distance for each product type, grouped by year (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"transportation_report.csv\")\nsns.barplot(x=\"product\",\n y=\"amount-distance (tonne-km)\",\n hue=\"year\",\n data=data.groupby([\"product\", \"year\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Map of transportation lines (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport geopandas as gp\nfrom shapely.geometry import Point, LineString\nimport matplotlib.pyplot as plt\nfrom matplotlib import collections\n\n# Plot base map\nworld = gp.read_file(gp.datasets.get_path('naturalearth_lowres'))\nax = world.plot(color='white', edgecolor='50', figsize=(14,7))\nax.set_ylim([23, 50])\nax.set_xlim([-128, -65])\n\n# Draw transportation lines\ndata = pd.read_csv(\"transportation_report.csv\")\nlines = [[(row[\"source longitude (deg)\"], row[\"source latitude (deg)\"]),\n (row[\"destination longitude (deg)\"], row[\"destination latitude (deg)\"])\n ] for (index, row) in data.iterrows()]\nax.add_collection(collections.LineCollection(lines,\n linewidths=0.25,\n zorder=1,\n alpha=0.5,\n color=\"50\"))\n\n# Draw source points\npoints = gp.points_from_xy(data[\"source longitude (deg)\"],\n data[\"source latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax,\n color=\"0.5\",\n markersize=1);\n\n# Draw destination points\npoints = gp.points_from_xy(data[\"destination longitude (deg)\"],\n data[\"destination latitude (deg)\"])\ngp.GeoDataFrame(data, geometry=points).plot(ax=ax,\n color=\"red\",\n markersize=50);","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"reports/#Transportation-emissions-report","page":"Simplified Solution Reports","title":"Transportation emissions report","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"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).","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Column Description\nsource type If product is being shipped from an initial location, equals Origin. If product is being shipped from a plant, equals plant type.\nsource location name Name of the location where the product is being shipped from.\nsource latitude (deg) Latitude of the source location.\nsource longitude (deg) Longitude of the source location.\ndestination type Type of plant the product is being shipped to.\ndestination location name Name of the location where the product is being shipped to.\ndestination latitude (deg) Latitude of the destination location.\ndestination longitude (deg) Longitude of the destination location.\nproduct Product being shipped.\nyear Year.\ndistance (km) Distance between source and destination.\nshipped amount (tonne) Total amount of product being shipped between the two locations this year.\nshipped amount-distance (tonne-km) Total amount being shipped this year times distance.\nemission type Type of emission.\nemission amount (tonne) Amount of emission produced by transportation segment this year.","category":"page"},{"location":"reports/#Sample-charts-5","page":"Simplified Solution Reports","title":"Sample charts","text":"","category":"section"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"Bar plot showing total emission amount by emission type, grouped by type of product being transported (in Python):","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"import pandas as pd\nimport seaborn as sns; sns.set()\n\ndata = pd.read_csv(\"transportation_emissions_report.csv\")\nsns.barplot(x=\"emission type\",\n y=\"emission amount (tonne)\",\n hue=\"product\",\n data=data.groupby([\"product\", \"emission type\"])\n .sum()\n .reset_index());","category":"page"},{"location":"reports/","page":"Simplified Solution Reports","title":"Simplified Solution Reports","text":"","category":"page"},{"location":"usage/#Usage","page":"Usage","title":"Usage","text":"","category":"section"},{"location":"usage/#.-Installation","page":"Usage","title":"1. Installation","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"To use RELOG, the first step is to install the Julia programming language 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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using Pkg\nPkg.add(name=\"RELOG\", version=\"0.7\")","category":"page"},{"location":"usage/#.-Modeling-the-problem","page":"Usage","title":"2. Modeling the problem","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"The two main model components in RELOG are products and plants.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nProducts that are initially available must be sent to a plant for processing during the same time period they became available.\nTransporting 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nPlants 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.\nProducts 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.\nAll 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the data format page.","category":"page"},{"location":"usage/#.-Running-the-optimization","page":"Usage","title":"3. Running the optimization","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"# Import package\nusing RELOG\n\n# Solve optimization problem\nsolution = RELOG.solve(\"/home/user/instance.json\")\n\n# Write full solution in JSON format\nRELOG.write(solution, \"solution.json\")\n\n# Write simplified reports in CSV format\nRELOG.write_plants_report(solution, \"plants.csv\")\nRELOG.write_transportation_report(solution, \"transportation.csv\")","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"For a complete description of the file formats above, and for a complete list of available reports, see the data format page.","category":"page"},{"location":"usage/#.-What-If-Analysis","page":"Usage","title":"4. What-If Analysis","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"The following snippet shows how to use the method:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"# Import package\nusing RELOG\n\n# Optimize for the average scenario\nsolution_avg, model_avg = RELOG.solve(\"input_avg.json\", return_model=true)\n\n# Write reports for the average scenario\nRELOG.write_plants_report(solution_avg, \"plants_avg.csv\")\nRELOG.write_transportation_report(solution_avg, \"transportation_avg.csv\")\n\n# Re-optimize for the high-demand scenario, keeping plants fixed\nsolution_high = RELOG.resolve(model_avg, \"input_high.json\")\n\n# Write reports for the high-demand scenario\nRELOG.write_plants_report(solution_high, \"plants_high.csv\")\nRELOG.write_transportation_report(solution_high, \"transportation_high.csv\")","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"Products: Transportation costs, energy, emissions and initial amounts (latitude, longitude and amount).\nPlants: Energy and emissions.\nPlant's location: Latitude and longitude.\nPlant's storage: Cost.\nPlant's capacity: Opening cost, fixed operating cost and variable operating cost.","category":"page"},{"location":"usage/#.-Advanced-options","page":"Usage","title":"5. Advanced options","text":"","category":"section"},{"location":"usage/#.1-Changing-the-solver","page":"Usage","title":"5.1 Changing the solver","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"By default, RELOG internally uses 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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using RELOG, Gurobi, JuMP\n\ngurobi = optimizer_with_attributes(\n Gurobi.Optimizer,\n \"TimeLimit\" => 3600,\n \"MIPGap\" => 0.001,\n)\n\nRELOG.solve(\n \"instance.json\",\n output=\"solution.json\",\n optimizer=gurobi,\n)","category":"page"},{"location":"usage/#.2-Multi-period-heuristics","page":"Usage","title":"5.2 Multi-period heuristics","text":"","category":"section"},{"location":"usage/","page":"Usage","title":"Usage","text":"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:","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"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.\nAfter 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.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"To solve an instance using this heuristic, use the option heuristic=true, as shown below.","category":"page"},{"location":"usage/","page":"Usage","title":"Usage","text":"using RELOG\n\nsolution = RELOG.solve(\n \"/home/user/instance.json\",\n heuristic=true,\n)","category":"page"},{"location":"model/#Optimization-Model","page":"Optimization Model","title":"Optimization Model","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"In this page, we describe the precise mathematical optimization model used by RELOG to find the optimal logistics plan. This model is a variation of the classical Facility Location Problem, which has been widely studied in the operations research literature. To simplify the exposition, we present the simplified case where there is only one type of plant.","category":"page"},{"location":"model/#Mathematical-Description","page":"Optimization Model","title":"Mathematical Description","text":"","category":"section"},{"location":"model/#Sets","page":"Optimization Model","title":"Sets","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description\nL Set of collection centers holding the primary material to be recycled\nM Set of materials recovered during the reverse manufacturing process\nP Set of potential plants to open\nT = 1 ldots t^max Set of time periods","category":"page"},{"location":"model/#Constants","page":"Optimization Model","title":"Constants","text":"","category":"section"},{"location":"model/#Plants","page":"Optimization Model","title":"Plants","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nc^textexp_pt Cost of adding one tonne of capacity to plant p at time t $/tonne\nc^textf-base_pt Fixed cost of keeping plant p open during time period t $\nc^textf-exp_pt Increase in fixed cost for each additional tonne of capacity $/tonne\nc^textopen_pt Cost of opening plant p at time t, at minimum capacity $\nc^textp-disp_pmt Cost of disposing recovered material m at plant p during time t $/tonne/km\nc^textstore_pt Cost of storing primary material at plant p at time t $/tonne\nc^textproc_pt Variable cost of processing primary material at plant p at time t $/tonne\nm^textmax_p Maximum capacity of plant p tonne\nm^textmin_p Minimum capacity of plant p tonne\nm^textinit_p Initial capacity of plant p tonne\nm^textp-disp_pmt Maximum amount of recovered material m that plant p can dispose of during time t tonne\nm^textstore_p Maximum amount of primary material that plant p can store for later processing. tonne","category":"page"},{"location":"model/#Products","page":"Optimization Model","title":"Products","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nalpha_pm Amount of material m recovered by plant t for each tonne of primary material tonne/tonne\nc^textacq_lt Cost of acquiring primary material at collection center l during time t $/tonne\nc^textc-disp_lt Cost of disposing primary material at collection center l during time t $/tonne\nm^textc-disp_t Maximum amount of primary material that can be disposed of across all collection centers during time t tonne\nm^textinitial_lt Amount of primary material available to be recycled at collection center l during time t tonne","category":"page"},{"location":"model/#Transportation","page":"Optimization Model","title":"Transportation","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nc^texttr_t Cost to transport primary material during time t $/tonne/km\nd_lp Distance between plant p and collection center l km","category":"page"},{"location":"model/#Decision-variables","page":"Optimization Model","title":"Decision variables","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Symbol Description Unit\nq_mpt Amount of material m recovered by plant p during time t tonne\nu_pt Binary variable that equals 1 if plant p starts operating at time t Boolean\nw_pt Extra capacity (amount above the minimum) added to plant p during time t tonne\nx_pt Binary variable that equals 1 if plant p is operational at time t Boolean\ny_lpt Amount of primary material sent from collection center l to plant p during time t tonne\nz^textp-disp_mpt Amount of recovered material m disposed of by plant p during time t tonne\nz^textc-disp_lt Amount of primary material disposed of at collection center l during time t tonne\nz^textstore_pt Amount of primary material in storage at plant p by the end of time period t tonne\nz^textproc_mpt Amount of primary material processed by plant p during time period t tonne","category":"page"},{"location":"model/#Objective-function","page":"Optimization Model","title":"Objective function","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"RELOG minimizes the overall capital, production and transportation costs:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n textminimize \n sum_t in T sum_p in P left\n c^textopen_pt u_pt +\n c^textf-base_pt x_pt +\n c^textf-exp_pt left( sum_i=0^t w_pi right) +\n c^textexp_pt w_pt\n right + \n \n sum_t in T sum_p in P left\n c^textstore_pt z^textstore_pt +\n c^textproc_pt z^textproc_pt\n right + \n \n sum_t in T sum_l in L sum_p in P\n c^texttr_t d_lp y_lpt +\n \n \n sum_t in T sum_p in P sum_m in M c^textp-disp_pmt z_pmt +\n \n \n sum_t in T sum_l in L c^textacq_lt left(\n m^textinitial_lt - z^textc-disp_lt\n right) + c^textc-disp_lt z^textc-disp_lt\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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. In the third line, we have transportation costs. In the fourth line, we have disposal costs at the plants. In the fifth line, we have acquisition and disposal cost at the collection centers.","category":"page"},{"location":"model/#Constraints","page":"Optimization Model","title":"Constraints","text":"","category":"section"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"All primary material must either be sent to a plant for processing or disposed of at the collection center:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_p in P y_lpt + z^textc-disp_lt = m^textinitial_lt\n forall l in L t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"There is a limit on how much primary material can be disposed of at the collection centers:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_l in L z^textc-disp_lt leq m^textc-disp_t\n t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Amount received equals amount processed plus stored. Furthermore, all primary material should be processed by the end of the simulation.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_l in L y_lpt + z^textstore_pt-1\n = z^textproc_pt + z^textstore_pt\n forall p in P t in T \n z^textstore_p0 = 0\n forall p in P \n z^textstore_pt^max = 0\n forall p in P\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants have a limited processing capacity. Furthermore, if a plant is closed, it has zero processing capacity:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n z^textproc_pt leq m^textmin_p x_p + sum_i=0^t w_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants have limited storage capacity. Furthermore, if a plant is closed, is has zero storage capacity:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n z^textstore_pt leq m^textstore_p x_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Plants can only be expanded up to their maximum capacity. Furthermore, if a plant is closed, it cannot be expanded:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n sum_i=0^t w_p leq left( m^textmax_p - m^textmin_p right) x_p\n forall p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Amount of recovered material is proportional to amount processed:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt = alpha_pm z^textproc_pt\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt = z^textp-disp_mpt\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"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.","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n x_pt = x_pt-1 + u_pt\n forall p in P t in T \nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Boundary constants:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n x_p0 = begincases\n 0 text if m^textinit_p = 0 \n 1 text otherwise \n endcases \n w_p0 = maxleft0 m^textinit_p - m^textmin_p right\nendalign*","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"Variable bounds:","category":"page"},{"location":"model/","page":"Optimization Model","title":"Optimization Model","text":"beginalign*\n q_mpt geq 0\n forall m in M p in P t in T \n u_pt in 01\n forall p in P t in T \n w_pt geq 0\n forall p in P t in T \n x_pt in 01\n forall p in P t in T \n y_lpt geq 0\n forall l in L p in P t in T \n z^textc-disp_lt geq 0\n l in L t in T \n z^textstore_pt geq 0\n p in P t in T \n z^textp-disp_mpt z^textproc_mpt geq 0\n forall m in M p in P t in T\nendalign*","category":"page"},{"location":"format/#Input-and-Output-Data-Formats","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce simplified reports in tabular data format.","category":"page"},{"location":"format/#Input-Data-Format-(JSON)","page":"Input and Output Data Formats","title":"Input Data Format (JSON)","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"RELOG accepts as input a JSON file with three sections: parameters, products and plants. Below, we describe each section in more detail.","category":"page"},{"location":"format/#Parameters","page":"Input and Output Data Formats","title":"Parameters","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The parameters section describes details about the simulation itself.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ntime horizon (years) Number of years in the simulation.\nbuilding 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.\ndistance 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\".","category":"page"},{"location":"format/#Example","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"parameters\": {\n \"time horizon (years)\": 2,\n \"building period (years)\": [1],\n \"distance metric\": \"driving\"\n }\n}","category":"page"},{"location":"format/#Products","page":"Input and Output Data Formats","title":"Products","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ntransportation cost ($/km/tonne) The cost to transport this product. Must be a time series.\ntransportation energy (J/km/tonne) The energy required to transport this product. Must be a time series. Optional.\ntransportation 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.\ninitial amounts A dictionary mapping the name of each location to its description (see below). If this product is not initially available, this key may be omitted. Must be a time series.\ndisposal limit (tonne) Total amount of product that can be disposed of across all collection centers. If omitted, all product must be processed. This parameter has no effect on product disposal at plants.\ndisposal cost ($/tonne) Cost of disposing one tonne of this product at a collection center. If omitted, defaults to zero. This parameter has no effect on product disposal costs at plants.\nacquisition cost ($/tonne) Cost of acquiring one tonne of this product at a collection center. If omitted, defaults to zero.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nlatitude (deg) The latitude of the location.\nlongitude (deg) The longitude of the location.\namount (tonne) The amount of the product initially available at the location. Must be a time series.","category":"page"},{"location":"format/#Example-2","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"products\": {\n \"P1\": {\n \"initial amounts\": {\n \"C1\": {\n \"latitude (deg)\": 7.0,\n \"longitude (deg)\": 7.0,\n \"amount (tonne)\": [934.56, 934.56]\n },\n \"C2\": {\n \"latitude (deg)\": 7.0,\n \"longitude (deg)\": 19.0,\n \"amount (tonne)\": [198.95, 198.95]\n },\n \"C3\": {\n \"latitude (deg)\": 84.0,\n \"longitude (deg)\": 76.0,\n \"amount (tonne)\": [212.97, 212.97]\n }\n },\n \"transportation cost ($/km/tonne)\": [0.015, 0.015],\n \"transportation energy (J/km/tonne)\": [0.12, 0.11],\n \"transportation emissions (tonne/km/tonne)\": {\n \"CO2\": [0.052, 0.05],\n \"CH4\": [0.003, 0.002]\n },\n \"disposal cost ($/tonne)\": [-10.0, -12.0],\n \"disposal limit (tonne)\": [1.0, 1.0],\n \"acquisition cost ($/tonne)\": [1.0, 1.0]\n },\n \"P2\": {\n \"transportation cost ($/km/tonne)\": [0.022, 0.02]\n },\n \"P3\": {\n \"transportation cost ($/km/tonne)\": [0.0125, 0.0125]\n },\n \"P4\": {\n \"transportation cost ($/km/tonne)\": [0.0175, 0.0175]\n }\n }\n}","category":"page"},{"location":"format/#Processing-plants","page":"Input and Output Data Formats","title":"Processing plants","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ninput The name of the product that this plant takes as input. Only one input is accepted per plant.\noutputs (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.\nenergy (GJ/tonne) The energy required to process 1 tonne of the input. Must be a time series. Optional.\nemissions (tonne/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). Must be a time series. Optional.\nlocations A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below).","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Each type of plant is associated with a set of potential locations where it can be built. Each location is represented by a dictionary with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nlatitude (deg) The latitude of the location, in degrees.\nlongitude (deg) The longitude of the location, in degrees.\ndisposal A dictionary describing what products can be disposed locally at the plant.\nstorage A dictionary describing the plant's storage.\ncapacities (tonne) A dictionary describing what plant sizes are allowed, and their characteristics.\ninitial capacity (tonne) Capacity already available at this location. Optional.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The storage dictionary should contain the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ncost ($/tonne) The cost to store a tonne of input product for one time period. Must be a time series.\nlimit (tonne) The maximum amount of input product this plant can have in storage at any given time.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The keys in the disposal dictionary should be the names of the products. The values are dictionaries with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\ncost ($/tonne) The cost to dispose of the product. Must be a time series.\nlimit (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.","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"The keys in the capacities (tonne) dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Key Description\nopening cost ($) The cost to open a plant of this size.\nfixed operating cost ($) The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series.\nvariable operating cost ($/tonne) The cost that the plant incurs to process each tonne of input. Must be a time series.","category":"page"},{"location":"format/#Example-3","page":"Input and Output Data Formats","title":"Example","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"plants\": {\n \"F1\": {\n \"input\": \"P1\",\n \"outputs (tonne/tonne)\": {\n \"P2\": 0.2,\n \"P3\": 0.5\n },\n \"energy (GJ/tonne)\": [0.12, 0.11],\n \"emissions (tonne/tonne)\": {\n \"CO2\": [0.052, 0.05],\n \"CH4\": [0.003, 0.002]\n },\n \"locations\": {\n \"L1\": {\n \"latitude (deg)\": 0.0,\n \"longitude (deg)\": 0.0,\n \"disposal\": {\n \"P2\": {\n \"cost ($/tonne)\": [-10.0, -12.0],\n \"limit (tonne)\": [1.0, 1.0]\n }\n },\n \"storage\": {\n \"cost ($/tonne)\": [5.0, 5.3],\n \"limit (tonne)\": 100.0\n },\n \"capacities (tonne)\": {\n \"100\": {\n \"opening cost ($)\": [500, 530],\n \"fixed operating cost ($)\": [300.0, 310.0],\n \"variable operating cost ($/tonne)\": [5.0, 5.2]\n },\n \"500\": {\n \"opening cost ($)\": [750, 760],\n \"fixed operating cost ($)\": [400.0, 450.0],\n \"variable operating cost ($/tonne)\": [5.0, 5.2]\n }\n }\n }\n }\n }\n }\n}","category":"page"},{"location":"format/#Geographic-database","page":"Input and Output Data Formats","title":"Geographic database","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Instead of specifying locations using latitudes and longitudes, it is also possible to specify them using unique identifiers, such as the name of a US state, or the county FIPS code. This works anywhere latitude (deg) and longitude (deg) are expected. For example, instead of:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"initial amounts\": {\n \"C1\": {\n \"latitude (deg)\": 37.27182,\n \"longitude (deg)\": -119.2704,\n \"amount (tonne)\": [934.56, 934.56]\n }\n }\n}","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"is is possible to write:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"{\n \"initial amounts\": {\n \"C1\": {\n \"location\": \"us-state:CA\",\n \"amount (tonne)\": [934.56, 934.56]\n }\n }\n}","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"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:","category":"page"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Database Description Examples\nus-state List of states of the United States. us-state:IL (State of Illinois)\n2018-us-county List of United States counties, as of 2018. IDs are 5-digit FIPS codes. 2018-us-county:17043 (DuPage county in Illinois)","category":"page"},{"location":"format/#Current-limitations","page":"Input and Output Data Formats","title":"Current limitations","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation.\nPlants can be expanded at any time, even long after they are open.\nAll 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.\nUp to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes.\nAccurate driving distances are only available for the continental United States.","category":"page"},{"location":"format/#Output-Data-Format-(JSON)","page":"Input and Output Data Formats","title":"Output Data Format (JSON)","text":"","category":"section"},{"location":"format/","page":"Input and Output Data Formats","title":"Input and Output Data Formats","text":"To be documented.","category":"page"},{"location":"#RELOG:-Reverse-Logistics-Optimization","page":"Home","title":"RELOG: Reverse Logistics Optimization","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"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.","category":"page"},{"location":"","page":"Home","title":"Home","text":"
      \n \n
      ","category":"page"},{"location":"#Table-of-Contents","page":"Home","title":"Table of Contents","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Pages = [\"usage.md\", \"format.md\", \"reports.md\", \"model.md\"]\nDepth = 3","category":"page"},{"location":"#Source-Code","page":"Home","title":"Source Code","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"https://github.com/ANL-CEEESA/RELOG","category":"page"},{"location":"#Authors","page":"Home","title":"Authors","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Alinson S. Xavier, Argonne National Laboratory \nNwike Iloeje, Argonne National Laboratory \nJohn Atkins\nKyle Sun\nAudrey Gallier","category":"page"},{"location":"#License","page":"Home","title":"License","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"RELOG: Reverse Logistics Optimization\nCopyright © 2020, UChicago Argonne, LLC. All Rights Reserved.\n\nRedistribution and use in source and binary forms, with or without modification, are permitted\nprovided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice, this list of\n conditions and the following disclaimer.\n2. Redistributions in binary form must reproduce the above copyright notice, this list of\n conditions and the following disclaimer in the documentation and/or other materials provided\n with the distribution.\n3. Neither the name of the copyright holder nor the names of its contributors may be used to\n endorse or promote products derived from this software without specific prior written\n permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR\nIMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY\nAND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR\nCONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY\nTHEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR\nOTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.","category":"page"}] } diff --git a/0.7/usage/index.html b/0.7/usage/index.html index ff4d9f4..96628f0 100644 --- a/0.7/usage/index.html +++ b/0.7/usage/index.html @@ -1,6 +1,6 @@ Usage · RELOG
      Edit on GitHub

      Usage

      1. Installation

      To use RELOG, the first step is to install the Julia programming language 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:

      using Pkg
-Pkg.add(name="RELOG", version="0.6")

      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.

      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:

      # Import package
+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.

      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:

      # Import package
 using RELOG
 
 # Solve optimization problem
@@ -43,4 +43,4 @@ RELOG.solve(
 solution = RELOG.solve(
     "/home/user/instance.json",
     heuristic=true,
-)
      +)