GHEtool

https://ghetool.readthedocs.io/en/latest/
Admin
GHEtool is an open-source borefield sizing tool designed to assist drilling companies, engineering...
Tokens:160,743
Snippets:1,064
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Python Example: Sizing with Building Load and Hourly Profile

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/sizing_with_building_load_hourly.rst.txt

This snippet shows a complete example of using GHEtool to size a building's heating and cooling system based on hourly load data. It requires the GHEtool library to be installed.

```python
from GHEtool import *
import numpy as np

# Create a building object
building = Building.Building()

# Define building parameters
building.set_building_dimensions(10, 10, 3, 100)
building.set_wall_U_value(0.3)
building.set_roof_U_value(0.15)
building.set_window_U_value(1.1)
building.set_window_g_value(0.6)
building.set_solar_gain_through_window(0.8)
building.set_heat_transfer_coefficient(0.3)

# Define HVAC system parameters
hvac = HVAC.HVAC()
hvac.cooling_power = 10000 # W
hvac.heating_power = 15000 # W
hvac.cooling_efficiency = 3.5
hvac.heating_efficiency = 3.0

# Define hourly load profile
# Example: sinusoidal heating and cooling load for a year (8760 hours)
hourly_load = np.zeros(8760)
for h in range(8760):
    if 7*30*24 <= h < 10*30*24: # Heating season
        hourly_load[h] = -5000 * np.sin(2 * np.pi * (h - 7*30*24) / (3*30*24)) # Heating load
    elif 1*30*24 <= h < 4*30*24: # Cooling season
        hourly_load[h] = 7000 * np.sin(2 * np.pi * (h - 1*30*24) / (3*30*24)) # Cooling load

# Set the hourly load profile for the building
building.set_hourly_load_profile(hourly_load)

# Create a ground heat exchanger object
hed = GroundHeatExchanger.GroundHeatExchanger()

# Set the ground heat exchanger parameters
hed.set_bore_depth_factor(100)
hed.set_bore_diameter(0.125)
hed.set_number_of_bores(100)
hed.set_bore_wall_conductivity(0.7)

# Set the simulation time
hed.simulation_days = 365

# Perform the sizing calculation
hed.sizing_calculation(building, hvac)

# Print the results
print(f"Optimal bore depth: {hed.bore_depth} m")
print(f"Optimal bore diameter: {hed.bore_diameter} m")
print(f"Optimal number of bores: {hed.number_of_bores}")
print(f"Required heating capacity: {hed.required_heating_capacity} W")
print(f"Required cooling capacity: {hed.required_cooling_capacity} W")

```

--------------------------------

### Active and Passive Cooling Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/active_passive_cooling.rst.txt

Demonstrates the setup and execution of a combined active and passive cooling simulation using GHEtool. This example requires the GHEtool library to be installed.

```python
from GHEtool import *
import numpy as np

# --- Configuration ---
# Define borefield dimensions and properties
borefield = Borefield(100, 200, "depth", 0.04, 0.05, 0.1, 0.2, 1000, 2000, 15, 15)

# Define ground properties
# Thermal conductivity (W/mK), specific heat capacity (J/kgK), density (kg/m3)
ground_temp = 10 # degrees Celsius

# --- Load Building Load Profile ---
# Load hourly cooling and heating loads from a CSV file
# The CSV file should contain two columns: cooling load (W) and heating load (W)
# Example: cooling_load, heating_load
# 1000, 500
# 1200, 600
# ...
cooling_load = np.loadtxt("cooling_load.csv", delimiter=",", skiprows=1)[:, 0]
h = np.loadtxt("heating_load.csv", delimiter=",", skiprows=1)[:, 1]

# --- Initialize GHEtool ---
# Create a GHEtool object with the defined borefield and ground temperature
tool = GHEtool(borefield, ground_temp)

# --- Set Cooling and Heating Loads ---
# Set the cooling and heating loads for the simulation
tool.set_cooling_loads(cooling_load)
tool.set_heating_loads(h)

# --- Simulation Parameters ---
# Set the simulation time (in years)
simulation_time = 20

# --- Active Cooling Configuration ---
# Set the maximum allowable temperature for active cooling (degrees Celsius)
max_temp_active = 25

# Set the minimum allowable temperature for active cooling (degrees Celsius)
min_temp_active = 5

# Set the maximum allowable temperature for passive cooling (degrees Celsius)
max_temp_passive = 30

# Set the minimum allowable temperature for passive cooling (degrees Celsius)
min_temp_passive = 0

# --- Run Simulation ---
# Perform the simulation with combined active and passive cooling
# The simulation will try to maintain temperatures within the specified bounds
# using a combination of active and passive cooling strategies.
result = tool.simulate(simulation_time, max_temp_active, min_temp_active, max_temp_passive, min_temp_passive)

# --- Output Results ---
# Print the simulation results
print(result)

# You can also access specific results like:
# print(f"Required borehole length: {tool.borehole_length} m")
# print(f"Energy injected into the ground: {tool.energy_injection} Wh")
# print(f"Energy extracted from the ground: {tool.energy_extraction} Wh")

```

