Custom Components

[nkawerau]

I am currently trying to implement a new custom component in Tespy for an alkaline electrolysis. The basic steps are clear to me from the documentation. Nevertheless, I am having trouble setting up the method for the partial derivatives of the system equations for the Newton–Raphson solver correctly. I think the following section in the documentation tries to explain this: “For the derivative, the partial derivatives to all variables of the network are required. This means, that you have to calculate the partial derivatives to mass flow, pressure, enthalpy and all fluids in the fluid vector on each connection affecting the equation defined before”. However, it’s still not clear to me what the structure of the derivatives should look like. Please explain the differences between derivatives for component variables and for component equations. Some methods “_deriv“ write directly to self.jacobian others return a numpy array called deriv.

[fwitte]

Hi @nkawerau,

thank you for reaching out, the docs are kind of outdated here and should be improvemed!

However, it’s still not clear to me what the structure of the derivatives should look like. Please explain the differences between derivatives for component variables and for component equations. Some methods “_deriv“ write directly to self.jacobian others return a numpy array called deriv.

There are two different types of derivative methods:

1. Constant derivatives for mandatory equations (independet of the value of component parameters, e.g. mass balance)
2. Not constant derivatives for mandatory equations or parameter related equations (such equations that are only applied, if the corresponding parameter has been specified by the user)

For example,

1. The mass balance of a single inlet and outlet component (turbine, compressor, ...). Here the data are set up and written in to the Jacobian prior to solving the network, because their value will never change

   tespy/src/tespy/components/component.py

   Lines 1035 to 1053 in faf5a8c

   	def mass_flow_deriv(self):
   	r"""
   	Calculate partial derivatives for all mass flow balance equations.
   	Returns
   	-------
   	deriv : ndarray
   	Matrix with partial derivatives for the mass flow balance
   	equations.
   	"""
   	deriv = np.zeros((
   	self.num_i,
   	self.num_i + self.num_o + self.num_vars,
   	self.num_nw_vars))
   	for i in range(self.num_i):
   	deriv[i, i, 0] = 1
   	for j in range(self.num_o):
   	deriv[j, j + i + 1, 0] = -1
   	return deriv

2. The energy balance equation for a HeatExchanger (energy transferred from hot side equals energy transferred to cold side in magnitude)

   tespy/src/tespy/components/heat_exchangers/base.py

   Lines 302 to 320 in faf5a8c

   	def energy_balance_deriv(self, increment_filter, k):
   	r"""
   	Partial derivatives of energy balance function.
   	Parameters
   	----------
   	increment_filter : ndarray
   	Matrix for filtering non-changing variables.
   	k : int
   	Position of derivatives in Jacobian matrix (k-th equation).
   	"""
   	for i in range(2):
   	self.jacobian[k, i, 0] = (
   	self.outl[i].h.val_SI - self.inl[i].h.val_SI)
   	self.jacobian[k, i, 2] = -self.inl[i].m.val_SI
   	self.jacobian[k, 2, 2] = self.inl[0].m.val_SI
   	self.jacobian[k, 3, 2] = self.inl[1].m.val_SI

   , or the energy balance equation of a turbomachine, where the power of the component is specified

   tespy/src/tespy/components/turbomachinery/base.py

   Lines 140 to 154 in faf5a8c

   	def energy_balance_deriv(self, increment_filter, k):
   	r"""
   	Calculate partial derivatives of energy balance of a turbomachine.
   	Parameters
   	----------
   	increment_filter : ndarray
   	Matrix for filtering non-changing variables.
   	k : int
   	Position of derivatives in Jacobian matrix (k-th equation).
   	"""
   	self.jacobian[k, 0, 0] = self.outl[0].h.val_SI - self.inl[0].h.val_SI
   	self.jacobian[k, 0, 2] = -self.inl[0].m.val_SI
   	self.jacobian[k, 1, 2] = self.inl[0].m.val_SI

   Here the data need an update for every Newton iteration, therefore the data are updated directly in the Jacobian.

Hope it helps :). How would the equation(s) you want to implement look like?