<jupyter_start><jupyter_text>Tutorial 2: Planning Single-Node Example This example analyzes the planning mode of the energy system in a hypothetical region named Utopia.In this example, the Reference Energy System strats from an Oil Extraction technology which supplies raw oil to the refineries (Oil Refinery technology) where the oil fuel is processed to be sent to the Oil Power Plants or Diesel Pipelines. The Oil Power Plants alongside the Hydro Power Plants produce electricity which later is sent to the Electricity Transmission and Distribution technology to be delivered to the final demand sector. The Diesel Pipelines also take the processed oil fuel and transport it to the final demand sector.There are four technologies which are the representatives of the demand side of the energy system including Electric Vehicles, Internal Combustion Engine Vehicles, Household Electricity Demand and Other Electicity Demand.The time horizon of the model is set from 2020 to 2030 with weekdays/weekends and days/nights temporal resolution.   1. Building the excel-based structural input (set) files: Following the single-node approach of the Hypatia model, two set files including “global.xlsx” and “reg1.xlsx” must be provided. The global technologies and carriers in this case are identical to the regional ones as Utopia is modeled only as one region and no spatial resolution is considered. However, in a multi-node model application, the global technologies and carriers are the the aggregated list of the technologies and carriers involved in the Reference Energy System of all the locations. “global.xlsx”: indicates the technologies and carriers within the global (whole Utopia) energy system (similar to the regional one in this case),the locations (one location in this case), the modelling years, and the time steps within each year “reg1.xlsx”: indicates the Reference Energy System of Utopia including all the interconnections among the involved technologies and carriersTherefore, in single node approach, the "Technologies" and "Carriers" tables are completely identical in "reg1.xlsx" and "global.xlsx" files. Note: The name of the excel files must be determined as above. It is not possible to include arbitrary file names   1.1“global” excel file: As it is described in the building model documentation, the structural input excels consist of several tables for different sets of the model. The first table in the global file is “Regions” including the locations of the study and the name of each location. In this case only one location as whole utopia must be considered.  The second table is  “Technologies_glob” which includes all the technologies within Utopia, their name, and categories. Please note that the technology categories must be chosen from  Supply, Conversion, Conversion_plus, Transmission, and Storage categories  and can not be anything different from the mentioned names.  After global technologies, global carriers must be indicated in the table  “Carriers_glob”. In this table, all the carriers with their types and names must be included as below. The allowed carrier type are  Resource, Intermediate, and Demand.  Ultimately, the time horizon and temporal resolution of the model must be determined by the “Years” and “Timesteps” tables respectively.In this case, 11 modelling years have been considered starting from 2020 to 2030 without considering any past years for the callibration of the model and fixing the total installed capacities or production of the technologies.  In this case, the temporal resolution considered within each year is a hierarchy of weekend and weekdays with a day/night time bracket for each day type. Therefore, there are four time slices within each year including  Weekdays-days, Weekdays-nights, Weekends-days and Weekends-nights. The lengths of the time slices as a fraction of the length of the whole year are different from each other. It is assumed that from 365 days within each year, 261 days are weekdays and 104 days are weekend days, therefore, as an example the  Timeslice_fraction of weekdays-days is 261/365 * 0.5 = 0.35534247.   1.2 “reg1” excel file: As it is mentioed above, the  “reg1.xlsx” file consists of regional technologies, carriers (which are similar to global ones in this specific case), and the interconnections among them based on the Reference Energy System. The first table of regional files is named  “Technologies” where the user must indicate the technologies within the specific location (Utopia) as shown below:  The second table is named “Carriers” which is dedicated to determining the carriers within the specific location (Utopia).  The connections among the technologies and carriers within the Reference Energy System are determined by “Carrier-input” and “Carrier-output” tables. In the former, the input carriers of the technologies, and in the latter, the output carriers of technologies are represented. Please note that the “Supply” technologies and “Demand” technologies should not be included in the “Carrier-input" and “Carrier-output” tables respectively because the “Supply” category of technology just provide energy carrier to the system without any conversion process and the “Demand” category just sinks and removes the demand energy carriers from the system. Carrier InputCarrier Output There are a few important things to note about the structural input files:The name of the tables are fixed and cannot be chosen at will by the user. All the table names must be indicated as mentioned above. However, in case of any potential error, the Hypatia model delivers proper warnings to the user after reading the set files. The table names can be fixed in the excel files through the following path as shown in the following figure. Formulas tab of the ribbon > Name Manager > Edit > Name The name of the columns in each table must be exactly as the indicated names in this tutorial. There are also warning and exception errors for the possible mistakes in the column names.  2. Initializing the Hypatia model by reading the excel-based set files After specifying all the sets of the model, it is time to initialize the Hypatia model and read the structural input files.  Importing the hypatia model<jupyter_code>from hypatia import Model<jupyter_output><empty_output><jupyter_text>Intializing the hypatia model by passing the optimization mode and the path of the structural input files (sets of the model)<jupyter_code>utopia = Model(
    path = 'sets', 
    mode = 'Planning' 
)<jupyter_output><empty_output><jupyter_text>3. Creating the excel-based parameter files  Now the user can create the parameter files with their default values through running the following commandsAfter running this command line, we are going to open the created parameter files and fill them with the model data.<jupyter_code>#utopia.create_data_excels(
#    path = r'parameters'
#)<jupyter_output><empty_output><jupyter_text>In this case, as we have a single-node approach, it is expected to see only one file named as  “parameters_reg1.xlsx” in the given path.  4. Filling the parameter files with the input data Now it is time to insert the input data in the parameter file. In this case study, we are focusing on the planning mode of the energy system. Therefore, the following sheets can be found in the excel files:Specific investment cost, decommissioning cost, fixed and variable operation and maintenance costs:  These costs must be defined on an annual basis for each technology within each category. Different units can be considered for different technologies based on the indicated units for capacity and activity variables.(In the Hypatia model, it is possible to assign various capacity units to different technologies which can be converted to various activity units by defining the proper value for the "Annual Production per Unit of Capacity"  parameter). However the nominator of the cost units must be identical for all the specific costs and all the technologies. In this case, the variable costs of all the technologies are defined in MUSD/GWh and fixed and investment costs in MUSD/GW except for Oil Extraction and Oil Refinery technologies where the varibale costs are based on MUSD/1000BOE (million dollars per 1000 barrels of oil equivalent) and the investment costs are based on MUSD/b/d (million dollars per one barrel per day). The specific investmnet cost sheet is shown in the follwoing as an example. The investmnet cost of the Oil Extraction technology is assumed to be equal to zero. However, a very small value has been dedicated to it to avoid potential numerical problems. It is assumed that the dismantling process of the units of different technologies can be done without any cost, therefore, the decommissioning costs of all technologies are assumed to be equal to zero. Taxes and Subsidies:   In the Hypatia model, it is possible to define taxes and subsidies as a fraction per unit of investment or fixed cost of a technology. These parameters are named as "Investment_taxsub"  and "Fix_taxsub". In this case study, it is assumed that no tax or subsidy has been applied to the technologies as it is shown below: Carbon tax:  Moreover, carbon taxes can be also defined for the fossil fuel based technologies. This parameter must be indicated per unit of produced CO2-equivalent emissions from different technologies. In this specific case, this parameter has been left with its default value which is equal to zero. Residual capacity:   The total installed capacity of each technology before starting the modelling horizon. The Hypatia modeling framework is inspired by the OSeMOSYS Framework (Welcome to the OSeMOSYS’ Documentation! — OSeMOSYS 0.0.1 Documentation, n.d.) for calculating the annual total installed capacity of each technology. Therefore, in the planning mode, the total capacity of each technology is the summation of the optimized accumulated new installed capacity and the residual capacity of the technology in each year. It should be noted that the user must provide the annual residual capacities based on the capacity installation year before the modelling time horizon and the useful opertional lifetime of the technology. Again, the unit of capacity can differ from one technology to another. In this case, all the units are based on GW except for the Oil Extraction and Oil Refinery technologies which are based on number of extraction units and 1000 barrels of oil per day, respectively. Min/Max new/total capacity:  These parameters allow us to analyze various scenarios of the energy system transition by setting upper and lower limits for the future new and total installed capacities of different technologies. Moreover, it gives the chance to fixed the capacities for the past years of the time horizon required for the callibration of the model. In this particulare case, a BAU model of Utopia without any callibration is considered. Therefore, these limits have been left with their default values. Max/Min production: These parameters allow to set upper and lower limits on the annual production of each technology and are useful for scenario analysis and callibration of the model. We left them equal to their default values in this case Technology capacity factor:  This parameter allows to consider the planned outages or operation and maintenance time of each technology. It is the average capacity of a plant over one year divided by its nominal total capacity. In this case, it is assumed that the capacity factor of all the technologies is equal to 1. Resource capacity factor:  This parameter allows us to consider the availability of resources (especially for renewable technologies) in each time slice of the year.  It is the max production of one unit capacity of each technology in each time slice based on the variable resource availability. In this case study, the only present renewable technology is Hydro power plant. We define its resource capacity factor based on temporal resolution of the model as follows. It is assumed that the hydro resource are more available at nights than days. Technology efficiency: The technology efficiency in the Hypatia model is basically the ratio between the output carrier to the input carrier of a conversion, conversion-plus or a transmission technology. Considering the fact that the units of the carrier production and carrier consumption of each technology can be different in this model, the technology efficiency (output/input activity ratio) can be higher or lower than one. In this case study, the input energy carrier of Oil Power Plants is in the unit of 1000 barrels of oil equivalent (BOE) and its output is in the unit of GWh of electricty. The efficiency of this technology is around 0.4 if the input and output activities hold the same unit. However, considering the converting ratio of GWh to 1000BOE, it can be said that for each KBOE of oil, this technology can provide around 0.67976 GWh electricity. Moreover, in this case, the efficiencies of all the transmission technologies and Oil Refinery have been considered equal to 0.9. Specific emission:  In the Hypatia model the GHG emissions in terms of CO2 equivalent values or ad-hoc CO2 emissions can be considered. In this case, 420 ton/1000BOE of production has been considered for Oil Extraction technology as the embedded CO2 emission in the produced fuel oil. Annual emission limit:  Allows to put an upper limit for the total annual emission of each region. This case study follows a BAU logic, therefore, no annual emission cap has been defined Annual production per unit of capacity:  The amounts of output activity per unit of installed capacity of each technology in each year of the modelling horizon. In this case study, each unit of Oil Extraction is assumed to produce 1257.96 kBOE of oil, each kb/d capacity of Oil Refinery Technology can produce 365 kb/year and each GW capacity of the power generation and transmission technologies can produce 8760 GWh per year. Technical lifetime:  The useful operational lifetime of the technologies before decommissioning. Economic lifetime:  In the Hypatia model, contrary to most of the open-source planning models, the economic life time of technologies can be defined alongside their technical lifetime. This parameter represents the period over which the investment annuities are spread. In other words, each required investment in a specific year "y" is divided into a stream of annuities during several years starting from "y+1" to "y+economic lifetime". In this example, the economic lifetime of all the technologies have been left with their defaul value which is equal to one. Interest rate:  Alongside the economic lifetime, the interest rate of each technology must be defined by the user. In this way, the model would be able to calculate the depraciation rate required to calculate the annuities of investments on each technology. Ususally, the technological interest rate is different from the general discount rate which depends on the central bank of each specific region. However, if the user insert similar values for these two parameters, the stream of annuities would be equivalent to a single payment of the whole investment in year "y". In this case study, the default interest rate of 5% has been considered for all the technologies. Therefore, the discount rate and technological interest rate are equal and no investment annuity will be accounted. Discount rate:  The general location-specific discount rate based on the central bank data for calculating the net present value of different cost components of the objective fuction. In this case the default value of 0.05 has been considered for all the modelling years.  Demand:  The demand parameter must be defined on the time steps of each modelling year of the time horizon. In this case, the following wieghtings has been considered for different final demands. These values are coming from the assumption that 60% of the annual demand is dedicated to the weekdays and 40% is dedicated to the weekends for EV, ICE and other final demands, while for the households, the weightings are other way around where 60% of the annual demand takes place in weekends. These values are multiplied to the weightings of days/nights distributions where 80% percent of the daily demands are taking place in the days and 20% in the nights. The annual final demads for different technologies are based on a random and dummy scaled down IEA data for the whole world in 2020.  5. Reading the input data After filling out the parameter files, it is time to ask the model to read the input data following the below command line.<jupyter_code>utopia.read_input_data(
    path = r'parameters'
)<jupyter_output><empty_output><jupyter_text>6. Running the model Now we can run the model by giving the preferred solver, verbosity and the force_rewrite parameter which avoids overwriting the output results when it is equal to False and allows to overwrite them by taking a backup from the previous results when it is equal to True.<jupyter_code>utopia.run(
    solver = 'scipy',
    verbosity = True,
    force_rewrite = False
)<jupyter_output><empty_output><jupyter_text>7. Exporting the raw results to csv files There is the possibility to export the raw results into the csv files by passing the arbitary folder path and force_rewrite parameter which avoids to overwrite the results when it is equal to False.<jupyter_code>utopia.to_csv(path='results')<jupyter_output><empty_output><jupyter_text>8. Visualizing the results After solving the model, we can visualize the raw results by importing the plotting tool of the Hypatia model but before that, we need to ask the model to create the configuration excel file for indicating the desired information on technologies, fuels and regions.<jupyter_code>#utopia.create_config_file(path=r'config.xlsx')
from hypatia import Plotter<jupyter_output><empty_output><jupyter_text>Now, it is the time to initiallize the plotter class by passing the model's name, the created config file for the plots and the hourly resolution boolean parameter. The latter is True when the model has a hourly stepwise resolution and False when the timesteps are not in a hourly basis.<jupyter_code>results = Plotter(utopia,config=r'config.xlsx',hourly_resolution=False)
# Sketching the new installed capacity of different technologies for given tech group
results.plot_new_capacity(
    path = r'plots/newcapacity.html',
    tech_group = 'Power Generation',
    regions = ['reg1'],
    cummulative=False,
)