--------------------------------

### Combined Active and Passive Cooling Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/combined_active_and_passive_cooling.rst.txt

Demonstrates the integration of active and passive cooling techniques. Ensure GHEtool is installed and configured.

```python
import numpy as np

from GHEtool import * 

# Create a ground heat exchanger model
hed = GroundHeatExchanger(10, 20, 100000)

# Add boreholes
hed.add_borehole(0, 0, 0.1, 100, 0.04)
hed.add_borehole(0, 10, 0.1, 100, 0.04)
hed.add_borehole(10, 0, 0.1, 100, 0.04)
hed.add_borehole(10, 10, 0.1, 100, 0.04)

# Set ground properties
hed.set_ground_parameters(1.5, 10, 0.04)

# Set fluid properties
hed.set_fluid_parameters(2000, 1000, 0.0001)

# Set simulation parameters
hed.simulation_period = 30

# Set cooling load
cooling_load = np.array([0.0] * 30)

# Set heating load
heating_load = np.array([0.0] * 30)

# Set temperature boundaries
hed.temperature_boundary = np.array([15] * 30)

# Calculate the required borehole length for cooling
hed.calculate_borehole_length(cooling_load, heating_load)

# Print the required borehole length
print(f"Required borehole length: {hed.borehole_length} m")

# Set the borehole length to the calculated value
hed.borehole_length = hed.borehole_length

# Calculate the temperature profile
temp_profile = hed.calculate_temperatures(cooling_load, heating_load)

# Print the temperature profile
print(f"Temperature profile: {temp_profile}")

# Calculate the required borehole length for heating
hed.calculate_borehole_length(cooling_load, heating_load, temp_profile)

# Print the required borehole length for heating
print(f"Required borehole length for heating: {hed.borehole_length} m")

# Calculate the temperature profile for heating
temp_profile_heating = hed.calculate_temperatures(cooling_load, heating_load, temp_profile)

# Print the temperature profile for heating
print(f"Temperature profile for heating: {temp_profile_heating}")

```

--------------------------------

### Example of Variable Flow Rate Calculation

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/variable_flow_rate.rst.txt

This snippet demonstrates how to set up and run a sizing calculation with a variable flow rate using GHEtool. Ensure GHEtool is installed and imported.

```python
import numpy as np

from GHEtool import * 

# Create a ground heat exchanger object
hed = GroundHeatExchanger(1, 1, 1, 1)

# Set the ground properties
hed.set_ground_parameters(1, 1, 1, 1)

# Set the boreholes properties
hed.set_borehole_parameters(1, 1, 1, 1, 1)

# Set the pipe properties
hed.set_pipe_parameters(1, 1, 1, 1)

# Set the simulation time
hed.simulation_period = 30

# Set the load profile
load = np.zeros(30)
load[0:15] = 10000
load[15:30] = -10000
hed.set_load_profile(load, load)

# Set the variable flow rate
flow_rate = np.zeros(30)
flow_rate[0:15] = 0.5
flow_rate[15:30] = 0.2
hed.set_variable_flow_rate(flow_rate)

# Perform the sizing calculation
hed.sizing_calculation()

# Print the result
print(hed.results.borehole_depth)
```

--------------------------------

### Install GHEtool with Pip

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/getting_started.md.txt

Use this command to install the latest stable version of GHEtool from PyPI.

```bash
pip install GHEtool
```

--------------------------------

### Check GHEtool Installation

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/getting_started.md.txt

Run this command to verify that GHEtool and its internal dependencies are installed correctly. It executes predefined test cases.

```bash
pytest --pyargs GHEtool
```

--------------------------------

### Install Development Version with Pip

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/getting_started.md.txt

Install a newer development version of GHEtool from the test PyPI repository.

```bash
pip install --extra-index-url https://test.pypi.org/simple/ GHEtool
```

--------------------------------

### Example of multiple ground layers

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/multiple_ground_layers.rst.txt

This snippet shows how to define and use multiple ground layers in GHEtool. Ensure you have the GHEtool library installed.

```python
from GHEtool import *

# Create a ground with multiple layers
ground_data = [
    {'depth': 0.5, 'thermal_resistivity': 1.0},
    {'depth': 1.0, 'thermal_resistivity': 1.5},
    {'depth': 2.0, 'thermal_resistivity': 2.0},
    {'depth': 5.0, 'thermal_resistivity': 2.5},
]
ground = Ground(depth=10, **{'layers': ground_data})

# Create a borehole with the defined ground
borehole = Borehole(depth=100, diameter=0.15,
                    load=MonthlyLoad(100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100, 100),
                    borehole_resistance=0.05,
                    thermal_conductivity=2.0)

# Create a GSHP field with the borehole and ground
field = GSHPField(borehole, ground)

# Calculate the temperature at the bottom of the borehole
temp_bottom = field.calculate_temperature_at_depth(100)
print(f'Temperature at the bottom of the borehole: {temp_bottom:.2f} °C')

# Calculate the temperature at a depth of 50m
temp_50m = field.calculate_temperature_at_depth(50)
print(f'Temperature at 50m depth: {temp_50m:.2f} °C')

```

