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.
103 lines
21 KiB
103 lines
21 KiB
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Input and Output Data Formats · 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><a class="tocitem" href="../usage/">Usage</a></li><li class="is-active"><a class="tocitem" href>Input and Output Data Formats</a><ul class="internal"><li><a class="tocitem" href="#Input-Data-Format-(JSON)"><span>Input Data Format (JSON)</span></a></li><li><a class="tocitem" href="#Output-Data-Format-(JSON)"><span>Output Data Format (JSON)</span></a></li></ul></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>Input and Output Data Formats</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Input and Output Data Formats</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/ANL-CEEESA/RELOG/blob/master/docs/src/format.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="Input-and-Output-Data-Formats"><a class="docs-heading-anchor" href="#Input-and-Output-Data-Formats">Input and Output Data Formats</a><a id="Input-and-Output-Data-Formats-1"></a><a class="docs-heading-anchor-permalink" href="#Input-and-Output-Data-Formats" title="Permalink"></a></h1><p>In this page, we describe the input and output JSON formats used by RELOG. In addition to these, RELOG can also produce <a href="../reports/">simplified reports</a> in tabular data format.</p><h2 id="Input-Data-Format-(JSON)"><a class="docs-heading-anchor" href="#Input-Data-Format-(JSON)">Input Data Format (JSON)</a><a id="Input-Data-Format-(JSON)-1"></a><a class="docs-heading-anchor-permalink" href="#Input-Data-Format-(JSON)" title="Permalink"></a></h2><p>RELOG accepts as input a JSON file with three sections: <code>parameters</code>, <code>products</code> and <code>plants</code>. Below, we describe each section in more detail.</p><h3 id="Parameters"><a class="docs-heading-anchor" href="#Parameters">Parameters</a><a id="Parameters-1"></a><a class="docs-heading-anchor-permalink" href="#Parameters" title="Permalink"></a></h3><p>The <strong>parameters</strong> section describes details about the simulation itself.</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>time horizon (years)</code></td><td style="text-align: left">Number of years in the simulation.</td></tr><tr><td style="text-align: left"><code>building period (years)</code></td><td style="text-align: left">List of years in which we are allowed to open new plants. For example, if this parameter is set to <code>[1,2,3]</code>, we can only open plants during the first three years. By default, this equals <code>[1]</code>; that is, plants can only be opened during the first year.</td></tr></table><h4 id="Example"><a class="docs-heading-anchor" href="#Example">Example</a><a id="Example-1"></a><a class="docs-heading-anchor-permalink" href="#Example" title="Permalink"></a></h4><pre><code class="language-json hljs">{
|
|
"parameters": {
|
|
"time horizon (years)": 2,
|
|
"building period (years)": [1]
|
|
}
|
|
}</code></pre><h3 id="Products"><a class="docs-heading-anchor" href="#Products">Products</a><a id="Products-1"></a><a class="docs-heading-anchor-permalink" href="#Products" title="Permalink"></a></h3><p>The <strong>products</strong> section describes all products and subproducts in the simulation. The field <code>instance["Products"]</code> is a dictionary mapping the name of the product to a dictionary which describes its characteristics. Each product description contains the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>transportation cost ($/km/tonne)</code></td><td style="text-align: left">The cost to transport this product. Must be a time series.</td></tr><tr><td style="text-align: left"><code>transportation energy (J/km/tonne)</code></td><td style="text-align: left">The energy required to transport this product. Must be a time series. Optional.</td></tr><tr><td style="text-align: left"><code>transportation emissions (tonne/km/tonne)</code></td><td style="text-align: left">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.</td></tr><tr><td style="text-align: left"><code>initial amounts</code></td><td style="text-align: left">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.</td></tr></table><p>Each product may have some amount available at the beginning of each time period. In this case, the key <code>initial amounts</code> maps to a dictionary with the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>latitude (deg)</code></td><td style="text-align: left">The latitude of the location.</td></tr><tr><td style="text-align: left"><code>longitude (deg)</code></td><td style="text-align: left">The longitude of the location.</td></tr><tr><td style="text-align: left"><code>amount (tonne)</code></td><td style="text-align: left">The amount of the product initially available at the location. Must be a time series.</td></tr></table><h4 id="Example-2"><a class="docs-heading-anchor" href="#Example-2">Example</a><a class="docs-heading-anchor-permalink" href="#Example-2" title="Permalink"></a></h4><pre><code class="language-json hljs">{
|
|
"products": {
|
|
"P1": {
|
|
"initial amounts": {
|
|
"C1": {
|
|
"latitude (deg)": 7.0,
|
|
"longitude (deg)": 7.0,
|
|
"amount (tonne)": [934.56, 934.56]
|
|
},
|
|
"C2": {
|
|
"latitude (deg)": 7.0,
|
|
"longitude (deg)": 19.0,
|
|
"amount (tonne)": [198.95, 198.95]
|
|
},
|
|
"C3": {
|
|
"latitude (deg)": 84.0,
|
|
"longitude (deg)": 76.0,
|
|
"amount (tonne)": [212.97, 212.97]
|
|
}
|
|
},
|
|
"transportation cost ($/km/tonne)": [0.015, 0.015],
|
|
"transportation energy (J/km/tonne)": [0.12, 0.11],
|
|
"transportation emissions (tonne/km/tonne)": {
|
|
"CO2": [0.052, 0.050],
|
|
"CH4": [0.003, 0.002]
|
|
}
|
|
},
|
|
"P2": {
|
|
"transportation cost ($/km/tonne)": [0.022, 0.020]
|
|
},
|
|
"P3": {
|
|
"transportation cost ($/km/tonne)": [0.0125, 0.0125]
|
|
},
|
|
"P4": {
|
|
"transportation cost ($/km/tonne)": [0.0175, 0.0175]
|
|
}
|
|
}
|
|
}</code></pre><h3 id="Processing-plants"><a class="docs-heading-anchor" href="#Processing-plants">Processing plants</a><a id="Processing-plants-1"></a><a class="docs-heading-anchor-permalink" href="#Processing-plants" title="Permalink"></a></h3><p>The <strong>plants</strong> section describes the available types of reverse manufacturing plants, their potential locations and associated costs, as well as their inputs and outputs. The field <code>instance["Plants"]</code> is a dictionary mapping the name of the plant to a dictionary with the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>input</code></td><td style="text-align: left">The name of the product that this plant takes as input. Only one input is accepted per plant.</td></tr><tr><td style="text-align: left"><code>outputs (tonne/tonne)</code></td><td style="text-align: left">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 <code>{"P2": 0.5, "P3": 0.25}</code>. If the plant does not output anything, this key may be omitted.</td></tr><tr><td style="text-align: left"><code>energy (GJ/tonne)</code></td><td style="text-align: left">The energy required to process 1 tonne of the input. Must be a time series. Optional.</td></tr><tr><td style="text-align: left"><code>emissions (tonne/tonne)</code></td><td style="text-align: left">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.</td></tr><tr><td style="text-align: left"><code>locations</code></td><td style="text-align: left">A dictionary mapping the name of the location to a dictionary which describes the site characteristics (see below).</td></tr></table><p>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:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: right">Description</th></tr><tr><td style="text-align: left"><code>latitude (deg)</code></td><td style="text-align: right">The latitude of the location, in degrees.</td></tr><tr><td style="text-align: left"><code>longitude (deg)</code></td><td style="text-align: right">The longitude of the location, in degrees.</td></tr><tr><td style="text-align: left"><code>disposal</code></td><td style="text-align: right">A dictionary describing what products can be disposed locally at the plant.</td></tr><tr><td style="text-align: left"><code>storage</code></td><td style="text-align: right">A dictionary describing the plant's storage.</td></tr><tr><td style="text-align: left"><code>capacities (tonne)</code></td><td style="text-align: right">A dictionary describing what plant sizes are allowed, and their characteristics.</td></tr></table><p>The <code>storage</code> dictionary should contain the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>cost ($/tonne)</code></td><td style="text-align: left">The cost to store a tonne of input product for one time period. Must be a time series.</td></tr><tr><td style="text-align: left"><code>limit (tonne)</code></td><td style="text-align: left">The maximum amount of input product this plant can have in storage at any given time.</td></tr></table><p>The keys in the <code>disposal</code> dictionary should be the names of the products. The values are dictionaries with the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>cost ($/tonne)</code></td><td style="text-align: left">The cost to dispose of the product. Must be a time series.</td></tr><tr><td style="text-align: left"><code>limit (tonne)</code></td><td style="text-align: left">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.</td></tr></table><p>The keys in the <code>capacities (tonne)</code> dictionary should be the amounts (in tonnes). The values are dictionaries with the following keys:</p><table><tr><th style="text-align: left">Key</th><th style="text-align: left">Description</th></tr><tr><td style="text-align: left"><code>opening cost ($)</code></td><td style="text-align: left">The cost to open a plant of this size.</td></tr><tr><td style="text-align: left"><code>fixed operating cost ($)</code></td><td style="text-align: left">The cost to keep the plant open, even if the plant doesn't process anything. Must be a time series.</td></tr><tr><td style="text-align: left"><code>variable operating cost ($/tonne)</code></td><td style="text-align: left">The cost that the plant incurs to process each tonne of input. Must be a time series.</td></tr></table><h4 id="Example-3"><a class="docs-heading-anchor" href="#Example-3">Example</a><a class="docs-heading-anchor-permalink" href="#Example-3" title="Permalink"></a></h4><pre><code class="language-json hljs">{
|
|
"plants": {
|
|
"F1": {
|
|
"input": "P1",
|
|
"outputs (tonne/tonne)": {
|
|
"P2": 0.2,
|
|
"P3": 0.5
|
|
},
|
|
"energy (GJ/tonne)": [0.12, 0.11],
|
|
"emissions (tonne/tonne)": {
|
|
"CO2": [0.052, 0.050],
|
|
"CH4": [0.003, 0.002]
|
|
},
|
|
"locations": {
|
|
"L1": {
|
|
"latitude (deg)": 0.0,
|
|
"longitude (deg)": 0.0,
|
|
"disposal": {
|
|
"P2": {
|
|
"cost ($/tonne)": [-10.0, -12.0],
|
|
"limit (tonne)": [1.0, 1.0]
|
|
}
|
|
},
|
|
"storage": {
|
|
"cost ($/tonne)": [5.0, 5.3],
|
|
"limit (tonne)": 100.0,
|
|
},
|
|
"capacities (tonne)": {
|
|
"100": {
|
|
"opening cost ($)": [500, 530],
|
|
"fixed operating cost ($)": [300.0, 310.0],
|
|
"variable operating cost ($/tonne)": [5.0, 5.2],
|
|
},
|
|
"500": {
|
|
"opening cost ($)": [750, 760],
|
|
"fixed operating cost ($)": [400.0, 450.0],
|
|
"variable operating cost ($/tonne)": [5.0, 5.2]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}</code></pre><h3 id="Geographic-database"><a class="docs-heading-anchor" href="#Geographic-database">Geographic database</a><a id="Geographic-database-1"></a><a class="docs-heading-anchor-permalink" href="#Geographic-database" title="Permalink"></a></h3><p>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 <code>latitude (deg)</code> and <code>longitude (deg)</code> are expected. For example, instead of:</p><pre><code class="language-json hljs">{
|
|
"initial amounts": {
|
|
"C1": {
|
|
"latitude (deg)": 37.27182,
|
|
"longitude (deg)": -119.2704,
|
|
"amount (tonne)": [934.56, 934.56]
|
|
},
|
|
}
|
|
}</code></pre><p>is is possible to write:</p><pre><code class="language-json hljs">{
|
|
"initial amounts": {
|
|
"C1": {
|
|
"location": "us-state:CA",
|
|
"amount (tonne)": [934.56, 934.56]
|
|
},
|
|
}
|
|
}</code></pre><p>Location names follow the format <code>db:id</code>, where <code>db</code> is the name of the database and <code>id</code> is the identifier for a specific location. RELOG currently includes the following databases:</p><table><tr><th style="text-align: left">Database</th><th style="text-align: left">Description</th><th style="text-align: left">Examples</th></tr><tr><td style="text-align: left"><code>us-state</code></td><td style="text-align: left">List of states of the United States.</td><td style="text-align: left"><code>us-state:IL</code> (State of Illinois)</td></tr><tr><td style="text-align: left"><code>2018-us-county</code></td><td style="text-align: left">List of United States counties, as of 2018. IDs are 5-digit FIPS codes.</td><td style="text-align: left"><code>2018-us-county:17043</code> (DuPage county in Illinois)</td></tr></table><h3 id="Current-limitations"><a class="docs-heading-anchor" href="#Current-limitations">Current limitations</a><a id="Current-limitations-1"></a><a class="docs-heading-anchor-permalink" href="#Current-limitations" title="Permalink"></a></h3><ul><li>Each plant can only be opened exactly once. After open, the plant remains open until the end of the simulation.</li><li>Plants can be expanded at any time, even long after they are open.</li><li>All material available at the beginning of a time period must be entirely processed by the end of that time period. It is not possible to store unprocessed materials from one time period to the next.</li><li>Up to two plant sizes are currently supported. Variable operating costs must be the same for all plant sizes.</li></ul><h2 id="Output-Data-Format-(JSON)"><a class="docs-heading-anchor" href="#Output-Data-Format-(JSON)">Output Data Format (JSON)</a><a id="Output-Data-Format-(JSON)-1"></a><a class="docs-heading-anchor-permalink" href="#Output-Data-Format-(JSON)" title="Permalink"></a></h2><p>To be documented.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../usage/">« Usage</a><a class="docs-footer-nextpage" href="../reports/">Simplified Solution Reports »</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.21 on <span class="colophon-date" title="Friday 26 August 2022 13:01">Friday 26 August 2022</span>. Using Julia version 1.7.3.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|