# Sketching the total installed capacity of different technologies for given tech group (considering the decommissioned capacities)
results.plot_total_capacity(
    path = r'plots/totalcapacity.html',
    tech_group = 'Power Generation',
    regions = ['reg1'],
    kind="bar",
    decom_cap=True,
)
# Sketching the annual production of each technology
results.plot_prod_by_tech(
    tech_group ='Power Generation',
    regions = ['reg1'],
    path = r'plots/productionbytech.html',
)
# Sketching the annual production of each technology
results.plot_prod_by_tech(
    tech_group ='Refinery',
    regions = ['reg1'],
    path = r'plots/productionbytech_oil.html',
)
# Skething the prduction and consumption share of each technology including the imports and exports
results.plot_fuel_prod_cons(
    path = r'plots/prod_con_share.html',
    years = [2030],
    fuel_group = 'Electricity',
    regions = ['reg1'],
    trade=False,
)

# Skething the prduction and consumption share of each technology including the imports and exports
results.plot_fuel_prod_cons(
    path = r'plots/prod_con_share_oil.html',
    years = [2030],
    fuel_group = 'Fuel',
    regions = ['reg1'],
    trade=False,
)
# Sketching the annual CO2-equivalent emissions
results.plot_emissions(
    path = r'plots/emissions.html',
    regions = ['reg1'],
    tech_group = 'Resource Extraction',
)<jupyter_output><empty_output>
{'fraction_non_alphanumeric': 0.03563373928732522, 'fraction_numerical': 0.007818373176965869, 'mean_word_length': 4.8965721040189125, 'pattern_counts': {'":': 0, '<': 33, '<?xml version=': 0, '>': 36, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'chain_length': '8', 'dir': 'jupyter-structured-clean-dedup', 'id': '647412', 'license': 'Apache-2.0', 'n_tokens_mistral': 4753, 'n_tokens_neox': 4450, 'n_words': 2940, 'path': 'examples/Utopia2_planning_single_node_DN/tutorial2.ipynb', 'repo_name': 'gitter-badger/Hypatia', 'size': '19953'}