--------------------------------

### Separatus Module Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/separatus.rst.txt

This snippet demonstrates the usage of the Separatus module, likely for structural analysis or component separation within GHEtool. It requires the GHEtool library to be installed.

```python
import GHEtool

# Create a Project object
project = GHEtool.Project(config_file='path/to/your/config.json')

# Load or define the geological structure
# Example: Using a predefined geological structure
project.load_geological_structure('path/to/geology.json')

# Perform separation analysis
# The 'separatus' method likely performs a specific analysis
# based on the project's configuration and loaded data.
# The exact parameters and return values would depend on the GHEtool version.
project.separatus()

# Further actions or analysis based on the 'separatus' results
# For example, accessing results or visualizing them:
# results = project.get_separatus_results()
# project.plot_separatus_results(results)

print('Separatus analysis completed.')
```

--------------------------------

### Install GHEtool with Conda

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/getting_started.md.txt

Install GHEtool using the conda package manager.

```bash
conda install GHEtool
```

--------------------------------

### Optimise Borefield Configuration Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/optimise_borefield_configuration.rst.txt

This Python script demonstrates how to optimize the borehole configuration for a geothermal heat exchanger system using GHEtool. It requires the GHEtool library to be installed.

```python
from GHEtool import Borefield, GroundParameters, Fluid
from GHEtool.tool import Tool

# Define ground parameters
ground_data = GroundParameters(1, 10, 100, 0.2, 0.04)

# Define fluid parameters
fluid_data = Fluid(0.2, 1000, 1000, 0.04)

# Define borefield
borefield = Borefield(ground_data=ground_data, fluid_data=fluid_data)

# Add boreholes
borefield.add_boreholes(100, 10, 0.05, 0.05)

# Define tool
tool = Tool(borefield)

# Set load profile (example)
load_profile = [0] * 8760
for i in range(8760):
    load_profile[i] = 10000

tool.load_profile = load_profile

# Optimize borefield configuration
optimal_borefield = tool.optimize_borefield_configuration()

# Print results
print(optimal_borefield)

```

--------------------------------

### Install Development Version using Pip

Source: https://ghetool.readthedocs.io/en/latest/sources/code/getting_started.html

Install a newer development version of GHEtool from the test PyPI repository. This is useful for testing the latest features.

```bash
pip install --extra-index-url https://test.pypi.org/simple/ GHEtool

```

--------------------------------

### Access and Analyze Simulation Results

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Provides an example of accessing simulation results after running a simulation. It shows how to retrieve and print the temperature profile.

```python
from GHEtool import *

system = System.load('system.json')
system.run_simulation()

# Access results
temperature_profile = system.results.Tmean
print("Mean temperature profile:", temperature_profile)
```

--------------------------------

### Turbocollector Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/turbocollector.rst.txt

This snippet demonstrates the usage of the Turbocollector. Ensure necessary imports are present.

```python
from GHEtool import *

# Create a ground heat exchanger
# ... (rest of the code from the file would go here)
```

--------------------------------

### Optimise Load Profile using GHEtool

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/optimise_load_profile.rst.txt

This snippet shows the basic process of optimizing a load profile with GHEtool. Ensure GHEtool is installed and the necessary libraries are imported.

```python
from GHEtool import *

# Create a ground heat exchanger object
htu = GroundHeatExchanger("data.txt")

# Set the load profile
htu.load_profile.load_from_file("data.txt")

# Optimize the load profile
htu.optimise_load_profile()

# Print the optimized load profile
print(htu.load_profile.values)

```

--------------------------------

### Kilfrost GEO (Plus) Example

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/kilfrost.rst.txt

This snippet demonstrates the usage of Kilfrost GEO (Plus) functionality in Python. It requires the GHEtool library.

```python
from GHEtool import * 

# Create a ground heat exchanger object
# Example with default values
# ... (code omitted for brevity as it's from a literalinclude directive)
```

--------------------------------

### Sizing with Building Load Calculation

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/sizing_with_building_load.rst.txt

This snippet shows the process of sizing a geothermal exchange system by incorporating building load data. Ensure GHEtool is installed and configured for use.

```python
from GHEtool import * 
import numpy as np

# Create a building object
building = Building.load_from_file('my_building.json')

# Create a ground data object
# For example, using a constant thermal conductivity
kappa_values = [1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5, 1.5]
# Use the ground data object to create the ground region
ground_region = GroundRegion(kappa=kappa_values)

# Create a geothermalsystem object
# The geothermalsystem object requires the building and ground region
# It also requires the depth of the boreholes and the number of boreholes
# For example, 100m depth and 100 boreholes
geothermal_system = GeothermalSystem(building, ground_region, depth=100, number_of_boreholes=100)

# Set the simulation period
geothermal_system.simulation_period = 30 # years

# Calculate the required borehole length
# The calculate_borehole_length method returns the required length in meters
required_length = geothermal_system.calculate_borehole_length()

# Print the result
print(f"Required borehole length: {required_length} m")

```

