{"id":17,"date":"2024-01-11T23:00:00","date_gmt":"2024-01-11T23:00:00","guid":{"rendered":"https:\/\/greoux.re\/explore\/?p=17"},"modified":"2024-01-11T23:00:00","modified_gmt":"2024-01-11T23:00:00","slug":"ieso-io-file-structure","status":"publish","type":"post","link":"https:\/\/greoux.re\/explore\/ieso-io-file-structure\/","title":{"rendered":"IESO IO File Structure"},"content":{"rendered":"\n<!--more-->\n\n\n<div class=\"alert alert-light\" role=\"alert\"> <div style=\"line-height: 1.75;\"> Recommended Citation:<br\/> Gr\u00e9oux Research. (2024). IESO IO File Structure. Online Article.<br\/> <a href=\"https:\/\/greoux.re\/explore\/ieso-io-file-structure\/\">https:\/\/greoux.re\/explore\/ieso-io-file-structure\/<\/a> <\/div> <\/div>\n\n\n<h4 class=\"wp-block-heading\">Introduction<\/h4>\n\n\n<p>This article documents the input-output (IO) file structure used by the <a href=\"https:\/\/github.com\/greoux-research\/ieso\" rel=\"noreferrer noopener\" target=\"_blank\">Integrated Energy Systems Optimiser<\/a> (IESO), a linear optimiser-based energy system modelling environment designed to support initial investigations such as options evaluation and trend analysis.<\/p>\n\n\n<div class=\"vsep1\"><\/div>\n<div class=\"text-center\">\n<div class=\"button\">\n<a class=\"btn btn-lg btn-primary\" href=\"https:\/\/github.com\/greoux-research\/ieso\" rel=\"noopener\" target=\"_blank\">\n<i class=\"bi bi-github\"><\/i>\n\u00a0\nGet IESO\n<\/a>\n<\/div>\n<\/div>\n<div class=\"vsep1\"><\/div>\n\n\n<p>IESO&#8217;s modelling approach is described in <a href=\"https:\/\/greoux.re\/explore\/ieso-modelling-approach\/\" rel=\"noreferrer noopener\">this article<\/a>. Installation and run instructions can be found in\u00a0<a href=\"https:\/\/greoux.re\/explore\/ieso-setup-guide\/\" rel=\"noreferrer noopener\">the setup guide<\/a>.<\/p>\n\n\n<p>IESO is called with one or two arguments: (1) a JSON file (referred to as <code>input.json<\/code>) that describes the dataset, and (2) an optional carbon constraint. The output is a file named <code>input.ieso.json<\/code>. It mirrors <code>input.json<\/code> and adds the optimisation results in place. <\/p>\n\n\n<h4 class=\"wp-block-heading\">High-level overview<\/h4>\n\n\n<p>An IESO dataset defines primary demands (electricity and X commodities: heat, hydrogen, water) and the supply and flexibility options that meet them. The JSON below shows the top-level structure.<\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/4ba64159422095d0e5277f5103fa580c.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<p>The five top-level objects are: <code>demand<\/code> (electricity and X), <code>p2x<\/code> (Power-to-X processes), <code>generator<\/code> (power generators), <code>flex<\/code> (flexibility means), and <code>solver<\/code> (linear solver summary). <\/p>\n\n\n<p>The philosophy of IESO is to first define the demand and its hourly profile, and then describe how this demand is met:<\/p>\n\n\n<ul class=\"wp-block-list\">\n<li>Electricity demand &#8211; whether primary (final consumption) or secondary (for battery charging or the operation of PtX processes) &#8211; is always met by the &#8220;grid&#8221;, i.e. the mix of available generators.<\/li>\n\n\n<li>Demand for commodity X (heat, hydrogen, water) is met by PtX processes, which consume electricity from the &#8220;grid&#8221; and, where relevant, heat from cogeneration plants.<\/li>\n<\/ul>\n\n\n<h4 class=\"wp-block-heading\">Demand objects<\/h4>\n\n\n<p>Demand objects represent the final consumption of electricity and other commodities (heat, hydrogen, water). Each demand entry follows a consistent structure.<\/p>\n\n\n<p><span class=\"spotlight\">Demand for electricity<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/3ef97e7b09343e1889e37f824c57e7f6.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<p><span class=\"spotlight\">Demand for other commodities (heat, hydrogen, water)<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/010132c083a89c361d0348978aa87266.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<h5 class=\"wp-block-heading\">General attributes<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>iden<\/code> &#8211; identifier (<em>electricity<\/em>, <em>heat<\/em>, <em>hydrogen<\/em>, or <em>water<\/em>)<\/li>\n\n\n<li><code>total<\/code> &#8211; annual demand (MWh, kg, or m\u00b3 depending on commodity)<\/li>\n\n\n<li><code>profile<\/code> &#8211; optional CSV with 8760 hourly values. May be provided as (1) a CSV file path, (2) an array of 8760 values, or (3) empty for a flat profile.<\/li>\n\n\n<li><code>supply_sources<\/code> &#8211; PtX processes supplying the X commodity (a list of <code>iden<\/code> of PtX processes is expected here)<\/li>\n\n\n<li><code>var_cost_ns<\/code> &#8211; penalty for unmet demand ($\/MWh, $\/kg, $\/m\u00b3)<\/li>\n\n\n<li><code>l_ns<\/code> &#8211; lower and upper bounds on annual unmet demand<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Outputs<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>output_ns<\/code> &#8211; hourly unmet demand<\/li>\n\n\n<li><code>shadow_prices[\"demand_match\"]<\/code> &#8211; hourly shadow prices ($\/unit), or, more precisely, the hourly marginal value of meeting one additional unit of demand (in $\/unit). It corresponds to the dual variable of the demand-balance constraint, reflecting the system cost reduction associated with a 1-unit increase in demand satisfaction during that hour. This value is defined for both electricity and all other commodities X (heat, hydrogen, water).<\/li>\n\n\n<li><code>shadow_prices[\"carbon_cap\"]<\/code> &#8211; carbon constraint shadow price ($\/unit). It measures the implicit cost of relaxing the system-wide carbon emission limit by one unit. This price applies only to the primary electricity demand, since the emission constraint is global and directly linked to total electricity generation.<\/li>\n\n\n<li><code>shadow_prices[\"reliability_cap\"]<\/code> &#8211; reliability constraint shadow price ($\/unit). It measures the marginal system cost of relaxing the reliability requirement by one unit of served electricity. This variable also applies only to the primary electricity demand, reflecting the upper constraint on non-served electricity (the \u201cnon-served power\u201d constraint).<\/li>\n\n\n<li><code><code>kpis[\"cost\"]<\/code><\/code> &#8211; average cost per unit of delivered output ($\/unit). It is derived from the total system cost (fixed + variable) incurred to meet all demands, allocated to each demand category in proportion to its electricity consumption.<\/li>\n\n\n<li><code><code>kpis[\"emis\"]<\/code><\/code> &#8211; average emissions per unit of delivered output (kg CO\u2082eq\/unit). It follows the same allocation principle as cost, i.e., emissions are distributed on the basis of electricity use.<\/li>\n\n\n<li><code><code>kpis[\"reli\"]<\/code><\/code> &#8211; reliability factor (%). The reliability factor expresses the system\u2019s ability to continuously meet the hourly demand for electricity or any other commodity X throughout the year. It quantifies the proportion of total demand that is effectively served, providing a direct measure of system adequacy and security of supply.<\/li>\n<\/ul>\n\n\n<h4 class=\"wp-block-heading\">Power-to-X (PtX) processes \u00a0 | \u00a0 <a href=\"https:\/\/greoux.re\/explore\/ieso-modelling-approach\/#ptx-processes\" rel=\"noreferrer noopener\">Modelling approach \u2192<\/a><\/h4>\n\n\n<p>PtX processes convert electricity, and sometimes heat, into products such as hydrogen, water, or heat. Each process combines general attributes, a production unit, and a storage unit.<\/p>\n\n\n<div class=\"text-center my-4\">\n<img decoding=\"async\" alt=\"IESO Representation of a PtX Process\" class=\"img-fluid\" src=\"https:\/\/greoux.re\/explore\/wp-content\/media\/img\/ieso-modelling-approach\/power-to-x.png\" style=\"max-width:50%;\"\/>\n<\/div>\n\n\n<p>PtX processes are described by a consistent JSON structure.<\/p>\n\n\n<p><span class=\"spotlight\">Electricity-consuming process (e.g., RO)<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/65095af825c5f3844a576097a5ed6e33.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<p><span class=\"spotlight\">Electricity- and heat-consuming process (e.g., MED)<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/b1cd0e431271117612a1428fd7f89d08.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<h5 class=\"wp-block-heading\">General attributes<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>type<\/code> &#8211; <em>elec<\/em> (electric only) or <em>elec + ther<\/em> (electricity plus heat)<\/li>\n\n\n<li><code>temperature<\/code> &#8211; required steam extraction temperature (\u00b0C, thermal processes only)<\/li>\n\n\n<li><code>capacity_factor<\/code> &#8211; capacity factor of the plant (fraction)<\/li>\n\n\n<li><code>profile<\/code> &#8211; optional CSV with 8760 hourly values. May be provided as (1) a CSV file path, (2) an array of 8760 values, or (3) empty for a flat profile.<\/li>\n\n\n<li><code>supply_sources<\/code> &#8211; thermal generators eligible to supply heat in cogeneration mode (a list of <code>iden<\/code> of thermal generators is expected here)<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Production unit<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>c_prod<\/code> &#8211; production capacity (Q\/hour). Will be optimised by the solver if set to -1<\/li>\n\n\n<li><code>l_prod<\/code> &#8211; lower and upper bounds (Q\/hour)<\/li>\n\n\n<li><code>fix_cost_prod<\/code> &#8211; fixed production costs ($ per (Q\/hour) per year)<\/li>\n\n\n<li><code>var_cost_prod<\/code> &#8211; variable costs excluding energy ($\/Q)<\/li>\n\n\n<li><code>pow_use_elec_prod<\/code> &#8211; electricity use (MWh\/Q)<\/li>\n\n\n<li><code>pow_use_ther_prod<\/code> &#8211; heat use (MWh\/Q)<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Storage unit<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>c_strg<\/code> &#8211; storage capacity (Q). Will be optimised by the solver if set to -1<\/li>\n\n\n<li><code>l_strg<\/code> &#8211; lower and upper bounds (Q)<\/li>\n\n\n<li><code>fix_cost_strg<\/code> &#8211; fixed storage costs ($ per Q per year)<\/li>\n\n\n<li><code>soc_ini<\/code> &#8211; initial state of charge (fraction of <code>c_strg<\/code>)<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Outputs<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>x_prod<\/code> &#8211; hourly production (Q\/hour)<\/li>\n\n\n<li><code>x_strg<\/code> &#8211; storage level (Q)<\/li>\n\n\n<li><code>x_supp<\/code> &#8211; hourly supply (Q\/hour)<\/li>\n\n\n<li><code>shadow_prices[\"demand_match\"]<\/code> &#8211; hourly shadow heat supply prices ($\/MWh). Applies to thermal processes only. These are thermally coupled to cogeneration units through heat extraction constraints.<\/li>\n<\/ul>\n\n\n<h4 class=\"wp-block-heading\">Generators \u00a0 | \u00a0 <a href=\"https:\/\/greoux.re\/explore\/ieso-modelling-approach\/#generators\" rel=\"noreferrer noopener\">Modelling approach \u2192<\/a><\/h4>\n\n\n<p>Generators represent technologies that produce electricity, heat, or both.<\/p>\n\n\n<div class=\"text-center my-4\">\n<img decoding=\"async\" alt=\"IESO Representation of a Generator\" class=\"img-fluid\" src=\"https:\/\/greoux.re\/explore\/wp-content\/media\/img\/ieso-modelling-approach\/generator.png\" style=\"max-width:25%;\"\/>\n<\/div>\n\n\n<p>Generators are described by a consistent JSON structure. Dispatchable units (nuclear, coal, CCGT) may use only a capacity factor, while variable renewables (solar, wind) require hourly profiles.<\/p>\n\n\n<p><span class=\"spotlight\">Electricity-generating plant &#8211; variable (e.g., wind)<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/c72d66ef8f7f74cb031b255685093f47.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<p><span class=\"spotlight\"><span class=\"spotlight\">Electricity-generating plant &#8211; fully dispatchable (e.g., OCGT)<\/span><\/span> <\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/e695b164d2e12665e25810cab23b477b.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<p><span class=\"spotlight\">Cogeneration plant (e.g., CCGT)<\/span><\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/01e4a21e190e6c385b9c49f37600d8fb.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<h5 class=\"wp-block-heading\">General attributes<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>type<\/code> &#8211; <em>elec<\/em> or <em>elec + ther<\/em> (thermal generators eligible to supply heat in cogeneration mode)<\/li>\n\n\n<li><code>profile<\/code> &#8211; empty for dispatchable units, required for renewables (CSV, 8760 values). May be provided as (1) a CSV file path, (2) an array of 8760 values, or (3) empty for a flat profile.<\/li>\n\n\n<li><code>capacity_factor<\/code> &#8211; capacity factor of the plant (fraction)<\/li>\n\n\n<li><code>l_prod<\/code> &#8211; lower and upper bounds (MW)<\/li>\n\n\n<li><code>c_prod<\/code> &#8211; installed capacity (MW). Will be optimised by the solver if set to -1<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Costs and emissions<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>fix_cost_prod<\/code> &#8211; fixed costs ($\/MW\/year)<\/li>\n\n\n<li><code>var_cost_prod<\/code> &#8211; variable costs ($\/MWh)<\/li>\n\n\n<li><code>var_emis_prod<\/code> &#8211; emissions (kg CO\u2082eq\/MWh)<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Cogeneration parameters<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>turbine_t_p<\/code> &#8211; turbine inlet temperature (\u00b0C) and pressure (bar)<\/li>\n\n\n<li><code>condenser_p<\/code> &#8211; condenser pressure (bar)<\/li>\n\n\n<li><code>a<\/code>, <code>b<\/code> &#8211; coefficients describing electricity-heat trade-off (calculated by IESO)<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Outputs<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>e_prod<\/code> &#8211; hourly electricity production (MWh)<\/li>\n\n\n<li><code>h_prod<\/code> &#8211; hourly heat production (MWh)<\/li>\n<\/ul>\n\n\n<h4 class=\"wp-block-heading\">Flexibility means \u00a0 | \u00a0 <a href=\"https:\/\/greoux.re\/explore\/ieso-modelling-approach\/#flexibility-means\" rel=\"noreferrer noopener\">Modelling approach \u2192<\/a><\/h4>\n\n\n<p>Flexibility means represent energy storage systems such as batteries or pumped hydro. They allow electricity to be shifted in time with round-trip efficiency losses.<\/p>\n\n\n<div class=\"text-center my-4\">\n<img decoding=\"async\" alt=\"IESO Representation of Flexibility Means\" class=\"img-fluid\" src=\"https:\/\/greoux.re\/explore\/wp-content\/media\/img\/ieso-modelling-approach\/flexibility-means.png\" style=\"max-width:30%;\"\/>\n<\/div>\n\n\n<p>Flexibility means are described by a consistent JSON structure.<\/p>\n\n\n<div class=\"row d-flex\">\n<div class=\"col-md-12\">\n<script src=\"https:\/\/gist.github.com\/greoux-research\/955513985521383ba4f5e3a7de2ac4da.js\"><\/script>\n<\/div>\n<\/div>\n\n\n<h5 class=\"wp-block-heading\">General attributes<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>fix_cost_strg<\/code> &#8211; annual fixed costs ($\/MWh\/year)<\/li>\n\n\n<li><code>hours_of_storage<\/code> &#8211; storage duration at maximum discharge<\/li>\n\n\n<li><code>round_trip_efficiency<\/code> &#8211; round-trip efficiency (in [0, 1])<\/li>\n\n\n<li><code>soc_ini<\/code> &#8211; initial state of charge (fraction of <code>c_strg<\/code>)<\/li>\n\n\n<li><code>l_strg<\/code> &#8211; lower and upper bounds (MWh)<\/li>\n\n\n<li><code>c_strg<\/code> &#8211; storage capacity. Will be optimised by the solver if set to -1<\/li>\n<\/ul>\n\n\n<h5 class=\"wp-block-heading\">Outputs<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>e_strg<\/code> &#8211; energy stored (MWh)<\/li>\n\n\n<li><code>e_char<\/code> &#8211; charging power (MW)<\/li>\n\n\n<li><code>e_disc<\/code> &#8211; discharging power (MW)<\/li>\n<\/ul>\n\n\n<h4 class=\"wp-block-heading\">Solver object \u00a0 | \u00a0 <a href=\"https:\/\/greoux.re\/explore\/ieso-modelling-approach\/#linear-optimisation-problem\" rel=\"noreferrer noopener\">More about the optimisation process \u2192<\/a><\/h4>\n\n\n<p>The solver object provides diagnostics for each optimisation run: status, run time, and problem size.<\/p>\n\n\n<h5 class=\"wp-block-heading\">Outputs<\/h5>\n\n\n<ul class=\"wp-block-list\">\n<li><code>stat_succ<\/code> &#8211; solver status (-1 initial, 0 failed, 1 success)<\/li>\n\n\n<li><code>stat_time<\/code> &#8211; elapsed time (seconds)<\/li>\n\n\n<li><code>stat_capa<\/code> &#8211; number of capacity variables<\/li>\n\n\n<li><code>stat_outp<\/code> &#8211; number of output variables<\/li>\n\n\n<li><code>stat_cons<\/code> &#8211; total number of constraints<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"<p>The JSON Input-Ouput (IO) file structure of the\u00a0Integrated Energy Systems Optimiser\u00a0(IESO), a linear-optimiser-based energy system modelling environment.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[7],"tags":[10,12],"class_list":["post-17","post","type-post","status-publish","format-standard","hentry","category-tech-docs","tag-ieso","tag-modelling-and-simulation"],"_links":{"self":[{"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/posts\/17","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/comments?post=17"}],"version-history":[{"count":0,"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/posts\/17\/revisions"}],"wp:attachment":[{"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/media?parent=17"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/categories?post=17"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/greoux.re\/explore\/wp-json\/wp\/v2\/tags?post=17"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}