Introduction#

In this section we provide you with the basics of the TESPy’s modeling concept. TESPy builds up on components that are connected using connections to form a topological network. The figure below highlights these three core components of the software at the example of a small heat pump.

Set up a plant#

In order to simulate a plant we start by creating the network (tespy.networks.network.Network). The network is the main container for the model.

from tespy.networks import Network

# create a network object with R134a as fluid
my_plant = Network()

It is possible to specify a unit system and value ranges for the network’s variables. If you do not specify these, TESPy will use SI-units.

# set the unitsystem for temperatures to °C and for pressure to bar
my_plant.set_attr(T_unit='C', p_unit='bar', h_unit='kJ / kg')

Now you can start to create the components of the network.

Set up components#

The list of components available can be found here. If you set up a component you have to specify a (within one network) unique label. Moreover, it is possible to specify parameters for the component, for example power \(P\) for a pump or upper terminal temperature difference \(ttd_\mathrm{u}\) of a heat exchanger. The full list of parameters for a specific component is stated in the respective class documentation. This example uses a compressor, a control valve two (simple) heat exchangers and a so-called cycle closer.

Note

Parameters for components are generally optional. Only the component’s label is mandatory. If an optional parameter is not specified by the user, it will be a result of the plant’s simulation. This way, the set of equations a component returns is determined by which parameters you specify. You can find all equations in each component’s documentation as well.

from tespy.components import (
    CycleCloser, Compressor, Valve, SimpleHeatExchanger
)

cc = CycleCloser('cycle closer')

# heat sink
co = SimpleHeatExchanger('condenser')
# heat source
ev = SimpleHeatExchanger('evaporator')

va = Valve('expansion valve')
cp = Compressor('compressor')

After creating the components the next step is to connect them in order to form your topological network.

Establish connections#

Connections are used to link two components (outlet of component 1 to inlet of component 2: source to target). If two components are connected with each other the fluid properties at the source will be equal to the properties at the target. It is possible to set the properties on each connection similarly as parameters are set for components. The basic specification options are:

mass flow (m)
volumetric flow (v)
pressure (p)
enthalpy (h)
temperature (T)
a fluid vector (fluid)

See also

There are more specification options available. Please refer to the connections section in the TESPy modules documentation for detailed information. The specification options are stated in the connection class documentation, too: tespy.connections.connection.Connection.

After creating the connections, we need to add them to the network. As the connections hold the information, which components are connected in which way, we do not need to pass the components to the network.

from tespy.connections import Connection

# connections of heat pump
c1 = Connection(cc, 'out1', ev, 'in1', label='1')
c2 = Connection(ev, 'out1', cp, 'in1', label='2')
c3 = Connection(cp, 'out1', co, 'in1', label='3')
c4 = Connection(co, 'out1', va, 'in1', label='4')
c0 = Connection(va, 'out1', cc, 'in1', label='0')

# this line is crutial: you have to add all connections to your network
my_plant.add_conns(c1, c2, c3, c4, c0)

Note

The CycleCloser is a necessary component when working with closed cycles, because a system would always be over determined, if, for example, a mass flow is specified at some point within the cycle. It would propagate through all the components, since they have an equality constraint for the mass flow at their inlet and their outlet. With the example here, that would mean: Without the cycle closer specification of mass flow at a connection would lead to the following set of equations for mass flow, which is an over determination:

\[\begin{split}\begin{split} \dot{m}_1 = &\;\text{5 kg/s}\\ \dot{m}_1 = &\;\dot{m}_2\\ \dot{m}_2 = &\;\dot{m}_3\\ \dot{m}_3 = &\;\dot{m}_4\\ \dot{m}_4 = &\;\dot{m}_1\\ \end{split}\end{split}\]

Similarly, this applies to the fluid composition.

The cycle closer will prompt a warning, if the mass flow and fluid composition are not equal at its inlet and outlet.

We can set the component and connection parameters. In this example, we specify the pressure losses (by outlet to inlet pressure ratio pr) in the condenser and the evaporator as well as the efficiency eta_s of the compressor. On top of that, the heat production of the heat pump can be set with Q for the condenser. Since we are working in subcritical regime in this tutorial, we set the state of the fluid at the evaporator’s outlet to fully saturated steam (x=1) and at the condenser’s outlet to fully saturated liquid (x=0). On top of that, we want to set the condensation and the evaporation temperature levels. Last, we have to specify the fluid vector at one point in our network.

co.set_attr(pr=0.98, Q=-1e6)
ev.set_attr(pr=0.98)
cp.set_attr(eta_s=0.85)

c2.set_attr(T=20, x=1, fluid={'R134a': 1})
c4.set_attr(T=80, x=0)

Note

The sign convention for energy transfer by components is always from the perspective of the component. Energy entering the component means positive sign, energy leaving the component’s system boundary means negative sign.

Start your calculation#

After building your network, the components and the connections, add the following line at the end of your script and run it. You can calculate the COP with the respective component parameters.

my_plant.solve(mode='design')
my_plant.print_results()

print(f'COP = {abs(co.Q.val) / cp.P.val}')

Next steps#

We highly recommend checking our other basic model examples on how to set up different standard thermodynamic cycles in TESPy. The heat pump cycle in that section builds on this heat pump. We will introduce a couple of different inputs and show, how to change the working fluid. The other tutorials show the usage of more components, for example the combustion chamber and the turbine or a condenser including the cooling water side of the system.

In the more advanced tutorials, you will learn, how to set up more complex plants step by step, make a design calculation of the plant as well as calculate offdesign/part load performance.

In order to get a good overview of the TESPy functionalities, the sections on the TESPy modules will guide you in detail.