--------------------------------

### Save GHEtool System Configuration

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Demonstrates saving the current GHEtool system configuration to a JSON file. This allows for later loading and reuse of the system setup.

```python
from GHEtool import *

system = System()
# ... configure system ...
system.save('my_system_config.json')

print("System configuration saved to my_system_config.json.")
```

--------------------------------

### Load GHEtool System and Run Simulation

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Demonstrates loading a GHEtool system from a file and executing a simulation. Ensure the 'system.json' file exists and is correctly formatted.

```python
from GHEtool import *

system = System.load('system.json')
system.run_simulation()

print(f"Simulation finished. Results are stored in system.results.")
```

--------------------------------

### Create and Configure a GHEtool System

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Shows how to programmatically create a GHEtool system, set its parameters, and add boreholes. This is useful for dynamic system configuration.

```python
from GHEtool import *

# Create a new system
system = System()

# Set basic parameters
system.set_building_load_profile("data.csv")
system.set_initial_temperature(273.15 + 15)

# Add a borehole
borehole = Borehole(depth=100, diameter=0.1, k_b=2.0)
system.add_borehole(borehole)

print("System created and configured.")
```

--------------------------------

### Set Initial Temperature for GHEtool System

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Shows how to set the initial ground temperature for the GHEtool simulation. Temperature should be provided in Kelvin.

```python
from GHEtool import *

system = System()
system.set_initial_temperature(273.15 + 18) # 18 degrees Celsius

print(f"Initial temperature set to {system.initial_temperature} K.")
```

--------------------------------

### Set Building Load Profile from CSV

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/main_functionalities.rst.txt

Demonstrates setting the building's hourly load profile using data from a CSV file. The CSV file should contain hourly load data.

```python
from GHEtool import *

system = System()
system.set_building_load_profile("data.csv")

print("Building load profile set from data.csv.")
```

--------------------------------

### Load Profile Optimization Example

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Examples/optimise_load_profile.html

This Python script demonstrates how to optimize a building's load profile for a ground heat exchanger system using GHEtool. It covers setting up ground and borefield data, loading hourly building loads, and applying power, energy, and balance-based optimization methods. The script prints key performance indicators and visualizes temperature profiles.

```python
1"""
2This document is an example of load optimisation.
3First an hourly profile is imported and a fixed borefield size is set.
4Then, based on a load-duration curve, the heating and cooling load is altered in order to fit as much load as possible on the field.
5The results are returned.
6
7"""
8import numpy as np
9import pandas as pd
10
11from GHEtool import *
12from GHEtool.Methods import *
13
14
15def optimise():
16    # initiate ground data
17    data = GroundConstantTemperature(3, 10)
18
19    # initiate borefield
20    borefield = Borefield()
21
22    # set ground data in borefield
23    borefield.ground_data = data
24
25    # set Rb
26    borefield.Rb = 0.12
27
28    # set borefield
29    borefield.create_rectangular_borefield(20, 20, 6, 6, 141, 1, 0.075)
30
31    # load the hourly profile
32    load = HourlyBuildingLoad(efficiency_heating=4.3, efficiency_cooling=5)
33    # load.dhw = 100000  # add domestic hot water
34    load.start_month = 9
35    df = pd.read_csv(FOLDER.joinpath("Examples/load_optimise.csv"))
36
37    cooling = df["cooling"].to_numpy()
38    heating = df["heating"].to_numpy()
39
40    load.set_hourly_cooling_load(cooling)
41    load.set_hourly_heating_load(heating)
42
43    # optimise the load for a 10x10 field (see data above) and a fixed depth of 150m.
44    # first for an optimisation based on the power
45    borefield.set_max_fluid_temperature(35)
46    borefield.set_min_fluid_temperature(-1.5)
47
48    building_load, _ = optimise_load_profile_power(borefield, load)
49    borefield.load = building_load
50
51    print(f'Max extraction power (primary): {borefield.load.max_peak_extraction:,.0f}kW')
52    print(f'Max injection power (primary): {borefield.load.max_peak_injection:,.0f}kW')
53
54    print(
55        f'Total energy extracted from the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_extraction_simulation_period):,.0f}MWh')
56    print(
57        f'Total energy injected in the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_injection_simulation_period):,.0f}MWh')
58    print('------------------------------------------------------------------------')
59    borefield.calculate_temperatures(hourly=True)
60    borefield.print_temperature_profile(plot_hourly=True)
61
62    # first for an optimisation based on the energy
63    building_load, _ = optimise_load_profile_energy(borefield, load)
64    borefield.load = building_load
65
66    print(f'Max extraction power (primary): {borefield.load.max_peak_extraction:,.0f}kW')
67    print(f'Max injection power (primary): {borefield.load.max_peak_injection:,.0f}kW')
68
69    print(
70        f'Total energy extracted from the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_extraction_simulation_period):,.0f}MWh')
71    print(
72        f'Total energy injected in the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_injection_simulation_period):,.0f}MWh')
73
74    borefield.calculate_temperatures(hourly=True)
75    borefield.print_temperature_profile(plot_hourly=True)
76
77    # first for an optimisation based on the balance
78    building_load, _ = optimise_load_profile_balance(borefield, load)
79    borefield.load = building_load
80
81    print(f'Max extraction power (primary): {borefield.load.max_peak_extraction:,.0f}kW')
82    print(f'Max injection power (primary): {borefield.load.max_peak_injection:,.0f}kW')
83
84    print(
85        f'Total energy extracted from the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_extraction_simulation_period):,.0f}MWh')
86    print(
87        f'Total energy injected in the borefield over simulation period: {np.sum(borefield.load.monthly_baseload_injection_simulation_period):,.0f}MWh')
88
89    borefield.calculate_temperatures(hourly=True)
90    borefield.print_temperature_profile(plot_hourly=True)
91
92
93if __name__ == "__main__":  # pragma: no cover
94    optimise()
```

