====== Convection Material ======
<note important>
This Documentation refers to Metafor version >= 3593.
for more informations on changes see [[https://gitlab.uliege.be/am-dept/MN2L/oo_meta/-/merge_requests/167|MR !167]] for technical informations). 

for a Metafor version < 3593, please refers to this [[convection_pre3593|page]].
</note>

The Convection Materials are implemented to take into account the heat exchange by convection between the boundary of a mesh and the surrounding fluid atmosphere. They are designed to be associated with ''Tm(2)Boundary2D(3D)Element'', but will also be usable with ''Tm(2)Source2D(3D)Element'', even if the physical meaning is questioning...

Excepted to the ''ConvectionMaterial'', the flux is linked to a spatial distribution functions related to a set of  local coordinates {$x'$, $y'$, $z'$}, which are handled by the X, Y and Z Axis defined in the Material.
The local Axis are Line Objects that are defined in the CurveSet and referred in the material by their number.


{{ doc:user:elements:boundaries:heat_localcoord.png?400 |Coordonnées locales du la source de chaleur}}


The different laws allows to exchange heat with atmosphere or to model heat exchange due to a fluid jet such as a gas torch for example.


===== Material =====


Therefore, the first step consist in defining an ''[[doc:user:elements:general:materials|MaterialProperties]]'', as

  mat = materset.define(no, matType )
  mat.put(param1, value1)
  mat.depend(param1, fct1, Lock1)) #optional

where
param1	name of the property associated to the element (for example RAY_EMISSIVITY
value1	value of the corresponding property
fct1	function which characterises the dependency of the property (optional: no fct if no dependency)
Lock1	Lock which defines the dependency variable of the property (compulsory if there is a dependency) 


==== ConvectionMaterial ====

the heat flux is computed by $flux = C (T_{fluid}-T)$ 
with : 
  * $C$ : Convection coefficient
  * $T$ : Temperature at the Integration Point
  * $T_{fluid}$ : Temperature of the fluid


=== Parameters ===
^   Name                                          ^     Description       ^  Dependency ^
| ''CONV_COEF'' | Convection coefficient |  TM / TO  |
| ''TEMP_FLUIDE''  | Temperature of the fluid |  TM  |


==== RectangularHConvectionMaterial ====

the heat flux is computed by $flux = C (T_{fluid}-T)$ inside the rectangular box
and $flux = 0.0$ outside of the rectangular box

<note important> Add Drawing </note>


The box is defined by its dimension ($kX$ and $kY$) and moving axes X & Z axis (=> Y axis is deducted from X & Z)

with : 
  * $C$ : Convection coefficient
  * $T$ : Temperature at the Integration Point
  * $T_{fluid}$ : Temperature of the fluid

^   Name                                          ^     Description       ^  Dependency ^
| ''CONV_COEF'' | Convection coefficient |  TM / TO  |
| ''TEMP_FLUIDE''  | Temperature of the fluid |  TM  |
| ''CONV_KX'' | Dimension of the rectangle in the first direction (Aligned on the local X Axis) |  TM  |
| ''CONV_KY''  | Dimension of the rectangle in the first direction (Aligned on the local Y Axis) |  TM  |
| ''HEATFLUX_NUM_AX_X'' | Number of the X Axis (Line object  in the CurveSet)  |  -  |
| ''HEATFLUX_NUM_AX_Z''  | Number of the Z Axis (Line object in the CurveSet) (optional) |  -  |

==== GaussianHConvectionMaterial ====
The heat flux is computed by $flux = C exp^{(-(\frac{x_l}{k_x})^2-(\frac{y_l}{k_y})^2)} (T_{fluid}-T)$ 
so a Gaussian distribution of the heat flux around moving axis.


<note important> Add Drawing </note>


The distribution is defined by its characteristic lengths ($k_x$ and $k_y$) and moving axes X & Z axis (=> Y axis is deducted from X & Z)

with : 
  * $C$ : Convection coefficient
  * $x_l$ & $y_l$ : local coordinate in the referential of the Gaussian
  * $k_x$ & $K_y$ : Characteristic dimension of the Gaussian in its local referential 
  * $T$ : Temperature at the Integration Point
  * $T_{fluid}$ : temperature of the fluid

^   Name                                          ^     Description       ^  Dependency ^
| ''CONV_COEF'' | Convection coefficient |  TM / TO  |
| ''TEMP_FLUIDE''  | Temperature of the fluid |  TM  |
| ''CONV_KX'' | Distribution characteristic length in X local direction |  TM  |
| ''CONV_KY''  | Distribution characteristic length in X local direction |  TM  |
| ''HEATFLUX_NUM_AX_X'' | Number of the X Axis (Line object  in the CurveSet)  |  -  |
| ''HEATFLUX_NUM_AX_Z''  | Number of the Z Axis (Line object in the CurveSet) (optional) |  -  |
| ''HEATFLUX_RESCALE'' | parameter activating the rescale algorithm \\ (to ensure the total heat given by the load is received by the system even with coarse mesh) |  -  | 

==== LogNormHConvectionMaterial ====

The heat flux is computed by $flux = C exp^{(-(log(\frac{|x_l|}{k_x}+1))^2-(log(\frac{|y_l|}{k_y}+1))^2)} (T_{fluid}-T)$  so a Logarithmic distribution of the heat flux around moving axis.


<note important> Add Drawing </note>


The distributionis defined by its  characteristic lengths ($k_x$ and $k_y$) and moving axes X & Z axis (=> Y axis is deducted from X & Z)

with : 
  * $C$ : Convection coefficient
  * $x_l$ & $y_l$ : local coordinate in the referential of the normalised logarithmic
  * $k_x$ & $K_y$ : Characteristic dimension of the normalised logarithmic in its local referential 
  * $T$ : Temperature at the Integration Point
  * $T_{fluid}$ : temperature of the fluid

^   Name                                          ^     Description       ^  Dependency ^
| ''CONV_COEF'' | Convection coefficient |  TM / TO  |
| ''TEMP_FLUIDE''  | Temperature of the fluid |  TM  |
| ''CONV_KX'' | Distribution characteristic length in X local direction |  TM  |
| ''CONV_KY''  | Distribution characteristic length in Y local direction |  TM  |
| ''HEATFLUX_NUM_AX_X'' | Number of the X Axis (Line object  in the CurveSet)  |  -  |
| ''HEATFLUX_NUM_AX_Z''  | Number of the Z Axis (Line object in the CurveSet) (optional) |  -  |
| ''HEATFLUX_RESCALE'' | parameter activating the rescale algorithm \\ (to ensure the total heat given by the load is received by the system even with coarse mesh) |  -  | 

==== CombineHConvectionMaterial ====

The CombineHConvectionMaterial is implemented to model moving and inclined  gas torch convective heat source.
The convective coefficient distribution is different according to local X and Y direction. It is also different upstream and down stream. Finally, outside of the gas flux, the heat transfer is driven by a free natural convection. 

The heat flux is computed by $flux = C exp^{(-xpart^2-ypart^2)} (T_{fluid}-T)$  so a distribution of the heat flux around moving axis.

<note important> Add Drawing </note>


The distribution is defined by different formulation : 
  * Gaussian : $ xpart = frac{x_l}{k_x}$
  * LogNorm : $ xpart = log(frac{|x_l|}{k_x}+1)$

In local X : it can also be different for $x_l > 0$ and $x_l < 0$ to model an inclined gas torch (where upstream and downstream fluid flow is not the same). Distribution type and characteristic dimension can be different up and downstream)

In local Y direction the distribution can also be Gaussian or LogNorm but is similar up and downstream.

Further more, if the "Distributed convection coefficient" is lower than a natural convective coefficient : 

$C exp^{(-xpart^2-ypart^2)} < C_{nat}$

the heatFlux is then computed by natural convection : $flux = C_{nat} (T_{nat fluid}-T)$


with : 
  * $C$ : Convection coefficient (forced)
  * $C_{nat}$ : Convection coefficient (Natural)
  * $x_l$ & $y_l$ : local coordinate in the referential of the normalised logarithmic
  * $k_x$ & $K_y$ : Characteristic dimension of distribution in its local referential 
  * $xpart$ - $ypart$ : distributed local coefficient
  * $T$ : Temperature at the Integration Point
  * $T_{fluid}$ : temperature of the fluid (foced 
  * $T_{nat fluid}$ : temperature of the fluid

^   Name                                          ^     Description       ^  Dependency ^
| ''CONV_COEF'' | Convection coefficient |  TM / TO  |
| ''TEMP_FLUIDE''  | Temperature of the fluid |  TM  |
| ''CONV_TYPE_XF''  | type of distribution for local upstream X direction (CONV_GAUSSIAN or CONV_LOGNORM)no default |  -  | 
| ''CONV_TYPE_XR''  | type of distribution for local upstream X direction  (CONV_GAUSSIAN or CONV_LOGNORM) no default |  -  | 
| ''CONV_TYPE_Y''   | type of distribution for local Y direction   (CONV_GAUSSIAN or CONV_LOGNORM) no default |  -  | 
| ''CONV_KX'' | Distribution characteristic length in Upstream X local direction |  TM  |
| ''CONV_KXR'' | Distribution characteristic length in Downstream X local direction |  TM  |
| ''CONV_KY''  | Distribution characteristic length in Upstream Y local direction |  TM  |
| ''WITH_NATCONV'' | activate natural convection |  -  |
| ''CONV_COEFNAT'' | Natural Convection coefficient |  TM / TO  |
| ''CONV_TEMPNAT''  | Natural Temperature of the fluid |  TM  |
| ''HEATFLUX_NUM_AX_X'' | Number of the X Axis (Line object  in the CurveSet)  |  -  |
| ''HEATFLUX_NUM_AX_Z''  | Number of the Z Axis (Line object in the CurveSet) (optional) |  -  |
| ''HEATFLUX_RESCALE'' | parameter activating the rescale algorithm \\ (to ensure the total heat given by the load is received by the system even with coarse mesh) |  -  |