API Documentation¶
network¶
This module is designed to hold the definition of the central ThermalNetwork object and its components.
This file is part of project dhnx (). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location:
SPDX-License-Identifier: MIT
-
class
dhnx.network.
ThermalNetwork
(dirname=None)[source]¶ Bases:
object
Class representing thermal (heating/cooling) networks.
Parameters: - availalable_components –
- component_attrs –
- components –
- sequences –
- results –
- graph –
Examples
>>> from dhnx.network import ThermalNetwork >>> tnw = ThermalNetwork('csv_folder') >>> tnw.is_consistent() True
-
add
(class_name, id, **kwargs)[source]¶ Adds a row with id to the component DataFrame specified by class_name.
Parameters: - class_name –
- id –
- kwargs –
-
is_consistent
()[source]¶ - Checks that
- pipes connect to existing nodes,
- pipes do not connect a node with itself,
- there are no duplicate pipes between two nodes.
-
remove
(class_name, id)[source]¶ Removes the row with id from the component DataFrame specified by class_name.
Parameters: - class_name (str) – Name of the component class
- id (int) – id of the component to remove
model¶
This module is designed to base classes for optimization and simulation models.
This file is part of project dhnx (). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location:
SPDX-License-Identifier: MIT
-
class
dhnx.model.
InvestOptimizationModel
(thermal_network)[source]¶ Bases:
dhnx.model.Model
Abstract base class for investment optimization models.
-
class
dhnx.model.
Model
(thermal_network)[source]¶ Bases:
object
Abstract base class for different kind of models.
-
class
dhnx.model.
OperationOptimizationModel
(thermal_network)[source]¶ Bases:
dhnx.model.Model
Abstract base class for operational optimization models.
-
class
dhnx.model.
SimulationModel
(thermal_network)[source]¶ Bases:
dhnx.model.Model
Abstract base class for simulation models.
optimization¶
This module is designed to hold optimization model implementations. The implementation makes use of oemof-solph.
This file is part of project dhnx (). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location:
SPDX-License-Identifier: MIT
-
class
dhnx.optimization.
OemofInvestOptimizationModel
(thermal_network, settings, investment_options)[source]¶ Bases:
dhnx.model.InvestOptimizationModel
Implementation of an invest optimization model using oemof-solph.
…
-
settings
¶ Dictionary holding the optimisation settings. See .
Type: dict
-
invest_options
¶ Dictionary holding the investment options for the district heating system.
Type: dict
-
nodes
¶ Empty list for collecting all oemof.solph nodes.
Type: list
-
buses
¶ Empty dictionary for collecting all oemof.solph.Buses of the energy system.
Type: dict
-
es
¶ Empty oemof.solph.EnergySystem.
Type: oemof.solph.EnergySystem
-
om
¶ Attribute, which will be the oemof.solph.Model for optimisation.
Type: oemof.solph.Model
-
oemof_flow_attr
¶ Possible flow attributes, which can be used additionally: {‘nominal_value’, ‘min’, ‘max’, ‘variable_costs’, ‘fix’}
Type: set
-
results
¶ Empty dictionary for the results.
Type: dict
-
check_input():
Performs checks on the input data.
-
complete_exist_data():
Sets the investment status for the results dataframe of the pipes.
-
get_pipe_data():
Adds heat loss and investment costs to pipes dataframe.
-
setup_oemof_es():
The energy system es is build.
-
setup():
Calls check_input(), complete_exist_data(), get_pipe_data(), and setup_oemof_es().
-
check_existing
()[source]¶ Checks if the attributes existing and hp_type are given in the pipes table. If not, the attribute is added, and set to None / 0.
Checks for all existing pipes, if the heatpipe type is given in the pipe type table .invest_options[‘network’][‘pipes’], and if the capacity is greater than zero.
-
check_input
()[source]¶ Check 1:
Check and make sure, that the dtypes of the columns of the sequences and the indices (=ids) of the forks, pipes, producers and consumers are of type ‘str’. (They need to be the same dtye.)
Check 2:
Firstly, it is checked, if there are any not-allowed connection in the pipe data. The following connections are not allowed:
- consumer -> consumer
- producer -> producer
- producer -> consumer
- consumer -> fork
Secondly, it is checked, if a pipes goes to a consumer, which does not exist.
Check 3
Checks if graph of network is connected.
An error is raised if one of these connection occurs.
-
prepare_heat_demand
()[source]¶ This method performs the pre-processing of the heat demand data, depending on the given optimisation settings.
- If attribute ‘P_heat_max’ not given at the consumers, the maximum heat demand is calculated from the timeseries and added the consumers table.
- If the optimisation setting ‘heat_demand’ == scalar, the number of time steps of the optimisation is set to 1, and the ‘P_heat_max’ values are copied to the consumers heat flow sequences (which is always the input for the optimisation model).
- The consumers heat flow sequences are multiplied by the simultaneity factor.
- Finally, a sufficient length of the heat demand timeseries is checked.
Returns: - Updated .network.components[‘consumers’] and
- .network.sequences[‘consumers’][‘heat_flow’]
-
remove_inactive
()[source]¶ If the attribute active is present in any of the components columns, or in any the investment options tables, all rows with active == 0 are deleted, and the column active is deleted.
-
setup
()[source]¶ Calls remove_inactive() check_input(), prepare_heat_demand(), complete_exist_data(), and setup_oemof_es().
-
setup_oemof_es
()[source]¶ The oemof solph energy system is initialised based on the settings, and filled with oemof-solph object:
The oemof-solph objects of the consumers and producers are defined at the consumers and producers investment options.
For the heating infrastructure, there is a oemof.solph.Bus added for every fork, and a pipe component for every pipe as defined in /network/pipes.csv.
-
-
class
dhnx.optimization.
OemofOperationOptimizationModel
(thermal_network)[source]¶ Bases:
dhnx.model.OperationOptimizationModel
Implementation of an operation optimization model using oemof-solph.
-
dhnx.optimization.
optimize_operation
(thermal_network)[source]¶ Takes a thermal network and returns the result of the operational optimization.
-
dhnx.optimization.
setup_optimise_investment
(thermal_network, invest_options, heat_demand='scalar', num_ts=1, time_res=1, start_date='1/1/2018', frequence='H', solver='cbc', solve_kw=None, solver_cmdline_options=None, simultaneity=1, bidirectional_pipes=False, dump_path=None, dump_name='dump.oemof', print_logging_info=False, write_lp_file=False)[source]¶ Function for setting up the oemof solph operational Model.
Parameters: - thermal_network (ThermalNetwork) – See the ThermalNetwork class.
- invest_options (dict) – Dictionary holding the investment options for the district heating system.
- heat_demand (str) – ‘scalar’: Peak heat load is used as heat consumers’ heat demand. ‘series’: Heat load time-series is used.
- num_ts (int) – Number of time steps of optimisation.
- time_res (float) – Time resolution.
- start_date (str or datetime-like) – Startdate for oemof optimisation.
- frequence (str or DateOffset) – Lenght of period.
- solver (str) – Name of solver.
- solve_kw (dict) – Solver kwargs.
- solver_cmdline_options (dict) – Dictionary with command line options for solver.
- simultaneity (float) – Simultaneity factor.
- bidirectional_pipes (bool) – Bidirectional pipes leads to bi-directional flow attributes at the heatpipeline components {‘min’: -1, bidirectional: True}.
- dump_path (str) – If a dump path is provided, the oemof dump file is stored.
- dump_name (str) – Name of dump file.
- print_logging_info (bool) – Additional logging info is printed.
- write_lp_file (bool) – Linear program file is stored (‘User/.oemof/lp_files/DHNx.lp’).
Returns: oemof.solph.Model
Return type: The oemof.solph.Model is build.
-
dhnx.optimization.
solve_optimisation_investment
(model)[source]¶ Parameters: model (oemof.solph.Model) – The oemof model, which is optimized. Returns: dict – - ‘oemof’ : Complete “oemof” results of the energy system optimisation (.results[‘main’]).
- ’oemof_meta’ : Meta results of oemof solph optimisation.
- ’components’ : ‘pipes’ : Investment results of pipes.
Return type: Results of optimisation. Contains:
simulation¶
This module is designed to hold implementations of simulation models. The implementation uses oemof/tespy.
This file is part of project dhnx (). It’s copyrighted by the contributors recorded in the version control history of the file, available from its original location:
SPDX-License-Identifier: MIT
-
class
dhnx.simulation.
SimulationModelNumpy
(thermal_network, rho=971.78, c=4190, mu=0.00035, eta_pump=1, tolerance=1e-10)[source]¶ Bases:
dhnx.model.SimulationModel
Implementation of a simulation model using numpy.
-
_concat_scalars
(name)[source]¶ Concatenates scalars of all components with a given variable name
Parameters: name (str) – Name of the variable Returns: concat_sequences – DataFrame containing the sequences Return type: pd.DataFrame
-
_concat_sequences
(name)[source]¶ Concatenates sequences of all components with a given variable name
Parameters: name (str) – Name of the variable Returns: concat_sequences – DataFrame containing the sequences Return type: pd.DataFrame
-
static
_set_producers_mass_flow
(m)[source]¶ Sets the mass flow of the producer.
Parameters: m (pd.DataFrame) – DataFrame with all know consumer mass flows. Returns: m – DataFrame with all know mass flow of consumers and producer. Return type: pd.DataFrame
-
_calculate_pipes_mass_flow
()[source]¶ Determines the mass flow in all pipes using numpy’s least squares function.
Returns: pipes_mass_flow – Mass flow in the pipes [kg/s] Return type: pd.DataFrame
-
_calculate_reynolds
()[source]¶ Calculates the Reynolds number.
Returns: re – Reynolds number for every time step and pipe [-] Return type: pd.DataFrame
-
_calculate_lambda
(reynolds)[source]¶ Calculates the darcy friction factor.
Parameters: re (pd.DataFrame) – Reynolds number for every time step and pipe [-] Returns: lamb – Darcy friction factor for every time step and pipe [-] Return type: pd.DataFrame
-
_calculate_pipes_distributed_pressure_losses
(lamb)[source]¶ Calculates the pressure losses in the pipes.
Equal-sized inlet and return pipes are assumed which leads to equal mass flows and pressure losses for both. This introduces the initial factor of 2 in the equation.
Parameters: lamb (pd.DataFrame) – Darcy friction factor for every time step and pipe [-] Returns: pipes_pressure_losses – DataFrame with distributed pressure losses for inlet and return for every time step and pipe [Pa] Return type: pd.DataFrame
-
_calculate_pipes_localized_pressure_losses
()[source]¶ Calculates localized pressure losses at the nodes.
Returns: nodes_pressure_losses – Localized pressure losses at the nodes [Pa] Return type: pd.DataFrame
-
_calculate_global_pressure_losses
(pipes_pressure_losses)[source]¶ Calculates global pressure losses.
Finds the path with the maximal pressure loss among from the set of paths from the producer to all consumers.
Parameters: pipes_pressure_losses (pd.DataFrame) – Total pressure losses for every time step and pipe [Pa] Returns: global_pressure_losses – Global pressure losses [Pa] Return type: pd.DataFrame
-
_calculate_pump_power
(global_pressure_losses)[source]¶ Calculates the pump power.
Parameters: global_pressure_losses (pd.DataFrame) – Global pressure losses [Pa] Returns: pump_power – Pump power [W] Return type: pd.Series
-
_calculate_exponent_constant
()[source]¶ Calculates the constant part of the exponent that determines the cooling of the medium in the pipes.
Returns: exponent_constant – Constant part of the exponent [kg/s] Return type: np.matrix
-
_calc_temps
(exponent_constant, known_temp, direction)[source]¶ Calculate temperatures
Parameters: - exponent_constant (np.array) – Constant part of the exponent [kg/s]
- known_temp (pd.DataFrame) – Known temperatures at producers or consumers [°C]
- direction (+1 or -1) – For inlet and return flow [-]
Returns: temp_df – DataFrame containing temperatures for all nodes [°C]
Return type: pd.DataFrame
-