--------------------------------

### GHEtool Main Functionalities Example

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Examples/main_functionalities.html

Demonstrates the core functionalities of GHEtool, including setting up ground and load data, creating a borefield, sizing it, and plotting temperature profiles. This snippet covers borefield sizing for both general use and specific quadrants, as well as temperature profile visualization.

```python
import numpy as np

# import all the relevant functions
from GHEtool import Borefield, ConstantFlowRate, ConstantFluidData, DoubleUTube, GroundConstantTemperature, \
    MonthlyGeothermalLoadAbsolute


def main_functionalities():
    # relevant borefield data for the calculations
    data = GroundConstantTemperature(3,  # conductivity of the soil (W/mK)
                                     10,  # Ground temperature at infinity (degrees C)
                                     2.4 * 10 ** 6)  # ground volumetric heat capacity (J/m3K)

    # monthly loading values
    peak_cooling = np.array([0., 0, 34., 69., 133., 187., 213., 240., 160., 37., 0., 0.])  # Peak cooling in kW
    peak_heating = np.array([160., 142, 102., 55., 0., 0., 0., 0., 40.4, 85., 119., 136.])  # Peak heating in kW

    # annual heating and cooling load
    annual_heating_load = 300 * 10 ** 3  # kWh
    annual_cooling_load = 160 * 10 ** 3  # kWh

    # percentage of annual load per month (15.5% for January ...)
    monthly_load_heating_percentage = np.array(
        [0.155, 0.148, 0.125, .099, .064, 0., 0., 0., 0.061, 0.087, 0.117, 0.144])
    monthly_load_cooling_percentage = np.array([0.025, 0.05, 0.05, .05, .075, .1, .2, .2, .1, .075, .05, .025])

    # resulting load per month
    monthly_load_heating = annual_heating_load * monthly_load_heating_percentage  # kWh
    monthly_load_cooling = annual_cooling_load * monthly_load_cooling_percentage  # kWh

    # set the load
    load = MonthlyGeothermalLoadAbsolute(monthly_load_heating, monthly_load_cooling, peak_heating, peak_cooling)

    # create the borefield object
    borefield = Borefield(load=load)

    borefield.ground_data = data
    borefield.create_rectangular_borefield(10, 12, 6, 6, 100, 4, 0.075)

    borefield.Rb = 0.12  # equivalent borehole resistance (K/W)

    # set temperature boundaries
    borefield.set_max_fluid_temperature(16)  # maximum temperature
    borefield.set_min_fluid_temperature(0)  # minimum temperature

    # size borefield
    length = borefield.size()
    print("The borehole length is: ", length, "m")

    # print imbalance
    print("The borefield imbalance is: ", borefield._borefield_load.imbalance,
          "kWh/y. (A negative imbalance means the the field is heat extraction dominated so it cools down year after year.)")

    # plot temperature profile for the calculated borehole length
    borefield.print_temperature_profile(legend=True)

    # plot temperature profile for a fixed borehole length
    borefield.print_temperature_profile_fixed_length(length=75, legend=False)

    # print gives the array of monthly temperatures for peak cooling without showing the plot
    borefield.calculate_temperatures(length=90)
    print("Result array for cooling peaks")
    print(borefield.results.peak_injection)
    print("---------------------------------------------")

    # size the borefield for quadrant 3
    # for more information about borefield quadrants, see (Peere et al., 2021)
    depth = borefield.size(quadrant_sizing=3)
    print("The borehole depth is: ", str(round(depth, 2)), "m for a sizing in quadrant 3")
    # plot temperature profile for the calculated depth
    borefield.print_temperature_profile(legend=True)

    # size with a dynamic Rb* value
    # note that the original Rb* value will be overwritten!

    # this requires pipe and fluid data
    fluid_data = ConstantFluidData(0.568, 998, 4180, 1e-3)
    flow_data = ConstantFlowRate(mfr=0.2)
    pipe_data = DoubleUTube(1, 0.015, 0.02, 0.4, 0.05)
    borefield.fluid_data = fluid_data
    borefield.pipe_data = pipe_data
    borefield.flow_data = flow_data

    # disable the use of constant_Rb with the setup, in order to plot the profile correctly
    # when it is given as an argument to the size function, it will size correctly, but the plot will be with
    # constant Rb* since it has not been changed in the setup function
    borefield.calculation_setup(use_constant_Rb=False)
    depth = borefield.size()
    print("The borehole depth is: ", str(round(depth, 2)), "m for a sizing with dynamic Rb*.")
    borefield.print_temperature_profile(legend=True)


if __name__ == "__main__":  # pragma: no cover
    main_functionalities()
```

