mirror of https://github.com/ANL-CEEESA/RELOG.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
47 lines
16 KiB
47 lines
16 KiB
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Usage · RELOG</title><script data-outdated-warner src="../assets/warner.js"></script><link href="https://cdnjs.cloudflare.com/ajax/libs/lato-font/3.0.0/css/lato-font.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/juliamono/0.045/juliamono.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.13.24/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark" data-theme-primary-dark/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script><link href="../assets/custom.css" rel="stylesheet" type="text/css"/></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit"><a href="../">RELOG</a></span></div><form class="docs-search" action="../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../">Home</a></li><li class="is-active"><a class="tocitem" href>Usage</a><ul class="internal"><li><a class="tocitem" href="#.-Installation"><span>1. Installation</span></a></li><li><a class="tocitem" href="#.-Modeling-the-problem"><span>2. Modeling the problem</span></a></li><li><a class="tocitem" href="#.-Running-the-optimization"><span>3. Running the optimization</span></a></li><li><a class="tocitem" href="#.-What-If-Analysis"><span>4. What-If Analysis</span></a></li><li><a class="tocitem" href="#.-Advanced-options"><span>5. Advanced options</span></a></li></ul></li><li><a class="tocitem" href="../format/">Input and Output Data Formats</a></li><li><a class="tocitem" href="../reports/">Simplified Solution Reports</a></li><li><a class="tocitem" href="../model/">Optimization Model</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Usage</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Usage</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/ANL-CEEESA/RELOG/blob/master/docs/src/usage.md" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Usage"><a class="docs-heading-anchor" href="#Usage">Usage</a><a id="Usage-1"></a><a class="docs-heading-anchor-permalink" href="#Usage" title="Permalink"></a></h1><h2 id=".-Installation"><a class="docs-heading-anchor" href="#.-Installation">1. Installation</a><a id=".-Installation-1"></a><a class="docs-heading-anchor-permalink" href="#.-Installation" title="Permalink"></a></h2><p>To use RELOG, the first step is to install the <a href="https://julialang.org/">Julia programming language</a> 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:</p><pre><code class="language-julia hljs">using Pkg
|
|
Pkg.add(name="RELOG", version="0.6")</code></pre><p>After the package and all its dependencies have been installed, please run the RELOG test suite, as shown below, to make sure that the package has been correctly installed:</p><pre><code class="language-julia hljs">Pkg.test("RELOG")</code></pre><h2 id=".-Modeling-the-problem"><a class="docs-heading-anchor" href="#.-Modeling-the-problem">2. Modeling the problem</a><a id=".-Modeling-the-problem-1"></a><a class="docs-heading-anchor-permalink" href="#.-Modeling-the-problem" title="Permalink"></a></h2><p>The two main model components in RELOG are <strong>products</strong> and <strong>plants</strong>.</p><p>A <strong>product</strong> 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.</p><ul><li><p>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.</p></li><li><p>Products that are initially available must be sent to a plant for processing during the same time period they became available.</p></li><li><p>Transporting products from one location to another incurs a transportation cost (<code>$/km/tonne</code>), spends some amount of energy (<code>J/km/tonne</code>) and may generate multiple types of emissions (<code>tonne/tonne</code>). All these parameters are user-specified and may be product- and time-specific.</p></li></ul><p>A <strong>plant</strong> 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 <em>disassembly plant</em>, which converts <em>batteries</em> into <em>cathode</em> and <em>anode</em>. Another type of plant could be <em>anode recycling plant</em>, which converts <em>anode</em> into <em>rare-earth elements</em> and <em>scrap metals</em>.</p><ul><li><p>To process each tonne of input material, plants incur a variable operating cost (<code>$/tonne</code>), spend some amount of energy (<code>GJ/tonne</code>), and produce multiple types of emissions (<code>tonne/tonne</code>). Plants also incur a fixed operating cost (<code>$</code>) regardless of the amount of material they process. All these parameters are user-specified and may be region- and time-specific.</p></li><li><p>Plants can be built at user-specified potential locations. Opening a plant incurs a one-time opening cost (<code>$</code>) which may be region- and time-specific. Plants also have a limited capacity (in <code>tonne</code>), 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.</p></li><li><p>Products received by a plant can be either processed immediately or stored for later processing. Plants have a maximum storage capacity (<code>tonne</code>). Storage costs (<code>$/tonne</code>) can also be specified.</p></li><li><p>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 (<code>$/tonne</code>). To model environmental regulations, it is also possible to specify the maximum amount of each product that can be disposed of at each location.</p></li></ul><p>All user parameters specified above must be provided to RELOG as a JSON file, which is fully described in the <a href="../format/">data format page</a>.</p><h2 id=".-Running-the-optimization"><a class="docs-heading-anchor" href="#.-Running-the-optimization">3. Running the optimization</a><a id=".-Running-the-optimization-1"></a><a class="docs-heading-anchor-permalink" href="#.-Running-the-optimization" title="Permalink"></a></h2><p>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:</p><pre><code class="language-julia hljs"># Import package
|
|
using RELOG
|
|
|
|
# Solve optimization problem
|
|
solution = RELOG.solve("/home/user/instance.json")
|
|
|
|
# Write full solution in JSON format
|
|
RELOG.write(solution, "solution.json")
|
|
|
|
# Write simplified reports in CSV format
|
|
RELOG.write_plants_report(solution, "plants.csv")
|
|
RELOG.write_transportation_report(solution, "transportation.csv")</code></pre><p>For a complete description of the file formats above, and for a complete list of available reports, see the <a href="../format/">data format page</a>.</p><h2 id=".-What-If-Analysis"><a class="docs-heading-anchor" href="#.-What-If-Analysis">4. What-If Analysis</a><a id=".-What-If-Analysis-1"></a><a class="docs-heading-anchor-permalink" href="#.-What-If-Analysis" title="Permalink"></a></h2><p>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.</p><p>To simplify this what-if analysis, RELOG provides the <code>resolve</code> 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 <code>resolve</code> 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.</p><p>The following snippet shows how to use the method:</p><pre><code class="language-julia hljs"># Import package
|
|
using RELOG
|
|
|
|
# Optimize for the average scenario
|
|
solution_avg, model_avg = RELOG.solve("input_avg.json", return_model=true)
|
|
|
|
# Write reports for the average scenario
|
|
RELOG.write_plants_report(solution_avg, "plants_avg.csv")
|
|
RELOG.write_transportation_report(solution_avg, "transportation_avg.csv")
|
|
|
|
# Re-optimize for the high-demand scenario, keeping plants fixed
|
|
solution_high = RELOG.resolve(model_avg, "input_high.json")
|
|
|
|
# Write reports for the high-demand scenario
|
|
RELOG.write_plants_report(solution_high, "plants_high.csv")
|
|
RELOG.write_transportation_report(solution_high, "transportation_high.csv")</code></pre><p>To use the <code>resolve</code> method, the new input file should be very similar to the original one. Only the following entries are allowed to change:</p><ul><li><strong>Products:</strong> Transportation costs, energy, emissions and initial amounts (latitude, longitude and amount).</li><li><strong>Plants:</strong> Energy and emissions.</li><li><strong>Plant's location:</strong> Latitude and longitude.</li><li><strong>Plant's storage:</strong> Cost.</li><li><strong>Plant's capacity:</strong> Opening cost, fixed operating cost and variable operating cost.</li></ul><h2 id=".-Advanced-options"><a class="docs-heading-anchor" href="#.-Advanced-options">5. Advanced options</a><a id=".-Advanced-options-1"></a><a class="docs-heading-anchor-permalink" href="#.-Advanced-options" title="Permalink"></a></h2><h3 id=".1-Changing-the-solver"><a class="docs-heading-anchor" href="#.1-Changing-the-solver">5.1 Changing the solver</a><a id=".1-Changing-the-solver-1"></a><a class="docs-heading-anchor-permalink" href="#.1-Changing-the-solver" title="Permalink"></a></h3><p>By default, RELOG internally uses <a href="https://github.com/coin-or/Cbc">Cbc</a>, an open-source and freely-available Mixed-Integer Linear Programming solver developed by the <a href="https://www.coin-or.org/">COIN-OR Project</a>. For larger-scale test cases, a commercial solver such as Gurobi, CPLEX or XPRESS is recommended. The following snippet shows how to switch from Cbc to Gurobi, for example:</p><pre><code class="language-julia hljs">using RELOG, Gurobi, JuMP
|
|
|
|
gurobi = optimizer_with_attributes(
|
|
Gurobi.Optimizer,
|
|
"TimeLimit" => 3600,
|
|
"MIPGap" => 0.001,
|
|
)
|
|
|
|
RELOG.solve(
|
|
"instance.json",
|
|
output="solution.json",
|
|
optimizer=gurobi,
|
|
)</code></pre><h3 id=".2-Multi-period-heuristics"><a class="docs-heading-anchor" href="#.2-Multi-period-heuristics">5.2 Multi-period heuristics</a><a id=".2-Multi-period-heuristics-1"></a><a class="docs-heading-anchor-permalink" href="#.2-Multi-period-heuristics" title="Permalink"></a></h3><p>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:</p><ol><li><p>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.</p></li><li><p>After solving the simplified problem, RELOG resolves the multi-period version of the problem, but considering only candidate plant locations that were selected by the optimal solution to the single-period version of the problem. All remaining candidate plant locations are removed.</p></li></ol><p>To solve an instance using this heuristic, use the option <code>heuristic=true</code>, as shown below.</p><pre><code class="language-julia hljs">using RELOG
|
|
|
|
solution = RELOG.solve(
|
|
"/home/user/instance.json",
|
|
heuristic=true,
|
|
)</code></pre></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../">« Home</a><a class="docs-footer-nextpage" href="../format/">Input and Output Data Formats »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 0.27.23 on <span class="colophon-date" title="Thursday 15 December 2022 10:35">Thursday 15 December 2022</span>. Using Julia version 1.6.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|