multiPhysicsFoam – Boundary-Condition

Docs: fixedGradientCorrected

Mon, 01 Jan 0001 00:00:00 +0000

Overview

fixedGradientCorrected is a Neumann condition for fields of any type (scalar, vector, sphericalTensor, symmTensor, tensor). It prescribes the patch-normal gradient. Its patch value and value coefficients include a non-orthogonal correction $\mathbf{c}\cdot\nabla\phi_P$, evaluated on a small sub-mesh around the patch. Unlike fixedValueCorrected, the correction enters the matrix directly, through valueBoundaryCoeffs. It comes from the foam-extend interface-tracking solver (interTrackFoam, Tuković). The BC is compiled into libinterfaceTrackingFvMesh. It derives from the common base correctedFvPatchField (type corrected). The base class, the sub-mesh machinery, the corrected type and the porting status (interTrackFluid disabled, patchCorrected snGrad not ported) are described on the fixedValueCorrected page.

Mathematical Formulation

$$ \left.\frac{\partial\phi}{\partial n}\right|_b = g \quad \text{on } \partial\Omega, \qquad \phi_b = \phi_P + \phi_c + \delta\, g $$

with the correction from the base class

$$ \mathbf{c} = \boldsymbol{\Delta} - \mathbf{n}\,(\mathbf{n}\cdot\boldsymbol{\Delta}), \qquad \phi_c = \mathbf{c}\cdot(\nabla\phi)_P $$

Matrix coefficients:

Coefficient	Value
`valueInternalCoeffs`	$1$
`valueBoundaryCoeffs`	$\phi_c + \delta\,g$
`gradientInternalCoeffs`	$0$
`gradientBoundaryCoeffs`	$g$
`snGrad()`	$g$

Symbol	Description	Unit
$\phi$	Patch field	field unit
$g$	Prescribed normal gradient (`gradient`)	field unit/m
$\mathbf{n}$	Patch unit normal	–
$\boldsymbol{\Delta}$	Patch delta vector (`patch().delta()`)	m
$\mathbf{c}$	Correction vector	m
$\phi_c$	Stored correction (`corrVecGrad`), updated in `updateCoeffs()`	field unit
$\delta$	$1/$`patch().deltaCoeffs()`	m

Note on OpenFOAM.com. fvPatch::delta() is patch-normal for every non-coupled patch in OpenFOAM.com, so $\mathbf{c} \equiv \mathbf{0}$ and $\phi_c \equiv 0$. The coefficients reduce to those of stock fixedGradient.

Implementation

Construction: the base class reads volFieldName (required) and the optional corrVecGrad. This class then reads gradient (required). If value is given, it is used as the initial patch value. Otherwise $\phi_P + \delta g + \phi_c$ is used, with $\phi_c = 0$ at that point unless corrVecGrad was given. nGradInternal is set to $g$.
updateCoeffs() (base class): recomputes $\mathbf{c}$ if the mesh moves, rebuilds $\phi_c$ on the patch sub-mesh (gradient scheme snGradCorr(<volFieldName>)). It is called whenever an fvMatrix for the field is constructed, so valueBoundaryCoeffs always uses the current $\phi_c$.
evaluate(): the class declares evaluate() without the Pstream::commsTypes argument. It therefore does not override fvPatchField::evaluate(const Pstream::commsTypes), which correctBoundaryConditions() calls. In practice the base evaluate runs, and that only resets the updated flag. The patch value is not recomputed from $\phi_P + \phi_c + \delta g$ after a solve. It keeps its initial value unless code assigns it explicitly. Only the matrix coefficients follow the formula above.
Mapping: autoMap/rmap map the value and gradient.
Sub-mesh motion: interfaceTrackingFvMesh::update() moves the sub-mesh only for U and p.
write(): type, volFieldName, corrVecGrad, gradient, value.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`fixedGradientCorrected`	yes	–
`volFieldName`	Name of the volume field this patch field belongs to	yes	– (no default)
`gradient`	Prescribed normal gradient $g$	yes	–
`value`	Initial patch value	no	$\phi_P + \delta g + \phi_c$
`corrVecGrad`	Initial stored correction $\phi_c$	no	zero

The library must be loaded with libs ("libinterfaceTrackingFvMesh.so"); in system/controlDict.

Usage

outlet
{
 type fixedGradientCorrected;
 volFieldName p;
 gradient uniform 0;
 value uniform 0;
}

Known Limitations

Patch value not updated by correctBoundaryConditions() because the evaluate() signature does not match (see Implementation). Explicit operators that use patch values (fvc::grad, fvc::interpolate, face fluxes) see a stale value.
No correction in OpenFOAM.com (patch-normal delta()). The cost of the sub-mesh gradient remains on every updateCoeffs().
Interface-tracking context not available: interTrackFluid is disabled and patchCorrected is not ported (see fixedValueCorrected).
volFieldName has no default and must match the field name.
Sub-mesh motion only for U and p.

In practice, use the stock fixedGradient instead.

Tutorials

No tutorial uses fixedGradientCorrected.

References

Tuković, Ž., Jasak, H., A moving mesh finite volume interface tracking method for surface tension dominated interfacial fluid flow, Computers & Fluids 55, 2012. DOI: 10.1016/j.compfluid.2011.11.003
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: fixedValueCorrected

Mon, 01 Jan 0001 00:00:00 +0000

Overview

fixedValueCorrected is a Dirichlet condition for fields of any type (scalar, vector, sphericalTensor, symmTensor, tensor). On top of the fixed value it stores a non-orthogonal correction $\mathbf{c}\cdot\nabla\phi_P$ of the near-wall value. The correction is evaluated on a small sub-mesh around the patch. It comes from the foam-extend interface-tracking solver (interTrackFoam, Tuković), where it is used on patches whose near-wall cells become skewed as the mesh follows a moving interface. The fixed-value matrix coefficients themselves are not corrected. The correction only reaches the discretisation through snGradCorrection(), which is called by the patchCorrected snGrad scheme. That scheme is not ported (see Known Limitations).

The BC is compiled into libinterfaceTrackingFvMesh, not libmultiRegionSystem, so this library must be loaded. It is one of three types derived from the common base correctedFvPatchField:

Type	Page
`fixedValueCorrected`	this page
`fixedGradientCorrected`	fixedGradientCorrected
`zeroGradientCorrected`	zeroGradientCorrected
`corrected`	the base class itself, registered as a type but not usable on its own (see below)

Mathematical Formulation

$$ \phi_b = \phi_\text{fixed} \quad \text{on } \partial\Omega $$

With $\mathbf{n}$ the patch unit normal, $\boldsymbol{\Delta}$ the patch delta vector and $\delta = 1/\texttt{deltaCoeffs}$, the base class defines the correction vector and the stored correction

$$ \mathbf{c} = \boldsymbol{\Delta} - \mathbf{n}\,(\mathbf{n}\cdot\boldsymbol{\Delta}), \qquad \phi_c = \mathbf{c}\cdot(\nabla\phi)_P $$

and the corrected normal gradient

$$ \left.\frac{\partial\phi}{\partial n}\right|_b = \frac{\phi_b - \phi_P}{\delta} - \frac{\phi_c}{\delta} = \frac{\phi_b - (\phi_P + \phi_c)}{\delta} $$

The matrix coefficients are those of plain fixedValue:

Coefficient	Value
`valueInternalCoeffs`	$0$
`valueBoundaryCoeffs`	$\phi_b$
`gradientInternalCoeffs`	$-1/\delta$
`gradientBoundaryCoeffs`	$\phi_b/\delta$
`snGradCorrection()`	$-\phi_c/\delta$

Symbol	Description	Unit
$\phi$	Patch field	field unit
$\mathbf{n}$	Patch unit normal	–
$\boldsymbol{\Delta}$	Patch delta vector (`patch().delta()`)	m
$\mathbf{c}$	Correction vector (`correctionVectors()`)	m
$(\nabla\phi)_P$	Cell gradient next to the patch, computed on the patch sub-mesh	field unit/m
$\phi_c$	Stored correction (`corrVecGrad`)	field unit
$\delta$	$1/$`patch().deltaCoeffs()`	m

Note on OpenFOAM.com. In OpenFOAM.com (v2512 and v2606), fvPatch::delta() returns the patch-normal delta for every non-coupled patch. So $\mathbf{c} \equiv \mathbf{0}$ and $\phi_c \equiv 0$ identically. The BC then behaves exactly like stock fixedValue, but still does the sub-mesh work described below on every update. The correction is only non-zero in foam-extend, where delta() is the full $\mathbf{C}_f - \mathbf{C}_P$.

Implementation

Base class correctedFvPatchField (type corrected).

Construction: reads volFieldName (required) and, if present, corrVecGrad. It computes the correction vectors $\mathbf{c}$. It does not read value or patchType.
updateCoeffs(): if the mesh is moving, recomputes $\mathbf{c}$. Then it always calls updateCorrVecGrad():
1. On first use, builds a patch sub-mesh (fvMeshSubset) from the patch face cells plus all their neighbouring cells. The sub-mesh takes its fvSchemes/fvSolution from the region mesh.
2. Interpolates the volume field named volFieldName onto the sub-mesh.
3. For each component, computes fvc::grad with the gradient scheme named snGradCorr(<volFieldName>) (normally covered by gradSchemes { default ...; }).
4. Stores $\phi_c = \mathbf{c}\cdot(\nabla\phi)_P$ and $\mathbf{n}\cdot(\nabla\phi)_P$ (nGradInternal, not used by any active code path).
movePatchSubMesh(): moves the sub-mesh points to the current mesh points. interfaceTrackingFvMesh::update() calls it after each mesh motion for every fixedValueCorrected, fixedGradientCorrected or zeroGradientCorrected patch of the fields U and p only. The sub-meshes of other fields are not moved.
write(): writes type, volFieldName and corrVecGrad.

fixedValueCorrected.

Construction: reads value (required) in addition to the base keywords.
fixesValue() returns true, so no pressure reference is needed if the BC is used on p.
All assignment operators (=, +=, -=, *=, /= with fields, patch fields or constants) are no-ops, as in stock fixedValue. The value can only be changed with ==.
evaluate() is not overridden, so the value stays fixed.
write(): base entries plus value.

patchCorrectedSnGrad (not compiled). The source is in src/dynamicFvMesh/interfaceTrackingFvMesh/patchCorrectedSnGrad. It is a central snGrad scheme with explicit non-orthogonal correction, using the gradient scheme snGradCorr(<field>). On patches of type fixedValueCorrected it replaces the boundary correction by snGradCorrection(). This is the only code path through which the stored correction would enter a discretised equation. The entry in src/dynamicFvMesh/Make/files is commented out (“NEEDS TO BE PORTED STILL”), so the scheme cannot be selected.

The `corrected` type

makePatchFields(corrected) registers the base class as type corrected for scalar, vector, sphericalTensor, symmTensor and tensor fields. The base class does not implement any matrix coefficients (valueInternalCoeffs etc. fall back to fvPatchField, which raises NotImplemented). It does not read or write value, so its patch values are uninitialised. It also does not override evaluate(). type corrected; is therefore not a usable boundary condition. Use one of the three derived types.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`fixedValueCorrected`	yes	–
`volFieldName`	Name of the volume field this patch field belongs to (e.g. `U`, `p`). Used to look up the field for the sub-mesh gradient.	yes	– (no default)
`value`	Fixed patch value	yes	–
`corrVecGrad`	Initial stored correction $\phi_c$ (written on output; overwritten at the first update)	no	zero

Library loading (system/controlDict of the case):

libs
(
 "libinterfaceTrackingFvMesh.so"
);

Usage

movingWall
{
 type fixedValueCorrected;
 volFieldName U;
 value uniform (0 0 0);
}

The field must be the one named in volFieldName. The sub-mesh is only kept in step with mesh motion if the field is U or p and the region mesh is an interfaceTrackingFvMesh.

Known Limitations

No effect in OpenFOAM.com. The patch delta is patch-normal, so the correction vectors and $\phi_c$ are identically zero. The BC is equivalent to fixedValue, at the cost of a sub-mesh construction and a gradient evaluation per component on every updateCoeffs().
patchCorrected snGrad scheme not ported. Even with a non-zero correction, nothing in the compiled code would use snGradCorrection(). The matrix coefficients are those of plain fixedValue.
Interface-tracking region type disabled. The BCs were meant for interTrackFluid, which is commented out in src/multiRegionSystem/Make/files. The multiphaseFlow tutorials that need it (2dRisingBubble, 3dDuineveldRisingBubble, 3dOscillatingBubble) cannot currently be run. Only 3dDuineveldRisingBubble mentions patchCorrected, and only in comments in its base-mesh fvSchemes.
volFieldName has no default and must match the field name. Otherwise the field lookup in updateCoeffs() fails.
Sub-mesh motion only for U and p. For any other field, the sub-mesh keeps its initial geometry while the mesh moves.
corrected is not a standalone BC (see above).

In practice, use the stock fixedValue instead.

Tutorials

No tutorial uses fixedValueCorrected (or any *Corrected type). The FSI tutorials beamInCrossFlow, heatedBeamInCrossFlow and HronTurekFsi3 load libinterfaceTrackingFvMesh.so for their interfaceTrackingFvMesh fluid mesh, but their fields use stock and regionCoupled* boundary conditions.

References

Tuković, Ž., Jasak, H., A moving mesh finite volume interface tracking method for surface tension dominated interfacial fluid flow, Computers & Fluids 55, 2012. DOI: 10.1016/j.compfluid.2011.11.003
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: genericRegionCoupledFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

genericRegionCoupledFlux<Type> is the flux side (Neumann side) of the partitioned Dirichlet–Neumann (DNA) coupling. It derives from fixedGradient and from interfaceToInterfaceCoupleManager. In each coupling iteration it reads the diffusive flux of the value-side partner (a genericRegionCoupledJump-derived BC on the neighbour patch), interpolates it onto this patch, negates it, adds a flux jump $j_q$ and divides by the local diffusivity. The result is relaxed with an acceleration model and fixed as the patch-normal gradient. Every partitioned flux-side BC derives from it: regionCoupledScalarFlux, regionCoupledHeatFlux, regionCoupledPhaseChangeHeatFlux, regionCoupledVelocityFlux, regionCoupledPressureFlux, regionCoupledMassTransferVelocityFlux and regionCoupledTraction.

The template is also registered as a selectable patch field type genericRegionCoupledFlux for scalar and vector fields. Both fluxJump() and flux() are notImplemented, so the bare type aborts on the first updateCoeffs() (see Known Limitations). In a case, use a derived BC such as regionCoupledScalarFlux.

Mathematical Formulation

Let $F$ be the patch with this BC and $J$ the neighbour patch with the value-side partner. The unrelaxed gradient in coupling iteration $k$ is

$$ \left.\frac{\partial \tilde\phi_F}{\partial n}\right|^{k} = \frac{-\,\mathcal{I}_{J\to F}\!\left(q_J\right) + j_q}{\Gamma_F} \quad \text{on } \Gamma, \qquad q_J = \Gamma_J \left.\frac{\partial \phi_J}{\partial n}\right|_b $$

so that, at convergence,

$$ \Gamma_F \frac{\partial \phi_F}{\partial n_F} + \Gamma_J \frac{\partial \phi_J}{\partial n_J} = j_q . $$

$q_J$ is the flux() of the jump-side partner, computed with its own non-orthogonal/second-order settings (see genericRegionCoupledJump). The gradient is then relaxed (fixed, Aitken or IQN-ILS, as for genericRegionCoupledJump):

$$ g_F^{\,k} = g_F^{\,k-1} + \omega^k \left(\tilde g_F^{\,k} - g_F^{\,k-1}\right). $$

The patch value is evaluated from the gradient:

$$ \phi_b = \begin{cases} \phi_P + \mathbf{k}\cdot\nabla\phi_P + \dfrac{g_F}{\Delta_f} & \texttt{secondOrder false} \\[8pt] \phi_P + \mathbf{k}\cdot\nabla\phi_P + \dfrac{g_F + \mathbf{n}\cdot\nabla\phi_P}{2\,\Delta_f} & \texttt{secondOrder true} \end{cases} $$

The term $\mathbf{k}\cdot\nabla\phi_P$ ($\mathbf{k} = \mathbf{d} - \mathbf{n}(\mathbf{n}\cdot\mathbf{d})$) is only present with nonOrthCorr true.

Symbol	Description	Unit
$\phi$	Coupled field (`scalar` or `vector`), same name in both regions	field-dependent
$g_F$	Fixed patch-normal gradient (`gradient()`)	field-dependent / m
$q_J$	Diffusive flux of the jump-side partner	field-dependent
$\mathcal{I}_{J\to F}$	Interface-to-interface interpolation of the owning interface	–
$j_q$	Flux jump, `fluxJump()` of the derived class	as $q$
$\Gamma_F$, $\Gamma_J$	Diffusivities from `diffCoeff()` on each side	field-dependent
$\Delta_f$	`patch().deltaCoeffs()`	1/m
$\mathbf{n}$, $\mathbf{d}$	Outward unit face normal, face-to-cell-centre vector	–, m

The interface residual checked by the DNA loop is

$$ r = \left|\Gamma_F\, g_F + \mathcal{I}_{J\to F}(q_J) - j_q\right|, \qquad \|r\| = \frac{\|r\|_2}{\max\!\left(\min\!\left(\|\Gamma_F\, g_F\|_2,\ \|-\mathcal{I}_{J\to F}(q_J) + j_q\|_2\right),\ \texttt{SMALL}\right)} $$

with the global $L_2$ norm over the patch faces. The own flux uses the stored (relaxed) gradient $g_F$, not a gradient recomputed from the solution.

Implementation

Finding the interface. As for genericRegionCoupledJump: the interface is the registered regionInterfaceType whose type equals the first interfaceType entry and that contains this region/patch on side A or B. No match, or more than one match of that type, is a FatalError. The neighbour region/patch is the other side of that interface.

updateCoeffs():

Returns at once if already updated or if the interface is not coupled (the gradient keeps its last value).
Calls update() on the matched interface (topology update, curvature update if a finite-area mesh exists, then the interface’s correct()).
If the derived class returns useDirectFlux() == true, the gradient is set to flux() directly. In this repository only regionCoupledTraction does that.
Otherwise it looks up the neighbour field under the local field name, refCasts its patch field on the neighbour patch to genericRegionCoupledJumpFvPatchField<Type> and calls its flux(). The flux is interpolated with interpolateFromNbrField, multiplied by $-1$, fluxJump() is added, and the result is divided by diffCoeff().
Relaxes the gradient in place with the acceleration model (accModel_->relax(this->gradient())).
Calls fixedGradientFvPatchField::updateCoeffs().

evaluate() is specialised for scalar and vector. It calls updateCoeffs() if needed and sets the patch value with the formula above, using grad(<field>) if registered, otherwise fvc::grad(<field>). The vector version first calls fixedGradientFvPatchVectorField::evaluate() and then overwrites the value. The matrix coefficients (valueInternalCoeffs, valueBoundaryCoeffs, gradientInternalCoeffs, gradientBoundaryCoeffs) are not overridden. The diffusion term therefore receives exactly $g_F$, while the corrections only enter through the evaluated patch value.

diffCoeff() is identical to the jump side: name from diffusivityName() (the diffusivity keyword unless overridden), v → rho, volScalarField of that name if registered, else a uniform dimensionedScalar from the region’s transportProperties, and 1 for a field named pKin.

Residuals. rawResidual() and normResidual() are called through regionInterfaceType::rawFluxRes/normFluxRes. dnaControl compares the normalised value against maxFluxRes and writes the raw value to <field>initialFluxRes / <field>finalFluxRes when outputFluxResField is on. ofNormResidual() exists but is not called. With useDirectFlux() all residual functions stop with a FatalError, so a derived class that uses the direct flux must not be checked through the generic flux residual.