--------------------------------

### Correct Load for Start Month

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Load.html

Corrects a load array to align with the simulation's start month.

```APIDOC
## correct_for_start_month

### Description
This function corrects the load for the correct start month. If the simulation starts in September, the start month is 9 and hence the array should start at index 9.

### Method
`correct_for_start_month(_array : ndarray_)`

### Parameters
#### Input Parameters
- **array** (ndarray) - Load array

### Returns
- **load** (ndarray) - Corrected load array
```

--------------------------------

### Correct Load Array for Start Month

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Load.html

Adjusts a load array to align with the correct start month of the simulation.

```APIDOC
## Correct for Start Month

### Description
Corrects the load array for the correct start month. If the simulation starts in September, the start month is 9, and the array should begin at index 9.

### Parameters
- **array** (np.ndarray): The load array to be corrected.

### Returns
- np.ndarray: The corrected load array.
```

--------------------------------

### Simulate Borefield with Different Start Months

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Examples/start_in_different_month.html

This function simulates a borefield's performance by varying the start month of operation. It calculates and visualizes the required borehole length for each start month. Ensure GHEtool, matplotlib, and necessary validation cases are imported.

```python
from GHEtool import *
from GHEtool.Validation.cases import load_case

import matplotlib.pyplot as plt


def start_in_different_month():
    # set data
    ground_data = GroundTemperatureGradient(2.5, 10)
    load = MonthlyGeothermalLoadAbsolute(*load_case(1))

    # create borefield object
    borefield = Borefield(load=load)
    borefield.ground_data = ground_data
    borefield.create_rectangular_borefield(10, 8, 6, 6, 100)

    borefield.set_max_fluid_temperature(17)
    borefield.set_min_fluid_temperature(3)
    borefield.calculation_setup(max_nb_of_iterations=100)

    length_list = []

    # iterate over all the start months
    for month in range(1, 13, 1):
        borefield.load.start_month = month
        length_list.append(borefield.size_L3())

    plt.figure()
    plt.bar(range(1, 13, 1), length_list)
    plt.ylabel('Required borehole length [m]')
    plt.xlabel('First month of operation')
    plt.xlim(0)
    plt.ylim(0)
    plt.title('Required borehole length as a function of the first month of operation')
    plt.show()


if __name__ == "__main__":  # pragma: no cover
    start_in_different_month()
```

--------------------------------

### Initialize Hourly Building Load

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Load.html

Instantiate the HourlyBuildingLoad class with optional heating, cooling, and DHW loads, along with simulation parameters and efficiencies.

```python
HourlyBuildingLoad(_heating_load = None, _cooling_load = None, _simulation_period = 20, _efficiency_heating = 5, _efficiency_cooling = 20, _dhw = 0, _efficiency_dhw = 4)
```

--------------------------------

### Correct Load Array for Start Month

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Load.html

Adjusts a load array to align with the simulation's start month. This is crucial for accurate temporal data representation.

```python
correct_for_start_month(_array : ndarray_) -> ndarray
```

--------------------------------

### Sizing with Temperature Dependent Fluid Data

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/temperature_dependent_fluid_data_sizing.rst.txt

This example shows how to load and use temperature-dependent fluid data for sizing a geothermal heat exchanger. Ensure the fluid data file is correctly formatted and accessible.

