Updating the documenation around the heat pump

On the left is the primary circuit of geothermal brine while on the right is the circuit of the district-heating system.

The model has four elements:

1. A Geothermal system, Tprod is the temperature of the water produced from the reservoir, while Tinj is the temperature of the water pumped back into the aquifer.

2. A District heating system, Tdh_out is the water that comes _from_ the district heating system, while Tdh_in is the water that goes _to_ the district heating system

3. A Heat Exchanger, which transfers heat from the production water of the Geothermal system to the district-heating system.

4. A Heat Pump, which consumes grid electricity to further heat up the district-heating water and cool the geothermal system water. 

When modelling the system:

1. The production temperature, Tprod, is assumed equal to the temperature of the reservoir.

2. The district heating return temperature, Tdh_out, is known (set by the user, default: 35°C)

2. The district heating input temperature, Tdh_in, is known (set by the user, default: 70°C)

2. The district heating return temperature, Tdh_out, is known (set by the user, default: 35°C).

3. The district heating input temperature, Tdh_in, is known (set by the user, default: 70°C).

4. The total difference between the district heating input and district heating return temperature, ΔT.

5. The minimum absolute injection temperature and the maximum temperature difference between reservoir and injection temperature is also specified by the user, and is used as a condition on the final injection temperature.

This leaves the Injection temperature Tinj, as the remaining unknown.

This is calculated using the equation:

Tinj = Tprod - ΔT1 - ΔT2

where:

ΔT1 = Tprod - Tdh_in, must be between 0 -> ΔTmax (user specified)

ΔT1 = Tprod - Tdh_out, must be between 0 -> ΔT (user specified)

ΔT2 = Tdh_in - (Tdh_out + ΔT1)

### Two simple examples

The final Tinj is then corrected using an absolute and relative injection temperature boundary, ensuring the injection temperature is:

- Always above the absolute minimum injection temperature

- The difference between Tprod - Tinj is never greater than the maximum allowed difference.

### Example 1: Heat pump required

Using the following input: 

- Tprod = 60°C

- Tdh_in = 70°C

- Tdh_out = 35°C

- ΔT = Tdh_in - Tdh_out = 35°C

It is clear that the production temperature of the aquifer is not hot enough to fully supply the district-heating system without assistance from the heat pump, as the temperature from the aquifer is 10°C colder than the temperature required by the district heating systm.

This means that the extra heat will be provided by the heatpump.

Transferred from geothermal heating system to district heating system:

ΔT1 = Tprod - Tdh_out, 60°C - 35°C = 25°C.

Heat additionally added by the heat pump to the district heating system:

ΔT2 = Tdh_in - (Tdh_out + ΔT1) = 70°C - 60°C = 10°C

Injection temperature is the production temperature minus the two deltas above: 

Tinj = Tprod - ΔT1 - ΔT2 = 60°C - 25°C - 10°C = 25°C

### Example 2: Heat pump _not_ required

What happens when the production temperature from the aquifer is hot enough that the heatpump is not required?

- Tprod = 75°C

- Tdh_in = 70°C

- Tdh_out = 35°C

- ΔT = Tdh_in - Tdh_out = 35°C

It is clear that the production temperature of the aquifer is not hot enough to fully supply the district-heating system without assistance from the heat pump, as the temperature from the aquifer is 10°C colder than the temperature required by the district heating systm.

This means that the extra heat will be provided by the heatpump.

Transferred from geothermal heating system to district heating system:

Using the following input: Tprod = 60°C, Tdh_in = 70°C, Tdh_out = 35°C

ΔT1 = Tprod - Tdh_out, 75°C - 35°C = 40°C.

40°C < 35°C therefore ΔT1 = 35°C  

It is clear that the production temperature of the aquifer is not hot enough to fully supply the district-heating system.

First, the district heating system is heated by:

This means that the heat exchanger is able to provide all the heat necessary to the district heating system.

ΔT1 = Tprod - Tdh_in, 60 - 70 = -10°C. This is below 0°C so ΔT1 = 0°C.

ΔT2 = Tdh_in - (Tdh_out + ΔT1) = Tdh_in - Tdh_out = 35°C

Heat additionally added by the heat pump to the district heating system:

Tinj = 60 - ΔT1 - ΔT2 = 25°C

ΔT2 = Tdh_in - (Tdh_out + ΔT1) = 70°C - (35°C + 35°C) = 0°C

Injection temperature is the production temperature minus the two deltas above: 

Tinj = Tprod - ΔT1 - ΔT2 = 75°C - 35°C - 0°C = 35°C

### Calculating the Coefficient of Performance (COP)

        # Act

        results = doublet.calculateDoubletPerformance(input)

        print(results)

        # Assert

        self.assertTrue(np.isclose(17499.99940, transmissivity, 0.001))

        self.assertTrue(np.isclose(163.99771118164062, results.flow(), 1))

        self.assertTrue(np.isclose(60, results.pres(), 0.001))

        self.assertTrue(np.isclose(4.97566556930542, results.power(), 0.001))

        self.assertTrue(np.isclose(989.2578125, results.welld(), 0.001))

        self.assertTrue(np.isclose(4.383212200392486, results.cop(), 0.001))

        self.assertTrue(np.isclose(10.401010755009017, results.utc(), 0.001))

        self.assertTrue(np.isclose(16.50359210062243, results.capex(), 0.001))

        self.assertTrue(np.isclose(5.6734843, results.power(), 0.001))

        self.assertTrue(np.isclose(955.27344, results.welld(), 0.001))

        self.assertTrue(np.isclose(3.8904712, results.cop(), 0.001))

        self.assertTrue(np.isclose(10.368587, results.utc(), 0.001))

        self.assertTrue(np.isclose(17.378712, results.capex(), 0.001))

    # @pytest.mark.skip("This test requires a fix in the java core. ignore until fix is pushed")

    def test_calculateDoubletPerformance_directheatHP_App(self):

        """

        This is a copy of a test from the Java ThermoGisDoubletTest.java script; to validate that this python implementation of the ThermoGIS Doublet

        # Act

        results = doublet.calculateDoubletPerformance(input)

        print(results.power())

        print(results.welld())

        print(results.cop())

        print(results.utc())

        print(results.capex())

        print(results)

        # Assert

        self.assertTrue(np.isclose(17499.99940, transmissivity, 0.001))

        self.assertTrue(np.isclose(163.99771118164062, results.flow(), 1))

        self.assertTrue(np.isclose(60, results.pres(), 0.001))

        self.assertTrue(np.isclose(4.97566556930542, results.power(), 0.001))

        self.assertTrue(np.isclose(989.2578125, results.welld(), 0.001))

        self.assertTrue(np.isclose(4.383212200392486, results.cop(), 0.001))

        self.assertTrue(np.isclose(10.401010755009017, results.utc(), 0.001))

        self.assertTrue(np.isclose(16.50359210062243, results.capex(), 0.001))

        self.assertTrue(np.isclose(5.140035, results.power(), 0.001))

        self.assertTrue(np.isclose(977.9297, results.welld(), 0.001))

        self.assertTrue(np.isclose(2.7099774, results.cop(), 0.001))

        self.assertTrue(np.isclose(13.172601, results.utc(), 0.001))

        self.assertTrue(np.isclose(18.448061, results.capex(), 0.001))

    def test_calculateDoubletPerformance_ORC(self):

        """