Acceleration. The same accelerationModel family as on the jump side (fixed, aitken, IQNILS), applied to the gradient field. See genericRegionCoupledJump for the update formulas.

Dictionary Entries

All keywords read by the dictionary constructor (including those of interfaceToInterfaceCoupleManager, fixedGradient and the acceleration model):

Keyword	Description	Required	Default
`type`	`genericRegionCoupledFlux` (or a derived type)	yes	—
`interfaceType`	List of interface type names; only the first entry is used	yes	—
`neighbourFieldName`	Read and written back, but not used (the neighbour field is looked up under the local name)	no	local field name
`diffusivity`	Name of the diffusivity (`volScalarField` or `transportProperties` entry)	no (but see Known Limitations)	`word::null`
`accType`	Acceleration model: `fixed`, `aitken`, `IQNILS`	no	`fixed` (a warning is printed when missing)
`relax`	Initial / fixed relaxation factor $\omega_0$	no	`1.0`
`couplingReuse`	`IQNILS` only: number of past time steps whose modes are kept	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order patch-value evaluation	no	`false`
`gradient`	Initial gradient (`fixedGradient`). If present, the patch value is evaluated from it at construction. If absent, the gradient is zero and the patch value is the patch-internal value.	no	zero
`value`	Written by `write()`, but not read by the constructor (`fixedGradient` constructs the value from `gradient` or by extrapolation)	no	—

write() writes type, interfaceType, neighbourFieldName, diffusivity (if non-empty), accType, relax (couplingReuse for IQNILS), nonOrthCorr, secondOrder and value. The gradient is not written.

Usage

As with the jump side, only derived types are usable. Generic layout (shown with the concrete scalar BC):

// 0/regionB/C
interfaceB
{
 type regionCoupledScalarFlux; // genericRegionCoupledFlux-derived
 interfaceType (defaultInterface);
 diffusivity "D";
 nonOrthCorr false;
 secondOrder false;
 value uniform 0;
}

Partner on the neighbour region (must be genericRegionCoupledJump-derived, same field name and type):

// 0/regionA/C
interfaceA
{
 type regionCoupledScalarJump;
 interfaceType (defaultInterface);
 diffusivity "D";
 accType aitken;
 relax 0.75;
 value uniform 0;
}

The interface entry in constant/regionInterfaceProperties is the same as shown for genericRegionCoupledJump.

Known Limitations

Not usable on its own. fluxJump() and flux() call notImplemented (a FatalError). updateCoeffs() calls fluxJump(), so the bare type aborts on the first coupled solve.
The partner must be a jump BC. The neighbour patch field is refCast to genericRegionCoupledJumpFvPatchField<Type>. Any other neighbour BC (including another flux BC) stops the run with a bad-cast error.
diffusivity effectively required. With the default word::null the diffCoeff() lookup fails unless the derived class overrides diffusivityName().
First relaxation uses the wrong reference. The acceleration model is initialised with the patch values (initialize(*this)), but it relaxes the gradient. In the very first coupled iteration $g = \phi_b + \omega(\tilde g - \phi_b)$ for $\omega \ne 1$. With the default fixed/relax 1 (all tutorials) this has no effect.
gradient is not written. On restart the flux BC starts from a zero gradient (or from gradient if added by hand), not from the last coupled gradient.
value is ignored on input. The initial patch value comes from gradient or zero-gradient extrapolation.
Corrections are explicit. nonOrthCorr/secondOrder only change the evaluated patch value. The fixed-gradient matrix coefficients are unchanged.
diffusivity "v" is not inverted (same dead check as on the jump side: $\Gamma = \rho$ instead of $1/\rho$).
neighbourFieldName has no effect; the same field name is required on both sides.
IQNILS is not parallel-consistent (processor-local sum).
Partitioned only.

Tutorials

Tutorial	Description
—	No tutorial uses the bare `genericRegionCoupledFlux` type. Derived BCs are used in `tutorials/conjugateHeatTransfer/*`, `tutorials/electrochemistry/NTGKBatteryWithTabs` and `tutorials/fluidStructureInteraction/heatedBeamInCrossFlow` (see `regionCoupledScalarFlux`, `regionCoupledHeatFlux`).

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: genericRegionCoupledJump

Mon, 01 Jan 0001 00:00:00 +0000

Overview

genericRegionCoupledJump<Type> is the value side (Dirichlet side) of the partitioned Dirichlet–Neumann (DNA) coupling. It derives from fixedValue and from interfaceToInterfaceCoupleManager. In each coupling iteration it sets the patch value to the neighbour patch value, interpolated onto this patch, plus a value jump $j$. It then relaxes this value with an acceleration model. It also provides the diffusive flux $\Gamma\,\partial\phi/\partial n$ that the flux-side partner (genericRegionCoupledFlux or a class derived from it) reads on the other side of the interface. Every partitioned value-side BC derives from it: regionCoupledScalarJump, regionCoupledTemperatureJump, regionCoupledVelocityValue, regionCoupledPressureValue, regionCoupledMassTransferVelocityValue and regionCoupledMassTransferPressureValue.

The template is also registered as a selectable patch field type genericRegionCoupledJump for scalar and vector fields. It cannot be used on its own, though: valueJump() is notImplemented and aborts the run on the first updateCoeffs() (see Known Limitations). In a case, use a derived BC such as regionCoupledScalarJump instead.

Mathematical Formulation

Let $J$ be the patch with this BC and $F$ the neighbour patch with the flux-side partner. In coupling iteration $k$ the BC computes

$$ \tilde\phi_J^{\,k} = \mathcal{I}_{F\to J}\!\left(\phi_F\right) + j \quad \text{on } \Gamma $$

and fixes the relaxed value

$$ \phi_J^{\,k} = \phi_J^{\,k-1} + \omega^k \left(\tilde\phi_J^{\,k} - \phi_J^{\,k-1}\right) $$

(or the IQN-ILS update; see Implementation). The flux handed to the partner is

$$ q_J = \Gamma_J \left.\frac{\partial \phi_J}{\partial n}\right|_b $$

with the coupled patch-normal gradient (scalar fields)

$$ \left.\frac{\partial \phi}{\partial n}\right|_b = \begin{cases} \Delta_f \left(\phi_b - \phi_P - \mathbf{k}\cdot\nabla\phi_P\right) & \texttt{secondOrder false} \\[4pt] 2\,\Delta_f \left(\phi_b - \phi_P - \mathbf{k}\cdot\nabla\phi_P\right) - \mathbf{n}\cdot\nabla\phi_P & \texttt{secondOrder true} \end{cases} \qquad \mathbf{k} = \mathbf{d} - \mathbf{n}\,(\mathbf{n}\cdot\mathbf{d}) $$

The term $\mathbf{k}\cdot\nabla\phi_P$ is only present with nonOrthCorr true. For vector fields the same expressions are used, and then the normal component is removed: $\partial_n\boldsymbol{\phi} \leftarrow (\mathbf{I} - \mathbf{n}\mathbf{n})\cdot\partial_n\boldsymbol{\phi}$.

Symbol	Description	Unit
$\phi$	Coupled field (`scalar` or `vector`), same name in both regions	field-dependent
$\mathcal{I}_{F\to J}$	Interface-to-interface interpolation (`AMI` or `directMap`) of the owning interface	–
$j$	Value jump, `valueJump()` of the derived class	as $\phi$
$\omega^k$	Relaxation factor of the acceleration model	–
$\Gamma_J$	Diffusivity of side $J$, from `diffCoeff()`	field-dependent
$\phi_P$, $\nabla\phi_P$	Patch-internal cell value and cell gradient	–
$\Delta_f$	`patch().deltaCoeffs()`	1/m
$\mathbf{n}$, $\mathbf{d}$	Outward unit face normal, face-to-cell-centre vector (`patch().delta()`)	–, m

The interface residual checked by the DNA loop is

$$ r = \left|\phi_J - \mathcal{I}_{F\to J}(\phi_F) - j\right|, \qquad \|r\| = \frac{\|r\|_2}{\max\!\left(\min\!\left(\|\phi_J\|_2,\ \|\mathcal{I}_{F\to J}(\phi_F) + j\|_2\right),\ \texttt{SMALL}\right)} $$

where $\|\cdot\|_2$ is the global (all-processor) $L_2$ norm over the patch faces.

Implementation

Finding the interface. The coupling data are taken from a regionInterfaceType object. interfaceToInterfaceCoupleManager looks up all registered interfaces and keeps the one whose type equals the first entry of the BC’s interfaceType list and whose side A or side B is this region/patch. If there is no match, or more than one interface of that type contains this patch, the run stops with a FatalError. The neighbour region and patch are taken from the matched interface: if this patch’s name equals patchA of the interface, the neighbour is side B, otherwise side A.

updateCoeffs(), called when the coupled equation is assembled in the DNA loop:

Returns at once if the BC is already updated or the interface is not coupled. In that case the patch keeps its last value.
Calls update() on the matched interface. This rebuilds the global patches if the mesh topology changed, updates the curvature if the interface has a finite-area mesh, and calls the interface’s correct().
If the derived class returns useDirectValue() == true, the value is set to value() directly. No derived class in this repository does that; the base class returns false.
Otherwise it looks up the neighbour field under the local field name, interpolates the neighbour patch values with interpolateFromNbrField, adds valueJump() and assigns the result.
Relaxes the patch values in place with the acceleration model (accModel_->relax(*this)).
Calls fixedValueFvPatchField::updateCoeffs().

Matrix coefficients. snGrad() and gradientBoundaryCoeffs() are specialised for scalar and vector. They use the cell gradient grad(<field>) if a field of that name is registered, otherwise they compute fvc::grad(<field>) on the fly. They add the non-orthogonal and second-order corrections of the formula above, so the implicit fvm::laplacian of the coupled equation sees the same face gradient that flux() reports. gradientInternalCoeffs() is inherited from fixedValue ($-\Delta_f$).

flux() returns snGrad() * diffCoeff(). The flux-side partner calls it through a refCast to genericRegionCoupledJumpFvPatchField<Type>.

diffCoeff() resolves the diffusivity name returned by the virtual diffusivityName(). The base class returns the diffusivity keyword; derived classes may override it (regionCoupledTemperatureJump falls back to kappa):

The name v is replaced by rho.
If a volScalarField with that name is registered on the local region, its patch values are used.
Otherwise a uniform dimensionedScalar with that name is read from the region’s registered transportProperties dictionary. A missing entry or dictionary is a fatal error.
For a field named pKin the diffusivity is set to 1.

Residuals. rawResidual() (per face) and normResidual() (normalised, see above) are called by regionInterfaceType::rawJumpRes/normJumpRes. The DNA loop (dnaControl) compares the normalised residual against maxJumpRes and writes the raw residual to <field>initialJumpRes / <field>finalJumpRes if outputJumpResField is on. ofNormResidual() (an OpenFOAM-style normalisation) is implemented but not called anywhere. All three residual functions stop with a FatalError if useDirectValue() is true.

Acceleration models

The acceleration model is built from the patch dictionary by accelerationModel<Type>::New. It is initialised with the initial patch values and stores the last relaxed value $x^{k-1}$. In each call it forms the residual $r^k = \tilde x^k - x^{k-1}$. The iteration counter is reset to 1 on the first call in a new time step; $x^{k-1}$ is not reset, so the first iteration of a time step is relaxed against the final value of the previous one.

`accType`	Update
`fixed` (default)	$x^k = x^{k-1} + \omega_0\, r^k$ with $\omega_0 =$ `relax`. With `relax 1` this is no relaxation.
`aitken`	$x^k = x^{k-1} + \omega^k r^k$ with $\omega^k = \left
`IQNILS`	Interface quasi-Newton with inverse Jacobian from a least-squares model. Iteration 1 of a time step drops stored modes older than `couplingReuse` time steps. Iteration 2 stores the reference $(\tilde x_{ref}, r_{ref})$. From iteration 3 the columns $V_i = r^k - r_{ref}$, $W_i = \tilde x^k - \tilde x_{ref}$ are added. With more than one column, $c = \arg\min\\|V c + r^k\\|$ is solved by modified Gram–Schmidt QR and $x^k = \tilde x^k + W c$. Otherwise the fixed update with $\omega_0$ is used.

Dictionary Entries

All keywords read by the dictionary constructor (including those of interfaceToInterfaceCoupleManager and the acceleration model):

Keyword	Description	Required	Default
`type`	`genericRegionCoupledJump` (or a derived type)	yes	—
`interfaceType`	List of interface type names, e.g. `(defaultInterface)`. Only the first entry is used to find the interface. Must be a list.	yes	—
`neighbourFieldName`	Name of the neighbour field. Read and written back, but not used: the neighbour field is always looked up under the local field name.	no	local field name
`diffusivity`	Name of the diffusivity (`volScalarField` or `transportProperties` entry) used by `flux()`	no (but see Known Limitations)	`word::null`
`jumpCoefficient`	Name of a jump-coefficient field/entry. Stored by the base class, used only by `regionCoupledScalarJump`.	no	`word::null`
`accType`	Acceleration model: `fixed`, `aitken`, `IQNILS`	no	`fixed` (a warning is printed when missing)
`relax`	Initial / fixed relaxation factor $\omega_0$	no	`1.0`
`couplingReuse`	`IQNILS` only: number of past time steps whose modes are kept	no	`0`
`nonOrthCorr`	Non-orthogonal correction $\mathbf{k}\cdot\nabla\phi_P$ in `snGrad`	no	`false`
`secondOrder`	Second-order one-sided `snGrad`	no	`false`
`value`	Initial patch value. Read if present; otherwise the patch values are left uninitialised, so always give it.	effectively yes	—

write() writes type, interfaceType, neighbourFieldName, diffusivity (if the resolved name is non-empty), accType, relax (couplingReuse for IQNILS), nonOrthCorr, secondOrder and value. jumpCoefficient is not written.

Usage

Direct use only makes sense with a derived class; the base type aborts in valueJump(). The generic entry layout (shown with the concrete scalar BC) is:

// 0/regionA/C
interfaceA
{
 type regionCoupledScalarJump; // genericRegionCoupledJump-derived
 interfaceType (defaultInterface);
 diffusivity "D";
 accType aitken;
 relax 0.75;
 nonOrthCorr false;
 secondOrder false;
 value uniform 0;
}

The partner on the neighbour region must be a genericRegionCoupledFlux-derived BC of the same field type, e.g. regionCoupledScalarFlux:

// 0/regionB/C
interfaceB
{
 type regionCoupledScalarFlux;
 interfaceType (defaultInterface);
 diffusivity "D";
 nonOrthCorr false;
 secondOrder false;
 value uniform 0;
}

and the patch pair must be declared in constant/regionInterfaceProperties under partitionedCoupledPatches, with the field in coupledFields:

partitionedCoupledPatches
(
 regionAregionB
 {
 interfaceType (defaultInterface);
 coupledPatchPair ((regionA interfaceA) (regionB interfaceB));
 coupledFields (C);
 defaultInterfaceCoeffs {}
 }
);

Known Limitations

Not usable on its own. genericRegionCoupledJump is registered for scalar and vector, but valueJump() calls notImplemented, which is a FatalError. updateCoeffs() calls it in every coupled iteration, so a case using the bare type aborts on the first coupled solve.
diffusivity effectively required. The default is word::null. Unless a derived class overrides diffusivityName(), flux() (called by the partner) then looks up an empty name in transportProperties and stops.
neighbourFieldName has no effect. Both coupled patches must carry a field of the same name.
diffusivity "v" is not inverted. The name v is mapped to rho. The following check for v, meant to return $1/\rho$, compares the already replaced name and is never true, so $\Gamma = \rho$ is used.
Vector snGrad is tangential only. For vector fields the normal component of $\partial_n\boldsymbol\phi$ is removed in snGrad() and gradientBoundaryCoeffs(). This suits the velocity BCs built on it, but not a general vector diffusion problem.
Acceleration state carries over time steps. $x^{k-1}$ is not reset at a new time step, so relax < 1 damps the transient change of the interface value in the first iteration of every step.
IQNILS is not parallel-consistent. The QR products use processor-local sum instead of gSum, so in a decomposed run each processor computes its own coefficients.
Side detection by patch name only. The neighbour side is decided by comparing the local patch name with patchA of the interface. Two coupled patches with the same name in both regions would resolve to the wrong neighbour (inferred, untested).
jumpCoefficient is not written by write(), so it is lost after decomposePar/reconstructPar round trips or in written time directories.
Jump–jump pairing. Nothing prevents a jump BC on both sides, but then no flux BC exists and normFluxRes returns GREAT with a warning, so the DNA loop always runs maxCoupleIter iterations (inferred from the code).
Partitioned only. The monolithic solve is commented out in multiRegionSystem::solve().

Tutorials

Tutorial	Description
—	No tutorial uses the bare `genericRegionCoupledJump` type. Derived BCs are used in `tutorials/conjugateHeatTransfer/*`, `tutorials/electrochemistry/NTGKBatteryWithTabs` and `tutorials/fluidStructureInteraction/heatedBeamInCrossFlow` (see `regionCoupledScalarJump`, `regionCoupledTemperatureJump`).

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4
Küttler, U., Wall, W. A., Fixed-point fluid–structure interaction solvers with dynamic relaxation, Computational Mechanics 43, 2008. DOI: 10.1007/s00466-008-0255-5
Degroote, J., Bathe, K.-J., Vierendeels, J., Performance of a new partitioned procedure versus a monolithic procedure in fluid–structure interaction, Computers & Structures 87, 2009. DOI: 10.1016/j.compstruc.2008.11.013

Docs: paraboloidInletVelocity

Mon, 01 Jan 0001 00:00:00 +0000

Overview

paraboloidInletVelocity is a fixedValue condition for a velocity field. It prescribes a velocity in the $+x$ direction whose magnitude is parabolic in both $y$ and $z$, as found in the developed laminar inflow of a rectangular channel. The peak velocity can be ramped up smoothly from zero with a half-cosine. The BC is based on the setInletVelocity function object of Ž. Tuković and was taken over from the foam-extend solid-mechanics toolbox. It is used for the 3-D FSI benchmark “beam in cross-flow”. The profile is written in global coordinates: the inlet must be normal to $x$, and the channel must be placed as described below.

Mathematical Formulation

$$ \mathbf{U}_b = U(t)\; \frac{y\,(2y_m - y)\,\left(z_m^2 - z^2\right)}{y_m^2\, z_m^2}\; \mathbf{e}_x $$

$(y, z)$ are the global coordinates of each face centre. The profile reaches $U(t)$ at $y = y_m$, $z = 0$. It is zero at $y = 0$, $y = 2y_m$ and $z = \pm z_m$. The time function is

$$ U(t) = \begin{cases} \dfrac{U_\text{max}}{2}\left[1 - \cos\left(\dfrac{\pi\, t}{t_\text{max}}\right)\right] & t < t_\text{end} \\[2ex] U_\text{max} & t \ge t_\text{end} \end{cases} $$

With $t_\text{end} = t_\text{max}$ (as in the tutorials), this is a smooth ramp from $0$ to $U_\text{max}$, after which the velocity is constant. With $t_\text{end} > t_\text{max}$, the velocity follows the cosine further (it oscillates between $0$ and $U_\text{max}$) until $t_\text{end}$, and then jumps to $U_\text{max}$. With $t_\text{end} < t_\text{max}$, the ramp is cut off and the velocity jumps to $U_\text{max}$ at $t_\text{end}$. With $t_\text{end} \le 0$, $U(t) = U_\text{max}$ from the start.

Symbol	Description	Unit
$\mathbf{U}_b$	Patch velocity	m/s
$U_\text{max}$	`maxVelocity`, peak velocity at full load	m/s
$y_m$	`yWidth`: $y$ position of the peak, i.e. half the channel height for a channel $0 \le y \le 2y_m$	m
$z_m$	`zWidth`: half-width in $z$ for a channel $-z_m \le z \le z_m$ (or the full width with a symmetry plane at $z=0$)	m
$t_\text{end}$	`timeVaryingEndTime`	s
$t_\text{max}$	`timeAtMaxVelocity`	s
$t$	`time().value()`	s