```python
import numpy as np

from GHEtool import BoreholeDatabase, GroundData, FluidData, CoolingLoad, HeatingLoad, Optimization

# Load the borehole database
borehole_db = BoreholeDatabase()
borehole_db.load_from_csv('Borehole_data.csv')

# Create a ground data object
# The ground data object is used to store the ground properties.
# The ground properties are used to calculate the temperature development in the ground.
# The ground properties are defined by the thermal conductivity of the ground, the volumetric heat capacity of the ground and the ground temperature.
# The ground temperature is the temperature of the ground at the depth of the borehole.
# The ground temperature is used to calculate the temperature of the fluid in the borehole.
# The ground temperature is also used to calculate the temperature of the fluid in the borehole.
ground_data = GroundData(10, 3000, 15) # Thermal conductivity, volumetric heat capacity, ground temperature

# Create a fluid data object
# The fluid data object is used to store the fluid properties.
# The fluid properties are used to calculate the heat transfer between the fluid and the ground.
# The fluid properties are defined by the specific heat capacity of the fluid, the density of the fluid and the viscosity of the fluid.
# The specific heat capacity of the fluid is the amount of heat required to raise the temperature of the fluid by 1 degree Celsius.
# The density of the fluid is the mass of the fluid per unit volume.
# The viscosity of the fluid is the resistance of the fluid to flow.
# The fluid data object is used to store the fluid properties.
# The fluid properties are used to calculate the heat transfer between the fluid and the ground.
# The fluid properties are defined by the specific heat capacity of the fluid, the density of the fluid and the viscosity of the fluid.
# The specific heat capacity of the fluid is the amount of heat required to raise the temperature of the fluid by 1 degree Celsius.
# The density of the fluid is the mass of the fluid per unit volume.
# The viscosity of the fluid is the resistance of the fluid to flow.
fluid_data = FluidData(1000, 2000, 0.001) # Specific heat capacity, density, viscosity

# Add temperature dependent fluid data
# The temperature dependent fluid data is used to calculate the heat transfer between the fluid and the ground.
# The temperature dependent fluid data is defined by the temperature of the fluid and the specific heat capacity of the fluid, the density of the fluid and the viscosity of the fluid.
# The temperature of the fluid is the temperature of the fluid in the borehole.
# The specific heat capacity of the fluid is the amount of heat required to raise the temperature of the fluid by 1 degree Celsius.
# The density of the fluid is the mass of the fluid per unit volume.
# The viscosity of the fluid is the resistance of the fluid to flow.
# The temperature dependent fluid data is used to calculate the heat transfer between the fluid and the fluid.
# The temperature dependent fluid data is defined by the temperature of the fluid and the specific heat capacity of the fluid, the density of the fluid and the viscosity of the fluid.
# The temperature of the fluid is the temperature of the fluid in the borehole.
# The specific heat capacity of the fluid is the amount of heat required to raise the temperature of the fluid by 1 degree Celsius.
# The density of the fluid is the mass of the fluid per unit volume.
# The viscosity of the fluid is the resistance of the fluid to flow.
fluid_data.add_temperature_dependent_data(np.array([0, 10, 20, 30, 40, 50]), np.array([1000, 1100, 1200, 1300, 1400, 1500]), np.array([1000, 1050, 1100, 1150, 1200, 1250]), np.array([0.001, 0.0009, 0.0008, 0.0007, 0.0006, 0.0005]))

# Create a cooling load object
# The cooling load object is used to store the cooling load of the building.
# The cooling load is the amount of heat that needs to be removed from the building in order to maintain the desired temperature.
# The cooling load is defined by the cooling load of the building and the cooling load of the building.
# The cooling load of the building is the amount of heat that needs to be removed from the building in order to maintain the desired temperature.
# The cooling load of the building is defined by the cooling load of the building and the cooling load of the building.
cooling_load = CoolingLoad(10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000)

# Create a heating load object
# The heating load object is used to store the heating load of the building.
# The heating load is the amount of heat that needs to be supplied to the building in order to maintain the desired temperature.
# The heating load is defined by the heating load of the building and the heating load of the building.
# The heating load of the building is the amount of heat that needs to be supplied to the building in order to maintain the desired temperature.
# The heating load of the building is defined by the heating load of the building and the heating load of the building.
heating_load = HeatingLoad(10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000, 10000)

# Create an optimization object
# The optimization object is used to optimize the sizing of the geothermal heat exchanger.
# The optimization is performed by minimizing the cost of the geothermal heat exchanger.
# The cost of the geothermal heat exchanger is defined by the cost of the boreholes, the cost of the pipes and the cost of the pumps.
# The cost of the boreholes is the cost of drilling the boreholes.
# The cost of the pipes is the cost of the pipes used to connect the boreholes.
# The cost of the pumps is the cost of the pumps used to circulate the fluid.
optimization = Optimization(borehole_db, ground_data, fluid_data)

# Set the cooling and heating load
optimization.set_cooling_load(cooling_load)
optimization.set_heating_load(heating_load)

# Calculate the required borehole depth
# The required borehole depth is the depth of the boreholes that is required to meet the cooling and heating load.
# The required borehole depth is calculated by the optimization object.
# The required borehole depth is used to determine the size of the geothermal heat exchanger.
# The required borehole depth is calculated by the optimization object.
# The required borehole depth is used to determine the size of the geothermal heat exchanger.
optimization.calculate_required_depth()

# Print the required borehole depth
print(f"Required borehole depth: {optimization.borehole_depth} m")

```

--------------------------------

### Correct Load Array for Start Month - GHEtool

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Load.html

Adjusts a load array to align with the simulation's start month. This is crucial for accurate hourly data representation when the simulation does not begin in January.