Implementation

updateCoeffs() computes $U(t)$ from the current time value and evaluates the formula for every face centre. It assigns the result with operator== and calls fixedValue::updateCoeffs(). The profile does not depend on the patch normal or the internal field.

snGrad() returns $(\mathbf{U}_b - \mathbf{U}_P^{*})\,/\,\delta$, where $\mathbf{U}_P^{*} = \mathbf{U}_P + \mathbf{k}\cdot(\nabla\mathbf{U})_P$ and $\mathbf{k} = (\mathbf{I}-\mathbf{n}\mathbf{n})\cdot\boldsymbol{\Delta}$. The correction is only applied if a volTensorField named grad(<U>) is registered. Otherwise the plain $(\mathbf{U}_b-\mathbf{U}_P)/\delta$ is used.

gradientBoundaryCoeffs() returns $(\mathbf{U}_b - \mathbf{k}\cdot(\nabla\mathbf{U})_P)/\delta$. If no grad(<U>) field is registered, it computes fvc::grad(U) on the fly for this. gradientInternalCoeffs() and the value coefficients are inherited from fixedValue.

A second-order variant exists in both functions, but it is hard-coded off (secondOrder_ = false) and cannot be selected from the dictionary.

Note on OpenFOAM.com. fvPatch::delta() is patch-normal for non-coupled patches, so $\mathbf{k} \equiv \mathbf{0}$. The non-orthogonal correction does nothing, and the gradient coefficients are those of a plain fixedValue condition. The on-the-fly fvc::grad(U) in gradientBoundaryCoeffs() still costs time on every matrix assembly.

write() writes maxVelocity, yWidth, zWidth, timeVaryingEndTime, timeAtMaxVelocity, then type and value.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`paraboloidInletVelocity`	yes	–
`maxVelocity`	Peak velocity $U_\text{max}$	yes	–
`yWidth`	$y_m$, $y$ coordinate of the peak (half channel height)	yes	–
`zWidth`	$z_m$, $z$ half-width of the profile	yes	–
`timeVaryingEndTime`	$t_\text{end}$. `0` gives a constant velocity from the start.	yes	–
`timeAtMaxVelocity`	$t_\text{max}$, end of the cosine ramp	yes if `timeVaryingEndTime > 0`	`0` (not read otherwise)
`value`	Initial patch value (required by `fixedValue`, overwritten at the first update)	yes	–

Usage

From tutorials/fluidStructureInteraction/beamInCrossFlow/0/fluid/orig/partitioned/U. The fluid domain is $0 \le y \le 0.4$, $-0.4 \le z \le 0$ with a symmetry plane at $z = 0$, so yWidth 0.2 puts the peak at mid-height and zWidth 0.4 puts it on the symmetry plane:

inlet
{
 type paraboloidInletVelocity;
 maxVelocity 0.3;
 yWidth 0.2;
 zWidth 0.4;
 timeVaryingEndTime 1.0;
 timeAtMaxVelocity 1.0;
 value uniform (0 0 0);
}

Known Limitations

x-direction and global coordinates only. The velocity always points along $+\mathbf{e}_x$. $y$ and $z$ are absolute coordinates, so the channel must start at $y = 0$ and be centred on $z = 0$. The profile cannot be translated or rotated.
No clipping. Faces outside $0 \le y \le 2y_m$, $|z| \le z_m$ get a negative (reversed) velocity.
timeAtMaxVelocity must be positive when timeVaryingEndTime > 0. Otherwise $U(t)$ divides by zero.
Uses time().value(), not the user time (timeOutputValue()), unlike solidTraction’s series.
Second-order correction not selectable (hard-coded off).
Non-orthogonal correction has no effect in OpenFOAM.com, but gradientBoundaryCoeffs() still computes fvc::grad(U) on each call unless grad(U) is registered (see the note above).

Tutorials

Tutorial	Description
`tutorials/fluidStructureInteraction/beamInCrossFlow`	Inlet of the `pimpleFluid` region, ramped to 0.3 m/s over 1 s.
`tutorials/fluidStructureInteraction/heatedBeamInCrossFlow`	Same inlet in the thermo-FSI variant (`pimpleFluid transportTemperature`).

References

Cardiff, P., Karač, A., De Jaeger, P., Jasak, H., Nagy, J., Ivanković, A., Tuković, Ž., An open-source finite volume toolbox for solid mechanics and fluid-solid interaction simulations, arXiv:1808.10736, 2018.
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledHeatFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledHeatFlux is the flux side (Neumann side) of the temperature coupling used with heatTransferInterface for conjugate heat transfer and thermo-FSI. It derives from genericRegionCoupledFlux<scalar> (and so from fixedGradient). It fixes the normal temperature gradient so that the local conductive heat flux is equal and opposite to the heat flux of the value-side partner on the neighbour region, without an interfacial source. The partner must be a genericRegionCoupledJump<scalar>-derived BC, in practice regionCoupledTemperatureJump. Unlike its partner, this BC does not check the interface type (see Implementation).

Mathematical Formulation

Let $B$ be this patch and $A$ the neighbour (jump-side) patch:

$$ \kappa_A \frac{\partial T_A}{\partial n_A} + \kappa_B \frac{\partial T_B}{\partial n_B} = 0 \quad \text{on } \Gamma $$

imposed as the gradient

$$ \left.\frac{\partial T_B}{\partial n}\right|_b = -\frac{\mathcal{I}_{A\to B}\!\left(\kappa_A\, \partial_n T_A\right)}{\kappa_B} $$

followed by relaxation with the acceleration model. fluxJump() returns zero.

Symbol	Description	Unit
$T$	Temperature (field `T` in both regions)	K
$\kappa_B$	Diffusivity named by `diffusivity`, default `kappa`	W/(m K)
$\kappa_A\,\partial_n T_A$	`flux()` of the jump-side partner	W/m²
$\mathcal{I}_{A\to B}$	Interface-to-interface interpolation	–

Implementation

Run-time work is inherited from genericRegionCoupledFlux<scalar> (see there). The class adds:

fluxJump(): returns a zero field.
diffusivityName(): the diffusivity keyword if set, otherwise kappa. diffCoeff() uses a volScalarField with that name on the local region if one is registered, otherwise a uniform dimensionedScalar from the region’s transportProperties.
heatTransInterface(): a type check plus cast to heatTransferInterface, as in regionCoupledTemperatureJump. It is declared and defined but never called, so the BC accepts any interface type listed first in interfaceType.

Per DNA iteration of T, updateCoeffs() updates the interface, refCasts the neighbour T patch field to genericRegionCoupledJumpFvPatchField<scalar>, interpolates and negates its flux(), divides by the local $\kappa$, relaxes the gradient and fixes it. evaluate() sets the patch temperature from the gradient (with the optional non-orthogonal and second-order corrections). The flux residual $|\kappa_B g_B + \mathcal{I}(q_A)|$ is checked against maxFluxRes.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledHeatFlux`	yes	—
`interfaceType`	Interface type list; the first entry selects the interface (normally `heatTransferInterface`; not checked)	yes	—
`diffusivity`	Name of the thermal conductivity field / `transportProperties` entry	no	`kappa`
`neighbourFieldName`	Read and written, not used	no	local field name (`T`)
`accType`	`fixed`, `aitken` or `IQNILS`	no	`fixed` (with warning)
`relax`	Initial / fixed relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: reused time steps	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order value evaluation	no	`false`
`gradient`	Initial gradient; if given, the initial patch value is evaluated from it	no	zero
`value`	Not read (only written)	no	—

Usage

From tutorials/fluidStructureInteraction/heatedBeamInCrossFlow/0/solid/orig/partitioned/T:

interface
{
 type regionCoupledHeatFlux;
 interfaceType (heatTransferInterface);
 diffusivity "kappa";
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Partner in 0/fluid/orig/partitioned/T:

interfaceShadow
{
 type regionCoupledTemperatureJump;
 interfaceType (heatTransferInterface);
 diffusivity "kappa";
 accType aitken;
 relax 0.75;
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Interface in constant/regionInterfaceProperties (heat transfer stacked on FSI):

fluidsolid
{
 interfaceType (fsiInterface heatTransferInterface);
 coupledPatchPair
 (
 (fluid interfaceShadow)
 (solid interface)
 );
 coupledFields
 (
 D
 T
 );
 coupled yes;
 fsiInterfaceCoeffs
 {}
 heatTransferInterfaceCoeffs
 {
 jumpCoefficient jumpCoefficient [ 0 0 0 0 0 0 0 ] 1;
 }
}

Known Limitations

No interface-type check. heatTransInterface() is never called, so a wrong first interfaceType entry is not caught here. It is usually caught by the partner regionCoupledTemperatureJump, which does check.
Partner must be a jump BC of T (bad-cast error otherwise).
No interfacial heat source or contact resistance: fluxJump() is zero. For phase change use regionCoupledPhaseChangeHeatFlux.
No unit check on kappa across the two regions.
value is ignored on input and gradient is not written (restart starts from a zero gradient).
First relaxation uses the patch values as reference (inherited; the tutorials use the default fixed/relax 1 on this side, where it has no effect).
Inherited from genericRegionCoupledFlux: neighbourFieldName unused, corrections only in the evaluated value, IQNILS not parallel-consistent, partitioned only.

Tutorials

Tutorial	Description
`tutorials/conjugateHeatTransfer/flowOverHeatedPlate`	Solid side (`conductTemperature`, patch `top`), default `kappa`, no relaxation.
`tutorials/conjugateHeatTransfer/ShellAndTubeHeatExchanger`	Solid side towards both fluids (`solid_to_inner`, `solid_to_outer`), `nonOrthCorr true`, `AMI`.
`tutorials/fluidStructureInteraction/heatedBeamInCrossFlow`	Solid side (`solidStVK conductTemperature`) of the thermo-FSI interface.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledMassTransferPressureValue

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledMassTransferPressureValue is the Dirichlet (jump) half of the partitioned pressure coupling across a sharp liquid-vapour interface with phase change. It acts on a volScalarField (p or pKin) and derives from genericRegionCoupledJump<scalar>, i.e. from fixedValue. It applies the same normal-stress jump as regionCoupledPressureValue and adds the recoil pressure $-(1/\rho_\text{own}-1/\rho_\text{nbr})\,\dot m^2$. There is no mass-transfer pressure-flux BC; the partner is presumably regionCoupledPressureFlux (inferred). The BC needs a capillaryInterface as the first interfaceType entry and a massTransferInterface on the same patch pair.

Mathematical Formulation

The BC sits on side A (“own”), which carries the faMesh of the capillaryInterface; “nbr” is side B. $\tilde{\dot m} = \mathcal{I}_{\text{nbr}\to\text{own}}(\dot m)$.

For a field named p:

$$ p_\text{own}^{*} = \mathcal{I}(p_\text{nbr}) + 2(\mu_\text{nbr}-\mu_\text{own})\,\nabla_s\cdot\mathbf{u}_s - \sigma\kappa + (\rho_\text{nbr}-\rho_\text{own})\,(\mathbf{x}_f-\mathbf{x}_\text{ref})\cdot\mathbf{g} - \left(\frac{1}{\rho_\text{own}}-\frac{1}{\rho_\text{nbr}}\right)\tilde{\dot m}^2 \quad \text{on } \Gamma $$

For a field named pKin:

$$ p_{\text{kin,own}}^{*} = \frac{1}{\rho_\text{own}}\Big[\rho_\text{nbr}\,\mathcal{I}(p_\text{kin,nbr}) + 2(\mu_\text{nbr}-\mu_\text{own})\,\nabla_s\cdot\mathbf{u}_s - \sigma\kappa + (\rho_\text{nbr}-\rho_\text{own})\,(\mathbf{x}_f-\mathbf{x}_\text{ref})\cdot\mathbf{g} - \left(\frac{1}{\rho_\text{own}}-\frac{1}{\rho_\text{nbr}}\right)\tilde{\dot m}^2\Big] $$

followed by relaxation, $p^{k} = p^{k-1} + \omega\,(p^{*} - p^{k-1})$.

Symbol	Description	Unit
$p$, $p_\text{kin}$	Pressure / kinematic pressure	Pa / m²/s²
$\dot m$	Interfacial mass flux, `mDotS()` of the `massTransferInterface`	kg/(m² s)
$\mathbf{u}_s$	Surface velocity on the `faMesh` (`Us()`)	m/s
$\sigma$, $\kappa$	Surface tension and face curvature from the `capillaryInterface`	N/m, 1/m
$\mu$, $\rho$	`mu`, `rho` from each region’s `transportProperties`	Pa·s, kg/m³
$\mathbf{g}$	`uniformDimensionedVectorField g` of the local region	m/s²
$\mathbf{x}_\text{ref}$	`PISO.pRefPoint` from the local `fvSolution`	m

Implementation

updateCoeffs() is the generic one of genericRegionCoupledJump: return if updated or coupled no; call update() on the first interfaceType (the capillaryInterface); interpolate the neighbour field (looked up by the local field name); add valueJump(); relax; call fixedValue::updateCoeffs().

valueJump() is that of regionCoupledPressureValue with the extra recoil term. It aborts unless the first interfaceType is capillaryInterface, finds the massTransferInterface by type name and interpolates mDotS() from the neighbour side. PISO.pRefPoint, g, and mu/rho of both regions are required. The mesh flux and patch normals are computed but not used.

Since only the first interface is update()d, $\dot m$ is not recomputed by this BC. It changes only when a BC that lists massTransferInterface first (e.g. regionCoupledPhaseChangeHeatFlux on T) is updated. Until then the recoil term is zero and the BC behaves like regionCoupledPressureValue.

The p jump residual of the pUPimple DNA loop is taken from this BC (side A is checked first). flux() uses the hardcoded diffusivity v, for which diffCoeff() returns $\rho$ instead of $1/\rho$ (1 for pKin); the partner regionCoupledPressureFlux cancels this flux.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledMassTransferPressureValue`	yes	—
`interfaceType`	List of interface type names. First entry must be `capillaryInterface`; `massTransferInterface` must also be listed	yes	—
`value`	Initial patch value. Read if present. If missing, the patch values are not initialised	in practice yes	—
`diffusivity`	Read, but ignored: the BC always uses `v`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`jumpCoefficient`	Read by the base class, not used, not written back	no	empty
`accType`	Acceleration model: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `snGrad()` / matrix coefficients	no	`false`
`secondOrder`	Second-order face-normal gradient	no	`false`

Entries read from other files: PISO { pRefPoint (...); } in the local fvSolution, g in the local constant/, and mu, rho in transportProperties of both regions.

Usage

No tutorial uses this BC. Untested entry on side A, following massTransferInterface:

// 0/fluidA/p
interface
{
 type regionCoupledMassTransferPressureValue;
 interfaceType (capillaryInterface massTransferInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform 0;
}

Partner on side B (inferred):

// 0/fluidB/p
interfaceShadow
{
 type regionCoupledPressureFlux;
 interfaceType (capillaryInterface massTransferInterface);
 value uniform 0;
}

The regionInterfaceProperties entry is shown on the regionCoupledMassTransferVelocityValue page and in massTransferInterface.

Known Limitations

Untested, no tutorial; the intended region type interTrackFluid is disabled.
$\dot m$ is only updated through another BC. See Implementation.
mDotS() is interpolated from the neighbour although it is defined on side A (inferred), where this BC sits. Harmless only for identical conformal patches.
Must sit on side A (inferred): $\sigma$, $\kappa$ and $\nabla_s\cdot\mathbf{u}_s$ are used without interpolation.
No dedicated flux partner. regionCoupledPressureFlux does not account for phase change.
Constant properties, PISO.pRefPoint required, diffusivity and neighbourFieldName ignored (as for regionCoupledPressureValue).

Tutorials

Tutorial	Description
—	No tutorial uses `regionCoupledMassTransferPressureValue`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledMassTransferVelocityFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledMassTransferVelocityFlux is the Neumann (flux) half of the partitioned velocity coupling across a sharp liquid-vapour interface with phase change. It acts on a volVectorField (U) and derives from genericRegionCoupledFlux<vector>, i.e. from fixedGradient. It uses the same stress balance as regionCoupledVelocityFlux and adds the momentum flux $\dot m\,[\![\mathbf{u}_\text{rel}]\!]$ that the mass flux carries across the interface. The partner condition on the other side is regionCoupledMassTransferVelocityValue. The BC needs a capillaryInterface as the first interfaceType entry and a massTransferInterface on the same patch pair.

Mathematical Formulation

“own” is the side the BC sits on (side A, which carries the faMesh) and “nbr” the other side. $\mathbf{n}$ is the faMesh face normal, $\mathbf{n}_\varepsilon = \mathbf{n}$ if the local region is meshA of the capillaryInterface (otherwise $-\mathbf{n}$). $\tilde{\mathbf{F}}$ is the interpolated diffusive flux of the partner BC ($\mu_\text{nbr}$ times the tangential face-normal gradient) and $\tilde{\dot m} = \mathcal{I}_{\text{nbr}\to\text{own}}(\dot m)$.

$$ \mu_\text{own}\frac{\partial \mathbf{U}_\text{own}}{\partial n} = -(\mathbf{I}-\mathbf{n}\mathbf{n})\cdot\tilde{\mathbf{F}} + \mathbf{f}_{\sigma,t} - \mu_\text{own}\,\mathbf{n}\,(\nabla_s\cdot\mathbf{u}_s) + (\mu_\text{nbr}-\mu_\text{own})\,(\nabla_s\mathbf{u}_s)\cdot\mathbf{n} + \tilde{\dot m}\left[\left(\frac{\tilde{\dot m}}{\rho_\text{own}}\mathbf{n}_\varepsilon - \mathbf{U}_\text{own}\right) - \left(\frac{\tilde{\dot m}}{\rho_\text{nbr}}\mathbf{n}_\varepsilon - \mathbf{U}_\text{nbr}\right)\right] $$

with the tangential surface-tension force

$$ \mathbf{f}_{\sigma,t} = \sigma\,\frac{1}{S_f}\sum_{e} \mathbf{L}_e\,c_e \;-\; \sigma\kappa\,\mathbf{n} $$

$\mathbf{U}_\text{own}$ are the current patch values (previous iteration) and $\mathbf{U}_\text{nbr}$ the neighbour patch values without interpolation (see Known Limitations). The gradient is relaxed, $g^{k} = g^{k-1} + \omega\,(g^{*} - g^{k-1})$, and the patch value is reconstructed from it in evaluate() as described for regionCoupledVelocityFlux.

Symbol	Description	Unit
$\mathbf{U}$	Velocity	m/s
$\dot m$	Interfacial mass flux, `mDotS()` of the `massTransferInterface`	kg/(m² s)
$\mathbf{u}_s$	Surface velocity on the `faMesh` (`Us()`)	m/s
$\sigma$, $\kappa$	Surface tension and face curvature from the `capillaryInterface`	N/m, 1/m
$\mathbf{L}_e$, $c_e$	`faMesh` edge length vectors and `edgeLengthCorrection()`	m, –
$\mu$, $\rho$	`mu`, `rho` from each region’s `transportProperties`	Pa·s, kg/m³

Implementation

updateCoeffs() is the generic one of genericRegionCoupledFlux: return if updated or coupled no; call update() on the first interfaceType (the capillaryInterface); interpolate and negate the neighbour flux() (the neighbour patch field is refCast to genericRegionCoupledJump<vector>); add fluxJump(); divide by diffCoeff() (hardcoded name mu: registered volScalarField mu, else transportProperties); relax; call fixedGradient::updateCoeffs().

fluxJump():

aborts unless the first interfaceType is capillaryInterface; finds the massTransferInterface by type name;
computes $\nabla_s\cdot\mathbf{u}_s$, $\nabla_s\mathbf{u}_s$ and the edge-integrated surface-tension force on the faMesh;
reads mu and rho of both regions from transportProperties; if a region has a pKin field, its mu must equal rho*nu exactly, otherwise the run stops;
interpolates mDotS() from the neighbour side.

Because only the first interface is update()d, $\dot m$ is not recomputed by this BC. It changes only when a BC that lists massTransferInterface first (e.g. regionCoupledPhaseChangeHeatFlux on T) is updated.

The U flux residual of the pUPimple DNA loop is taken from this BC if it sits on side A: $\lVert\mu_\text{own}\partial_n\mathbf{U}_\text{own} + \tilde{\mathbf{F}} - \text{fluxJump}\rVert_2$, normalised as in genericRegionCoupledFlux.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledMassTransferVelocityFlux`	yes	—
`interfaceType`	List of interface type names. First entry must be `capillaryInterface`; `massTransferInterface` must also be listed	yes	—
`gradient`	Initial patch-normal gradient. Read if present; otherwise zero gradient and the patch value is set from the internal field	no	zero
`value`	Not read (`fixedGradient` ignores it). Written by `write()`	no	—
`diffusivity`	Read, but ignored: the BC always uses `mu`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`accType`	Acceleration model for the gradient: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order reconstruction of the patch value	no	`false`

write() does not write gradient.

Usage

No tutorial uses this BC. Untested entry on side A, following massTransferInterface:

// 0/fluidA/U
interface
{
 type regionCoupledMassTransferVelocityFlux;
 interfaceType (capillaryInterface massTransferInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0);
}

Partner on side B:

// 0/fluidB/U
interfaceShadow
{
 type regionCoupledMassTransferVelocityValue;
 interfaceType (capillaryInterface massTransferInterface);
 value uniform (0 0 0);
}

The regionInterfaceProperties entry is shown on the regionCoupledMassTransferVelocityValue page and in massTransferInterface.

Known Limitations

Neighbour velocity is not interpolated (bug). $\mathbf{U}_\text{nbr}$ in the mass-flux term is the raw neighbour patch field, combined index by index with local fields. This is only correct for conformal patches with identical face order; otherwise the sizes may not even match.
mDotS() is interpolated from the neighbour although it is defined on side A (inferred), where this BC sits. Harmless only for identical conformal patches.
Must sit on side A (inferred): faMesh normals, $\mathbf{u}_s$, $\sigma$, $\kappa$ are used without interpolation.
$\dot m$ is only updated through another BC. See Implementation.
Exact mu == rho*nu check for regions with pKin.
Relaxation history starts from the patch value (inferred). The base class initialises the acceleration model with the patch values but relaxes the gradient; harmless with relax 1.
Untested, no tutorial; interTrackFluid is disabled.

Tutorials

Tutorial	Description
—	No tutorial uses `regionCoupledMassTransferVelocityFlux`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledMassTransferVelocityValue

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledMassTransferVelocityValue is the Dirichlet (jump) half of the partitioned velocity coupling across a sharp liquid-vapour interface with phase change. It acts on a volVectorField (U) and derives from genericRegionCoupledJump<vector>, i.e. from fixedValue. The patch value is the interpolated neighbour velocity plus the jump in normal velocity that a mass flux $\dot m$ produces between two phases of different density. The partner condition on the other side is regionCoupledMassTransferVelocityFlux. The BC needs both a capillaryInterface and a massTransferInterface on the same patch pair, and the pressure is coupled by regionCoupledMassTransferPressureValue and (inferred) regionCoupledPressureFlux. It is the phase-change counterpart of regionCoupledVelocityValue.

Mathematical Formulation

“own” is the side the BC sits on and “nbr” the other side. $\mathcal{I}_{\text{nbr}\to\text{own}}$ is the patch-to-patch interpolation. $\mathbf{n}_\varepsilon$ is the local patch normal if the local region is meshA of the capillaryInterface, and its negative otherwise. In both cases it points out of region A.

$$ \mathbf{U}_\text{own}^{*} = \mathcal{I}_{\text{nbr}\to\text{own}}(\mathbf{U}_\text{nbr}) + \left(\frac{1}{\rho_\text{own}} - \frac{1}{\rho_\text{nbr}}\right)\tilde{\dot m}\,\mathbf{n}_\varepsilon, \qquad \tilde{\dot m} = \mathcal{I}_{\text{nbr}\to\text{own}}(\dot m) \quad \text{on } \Gamma $$

followed by relaxation, $\mathbf{U}^{k} = \mathbf{U}^{k-1} + \omega\,(\mathbf{U}^{*} - \mathbf{U}^{k-1})$.

Unlike regionCoupledVelocityValue, no surface-velocity or mesh-velocity correction of the normal component is applied. That version is still in the source but commented out.

The diffusive momentum flux handed to regionCoupledMassTransferVelocityFlux is the same as for regionCoupledVelocityValue: $\mu_\text{own}$ times the tangential part of the face-normal gradient (normal component removed in the vector snGrad() of genericRegionCoupledJump).

Symbol	Description	Unit
$\mathbf{U}$	Velocity	m/s
$\dot m$	Interfacial mass flux, `mDotS()` of the `massTransferInterface` (area field on the side-A `faMesh`)	kg/(m² s)
$\rho_\text{own}$, $\rho_\text{nbr}$	`rho` from each region’s `transportProperties`	kg/m³
$\mathbf{n}_\varepsilon$	Interface normal pointing out of region A	–
$\mu_\text{own}$	Diffusivity `mu` (field or `transportProperties`)	Pa·s

Implementation

updateCoeffs() is the generic one of genericRegionCoupledJump: return if updated or coupled no; call update() on the first interfaceType; interpolate the neighbour U (looked up by the local field name); add valueJump(); relax; call fixedValue::updateCoeffs().

valueJump():

finds the capillaryInterface and the massTransferInterface by type name on this patch (rgInterface(<type>)), independent of their order in interfaceType;
interpolates mDotS() from the neighbour side;
reads rho of both regions from transportProperties;
refCasts the neighbour U patch field to genericRegionCoupledFlux<vector> and uses its values only for a diagnostic line;
prints U Dirichlet boundary contributions: ... (integrated volume fluxes of the neighbour velocity, of the jump term and of mesh motion plus $\dot m/\rho$) on every call.

Only the interface listed first in interfaceType is update()d by this BC. With (capillaryInterface massTransferInterface) the massTransferInterface is not corrected here. $\dot m$ is only recomputed when a BC that lists massTransferInterface first (e.g. regionCoupledPhaseChangeHeatFlux on T) is updated. Otherwise it stays at its initial value of zero.

The class has two more functions that are not used in the solution:

updatePhi() would set the boundary phi to the negated interpolated neighbour flux plus $\pm(1/\rho_\text{own}-1/\rho_\text{nbr})\dot m\,|\mathbf{S}_f|$. The call in the base class is commented out.
The member correctClosedVolumePhi(phi, U, p, rAU) would correct the interface flux to the net volume flux $-\dot m/\rho\,|\mathbf{S}_f|$. It is never called. The global correctClosedVolumePhi() used by icoFluid and interTrackFluid (closedVolume on) recognises this BC, but forces the net volume flux through the patch to zero.

The U jump residual is evaluated on this BC if the side-A U patch is not jump-derived (as in the intended setup): $\lVert\mathbf{U}_\text{own} - \mathcal{I}(\mathbf{U}_\text{nbr}) - \text{valueJump}\rVert_2$, normalised as in genericRegionCoupledJump.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledMassTransferVelocityValue`	yes	—
`interfaceType`	List of interface type names. Must contain `capillaryInterface` and `massTransferInterface`; the first entry is the one this BC `update()`s	yes	—
`value`	Initial patch value. Read if present. If missing, the patch values are not initialised	in practice yes	—
`diffusivity`	Read, but ignored: the BC always uses `mu`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`jumpCoefficient`	Read by the base class, not used, not written back	no	empty
`accType`	Acceleration model: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `snGrad()` / matrix coefficients	no	`false`
`secondOrder`	Second-order face-normal gradient	no	`false`

rho (and mu) must be present in transportProperties of both regions.

Usage

No tutorial uses this BC. The entry below follows massTransferInterface and has not been run. Side B (second in coupledPatchPair):

// 0/fluidB/U
interfaceShadow
{
 type regionCoupledMassTransferVelocityValue;
 interfaceType (capillaryInterface massTransferInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0);
}

Partner on side A:

// 0/fluidA/U
interface
{
 type regionCoupledMassTransferVelocityFlux;
 interfaceType (capillaryInterface massTransferInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0);
}

regionInterfaceProperties (excerpt):

fluidAfluidB
{
 interfaceType (capillaryInterface massTransferInterface);

 coupledPatchPair
 (
 (fluidA interface)
 (fluidB interfaceShadow)
 );

 coupledFields
 (
 pUPimple
 T
 );

 capillaryInterfaceCoeffs { sigma sigma [1 0 -2 0 0 0 0] 0.07232; }
 massTransferInterfaceCoeffs { hlv hlv [0 2 -2 0 0 0 0] 2.257e6; TSat TSat [0 0 0 1 0 0 0] 373.15; }
}

The full case setup, including the T coupling that drives $\dot m$, is in massTransferInterface.

Known Limitations

Untested, no tutorial. The interface-tracking region type it was written for (interTrackFluid) is disabled in src/multiRegionSystem/Make/files.
$\dot m$ is only updated through another BC. See Implementation.
Must sit on side B (inferred). mDotS() lives on the side-A faMesh and is interpolated “from the neighbour”.
Neighbour must be flux-derived. The neighbour U patch field is refCast to genericRegionCoupledFlux<vector> (for a log line only); any other type aborts.
Closed-volume correction ignores phase change. With closedVolume on, the global correctClosedVolumePhi() forces zero net volume flux through this patch, which contradicts a non-zero $\dot m$ (inferred).
No normal mesh-velocity term. The normal velocity is not tied to the mesh motion as in regionCoupledVelocityValue (inferred from the commented-out code; intent unclear).
Log output on every call; diffusivity and neighbourFieldName are ignored.

Tutorials

Tutorial	Description
—	No tutorial uses `regionCoupledMassTransferVelocityValue`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledPhaseChangeHeatFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledPhaseChangeHeatFlux is the flux side (Neumann side) of the temperature coupling of massTransferInterface (evaporation/condensation between two fluid regions). It derives from genericRegionCoupledFlux<scalar> (and so from fixedGradient). It fixes the normal temperature gradient so that the conductive heat fluxes of both sides add up to the interfacial heat-flux jump $q_{sat}$, which massTransferInterface computes and consumes as latent heat. The interface found through the first interfaceType entry must be a massTransferInterface. The partner on the neighbour region must be a genericRegionCoupledJump<scalar>-derived BC. The class does not prescribe which one: regionCoupledScalarJump with interfaceType (massTransferInterface) and diffusivity k fits (inferred). regionCoupledTemperatureJump only works if a heatTransferInterface on the same patch pair is listed first in its own interfaceType.

Mathematical Formulation

Let $B$ be this patch and $A$ the neighbour (jump-side) patch:

$$ k_B \frac{\partial T_B}{\partial n_B} + k_A \frac{\partial T_A}{\partial n_A} = q_{sat} \quad \text{on } \Gamma $$

imposed as the gradient

$$ \left.\frac{\partial T_B}{\partial n}\right|_b = \frac{-\,\mathcal{I}_{A\to B}\!\left(k_A\, \partial_n T_A\right) + q_{sat}}{k_B} $$

followed by relaxation with the acceleration model. The flux jump is the heat-flux imbalance at saturation computed by massTransferInterface:

$$ q_{sat} = k_A \left.\frac{\partial T_A}{\partial n_A}\right|_{T_\Gamma = T_{sat}} + k_B \left.\frac{\partial T_B}{\partial n_B}\right|_{T_\Gamma = T_{sat}}, \qquad \dot m = -\frac{q_{sat}}{h_{lv}} $$

The value continuity $T_A = T_B$ comes from the jump-side partner. This BC does not fix $T_\Gamma$ to $T_{sat}$.

Symbol	Description	Unit
$T$	Temperature (field `T` in both regions)	K
$k_B$	Thermal conductivity, diffusivity name fixed to `k`	W/(m K)
$k_A\,\partial_n T_A$	`flux()` of the jump-side partner (its own `diffusivity`)	W/m²
$q_{sat}$	`massTransferInterface::fluxMTJump()` (area field `<patchA>fluxMTJump`)	W/m²
$T_{sat}$, $h_{lv}$	Saturation temperature and latent heat of the interface	K, J/kg
$\dot m$	Interfacial mass flux of the interface	kg/(m² s)

Implementation

Run-time work is inherited from genericRegionCoupledFlux<scalar> (see there). The class adds:

fluxJump(): returns the internal field of massTransInterface().fluxMTJump(), an areaScalarField on the interface’s finite-area mesh. It is used as is, without interpolation between the two sides.
massTransInterface(): checks that the interface matched through the first interfaceType entry is a massTransferInterface, otherwise FatalError. Called from fluxJump(), i.e. in every updateCoeffs() and every residual evaluation.
diffusivityName(): hard-coded to k. The diffusivity keyword is read by the base class but ignored. diffCoeff() takes a volScalarField k of the local region if one is registered, otherwise the uniform k from the region’s transportProperties.

Per DNA iteration of T, updateCoeffs() first calls the interface’s update(). This runs massTransferInterface::correct() → updateMDotS(), which recomputes $q_{sat}$ from copies of both T fields with the interface patches set to $T_{sat}$ (and sets $\dot m$ to zero at time index 1). The jump-side partner triggers the same update. The BC then refCasts the neighbour T patch field to genericRegionCoupledJumpFvPatchField<scalar>, interpolates and negates its flux(), adds $q_{sat}$, divides by $k_B$, relaxes and fixes the gradient. The flux residual $|k_B g_B + \mathcal{I}(q_A) - q_{sat}|$ is checked against maxFluxRes.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledPhaseChangeHeatFlux`	yes	—
`interfaceType`	Interface type list. The first entry must be `massTransferInterface`.	yes	—
`diffusivity`	Read by the base class but ignored (`k` is always used)	no	—
`neighbourFieldName`	Read and written, not used	no	local field name (`T`)
`accType`	`fixed`, `aitken` or `IQNILS`	no	`fixed` (with warning)
`relax`	Initial / fixed relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: reused time steps	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order value evaluation	no	`false`
`gradient`	Initial gradient; if given, the initial patch value is evaluated from it	no	zero
`value`	Not read (only written)	no	—

The interface parameters ($T_{sat}$, $h_{lv}$) are read from massTransferInterfaceCoeffs in constant/regionInterfaceProperties; see docs/interfaces/massTransferInterface.md.

Usage

There is no tutorial. Entry pattern (from docs/interfaces/massTransferInterface.md):

// 0/fluidB/T
interfaceShadow
{
 type regionCoupledPhaseChangeHeatFlux;
 interfaceType (massTransferInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform 373.15;
}

Partner on the other region (inferred: the class only requires a genericRegionCoupledJump<scalar>-derived BC):

// 0/fluidA/T
interface
{
 type regionCoupledScalarJump;
 interfaceType (massTransferInterface);
 diffusivity "k";
 accType aitken;
 relax 0.75;
 value uniform 373.15;
}

Both regions need a uniform k in their transportProperties (read by the interface and by this BC). The patch pair is declared in partitionedCoupledPatches with interfaceType (... massTransferInterface), coupledFields (T ...) and a massTransferInterfaceCoeffs sub-dictionary.

Known Limitations

No tutorial; untested. No case uses this BC or massTransferInterface. The interTrackFluid region type it was written for is commented out in src/multiRegionSystem/Make/files.
Needs massTransferInterface first in interfaceType; any other type aborts in fluxJump().
Conformal patches assumed. $q_{sat}$ lives on the finite-area mesh of the interface (built on side A) and is returned without mapping. If this BC is on side B, the result is only correct when both patches have the same faces in the same order (inferred). Otherwise the field sizes do not match.
Diffusivity name fixed to k. The diffusivity keyword is ignored, yet write() writes diffusivity k;. A registered volScalarField k takes precedence over the transportProperties entry. In a turbulent region that field is the turbulent kinetic energy, not the conductivity (inferred).
Interface update on every call. The interface’s correct() (recomputing $q_{sat}$ and $\dot m$, with an Info line) runs in every updateCoeffs() of every BC coupled through this interface.
$T_{sat}$ is not imposed on the interface temperature; it only enters $q_{sat}$.
Inherited from genericRegionCoupledFlux: partner must be a jump BC, value ignored on input, gradient not written, first relaxation uses the patch values as reference, neighbourFieldName unused, IQNILS not parallel-consistent, partitioned only.

Tutorials

Tutorial	Description
—	No tutorial uses `regionCoupledPhaseChangeHeatFlux`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledPressureFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledPressureFlux is the Neumann (flux) half of the partitioned pressure coupling across a sharp, mesh-tracked fluid-fluid interface. It acts on a volScalarField (p or pKin) and derives from genericRegionCoupledFlux<scalar>, i.e. from fixedGradient. Although it is built on the generic flux-matching scheme, its fluxJump() cancels the neighbour flux. The normal pressure gradient therefore depends only on the local normal acceleration $\mathbf{n}\cdot\partial\mathbf{U}/\partial t$. The partner condition on the other side is regionCoupledPressureValue (or regionCoupledMassTransferPressureValue, inferred: there is no mass-transfer pressure-flux BC). It is used with capillaryInterface.

Mathematical Formulation

The BC sits on side $B$ in all tutorials. $\mathbf{n}_B$ is the outward patch normal and $\tilde F = \mathcal{I}_{A\to B}(F_A)$ the interpolated neighbour flux snGrad(p_A)*k_A. The generic flux BC sets $k_B\,\partial p_B/\partial n = -\tilde F + \text{fluxJump}$ with

$$ \text{fluxJump} = \tilde F - \mathbf{n}_B\cdot\left(\frac{\partial\mathbf{U}_B}{\partial t}\right)_b $$

so that

$$ k_B\,\frac{\partial p_B}{\partial n} = -\,\mathbf{n}_B\cdot\left(\frac{\partial\mathbf{U}_B}{\partial t}\right)_b \quad \text{on } \Gamma_B $$

This is the normal momentum balance at the interface without the convective and viscous terms (the code that included them is commented out). The gradient is relaxed by the acceleration model, $g^{k} = g^{k-1} + \omega\,(g^{*} - g^{k-1})$, and the patch value is reconstructed as $p_B = p_P + \mathbf{k}\cdot\nabla p_P + g/\Delta_f$ (first order) or $p_P + \mathbf{k}\cdot\nabla p_P + (g + \mathbf{n}\cdot\nabla p_P)/(2\Delta_f)$ (secondOrder yes); the $\mathbf{k}$ term only with nonOrthCorr yes.

The diffusivity $k_B$ comes from diffCoeff() with the hardcoded name v:

Field name	Intended $k_B$	Actual $k_B$
`pKin`	$1$	$1$
any other (e.g. `p`)	$1/\rho_B$	$\rho_B$ (registered `volScalarField rho`, else `rho` from `transportProperties`)

For p the imposed gradient is therefore $-\mathbf{n}_B\cdot\partial_t\mathbf{U}_B/\rho_B$ instead of $-\rho_B\,\mathbf{n}_B\cdot\partial_t\mathbf{U}_B$ (see Known Limitations).

Symbol	Description	Unit
$p$	Pressure (`p`) or kinematic pressure (`pKin`)	Pa or m²/s²
$(\partial\mathbf{U}/\partial t)_b$	Patch value of `fvc::ddt(U)` in the local region	m/s²
$k_B$	Diffusivity from `diffCoeff()`	see table
$\Delta_f$	Patch `deltaCoeffs`	1/m

Implementation

updateCoeffs() is the generic one of genericRegionCoupledFlux:

Return if updated or coupled no (gradient frozen).
Call update() on the first interfaceType.
Look up the neighbour field by the local field name and refCast its patch field to genericRegionCoupledJump<scalar>; interpolate its flux() and negate it.
Add fluxJump(), divide by diffCoeff(), relax, call fixedGradient::updateCoeffs().

fluxJump() repeats step 3 to get $\tilde F$ and returns $\tilde F - \mathbf{n}_B\cdot(\partial_t\mathbf{U})_b$. It also reads rho and mu from the local transportProperties (required to exist), but does not use them. Unlike the other capillary BCs it never calls capInterface(), so it does not check the interface type.

The p flux residual of the pUPimple DNA loop comes from this BC, because the side-A pressure patch carries a jump BC. The neighbour flux cancels in it as well:

$$ r_\text{raw} = \left| k_B\,\partial_n p_B + \mathbf{n}_B\cdot(\partial_t\mathbf{U}_B)_b \right| $$

normalised as described in genericRegionCoupledFlux.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledPressureFlux`	yes	—
`interfaceType`	List of interface type names; the first entry is updated by this BC. Tutorials use `(capillaryInterface)`	yes	—
`gradient`	Initial patch-normal gradient. Read if present; otherwise zero gradient and the patch value is set from the internal field	no	zero
`value`	Not read (`fixedGradient` ignores it). Written by `write()`	no	—
`diffusivity`	Read, but ignored: the BC always uses `v`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`accType`	Acceleration model for the gradient: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order reconstruction of the patch value	no	`false`

write() does not write gradient.

Usage

tutorials/multiphaseFlow/2dRisingBubble/0/fluidB/orig/partitioned/p (side B):

interfaceShadow
{
 type regionCoupledPressureFlux;
 diffusivity "v"; // ignored, always v
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform 0; // not read
}

Partner on side A, 0/fluidA/orig/partitioned/p:

interface
{
 type regionCoupledPressureValue;
 interfaceType (capillaryInterface);
 value uniform 0;
}

The interface and DNA entries are shown on the regionCoupledVelocityValue page and in capillaryInterface.

Known Limitations

Wrong diffusivity for p (bug). diffCoeff() renames v to rho before it checks for v, so the reciprocal is never taken and $k_B = \rho_B$. For a field named p the imposed gradient is off by a factor $\rho_B^2$ and has the wrong units. pKin is not affected. The tutorials use p.
Simplified normal momentum balance. Convective and viscous contributions to the normal pressure gradient are not included.
Neighbour flux has no effect. The interpolated neighbour flux cancels. It is still computed, and the neighbour patch field must derive from genericRegionCoupledJump<scalar>, otherwise the refCast aborts.
No interface-type check. Any interface type listed first is accepted; it is only update()d.
diffusivity and neighbourFieldName are ignored; gradient is not written to the time directories.
No runnable tutorial. The tutorials use the disabled interTrackFluid.

Tutorials

Tutorial	Description
`tutorials/multiphaseFlow/2dRisingBubble`	2D rising gas bubble, `interTrackFluid` + `interTrackFluid` (region type currently disabled)
`tutorials/multiphaseFlow/3dDuineveldRisingBubble`	3D rising bubble (Duineveld), same setup
`tutorials/multiphaseFlow/3dOscillatingBubble`	3D oscillating bubble, same setup

The BC is set in the 0/fluidB/orig/partitioned/p variant of each tutorial.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledPressureValue

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledPressureValue is the Dirichlet (jump) half of the partitioned pressure coupling across a sharp, mesh-tracked fluid-fluid interface. It acts on a volScalarField (p, or the kinematic pressure pKin) and derives from genericRegionCoupledJump<scalar>, i.e. from fixedValue. The patch value is the interpolated neighbour pressure plus the normal-stress jump: capillary pressure $\sigma\kappa$, the viscous normal-stress jump and a hydrostatic correction. The partner condition on the other side is regionCoupledPressureFlux. Both belong to capillaryInterface, and this BC aborts if the first entry of its interfaceType list is not capillaryInterface. The variant with phase change is regionCoupledMassTransferPressureValue.

Mathematical Formulation

Region $A$ is the first entry of coupledPatchPair and carries the faMesh of the capillaryInterface. This BC sits on side $A$ (see Known Limitations). $\mathcal{I}_{B\to A}$ is the patch-to-patch interpolation.

For a field named p:

$$ p_A^{*} = \mathcal{I}_{B\to A}(p_B) + 2(\mu_B - \mu_A)\,\nabla_s\cdot\mathbf{u}_s - \sigma\kappa + (\rho_B - \rho_A)\,(\mathbf{x}_f - \mathbf{x}_\text{ref})\cdot\mathbf{g} \quad \text{on } \Gamma_A $$

For a field named pKin the same jump is applied in kinematic form:

$$ p_{\text{kin},A}^{*} = \frac{1}{\rho_A}\Big[\rho_B\,\mathcal{I}_{B\to A}(p_{\text{kin},B}) + 2(\mu_B - \mu_A)\,\nabla_s\cdot\mathbf{u}_s - \sigma\kappa + (\rho_B - \rho_A)\,(\mathbf{x}_f - \mathbf{x}_\text{ref})\cdot\mathbf{g}\Big] $$

The viscous term is the jump of $2\mu\,\partial u_n/\partial n$ with $\partial u_n/\partial n = -\nabla_s\cdot\mathbf{u}_s$. The gravity term implies that p excludes the hydrostatic part $\rho\,\mathbf{g}\cdot(\mathbf{x}-\mathbf{x}_\text{ref})$ (inferred from the formula). The value is then relaxed: $p_A^{k} = p_A^{k-1} + \omega\,(p_A^{*} - p_A^{k-1})$.

Symbol	Description	Unit
$p$, $p_\text{kin}$	Pressure / kinematic pressure	Pa / m²/s²
$\mathbf{u}_s$	Surface velocity on the `faMesh` (`Us()`)	m/s
$\sigma$	Surface tension (`sigma()` of the `capillaryInterface`)	N/m
$\kappa$	Face curvature, `faMesh::faceCurvatures()`	1/m
$\mu_A$, $\mu_B$	`mu` from each region’s `transportProperties`	Pa·s
$\rho_A$, $\rho_B$	`rho` from each region’s `transportProperties`	kg/m³
$\mathbf{g}$	`uniformDimensionedVectorField g` of region A	m/s²
$\mathbf{x}_f$	Patch face centres	m
$\mathbf{x}_\text{ref}$	`PISO.pRefPoint` from region A’s `fvSolution`	m

Implementation

updateCoeffs() is the generic one of genericRegionCoupledJump: return if updated or coupled no; call update() on the first interfaceType (curvature and $\mathbf{u}_s$); interpolate the neighbour field (looked up by the local field name) onto this patch; add valueJump(); relax; call fixedValue::updateCoeffs().

valueJump():

takes $\sigma$, $\kappa$ and $\mathbf{u}_s$ from the capillaryInterface and computes $\nabla_s\cdot\mathbf{u}_s$ with fac::div;
reads pRefPoint from the PISO sub-dictionary of region A’s fvSolution and looks up g in region A (both required);
reads mu and rho of both regions from their registered transportProperties dictionaries;
for pKin returns the bracket above divided by $\rho_A$, minus the interpolated neighbour value, so that the base class sum gives the kinematic formula.

It also computes the mesh flux and the patch normals, but does not use them.

The jump residual for p in the pUPimple DNA loop is taken from this BC, because side A is checked first: $\lVert p_A - \mathcal{I}_{B\to A}(p_B) - \text{valueJump}\rVert_2$, normalised as described in genericRegionCoupledJump.

flux() (inherited) returns snGrad()*k with $k$ from diffCoeff() and the hardcoded diffusivity name v. diffCoeff() maps v to rho, but the step that should take the reciprocal is never reached, so $k = \rho_A$ instead of $1/\rho_A$ ($k = 1$ for pKin). The partner regionCoupledPressureFlux cancels this flux, so the error does not reach the solution.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledPressureValue`	yes	—
`interfaceType`	List of interface type names. The first entry must be `capillaryInterface`	yes	—
`value`	Initial patch value. Read if present. If missing, the patch values are not initialised	in practice yes	—
`diffusivity`	Read, but ignored: the BC always uses `v`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`jumpCoefficient`	Read by the base class, not used, not written back	no	empty
`accType`	Acceleration model: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `snGrad()` / matrix coefficients	no	`false`
`secondOrder`	Second-order face-normal gradient	no	`false`

Entries read from other files:

Entry	File	Required
`PISO { pRefPoint (x y z); }`	`system/<regionA>/fvSolution`	yes
`g`	`constant/<regionA>/g` (registered `uniformDimensionedVectorField`)	yes
`mu`, `rho`	`constant/<region>/transportProperties`, both regions	yes

Usage

tutorials/multiphaseFlow/2dRisingBubble/0/fluidA/orig/partitioned/p (side A):

interface
{
 type regionCoupledPressureValue;
 diffusivity "v"; // ignored, always v
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform 0;
}

Partner on side B, 0/fluidB/orig/partitioned/p:

interfaceShadow
{
 type regionCoupledPressureFlux;
 diffusivity "v";
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform 0;
}

system/fluidA/fvSolution must contain PISO { ... pRefPoint (0 0 0); }. The interface and DNA entries are shown on the regionCoupledVelocityValue page and in capillaryInterface.

Known Limitations

capillaryInterface only. capInterface() aborts unless the first interfaceType entry is capillaryInterface.
Must sit on side A (inferred). $\sigma$, $\kappa$ and $\nabla_s\cdot\mathbf{u}_s$ are taken from the side-A faMesh index by index, without interpolation.
Constant properties. $\mu$ and $\rho$ are single scalars from transportProperties; registered mu or rho fields are not used.
PISO.pRefPoint is required, even if the region solver uses a PIMPLE dictionary.
diffCoeff() returns $\rho$ instead of $1/\rho$ for the diffusivity v. Without consequence for this BC (see Implementation).
diffusivity and neighbourFieldName are ignored.
The header example omits interfaceType, which is required.
No runnable tutorial. The tutorials use the disabled interTrackFluid.

Tutorials

Tutorial	Description
`tutorials/multiphaseFlow/2dRisingBubble`	2D rising gas bubble, `interTrackFluid` + `interTrackFluid` (region type currently disabled)
`tutorials/multiphaseFlow/3dDuineveldRisingBubble`	3D rising bubble (Duineveld), same setup
`tutorials/multiphaseFlow/3dOscillatingBubble`	3D oscillating bubble, same setup

The BC is set in the 0/fluidA/orig/partitioned/p variant of each tutorial.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledScalarFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledScalarFlux is the concrete scalar flux side (Neumann side) of the partitioned DNA coupling. It derives from genericRegionCoupledFlux<scalar> (and so from fixedGradient). It fixes the patch-normal gradient so that the local diffusive flux is equal and opposite to the flux of the value-side partner, i.e. flux continuity without a source at the interface. It does not check the interface type and is normally used with defaultInterface. The partner on the neighbour patch must be a genericRegionCoupledJump<scalar>-derived BC, usually regionCoupledScalarJump.

Mathematical Formulation

Let $F$ be this patch and $J$ the neighbour (jump-side) patch:

$$ \Gamma_F \frac{\partial \phi_F}{\partial n_F} + \Gamma_J \frac{\partial \phi_J}{\partial n_J} = 0 \quad \text{on } \Gamma $$

imposed as the gradient

$$ \left.\frac{\partial \phi_F}{\partial n}\right|_b = -\frac{\mathcal{I}_{J\to F}\!\left(\Gamma_J\, \partial_n \phi_J\right)}{\Gamma_F} $$

followed by relaxation with the acceleration model. fluxJump() returns zero.

Symbol	Description	Unit
$\phi$	Coupled scalar field (same name in both regions)	field-dependent
$\Gamma_F$	Diffusivity named by this BC’s `diffusivity`	field-dependent
$\Gamma_J\,\partial_n\phi_J$	`flux()` of the jump-side partner, with the partner’s `diffusivity`	field-dependent
$\mathcal{I}_{J\to F}$	Interface-to-interface interpolation	–

Implementation

Everything except fluxJump() is inherited from genericRegionCoupledFlux<scalar>. In each DNA iteration updateCoeffs() updates the interface, refCasts the neighbour patch field to genericRegionCoupledJumpFvPatchField<scalar>, takes its flux(), interpolates and negates it, adds fluxJump() (= 0), divides by the local diffCoeff(), relaxes the gradient and fixes it. evaluate() sets the patch value from the gradient with optional non-orthogonal and second-order corrections. The flux residual $|\Gamma_F\,g_F + \mathcal{I}(q_J)|$ is checked against maxFluxRes.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledScalarFlux`	yes	—
`interfaceType`	Interface type list, e.g. `(defaultInterface)`. Only the first entry is used; any type is accepted.	yes	—
`diffusivity`	Diffusivity name (`volScalarField` or `transportProperties` entry)	effectively yes	`word::null` (lookup fails)
`neighbourFieldName`	Read and written, not used	no	local field name
`accType`	`fixed`, `aitken` or `IQNILS`	no	`fixed` (with warning)
`relax`	Initial / fixed relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: reused time steps	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order value evaluation	no	`false`
`gradient`	Initial gradient; if given, the initial patch value is evaluated from it	no	zero
`value`	Not read (only written)	no	—

Usage

From tutorials/electrochemistry/NTGKBatteryWithTabs/0/negTabRegion/orig/partitioned/T (flux side on the tab):

toCellFromNeg
{
 type regionCoupledScalarFlux;
 interfaceType (defaultInterface);
 diffusivity "k";
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Partner in 0/batteryRegion/orig/partitioned/T:

toNegTab
{
 type regionCoupledScalarJump;
 interfaceType (defaultInterface);
 diffusivity "k";
 accType aitken;
 relax 0.75;
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

The regionInterfaceProperties (cellToNegTab, defaultInterface, coupledFields (phiPos phiNeg T)) and the DNA entries are shown in regionCoupledScalarJump. In this tutorial k is a uniform entry in the transportProperties of the NTGK and conductPotentialTemperature regions.

Known Limitations

Partner must be a jump BC of the same field (bad-cast error otherwise).
diffusivity must be set; the default word::null lookup fails.
No interfacial source. fluxJump() is always zero. Use a derived BC with its own fluxJump() (e.g. regionCoupledPhaseChangeHeatFlux) for a flux jump.
No consistency check between the diffusivities named on the two sides.
value is ignored on input and gradient is not written. On restart the coupled gradient starts from zero unless gradient is given.
First relaxation uses the patch values as reference (inherited; only matters with relax ≠ 1 or aitken/IQNILS on this side).
Inherited from genericRegionCoupledFlux: neighbourFieldName unused, nonOrthCorr/secondOrder only in the evaluated value, IQNILS not parallel-consistent, partitioned only.

Tutorials

Tutorial	Description
`tutorials/electrochemistry/NTGKBatteryWithTabs`	`phiPos`: flux side on the battery (`diffusivity sigmaPos`, initial `gradient uniform 0.1266`). `phiNeg`: flux side on the negative tab (`diffusivity sigma`). `T`: flux side on both tabs (`diffusivity k`). All with `defaultInterface` and `directMap`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledScalarJump

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledScalarJump is the concrete scalar value side (Dirichlet side) of the partitioned DNA coupling. It derives from genericRegionCoupledJump<scalar> (and so from fixedValue). It fixes the patch value to the neighbour value interpolated onto this patch, scaled by a jump (partition) coefficient $c$, which defaults to 1, i.e. continuity. It does not check the interface type, so it works with any interface, in practice defaultInterface. It is the generic choice for potentials, temperatures and concentrations that need no interface physics. The partner on the neighbour patch is regionCoupledScalarFlux (or any other genericRegionCoupledFlux<scalar>-derived BC, e.g. regionCoupledPhaseChangeHeatFlux).

Mathematical Formulation

Let $J$ be this patch and $F$ the neighbour (flux-side) patch:

$$ \phi_J = c\;\mathcal{I}_{F\to J}(\phi_F) \quad \text{on } \Gamma $$

implemented as $\phi_J = \mathcal{I}_{F\to J}(\phi_F) + j$ with the value jump

$$ j = \mathcal{I}_{F\to J}(\phi_F)\,(c - 1). $$

The value is then relaxed by the acceleration model. The flux handed to the partner is

$$ q_J = \Gamma_J \left.\frac{\partial \phi_J}{\partial n}\right|_b $$

with the coupled snGrad of genericRegionCoupledJump (optional non-orthogonal and second-order corrections).

Symbol	Description	Unit
$\phi$	Coupled scalar field (same name in both regions)	field-dependent
$c$	Jump (partition) coefficient, keyword `jumpCoefficient`	–
$\mathcal{I}_{F\to J}$	Interface-to-interface interpolation	–
$\Gamma_J$	Diffusivity named by `diffusivity`	field-dependent

Implementation

All run-time work (interface lookup, updateCoeffs(), relaxation, snGrad, flux(), diffCoeff(), residuals) is inherited from genericRegionCoupledJump<scalar>. The class only implements valueJump():

Looks up the neighbour field under the local field name and interpolates its neighbour patch values onto this patch.
Determines $c$ per face:
- if a volScalarField named jumpCoefficient is registered on the local region, its local patch values are used;
- else, if jumpCoefficient is set, a uniform dimensionedScalar of that name is read from the local region’s transportProperties;
- else $c = 1$.
Returns $\mathcal{I}_{F\to J}(\phi_F)\,(c - 1)$.

valueJump() is evaluated in updateCoeffs() and again in each residual evaluation (jump residual $|\phi_J - \mathcal{I}(\phi_F) - j|$, checked against maxJumpRes).

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledScalarJump`	yes	—
`interfaceType`	Interface type list, e.g. `(defaultInterface)`. Only the first entry is used to find the interface; any type is accepted.	yes	—
`diffusivity`	Diffusivity name (`volScalarField` or `transportProperties` entry) used by `flux()` for the partner	effectively yes	`word::null` (lookup fails)
`jumpCoefficient`	Name of the partition-coefficient field / `transportProperties` entry	no	`word::null` → $c = 1$
`neighbourFieldName`	Read and written, not used	no	local field name
`accType`	`fixed`, `aitken` or `IQNILS`	no	`fixed` (with warning)
`relax`	Initial / fixed relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: reused time steps	no	`0`
`nonOrthCorr`	Non-orthogonal correction of `snGrad`	no	`false`
`secondOrder`	Second-order `snGrad`	no	`false`
`value`	Initial patch value (read if present, otherwise uninitialised)	effectively yes	—

Usage

From tutorials/electrochemistry/NTGKBatteryWithTabs/0/posTabRegion/orig/partitioned/phiPos (jump side on the tab):

toCellFromPos
{
 type regionCoupledScalarJump;
 interfaceType (defaultInterface);
 diffusivity "sigma";
 accType aitken;
 relax 0.1;
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Partner in 0/batteryRegion/orig/partitioned/phiPos:

toPosTab
{
 type regionCoupledScalarFlux;
 interfaceType (defaultInterface);
 diffusivity "sigmaPos";
 secondOrder false;
 nonOrthCorr false;
 value $internalField;
 gradient uniform 0.1266;
}

Interface entry in constant/regionInterfaceProperties:

cellToPosTab
{
 interfaceType (defaultInterface);
 coupledPatchPair
 (
 (batteryRegion toPosTab)
 (posTabRegion toCellFromPos)
 );
 coupledFields
 (
 phiPos
 phiNeg
 T
 );
 defaultInterfaceCoeffs
 {}
}

and a DNA entry per coupled field in constant/multiRegionProperties:

DNA
{
 phiPos
 {
 maxCoupleIter 50;
 residualControl
 {
 maxJumpRes 1e-05;
 outputJumpResField no;
 maxFluxRes 1e-05;
 outputFluxResField no;
 }
 }
}

For a partition coefficient (e.g. Henry’s law $C_A = H\,C_B$), add jumpCoefficient H; and provide H either as a volScalarField on the jump-side region or as H H [0 0 0 0 0 0 0] 0.5; in its transportProperties.

Known Limitations

No interface-type check. Any interface type listed first in interfaceType is accepted. The interface’s own physics, if any, is not used, except that its correct() is called through update().
diffusivity must be set. The default word::null makes the diffCoeff() lookup in transportProperties fail as soon as the partner asks for flux().
Diffusivities are not checked for consistency. Each side uses whatever its diffusivity names (in NTGK, sigmaPos on the battery and sigma on the tab). Flux conservation requires the same units on both sides.
Jump coefficient is taken from the jump side only (local field or local transportProperties). With a volScalarField, the local patch values are used and not interpolated.
jumpCoefficient is not written by write(), so it disappears from written time directories and after decomposePar.
Inherited limitations of genericRegionCoupledJump: neighbourFieldName unused, side detection by patch name only, IQNILS not parallel-consistent, partitioned only.

Tutorials

Tutorial	Description
`tutorials/electrochemistry/NTGKBatteryWithTabs`	`batteryRegion (NTGK)` coupled to two `conductPotentialTemperature` tabs through `defaultInterface`. `phiPos`: jump side on the positive tab (`diffusivity sigma`, Aitken 0.1). `phiNeg`: jump side on the battery (`diffusivity sigmaNeg`, Aitken 0.75). `T`: jump side on the battery at both tabs (`diffusivity k`, Aitken 0.75). `directMap` transfer.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledTemperatureJump

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledTemperatureJump is the value side (Dirichlet side) of the temperature coupling of heatTransferInterface, used for conjugate heat transfer and thermo-FSI. It derives from genericRegionCoupledJump<scalar> (and so from fixedValue). It fixes the patch temperature to the neighbour temperature, interpolated onto this patch and scaled by the interface’s jumpCoefficient $c$ ($c = 1$: temperature continuity). It also supplies its heat flux $\kappa\,\partial T/\partial n$ to the partner regionCoupledHeatFlux on the neighbour region. The interface found through the first interfaceType entry must be a heatTransferInterface.

Mathematical Formulation

Let $A$ be this patch and $B$ the neighbour (flux-side) patch:

$$ T_A = c\;\mathcal{I}_{B\to A}(T_B) \quad \text{on } \Gamma $$

implemented as $T_A = \mathcal{I}_{B\to A}(T_B) + j$ with

$$ j = \mathcal{I}_{B\to A}(T_B)\,(c - 1), $$

followed by relaxation with the acceleration model. The heat flux handed to regionCoupledHeatFlux is

$$ q_A = \kappa_A \left.\frac{\partial T_A}{\partial n}\right|_b $$

with the coupled snGrad of genericRegionCoupledJump (optional non-orthogonal and second-order corrections).

Symbol	Description	Unit
$T$	Temperature (field `T` in both regions)	K
$c$	`heatTransferInterfaceCoeffs/jumpCoefficient` (uniform, constant)	–
$\kappa_A$	Diffusivity named by `diffusivity`, default `kappa`	W/(m K)
$\mathcal{I}_{B\to A}$	Interface-to-interface interpolation	–

Implementation

Run-time work is inherited from genericRegionCoupledJump<scalar> (see there). The class adds:

valueJump(): looks up the neighbour T under the local field name, interpolates its neighbour patch values, and returns $\mathcal{I}(T_B)\,(c - 1)$. Here $c$ is heatTransInterface().jumpCoefficient().value(), a single scalar.
heatTransInterface(): checks that the interface matched through the first interfaceType entry has type heatTransferInterface, otherwise FatalError (“BC can only be used in combination with a heatTransferInterface”). It is called from valueJump(), so the check runs on the first updateCoeffs() and on every residual evaluation.
diffusivityName(): returns the diffusivity keyword if set, otherwise kappa. diffCoeff() uses the volScalarField with this name on the local region if one is registered, else a uniform dimensionedScalar of that name from the region’s transportProperties.

Per DNA iteration of T: the interface is updated (its correct() is a no-op), the value $\mathcal{I}(T_B) + j$ is set, relaxed (accType, relax) and fixed. The jump residual $|T_A - \mathcal{I}(T_B) - j|$ is checked against maxJumpRes.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledTemperatureJump`	yes	—
`interfaceType`	Interface type list. The first entry must be `heatTransferInterface`.	yes	—
`diffusivity`	Name of the thermal conductivity field / `transportProperties` entry	no	`kappa`
`neighbourFieldName`	Read and written, not used	no	local field name (`T`)
`jumpCoefficient`	Read by the base class but ignored (the coefficient comes from the interface)	no	`word::null`
`accType`	`fixed`, `aitken` or `IQNILS`	no	`fixed` (with warning)
`relax`	Initial / fixed relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: reused time steps	no	`0`
`nonOrthCorr`	Non-orthogonal correction of `snGrad`	no	`false`
`secondOrder`	Second-order `snGrad`	no	`false`
`value`	Initial patch value (read if present, otherwise uninitialised)	effectively yes	—

Usage

From tutorials/conjugateHeatTransfer/flowOverHeatedPlate/0/fluid/orig/partitioned/T:

interface
{
 type regionCoupledTemperatureJump;
 interfaceType (heatTransferInterface);

 accType aitken;
 relax 0.75;

 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Partner in 0/solid/orig/partitioned/T:

top
{
 type regionCoupledHeatFlux;
 interfaceType (heatTransferInterface);

 secondOrder false;
 nonOrthCorr false;
 value $internalField;
}

Interface in constant/regionInterfacePropertiesPartitioned:

partitionedCoupledPatches
(
 fluidsolid
 {
 interfaceType (heatTransferInterface);
 coupledPatchPair
 (
 (fluid interface)
 (solid top)
 );
 coupledFields
 (
 T
 );
 heatTransferInterfaceCoeffs
 {
 jumpCoefficient jumpCoefficient [ 0 0 0 0 0 0 0 ] 1;
 }
 }
);

and the T entry in the DNA block of constant/multiRegionProperties (maxCoupleIter, maxJumpRes, maxFluxRes). For thermo-FSI the interface entry lists interfaceType (fsiInterface heatTransferInterface);, while the T patches keep interfaceType (heatTransferInterface); (tutorials/fluidStructureInteraction/heatedBeamInCrossFlow).

Known Limitations

Needs heatTransferInterface first in the BC’s interfaceType list; any other type aborts in valueJump().
Constant, uniform jump coefficient. $c$ is a single dimensionedScalar read once by the interface. The jumpCoefficient patch keyword (field lookup) of regionCoupledScalarJump is not used here.
No unit check on kappa. The flux balance with the partner only conserves energy if both sides name conductivities in the same units (e.g. not DT in m²/s on one side).
Missing diffusivity is fatal when the partner first asks for flux() (no kappa field and no kappa in transportProperties).
Inherited from genericRegionCoupledJump: neighbourFieldName unused, side detection by patch name only, acceleration state carried over time steps, IQNILS not parallel-consistent, partitioned only (the *Monolithic tutorial variants use other BCs).

Tutorials

Tutorial	Description
`tutorials/conjugateHeatTransfer/flowOverHeatedPlate`	Fluid side of `fluid (pimpleFluid transportTemperature)` / `solid (conductTemperature)`, Aitken 0.75, `directMap`.
`tutorials/conjugateHeatTransfer/ShellAndTubeHeatExchanger`	Fluid side on `inner_to_solid` and `outer_to_solid`, `nonOrthCorr true`, default `fixed` relaxation, `AMI`.
`tutorials/fluidStructureInteraction/heatedBeamInCrossFlow`	Fluid side of the thermo-FSI interface (`diffusivity "kappa"`, Aitken 0.75), stacked with `fsiInterface`.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledTraction

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledTraction applies the fluid load to the solid in a partitioned fluid-structure interaction. It acts on the solid displacement D (volVectorField) and derives from genericRegionCoupledFlux<vector>, i.e. from fixedGradient. It uses the “direct flux” path of the base class: the gradient is computed entirely from the fluid traction and the solid stress state, with no flux matching against a partner BC. There is no partner coupled BC on the fluid side, because the fluid has no D field. The fluid side follows the solid through the interfaceTrackingFvMesh mesh motion, and its velocity usually uses movingWallVelocity. The BC belongs to fsiInterface and aborts if the first entry of its interfaceType list is not fsiInterface. The solid region must be solidStVK.

Mathematical Formulation

The fluid traction is evaluated on the fluid patch, mapped to the solid patch and its sign is flipped:

$$ \mathbf{t} = -\,\mathcal{I}_{f\to s}\!\left(\boldsymbol{\sigma}_f\cdot\mathbf{n}_f\right) $$

The normal displacement gradient is then

$$ \frac{\partial \mathbf{D}}{\partial n} = \frac{1}{K}\left[\,\mathbf{t} - \mathbf{n}\cdot\boldsymbol{\sigma}_s + K\,\mathbf{n}_0\cdot\nabla\mathbf{D}\,\right], \qquad \mathbf{n} = \frac{\mathbf{F}^{-T}\cdot\mathbf{n}_0}{\lvert\mathbf{F}^{-T}\cdot\mathbf{n}_0\rvert} \quad \text{on } \Gamma_s $$

This is the usual segregated traction condition: the explicit stress $\mathbf{n}\cdot\boldsymbol{\sigma}_s$ is replaced by the implicit $K\,\partial\mathbf{D}/\partial n$ part. At convergence of the solid Picard loop $\mathbf{n}\cdot\boldsymbol{\sigma}_s = \mathbf{t}$ holds in the deformed configuration. The gradient is relaxed by the acceleration model, $g^{k} = g^{k-1} + \omega\,(g^{*} - g^{k-1})$, and the patch value is reconstructed as $\mathbf{D}_b = \mathbf{D}_P + \mathbf{k}\cdot\nabla\mathbf{D}_P + g/\Delta_f$ (first order) or $\mathbf{D}_P + \mathbf{k}\cdot\nabla\mathbf{D}_P + (g + \mathbf{n}_0\cdot\nabla\mathbf{D}_P)/(2\Delta_f)$ (secondOrder yes); the $\mathbf{k}$ term only with nonOrthCorr yes.

Symbol	Description	Unit
$\mathbf{D}$	Solid total displacement	m
$\boldsymbol{\sigma}_f$	Fluid Cauchy stress, `volSymmTensorField sigma` of the fluid region	Pa
$\mathbf{n}_f$	Outward unit normal of the fluid patch	–
$\boldsymbol{\sigma}_s$	Solid Cauchy stress (`sigma` of the solid)	Pa
$\mathbf{n}_0$	Undeformed solid patch normal	–
$\mathbf{n}$	Deformed solid patch normal	–
$\mathbf{F}^{-1}$	Inverse deformation gradient (`Finv`)	–
$K$	Implicit stiffness (`impK`); $1/K$ = `rImpK`	Pa
$\nabla\mathbf{D}$	Displacement gradient (`gradD`)	–

Implementation

updateCoeffs() is the generic one of genericRegionCoupledFlux with useDirectFlux() returning true:

Return if updated or if the interface has coupled no. The gradient is then frozen at its last value. With couplingStartTime, the coupling is switched on once that time is reached.
Call update() on the first interfaceType, i.e. the fsiInterface.
Set gradient() = flux(), relax it, call fixedGradient::updateCoeffs().

flux():

checks that the first interfaceType is fsiInterface;
looks up the fluid field named sigma (hardcoded) in the neighbour region, takes its patch values on the neighbour patch, dots them with the neighbour patch normals, interpolates the result to the solid patch and negates it;
looks up impK, rImpK, gradD, sigma and Finv on the solid patch (all provided by solidStVK);
calls fsiInterface::setTotalForce() with $\sum \mathbf{t}\,\lvert\mathbf{S}_0\rvert$ (undeformed face areas). The interface logs this value in info().

evaluate() uses the registered grad(D) if one exists. solidStVK registers its gradient as gradD, so in practice fvc::grad(D) is computed on every evaluation.

In the DNA loop for D (multiRegionSystem::solve()), each iteration runs solvePIMPLE() on the fluid (updating the fluid sigma), then assembles and solves D with this BC, then meshMotionCorrector() and interfaces_->update(). Convergence is judged by the fsiInterface interface residual (maxIntRes). The jump and flux residuals of the generic base classes cannot be used: rawResidual()/normResidual() abort for a direct-flux BC, and the fluid has no D field anyway.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledTraction`	yes	—
`interfaceType`	List of interface type names. The first entry must be `fsiInterface`	yes	—
`neighbourFieldName`	Read by the coupling manager, but ignored: the fluid field is always looked up as `sigma`	no	local field name (`D`)
`gradient`	Initial displacement gradient. Read if present; otherwise zero gradient and the patch value is set from the internal field	no	zero
`value`	Not read (`fixedGradient` ignores it). Written by `write()`	no	—
`diffusivity`	Read by the base class, not used (direct flux)	no	empty
`accType`	Acceleration model for the gradient: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order reconstruction of the patch value	no	`false`

write() writes diffusivity only if it was set, and does not write gradient.

Usage

Solid 0/solid/D from tutorials/fluidStructureInteraction/HronTurekFsi3/0/solid/orig/partitioned/D:

interface
{
 type regionCoupledTraction;
 neighbourFieldName sigma; // ignored, sigma is hardcoded
 interfaceType (fsiInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0); // not read
}

The matching fluid patch has no coupled BC. In the tutorials it uses movingWallVelocity for U, zeroGradient for pKin, and fixedValue for pointMotionU (driven by interfaceTrackingFvMesh with fsiInterface yes).

constant/regionInterfaceProperties:

partitionedCoupledPatches
(
 fluidsolid
 {
 interfaceType (fsiInterface);

 coupledPatchPair
 (
 (fluid interfaceShadow)
 (solid interface)
 );

 coupledFields
 (
 D
 );

 fsiInterfaceCoeffs
 {}
 }
);

constant/multiRegionProperties:

DNA
{
 D
 {
 maxCoupleIter 100;

 residualControl
 {
 maxIntRes 1e-7;
 }
 }
}

The full setup (dynamic mesh, transfer method, coupling start time) is described in fsiInterface.

Known Limitations

fsiInterface and solidStVK only. The interface type is checked; the solid fields impK, rImpK, gradD, sigma and Finv are only provided by solidStVK.
The fluid stress must be called sigma. neighbourFieldName is read but not used.
No generic residuals. Use the fsiInterface interface residual (maxIntRes); jump/flux residuals abort for this BC.
Relaxation history starts from the patch value (inferred). The base class initialises the acceleration model with the patch values of D but relaxes the gradient. With relax 1 (the default, used in all tutorials) this has no effect.
Total force uses the undeformed area and is set on every call of flux(). It is a diagnostic only.
gradient is not written to the time directories, so a restart starts from zero gradient until the first update.
Partitioned only. There is no monolithic FSI path.

Tutorials

Tutorial	Description
`tutorials/fluidStructureInteraction/HronTurekFsi3`	Hron-Turek FSI3 benchmark (`pimpleFluid` + `solidStVK`), AMI transfer, coupling starts at t = 2 s
`tutorials/fluidStructureInteraction/beamInCrossFlow`	Elastic beam in cross-flow (`pimpleFluid` + `solidStVK`), directMap transfer
`tutorials/fluidStructureInteraction/heatedBeamInCrossFlow`	Heated elastic beam; `fsiInterface` + `heatTransferInterface` on one patch pair

The BC is set in the 0/solid/orig/partitioned/D variant of each tutorial (./Allrun -p).

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledVelocityFlux

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledVelocityFlux is the Neumann (flux) half of the partitioned velocity coupling across a sharp, mesh-tracked fluid-fluid interface. It acts on a volVectorField (the velocity U) and derives from genericRegionCoupledFlux<vector>, i.e. from fixedGradient. It sets the normal velocity gradient so that the tangential viscous stress balances the neighbour stress plus the tangential surface-tension force. The normal component of the gradient follows from surface continuity. The partner condition on the other side is regionCoupledVelocityValue. Both belong to capillaryInterface, and this BC aborts if the first entry of its interfaceType list is not capillaryInterface.

Mathematical Formulation

Region $A$ is the first entry of coupledPatchPair and carries the finite-area mesh (faMesh) of the capillaryInterface. This BC sits on side $A$ (see Known Limitations). $\mathbf{n}$ is the faMesh face normal (faceAreaNormals()), $\mathcal{I}_{B\to A}$ the patch-to-patch interpolation, and $\mathbf{F}_B$ the flux computed by regionCoupledVelocityValue on side B ($\mu_B$ times the tangential part of $\partial\mathbf{U}_B/\partial n_B$). With $\tilde{\mathbf{F}} = \mathcal{I}_{B\to A}(\mathbf{F}_B)$, the gradient is

$$ \mu_A \frac{\partial \mathbf{U}_A}{\partial n} = -\tilde{\mathbf{F}} + \mathbf{n}(\mathbf{n}\cdot\tilde{\mathbf{F}}) + \mathbf{f}_{\sigma,t} - \mu_A\,\mathbf{n}\,(\nabla_s\cdot\mathbf{u}_s) + (\mu_B - \mu_A)\,(\nabla_s\mathbf{u}_s)\cdot\mathbf{n} \quad \text{on } \Gamma_A $$

The first two terms are $-(\mathbf{I}-\mathbf{n}\mathbf{n})\cdot\tilde{\mathbf{F}}$. The tangential surface-tension force is

$$ \mathbf{f}_{\sigma,t} = \sigma\,\frac{1}{S_f}\sum_{e} \mathbf{L}_e\,c_e \;-\; \sigma\kappa\,\mathbf{n} $$

The normal term $-\mu_A\mathbf{n}\,\nabla_s\cdot\mathbf{u}_s$ uses $\partial u_n/\partial n = -\nabla_s\cdot\mathbf{u}_s$ (incompressibility at the surface). The gradient is relaxed by the acceleration model: $g^{k} = g^{k-1} + \omega\,(g^{*} - g^{k-1})$.

The patch value is reconstructed from the gradient in evaluate():

$$ \mathbf{U}_A = \mathbf{U}_P + \mathbf{k}\cdot\nabla\mathbf{U}_P + \frac{1}{\Delta_f}\,\frac{\partial \mathbf{U}_A}{\partial n} \qquad\text{or}\qquad \mathbf{U}_A = \mathbf{U}_P + \mathbf{k}\cdot\nabla\mathbf{U}_P + \frac{1}{2\Delta_f}\left(\frac{\partial \mathbf{U}_A}{\partial n} + \mathbf{n}\cdot\nabla\mathbf{U}_P\right) $$

(first order / secondOrder yes; the $\mathbf{k}$ term only with nonOrthCorr yes).

Symbol	Description	Unit
$\mathbf{U}$	Velocity	m/s
$\mathbf{u}_s$	Surface velocity on the `faMesh` (`Us()`)	m/s
$\sigma$	Surface tension (`sigma()` of the `capillaryInterface`)	N/m
$\kappa$	Face curvature, `faMesh::faceCurvatures()`	1/m
$\mathbf{L}_e$, $c_e$	Edge length vectors and `edgeLengthCorrection()` of the `faMesh`	m, –
$\mu_A$, $\mu_B$	`mu` from each region’s `transportProperties`	Pa·s
$\Delta_f$	Patch `deltaCoeffs`	1/m
$\mathbf{k}$	Non-orthogonal part of the face-to-cell vector	m

Implementation

updateCoeffs() is the generic one of genericRegionCoupledFlux:

Return if already updated or if the interface has coupled no (the gradient is then frozen).
Call update() on the first interfaceType (refreshes curvature and $\mathbf{u}_s$ of the capillaryInterface).
Look up the neighbour U by the local field name and refCast its patch field to genericRegionCoupledJump<vector>. Its flux() is interpolated onto this patch and negated.
Add fluxJump() and divide by k = diffCoeff(). diffCoeff() uses the hardcoded name mu: the patch values of a registered volScalarField mu, otherwise the scalar mu from transportProperties.
Relax the gradient with the acceleration model and call fixedGradient::updateCoeffs().

fluxJump() computes $\nabla_s\cdot\mathbf{u}_s$ (fac::div), $\nabla_s\mathbf{u}_s$ (fac::grad) and the edge-integrated surface-tension force on the faMesh. $\mu_A$ and $\mu_B$ are always read from the transportProperties dictionaries, not from fields. If a region has a pKin field, its mu must equal rho*nu from the same dictionary (exact floating-point comparison), otherwise the run stops with a fatal error. Each call prints Us <value> (the volume swept by $\mathbf{u}_s$ in one time step) to the log.

evaluate() uses the registered grad(U) if it exists, otherwise fvc::grad(U).

The U flux residual of the pUPimple DNA loop is taken from this BC (side A is checked first):

$$ r = \frac{\lVert \mu_A\,\partial_n\mathbf{U}_A + \tilde{\mathbf{F}} - \text{fluxJump}\rVert_2} {\max\left(\min\left(\lVert\mu_A\,\partial_n\mathbf{U}_A\rVert_2,\ \lVert -\tilde{\mathbf{F}}+\text{fluxJump}\rVert_2\right),\ \text{SMALL}\right)} $$

with $\partial_n\mathbf{U}_A$ from snGrad() of the patch.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledVelocityFlux`	yes	—
`interfaceType`	List of interface type names. The first entry must be `capillaryInterface`	yes	—
`gradient`	Initial patch-normal gradient. Read if present; otherwise zero gradient and the patch value is set from the internal field	no	zero
`value`	Not read (`fixedGradient` ignores it). Written by `write()`	no	—
`diffusivity`	Read, but ignored: the BC always uses `mu`	no	empty
`neighbourFieldName`	Read by the coupling manager, not used by this BC	no	local field name
`accType`	Acceleration model for the gradient: `fixed`, `aitken`, `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `evaluate()`	no	`false`
`secondOrder`	Second-order reconstruction of the patch value	no	`false`

write() does not write gradient. After a restart or decomposePar the gradient therefore starts from zero.

Usage

tutorials/multiphaseFlow/2dRisingBubble/0/fluidA/orig/partitioned/U (side A):

interface
{
 type regionCoupledVelocityFlux;
 diffusivity "mu"; // ignored, always mu
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0); // not read
}

Partner on side B, 0/fluidB/orig/partitioned/U:

interfaceShadow
{
 type regionCoupledVelocityValue;
 interfaceType (capillaryInterface);
 value uniform (0 0 0);
}

The regionInterfaceProperties and multiRegionProperties entries are shown on the regionCoupledVelocityValue page and in capillaryInterface.

Known Limitations

capillaryInterface only. capInterface() aborts unless the first interfaceType entry is capillaryInterface.
Must sit on side A (inferred). The faMesh normals, $\mathbf{u}_s$, $\sigma$ and $\kappa$ are used index by index on the patch without interpolation, which is only valid on the side that owns the faMesh.
Partner must be jump-derived. The neighbour U patch field is refCast to genericRegionCoupledJump<vector>; any other type aborts.
Exact mu == rho*nu check for regions with pKin. Rounding in the input values can trigger the fatal error.
diffusivity and neighbourFieldName are ignored.
Relaxation history starts from the patch value (inferred). The base class initialises the acceleration model with the patch values but relaxes the gradient. With relax 1 (the default, used in all tutorials) this has no effect.
gradient is not written to the time directories.
No runnable tutorial. The tutorials use the disabled interTrackFluid.

Tutorials

Tutorial	Description
`tutorials/multiphaseFlow/2dRisingBubble`	2D rising gas bubble, `interTrackFluid` + `interTrackFluid` (region type currently disabled)
`tutorials/multiphaseFlow/3dDuineveldRisingBubble`	3D rising bubble (Duineveld), same setup
`tutorials/multiphaseFlow/3dOscillatingBubble`	3D oscillating bubble, same setup

The BC is set in the 0/fluidA/orig/partitioned/U variant of each tutorial.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: regionCoupledVelocityValue

Mon, 01 Jan 0001 00:00:00 +0000

Overview

regionCoupledVelocityValue is the Dirichlet (jump) half of the partitioned velocity coupling across a sharp, mesh-tracked fluid-fluid interface. It acts on a volVectorField (the velocity U) and derives from genericRegionCoupledJump<vector>, i.e. from fixedValue. The patch value is the neighbour velocity, interpolated onto this patch, with its normal component replaced by the normal velocity of the local mesh. The tangential velocity is therefore continuous. The partner condition on the other side is regionCoupledVelocityFlux. Both belong to capillaryInterface, and this BC aborts if the first entry of its interfaceType list is not capillaryInterface. The pressure is coupled by regionCoupledPressureValue and regionCoupledPressureFlux in the same pUPimple DNA loop.

Mathematical Formulation

Region $A$ is the first entry of coupledPatchPair and carries the finite-area mesh of the capillaryInterface. This BC sits on side $B$ (see Known Limitations). $\mathcal{I}_{A\to B}$ is the patch-to-patch interpolation (interfaceTransferMethod), $\mathbf{n}_B$ the outward unit normal of the local patch.

$$ \mathbf{U}_B^{*} = \mathcal{I}_{A\to B}(\mathbf{U}_A) - \mathbf{n}_B\left(\mathbf{n}_B\cdot\mathcal{I}_{A\to B}(\mathbf{u}_s)\right) + \mathbf{n}_B\,\frac{\phi_{\text{mesh},B}}{|\mathbf{S}_f|} \quad \text{on } \Gamma_B $$

$\mathbf{U}_B^{*}$ is then passed through the acceleration model:

$$ \mathbf{U}_B^{k} = \mathbf{U}_B^{k-1} + \omega\left(\mathbf{U}_B^{*} - \mathbf{U}_B^{k-1}\right) $$

with $\omega$ = relax (fixed), the Aitken factor (aitken), or an IQN-ILS update (IQNILS).

The surface velocity $\mathbf{u}_s$ of the capillaryInterface is $\mathbf{U}_A - (\mathbf{U}_A\cdot\mathbf{n}_A)\mathbf{n}_A + w_A\mathbf{n}_A$, where $w_A$ is the side-A mesh normal velocity. The term $-\mathbf{n}_B(\mathbf{n}_B\cdot\mathbf{u}_s)$ therefore removes the normal part of $\mathbf{U}_A$ up to the side-A mesh motion. The last term imposes the side-B mesh normal velocity.

The diffusive momentum flux handed to regionCoupledVelocityFlux is

$$ \mathbf{F}_B = \mu_B\,(\mathbf{I}-\mathbf{n}_B\mathbf{n}_B)\cdot\frac{\partial\mathbf{U}_B}{\partial n}, \qquad \frac{\partial\mathbf{U}_B}{\partial n} = \Delta_f\left(\mathbf{U}_B - \mathbf{U}_P - \mathbf{k}\cdot\nabla\mathbf{U}_P\right) $$

The non-orthogonal term $\mathbf{k}\cdot\nabla\mathbf{U}_P$ is only present with nonOrthCorr yes. With secondOrder yes the gradient is $2\Delta_f(\mathbf{U}_B - \mathbf{U}_P - \mathbf{k}\cdot\nabla\mathbf{U}_P) - \mathbf{n}_B\cdot\nabla\mathbf{U}_P$. In both cases the normal component is removed.

Symbol	Description	Unit
$\mathbf{U}$	Velocity	m/s
$\mathbf{u}_s$	Surface velocity of the `capillaryInterface` (`Us()`, on side A)	m/s
$\phi_{\text{mesh},B}$	Boundary value of `fvc::meshPhi(rho, U)` if a `volScalarField rho` is registered in region B, otherwise `fvc::meshPhi(U)`	m³/s
$\mathbf{S}_f$	Face area vector of the local patch	m²
$\mu_B$	Diffusivity `mu` of region B (field or `transportProperties`)	Pa·s
$\Delta_f$	Patch `deltaCoeffs`	1/m
$\mathbf{k}$	Non-orthogonal part of the face-to-cell vector, $\mathbf{d}-\mathbf{n}(\mathbf{n}\cdot\mathbf{d})$	m
$\omega$	Relaxation factor from the acceleration model	–

Implementation

updateCoeffs() is the generic one of genericRegionCoupledJump. Each call:

Returns immediately if the patch is already updated or the interface has coupled no. In that case the patch keeps its last value.
Calls update() on the interface named first in interfaceType. For capillaryInterface this refreshes the curvature and the surface velocity $\mathbf{u}_s$ (correct()).
Looks up the neighbour field with the local field name (U), interpolates its patch values onto this patch and adds valueJump(). valueJump() returns $-\mathbf{n}_B(\mathbf{n}_B\cdot\mathcal{I}_{A\to B}(\mathbf{u}_s)) + \mathbf{n}_B\,\phi_{\text{mesh},B}/|\mathbf{S}_f|$.
Assigns the result, relaxes it with the acceleration model and calls fixedValue::updateCoeffs().

The matrix coefficients come from the vector specialisations in genericRegionCoupledJump. gradientInternalCoeffs() is the fixedValue one ($-\Delta_f$). gradientBoundaryCoeffs() subtracts the normal part of the current face gradient explicitly, using the current cell values. At convergence only the tangential gradient enters the viscous term of the momentum equation. snGrad() drops the normal part in the same way. If a volTensorField named grad(U) is registered, it is used for the non-orthogonal and second-order terms; otherwise fvc::grad(U) is computed on every call.

flux() returns snGrad()*k. k comes from diffCoeff() with the hardcoded diffusivity name mu: the patch values of a registered volScalarField mu, otherwise the scalar mu from the region’s registered transportProperties dictionary.

The DNA loop for pUPimple (multiRegionSystem::solve()) runs solvePIMPLE() on all regions, in which this BC is evaluated, then meshMotionCorrector() and interfaces_->update(). The jump residual for U is taken from this BC, because the side-A U patch carries a flux BC:

$$ r = \frac{\lVert \mathbf{U}_B - \mathcal{I}_{A\to B}(\mathbf{U}_A) - \text{valueJump}\rVert_2} {\max\left(\min\left(\lVert\mathbf{U}_B\rVert_2,\ \lVert\mathcal{I}_{A\to B}(\mathbf{U}_A)+\text{valueJump}\rVert_2\right),\ \text{SMALL}\right)} $$

The class also defines updatePhi(), which would overwrite the boundary phi with the negated interpolated neighbour flux. The call in the base class is commented out, so it is never executed.

correctClosedVolumePhi() (used by icoFluid and interTrackFluid when closedVolume is on in fvSolution) looks for the patch carrying this BC (or regionCoupledMassTransferVelocityValue). It sets phi = U·Sf there and removes the net flux, weighted by $|\phi|$, so the net volume flux through the interface is zero.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`regionCoupledVelocityValue`	yes	—
`interfaceType`	List of interface type names. The first entry is the interface this BC belongs to and must be `capillaryInterface`. The neighbour region and patch are taken from the matching interface entry in `regionInterfaceProperties`	yes	—
`value`	Initial patch value. Read if present. If missing, the patch values are not initialised	in practice yes	—
`diffusivity`	Read, but ignored: the BC always uses `mu`	no	empty
`neighbourFieldName`	Read by the coupling manager. Not used by this BC, which looks up the neighbour field by the local name	no	local field name
`jumpCoefficient`	Read by the base class, not used, not written back	no	empty
`accType`	Acceleration model: `fixed`, `aitken` or `IQNILS`. A warning is printed if missing	no	`fixed`
`relax`	(Initial) relaxation factor	no	`1.0`
`couplingReuse`	`IQNILS` only: number of previous time steps whose coupling data are reused	no	`0`
`nonOrthCorr`	Non-orthogonal correction in `snGrad()` / matrix coefficients	no	`false`
`secondOrder`	Second-order face-normal gradient	no	`false`

write() writes interfaceType, the resolved neighbourFieldName, diffusivity mu, accType, relax (and couplingReuse for IQNILS), nonOrthCorr, secondOrder and value.

Usage

tutorials/multiphaseFlow/2dRisingBubble/0/fluidB/orig/partitioned/U (side B):

interfaceShadow
{
 type regionCoupledVelocityValue;
 diffusivity "mu"; // ignored, always mu
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0);
}

Partner on side A, 0/fluidA/orig/partitioned/U:

interface
{
 type regionCoupledVelocityFlux;
 diffusivity "mu";
 interfaceType (capillaryInterface);
 secondOrder false;
 nonOrthCorr false;
 value uniform (0 0 0);
}

constant/regionInterfaceProperties:

partitionedCoupledPatches
(
 fluidAfluidB
 {
 interfaceType (capillaryInterface);

 coupledPatchPair
 (
 (fluidA interface) // side A: faMesh, VelocityFlux, PressureValue
 (fluidB interfaceShadow) // side B: VelocityValue, PressureFlux
 );

 coupledFields
 (
 pUPimple
 );

 capillaryInterfaceCoeffs
 {
 sigma sigma [ 1 0 -2 0 0 0 0 ] 0.07232;
 }
 }
);

constant/multiRegionProperties (U and p must exist in both regions):

DNA
{
 pUPimple
 {
 maxCoupleIter 10;

 residualControl
 {
 U { maxJumpRes 1e-5; maxFluxRes 1e-4; }
 p { maxJumpRes 1e-5; maxFluxRes 1e-5; }
 }
 }
}

Known Limitations

capillaryInterface only. capInterface() aborts if the first interfaceType entry is not capillaryInterface.
Must sit on side B (inferred). $\mathbf{u}_s$ lives on the side-A finite-area mesh and is interpolated “from the neighbour”. On side A, the side-A field would be mapped as if it belonged to side B.
diffusivity is ignored. diffusivityName() is hardcoded to mu.
neighbourFieldName has no effect. The neighbour velocity is looked up by the local field name.
value should be given. The base class reads it only if present and does not initialise the patch otherwise.
updatePhi() is dead code, so the boundary phi is not set from the neighbour by this BC.
The header example omits interfaceType, which is required.
No runnable tutorial. All tutorials that use this BC run on interTrackFluid, which is commented out in src/multiRegionSystem/Make/files.
Partitioned only. There is no monolithic variant.

Tutorials

Tutorial	Description
`tutorials/multiphaseFlow/2dRisingBubble`	2D rising gas bubble, `interTrackFluid` + `interTrackFluid` (region type currently disabled)
`tutorials/multiphaseFlow/3dDuineveldRisingBubble`	3D rising bubble (Duineveld), same setup
`tutorials/multiphaseFlow/3dOscillatingBubble`	3D oscillating bubble, same setup

The BC is set in the 0/fluidB/orig/partitioned/U variant of each tutorial.

References

Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: solidSymmetry

Mon, 01 Jan 0001 00:00:00 +0000

Overview

solidSymmetry is a symmetry-plane condition ported from the foam-extend solid-mechanics toolbox (Cardiff, Tuković), where it is also known as symmetryDisplacement. It exists for two field types, both registered under the same type name:

solidSymmetryFvPatchVectorField, intended for the total displacement D of a solid region (solidStVK). It mirrors the near-wall displacement across the plane, so the normal displacement on the patch is zero and the tangential displacement is free. An optional second-order correction is available.
solidSymmetryFvPatchScalarField, the scalar counterpart. It sets the patch value to the corrected near-wall value (zero normal gradient).

Both classes derive from the stock symmetry constraint (symmetryFvPatchField). They only replace snGrad() and evaluate(), so the patch must be of mesh type symmetry. The class keeps the matrix coefficients (implicit part) of the stock condition.

Mathematical Formulation

Let $\mathbf{n}$ be the patch unit normal, $\boldsymbol{\Delta}$ the patch delta vector (face centre minus cell centre), $\delta = 1/\texttt{deltaCoeffs}$ the cell-to-face distance, and $\mathbf{R} = \mathbf{I} - 2\,\mathbf{n}\mathbf{n}$ the reflection tensor. The non-orthogonal correction vector and the corrected near-wall value are

$$ \mathbf{k} = (\mathbf{I} - \mathbf{n}\mathbf{n}) \cdot \boldsymbol{\Delta}, \qquad \mathbf{D}_P^{*} = \mathbf{D}_P + \mathbf{k} \cdot (\nabla \mathbf{D})_P $$

Vector field, first order (default)

$$ \mathbf{D}_b = \tfrac{1}{2}\left(\mathbf{D}_P^{*} + \mathbf{R}\,\mathbf{D}_P^{*}\right) = (\mathbf{I} - \mathbf{n}\mathbf{n})\,\mathbf{D}_P^{*}, \qquad \left.\frac{\partial \mathbf{D}}{\partial n}\right|_b = \frac{\mathbf{R}\,\mathbf{D}_P^{*} - \mathbf{D}_P^{*}}{2\,\delta} = -\frac{(\mathbf{n}\cdot\mathbf{D}_P^{*})\,\mathbf{n}}{\delta} $$

Vector field, second order (`secondOrder yes`)

$$ \mathbf{D}_b = (\mathbf{I} - \mathbf{n}\mathbf{n}) \cdot \left( \mathbf{D}_P^{*} + \tfrac{\delta}{2}\, \mathbf{n}\cdot(\nabla\mathbf{D})_P \right) $$ $$ \left.\frac{\partial \mathbf{D}}{\partial n}\right|_b = -\frac{2\,(\mathbf{n}\cdot\mathbf{D}_P^{*})\,\mathbf{n}}{\delta} - \mathbf{n}\left(\mathbf{n} \cdot \left[\mathbf{n}\cdot(\nabla\mathbf{D})_P\right]\right) $$

The tangential part of the value is extrapolated over half a cell with the mean of the zero face gradient and the cell gradient. The normal part of the gradient is the one-sided second-order estimate $2(\mathbf{D}_b - \mathbf{D}_P)\cdot\mathbf{n}/\delta - (\partial_n D_n)_P$.

Scalar field

A scalar is invariant under reflection, so $\mathbf{R}\,T = T$ and the formulas above reduce to

$$ T_b = T_P + \mathbf{k}\cdot(\nabla T)_P, \qquad \left.\frac{\partial T}{\partial n}\right|_b = 0 $$

Symbol	Description	Unit
$\mathbf{D}$, $T$	Patch field (vector / scalar)	field unit
$\mathbf{n}$	Patch unit normal (`patch().nf()`)	–
$\boldsymbol{\Delta}$	Patch delta vector (`patch().delta()`)	m
$\delta$	$1/$`patch().deltaCoeffs()`	m
$\mathbf{k}$	Non-orthogonal correction vector	m
$(\nabla\mathbf{D})_P$	Cell-centre gradient from the registered field `gradD`	field unit/m
$(\nabla T)_P$	Cell-centre gradient from the registered field `grad(<field>)`	field unit/m

Note on OpenFOAM.com. In OpenFOAM.com (v2512 and v2606), fvPatch::delta() returns the patch-normal delta $\mathbf{n}(\mathbf{n}\cdot(\mathbf{C}_f-\mathbf{C}_P))$ for all non-coupled patches. Then $\mathbf{k} \equiv \mathbf{0}$, $\mathbf{D}_P^{*} = \mathbf{D}_P$, and the non-orthogonal correction does nothing. It was written for foam-extend, where delta() is the full $\mathbf{C}_f - \mathbf{C}_P$. With the default first-order setting, the vector condition therefore gives exactly the values and normal gradient of the stock symmetry condition. The scalar condition is equivalent to stock symmetry / zeroGradient for scalars.

Implementation

Construction. The dictionary constructor calls the stock symmetry constructor. That constructor ignores value and evaluates the field once with the stock symmetry formula. The constructor then checks that the patch is exactly a symmetryFvPatch (isType). Any other patch type, including symmetryPlane, stops the run with a FatalIOError. The vector version reads the optional secondOrder switch and prints it. Both versions print “Symmetry boundary condition with non-orthogonal correction”.

evaluate() (called from correctBoundaryConditions()):

Calls updateCoeffs() if needed. This is the base no-op.
Looks up the cell gradient on the patch.
- Vector: the volTensorField named gradD, whatever the name of the field the BC is attached to.
- Scalar: the volVectorField named grad(<fieldName>), e.g. grad(T).
The lookup is mandatory. If the field is not registered on the mesh, the run stops with a fatal error.
Builds $\mathbf{D}_P^{*}$ and assigns the patch value with the formula above.
Vector only: calls the base evaluate(), which resets the updated flag. The scalar version does not call it.

snGrad() returns the normal gradient above. It is used wherever the patch gradient is requested explicitly. The matrix coefficients are inherited from the stock transform/basicSymmetry implementation: for vectors the implicit diagonal is $|n_i|$ per component. Because gradientBoundaryCoeffs() is snGrad() - gradientInternalCoeffs()·D_P, the overridden snGrad() (including the second-order term) enters fvm::laplacian as an explicit source. For scalars, the inherited coefficients are those of a zero-gradient condition.

In solidStVK. The momentum equation uses fvm::laplacian(impKf, D, "laplacian(DD,D)"), which picks up the coefficients above. gradD = fvc::grad(D) is recomputed in postSolve() from the patch values set in evaluate(). solidStVK registers gradD, so the vector BC works on its D field. It also works on any other vector field of that region, but it always uses gradD.

Dictionary Entries

Vector version:

Keyword	Description	Required	Default
`type`	`solidSymmetry`	yes	–
`secondOrder`	Second-order correction of value and normal gradient (`Switch`)	no	`false`
`patchType`	Generic `fvPatchField` keyword, read by the stock base class	no	–
`value`	Not read. The initial value comes from the stock symmetry evaluation. Written on output.	no	–

Scalar version:

Keyword	Description	Required	Default
`type`	`solidSymmetry`	yes	–
`patchType`	Generic `fvPatchField` keyword	no	–
`value`	Not read (see above). Written on output.	no	–

The scalar version does not read secondOrder.

Required registered fields:

Field	Type	Needed by	Provided by
`gradD`	`volTensorField`	vector version	`solidStVK`
`grad(<fieldName>)`	`volVectorField`	scalar version	no shipped region type

Usage

The mesh patch must be of type symmetry (e.g. symmetry symmetry (...) in blockMeshDict). From tutorials/fluidStructureInteraction/beamInCrossFlow/0/solid/orig/partitioned/D:

symmetry
{
 type solidSymmetry;
 patchType symmetry;
 value uniform (0 0 0);
}

With the second-order correction:

symmetry
{
 type solidSymmetry;
 secondOrder yes;
 value uniform (0 0 0);
}

For other fields of the solid region on the same patch, the tutorials use the stock condition (e.g. T in heatedBeamInCrossFlow: type symmetry;).

Known Limitations

Non-orthogonal correction has no effect in OpenFOAM.com. The patch delta is patch-normal, so $\mathbf{k} = \mathbf{0}$ (see the note above). With secondOrder no, the vector BC is numerically identical to stock symmetry. It still needs gradD.
Hard-coded gradient name (vector). The vector version always reads gradD. It is only usable in a region that registers a volTensorField named gradD, i.e. solidStVK.
Scalar version needs grad(<field>). No compiled region type registers a volVectorField with that name. Unless something else in the case provides it, the scalar BC fails on its first evaluation. Because it is equivalent to the stock condition in OpenFOAM.com, use symmetry for scalar fields instead.
Patch type symmetry only. symmetryPlane and other patch types are rejected.
value is ignored on read. The initial patch value is always the stock symmetry evaluation of the internal field.

Tutorials

Tutorial	Description
`tutorials/fluidStructureInteraction/beamInCrossFlow`	`D` of the `solidStVK` solid on the `symmetry` patch (first order).
`tutorials/fluidStructureInteraction/heatedBeamInCrossFlow`	Same `D` setup in a thermo-FSI case. `T` on the same patch uses stock `symmetry`.

No tutorial uses the scalar version or secondOrder yes.

References

Cardiff, P., Karač, A., De Jaeger, P., Jasak, H., Nagy, J., Ivanković, A., Tuković, Ž., An open-source finite volume toolbox for solid mechanics and fluid-solid interaction simulations, arXiv:1808.10736, 2018.
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: solidTraction

Mon, 01 Jan 0001 00:00:00 +0000

Overview

solidTraction imposes a known surface traction $\mathbf{t}$ and/or normal pressure $p$ on the displacement field D of a solid region. It is the uncoupled counterpart of the FSI traction BC: use it for loaded or traction-free solid surfaces that are not coupled to another region. The class derives from fixedGradient (vector only). In each update it recomputes the displacement normal gradient so that the stress on the patch matches the prescribed load. The traction and the pressure can each be given as a constant field, as a time series, or as a separate volume field. It was ported from the foam-extend solid-mechanics toolbox (Cardiff, Tuković). It reads the fields of solidStVK (impK, rImpK, gradD, sigma, Finv).

Mathematical Formulation

The target condition is a traction balance in the current (deformed) configuration:

$$ \mathbf{n}_c \cdot \boldsymbol{\sigma} = \mathbf{t} - p\,\mathbf{n}_c \quad \text{on } \partial\Omega_t, \qquad \mathbf{n}_c = \frac{\mathbf{F}^{-T}\cdot\mathbf{n}_0}{\lvert \mathbf{F}^{-T}\cdot\mathbf{n}_0 \rvert} $$

It is imposed through the normal gradient of D, in the segregated “implicit stiffness” form used by solidStVK:

$$ \mathbf{g}^{\,new} = \frac{1}{K}\left[ \left(\mathbf{t} - p\,\mathbf{n}_c\right) - \mathbf{n}_c\cdot\boldsymbol{\sigma} + K\, \mathbf{n}_0\cdot\nabla\mathbf{D} \right], \qquad \mathbf{g} \leftarrow \omega\,\mathbf{g}^{\,new} + (1-\omega)\,\mathbf{g}^{\,old} $$

$\boldsymbol{\sigma}$ and $\nabla\mathbf{D}$ are the current patch values. When the iteration has converged, $\mathbf{g} = \mathbf{n}_0\cdot\nabla\mathbf{D}$, so the bracket requires $\mathbf{n}_c\cdot\boldsymbol{\sigma} = \mathbf{t} - p\,\mathbf{n}_c$. The $K\,\mathbf{n}_0\cdot\nabla\mathbf{D}$ term mirrors the implicit/explicit Laplacian pair in the solidStVK momentum equation.

The patch value is then reconstructed from the gradient:

$$ \mathbf{D}_b = \begin{cases} \mathbf{D}_P + \mathbf{k}\cdot(\nabla\mathbf{D})_P + \delta\,\mathbf{g} & \text{first order} \\[1ex] \mathbf{D}_P + \mathbf{k}\cdot(\nabla\mathbf{D})_P + \tfrac{\delta}{2}\left(\mathbf{g} + \mathbf{n}_0\cdot(\nabla\mathbf{D})_P\right) & \texttt{secondOrder yes} \end{cases} $$

with $\mathbf{k} = (\mathbf{I}-\mathbf{n}_0\mathbf{n}_0)\cdot\boldsymbol{\Delta}$.

Symbol	Description	Unit
$\mathbf{D}$	Total displacement (patch field)	m
$\mathbf{t}$	Prescribed traction (`traction`, `tractionSeries` or `tractionField`)	Pa
$p$	Prescribed pressure, positive = compressive (`pressure`, `pressureSeries` or `pressureField`)	Pa
$\mathbf{n}_0$	Patch unit normal of the undeformed mesh	–
$\mathbf{n}_c$	Deformed unit normal from `Finv`	–
$\boldsymbol{\sigma}$	Cauchy stress, patch values of `sigma`	Pa
$\mathbf{F}^{-1}$	Inverse deformation gradient, patch values of `Finv`	–
$K$	Implicit stiffness, patch values of `impK` ($1/K$ from `rImpK`)	Pa
$\mathbf{g}$	Patch normal gradient (`gradient`)	–
$\omega$	`relaxationFactor`	–
$\delta$	$1/$`patch().deltaCoeffs()`	m
$\boldsymbol{\Delta}$, $\mathbf{k}$	Patch delta vector and non-orthogonal correction vector	m

Note on OpenFOAM.com. In OpenFOAM.com, fvPatch::delta() is patch-normal for non-coupled patches, so $\mathbf{k} \equiv \mathbf{0}$ and the non-orthogonal term in $\mathbf{D}_b$ has no effect.

Implementation

Construction. The dictionary constructor reads secondOrder, setEffectiveTraction and relaxationFactor. It reads gradient and value if present, otherwise it starts from zero gradient and the patch-internal value. It then sets up the traction and the pressure. For each, exactly one of three forms is allowed. Giving two forms of the same quantity stops the run (FatalError):

Traction	Pressure	Behaviour
`traction`	`pressure`	Patch field (`uniform` or `nonuniform`), constant in time
`tractionSeries {...}`	`pressureSeries {...}`	`interpolationTable` sub-dictionary, interpolated at `time().timeOutputValue()`. The value is uniform over the patch.
`tractionField <name>`	`pressureField <name>`	A `volVectorField` / `volScalarField` with that name is constructed by the BC (`MUST_READ` from the time directory, `AUTO_WRITE`), and its boundary values on this patch are used

If neither a series nor a field is given, traction and pressure are read as plain patch fields, so both are required.

updateCoeffs() (skipped if already updated in this evaluation):

Once per time step (tracked through curTimeIndex_), calls correctBoundaryConditions() on the tractionField / pressureField, if one is used.
Updates $\mathbf{t}$ and $p$ from the field or the series.
If setEffectiveTraction is on, subtracts the patch values of a volScalarField named p from the pressure. This applies the effective rather than the total traction, which is meant for poro-elastic solids.
Looks up impK, rImpK, gradD, sigma and Finv on the patch. All are mandatory.
Computes $\mathbf{n}_c$ and the relaxed gradient $\mathbf{g}$ above, then calls fixedGradient::updateCoeffs().

evaluate() calls updateCoeffs() if needed. It looks up the cell gradient field named grad<fieldName> (i.e. gradD for D), sets $\mathbf{D}_b$ by the formula above and resets the updated flag. The matrix coefficients are those of the stock fixedGradient condition: the gradient $\mathbf{g}$ enters the Laplacian as an explicit flux.

Interaction with solidStVK. D boundary conditions are updated when the momentum equation for D is assembled. sigma, gradD and Finv come from the previous Picard / DNA iteration (updated in solidStVK::postSolve()), so the traction is enforced iteratively. It converges together with the PICARD loop on D. The relaxationFactor gives extra under-relaxation of the gradient if this loop oscillates.

write() writes the form actually used for traction and pressure (tractionField/tractionSeries/traction, and likewise for pressure), then secondOrder, setEffectiveTraction, relaxationFactor, value and gradient.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`solidTraction`	yes	–
`traction`	Traction patch field (vector)	yes, unless `tractionSeries` or `tractionField` is given	–
`tractionSeries`	`interpolationTable<vector>` sub-dictionary (`file`, optional `outOfBounds`, `readerType`)	alternative to `traction`	–
`tractionField`	Name of a `volVectorField` to read from the time directory	alternative to `traction`	–
`pressure`	Pressure patch field (scalar, positive = compressive)	yes, unless `pressureSeries` or `pressureField` is given	–
`pressureSeries`	`interpolationTable<scalar>` sub-dictionary	alternative to `pressure`	–
`pressureField`	Name of a `volScalarField` to read from the time directory	alternative to `pressure`	–
`secondOrder`	Second-order reconstruction of the patch value	no	`false`
`setEffectiveTraction`	Subtract the region’s `p` field from the pressure	no	`false`
`relaxationFactor`	Under-relaxation $\omega$ of the gradient	no	`1.0`
`gradient`	Initial normal gradient	no	zero
`value`	Initial patch value	no	patch-internal value

In the series sub-dictionary, outOfBounds defaults to warn and readerType to openFoam. Both are standard OpenFOAM interpolationTable keywords.

Required registered fields on the solid mesh:

Field	Type	Provided by
`impK`, `rImpK`	`volScalarField`	`solidStVK`
`gradD`	`volTensorField`	`solidStVK`
`sigma`	`volSymmTensorField`	`solidStVK`
`Finv`	`volTensorField`	`solidStVK`
`grad<fieldName>`	`volTensorField`	`solidStVK` (`gradD`, when the BC is on `D`)
`p`	`volScalarField`	only with `setEffectiveTraction yes`; no shipped solid region type provides it

Usage

Traction-free surface (0/<solid>/D):

freeSurface
{
 type solidTraction;
 traction uniform (0 0 0);
 pressure uniform 0;
 value uniform (0 0 0);
}

Uniform pressure ramped in time from a table file:

loadedSurface
{
 type solidTraction;
 traction uniform (0 0 0);
 pressureSeries
 {
 file "$FOAM_CASE/constant/solid/pressureSeries";
 outOfBounds clamp;
 }
 relaxationFactor 0.8;
 value uniform (0 0 0);
}

with constant/solid/pressureSeries in the openFoam table format, e.g. ( (0 0) (1 1e4) ).

Known Limitations

Only for solidStVK. The fields impK, rImpK, gradD, sigma and Finv are looked up unconditionally. No other compiled region type provides all of them.
Field and series data are uniform or per face only. tractionSeries / pressureSeries give a value that is uniform over the patch. traction / pressure are constant in time. For space- and time-varying loads, use tractionField / pressureField and drive that field’s own boundary conditions (they are corrected once per time step).
setEffectiveTraction needs a p field on the solid mesh. No shipped solid region type registers one.
Non-orthogonal correction has no effect in OpenFOAM.com (patch-normal delta(); see the note above).
Copies lose the field link. The mapping and copy constructors do not copy tractionFieldPtr_ / pressureFieldPtr_. A cloned patch field (e.g. a stored old-time or previous-iteration copy) keeps the last traction/pressure values and stops following the field. The original boundary condition of D is not affected.
Inconsistent gradient names. updateCoeffs() always reads gradD, while evaluate() reads grad<fieldName>. On a field other than D the two differ.

Tutorials

No tutorial uses solidTraction. The FSI tutorials use regionCoupledTraction on the coupled solid surface and fixedValue / solidSymmetry elsewhere.

References

Cardiff, P., Karač, A., De Jaeger, P., Jasak, H., Nagy, J., Ivanković, A., Tuković, Ž., An open-source finite volume toolbox for solid mechanics and fluid-solid interaction simulations, arXiv:1808.10736, 2018.
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

Docs: zeroGradientCorrected

Mon, 01 Jan 0001 00:00:00 +0000

Overview

zeroGradientCorrected is a zero-gradient condition for fields of any type (scalar, vector, sphericalTensor, symmTensor, tensor). Instead of copying the near-wall cell value, it sets the patch value to the cell value plus a non-orthogonal correction $\mathbf{c}\cdot\nabla\phi_P$, evaluated on a small sub-mesh around the patch. The same correction enters the matrix through valueBoundaryCoeffs. It comes from the foam-extend interface-tracking solver (interTrackFoam, Tuković). The BC is compiled into libinterfaceTrackingFvMesh. It derives from the common base correctedFvPatchField (type corrected). The base class, the sub-mesh machinery, the corrected type and the porting status (interTrackFluid disabled, patchCorrected snGrad not ported) are described on the fixedValueCorrected page.

Mathematical Formulation

$$ \left.\frac{\partial\phi}{\partial n}\right|_b = 0 \quad \text{on } \partial\Omega, \qquad \phi_b = \phi_P + \phi_c, \qquad \phi_c = \mathbf{c}\cdot(\nabla\phi)_P, \quad \mathbf{c} = \boldsymbol{\Delta} - \mathbf{n}\,(\mathbf{n}\cdot\boldsymbol{\Delta}) $$

Matrix coefficients:

Coefficient	Value
`valueInternalCoeffs`	$1$
`valueBoundaryCoeffs`	$\phi_c$
`gradientInternalCoeffs`	$0$
`gradientBoundaryCoeffs`	$0$
`snGrad()`	$0$

Symbol	Description	Unit
$\phi$	Patch field	field unit
$\mathbf{n}$	Patch unit normal	–
$\boldsymbol{\Delta}$	Patch delta vector (`patch().delta()`)	m
$\mathbf{c}$	Correction vector	m
$\phi_c$	Stored correction (`corrVecGrad`), updated in `updateCoeffs()`	field unit

Implementation

Construction: the base class reads volFieldName (required) and the optional corrVecGrad. The patch value is set to $\phi_P + \phi_c$. value is not read.
updateCoeffs() (base class): recomputes $\mathbf{c}$ if the mesh moves, rebuilds $\phi_c$ on the patch sub-mesh (gradient scheme snGradCorr(<volFieldName>)). It is called whenever an fvMatrix for the field is constructed, so valueBoundaryCoeffs uses the current $\phi_c$.
evaluate(): declared without the Pstream::commsTypes argument. It does not override fvPatchField::evaluate(const Pstream::commsTypes), which correctBoundaryConditions() calls. The base version runs, and it only resets the updated flag. The patch value is not recomputed after a solve. It stays at the construction value $\phi_P + \phi_c$ of the initial field, so it does not behave like a zero-gradient value at all.
Mapping: autoMap/rmap map the value only.
Sub-mesh motion: interfaceTrackingFvMesh::update() moves the sub-mesh only for U and p.
write(): type, volFieldName, corrVecGrad. No value is written.

Dictionary Entries

Keyword	Description	Required	Default
`type`	`zeroGradientCorrected`	yes	–
`volFieldName`	Name of the volume field this patch field belongs to	yes	– (no default)
`corrVecGrad`	Initial stored correction $\phi_c$	no	zero

The library must be loaded with libs ("libinterfaceTrackingFvMesh.so"); in system/controlDict.

Usage

outlet
{
 type zeroGradientCorrected;
 volFieldName U;
}

Known Limitations

Patch value frozen at its initial value, because the evaluate() signature does not match (see Implementation). Explicit operators that use patch values (fvc::grad, fvc::interpolate, face fluxes) see the initial value.
No correction in OpenFOAM.com (patch-normal delta()). The cost of the sub-mesh gradient remains on every updateCoeffs().
Interface-tracking context not available: interTrackFluid is disabled and patchCorrected is not ported (see fixedValueCorrected).
volFieldName has no default and must match the field name.
Sub-mesh motion only for U and p.

In practice, use the stock zeroGradient instead.

Tutorials

No tutorial uses zeroGradientCorrected.

References

Tuković, Ž., Jasak, H., A moving mesh finite volume interface tracking method for surface tension dominated interfacial fluid flow, Computers & Fluids 55, 2012. DOI: 10.1016/j.compfluid.2011.11.003
Alkfri, A., Habes, C., Marschall, H., multiRegionFoam: A Unified Multiphysics Framework for Multi-Region Coupled Continuum-Physical Problems, Engineering with Computers, 2023. DOI: 10.1007/s00366-024-01974-4

multiPhysicsFoam – Boundary-Condition

Docs: fixedGradientCorrected

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: fixedValueCorrected

Overview

Mathematical Formulation

Implementation

The corrected type

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: genericRegionCoupledFlux

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: genericRegionCoupledJump

Overview

Mathematical Formulation

Implementation

Acceleration models

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: paraboloidInletVelocity

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: regionCoupledHeatFlux

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: regionCoupledMassTransferPressureValue

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: regionCoupledMassTransferVelocityFlux

Overview

Mathematical Formulation

Implementation

Dictionary Entries

Usage

Known Limitations

Tutorials

References

Docs: regionCoupledMassTransferVelocityValue

Overview

Mathematical Formulation

Implementation

Dictionary Entries

The `corrected` type