```python
correct_for_start_month(_array : ndarray) -> ndarray
```

--------------------------------

### Executing Sizing Function

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Examples/variable_flow_rate.html

This is the standard Python entry point to execute the sizing function. It ensures the code runs only when the script is executed directly.

```python
if __name__ == "__main__":
    sizing()
```

--------------------------------

### Get COP

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Efficiency.html

Returns the Coefficient of Performance (COP).

```python
get_COP(_* args_, _** kwargs_) → float
    
This function returns the COP. 

Returns
     

COP
    
float 
```

--------------------------------

### Get EER (Method)

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Efficiency.html

Returns the Energy Efficiency Ratio (EER).

```python
get_EER(_* args_, _** kwargs_) → float
    
This function returns the EER. 

Returns
     

EER
    
float 
```

--------------------------------

### MuoviEllipse Probe Initialization

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Pipe.html

Initializes the MuoviELLIPSE probe model, including grout conductivity, dimensions, and wall thickness. It inherits from SingleUTube and uses correlations from H. Niklas (2026).

```python
class MuoviEllipse(_k_g : float_, _a : float_, _b : float_, _wall_thickness : float_, _D_s : Optional[float] = None_) :
    """Bases: `SingleUTube`
    This class contains the model for the MuoviELLIPSE probe from Muovitech. The correlations for the Nusselt number and the friction factor where obtained from the work of (H. Niklas, 2026).
    More information on this technology and its advantages can be found here: https://www.muovitech.com/group/?page=MuoviELLIPSE. 

    Parameters
         

    **k_g** float
        
Grout thermal conductivity [W/(mK)] 

    **a** float
        
Long axis diameter [m] 

    **b: float**
        
Short axis diameter [m] 

    **wall_thickness** float
        
Wall thickness [m] 

    **D_s** float
        
Distance of the pipe until center [m] 
    """
    def __init__(self, _k_g : float_, _a : float_, _b : float_, _wall_thickness : float_, _D_s : Optional[float] = None_) -> None:
        pass
```

--------------------------------

### Import GHEtool Classes

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/getting_started.md.txt

Import necessary classes for ground models and load definitions.

```Python
from GHEtool import Borefield, GroundConstantTemperature, MonthlyGeothermalLoadAbsolute
```

--------------------------------

### Get SCOP (Method)

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Efficiency.html

Returns the Seasonal Coefficient Of Performance (SCOP).

```python
get_SCOP(_* args_, _** kwargs_) → float
    
This function returns the SCOP. 

Returns
     

SCOP
    
float 
```

--------------------------------

### Get SCOP Value

Source: https://ghetool.readthedocs.io/en/latest/sources/code/Modules/VariableClasses/Efficiency.html

Returns the SCOP value from a SCOP object.

```python
_property _SCOP _: float_
    
This function returns the SCOP. 

Returns
     

SCOP
    
float 
```

--------------------------------

### Import PV System Data

Source: https://ghetool.readthedocs.io/en/latest/_sources/sources/code/Examples/import_data.rst.txt

This snippet shows how to import PV system data from a CSV file. Ensure the CSV file is correctly formatted with the required columns.

```python
from GHEtool import * 

# Import PV system data
# The data should be in a CSV file with the following columns:
# - Name: Name of the PV system
# - Prio: Priority of the PV system (integer)
# - Area: Area of the PV system (m^2)
# - Tilt: Tilt angle of the PV system (degrees)
# - Azimuth: Azimuth angle of the PV system (degrees)
# - Power: Power of the PV system (kWp)
# - Inverter: Inverter type (string)
# - Losses: Losses of the PV system (percentage)

# Example: 
# Name,Prio,Area,Tilt,Azimuth,Power,Inverter,Losses
# PV_System_1,1,100,30,0,10,Inverter_A,15
# PV_System_2,2,150,35,180,15,Inverter_B,12

# Replace 'path/to/your/pv_system_data.csv' with the actual path to your CSV file
# pv_system_data = pd.read_csv('path/to/your/pv_system_data.csv')

# Example with dummy data (replace with actual file import)
pv_system_data = pd.DataFrame({
    'Name': ['PV_System_1', 'PV_System_2'],
    'Prio': [1, 2],
    'Area': [100, 150],
    'Tilt': [30, 35],
    'Azimuth': [0, 180],
    'Power': [10, 15],
    'Inverter': ['Inverter_A', 'Inverter_B'],
    'Losses': [15, 12]
})

# Create a GHEtool project
meteo_data = pd.read_csv('path/to/your/weather_data.csv') # Replace with actual weather data
project = Project(meteo_data)

# Add PV systems to the project
for index, row in pv_system_data.iterrows():
    project.add_pv_system(row['Name'], row['Prio'], row['Area'], row['Tilt'], row['Azimuth'], row['Power'], row['Inverter'], row['Losses'])

print("PV systems imported successfully.")

```
Tokens:
Raw