multiPhysicsFoam – Generic

Docs: defaultInterface

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

Overview

defaultInterface is the generic interface type. It adds no interface physics of its own: correct() is a no-op, getMinDeltaT() returns GREAT and info() prints nothing. All of its behaviour comes from the base class regionInterfaceType, which every interface type inherits: it pairs two patches of two regions, builds the patch-to-patch mapping and provides the residuals for the DNA (partitioned) coupling loop. The coupling conditions themselves are set by the boundary conditions on the two patches.

With the generic regionCoupledScalarJump / regionCoupledScalarFlux boundary conditions, defaultInterface couples a scalar quantity that is continuous (or continuous up to a constant partition coefficient) and whose diffusive flux is conserved across the interface. Examples are temperature and electric potential across a perfectly conducting contact, as between an NTGK battery region and its conductPotentialTemperature current-collector tabs.

This page also documents the base-class behaviour (interface naming, dictionary keywords, interface-to-interface mapping, generic coupled boundary conditions). It applies to every interface type unless the derived type overrides it.

Interface Conditions

The conditions are set by the boundary-condition pair, not by defaultInterface. One side of the interface carries a jump (Dirichlet) BC, side $J$, and the other side carries a flux (Neumann) BC, side $F$. Which region gets which BC does not depend on the patch order in coupledPatchPair. The tutorial uses different assignments for different fields.

Jump condition

regionCoupledScalarJump sets the patch value on side $J$ from the neighbour value, interpolated onto the side-$J$ faces:

$$ \phi_J = c \, \phi_F \quad \text{on } \Gamma $$

Internally this is $\phi_J = \phi_F + \Delta\phi$ with valueJump() $\Delta\phi = (c - 1)\,\phi_F$. If the jumpCoefficient keyword is not given, $c = 1$, which gives continuity.

Flux condition

regionCoupledScalarFlux sets the normal gradient on side $F$ so that the diffusive flux matches the flux computed on side $J$:

$$ \Gamma_F \nabla \phi_F \cdot \mathbf{n}_F + \Gamma_J \nabla \phi_J \cdot \mathbf{n}_J = 0 \quad \text{on } \Gamma $$

In code this is gradient() = (-flux_J + fluxJump())/k_F, where flux_J = k_J * snGrad(phi_J) is interpolated onto the side-$F$ faces. regionCoupledScalarFlux::fluxJump() returns zero.

Symbol	Keyword / field	Description	Unit
$\phi$	field listed in `coupledFields` (e.g. `T`, `phiPos`, `phiNeg`)	Coupled scalar field (same name in both regions)	field-dependent
$\Gamma_J$, $\Gamma_F$	`diffusivity` (BC keyword)	Diffusivity on each side	field-dependent
$c$	`jumpCoefficient` (jump-BC keyword)	Value-jump (partition) coefficient, default 1	—
$\mathbf{n}_J$, $\mathbf{n}_F$	—	Outward patch normals of each side	—

Interface residuals

The DNA loop (src/numerics/dnaSolutionControl) measures convergence with residuals computed by the BCs and collected by regionInterfaceType::normJumpRes / normFluxRes:

$$ r_\text{jump} = \frac{\lVert \phi_J - \phi_F - \Delta\phi \rVert_2} {\max\left(\min\left(\lVert \phi_J \rVert_2,\ \lVert \phi_F + \Delta\phi \rVert_2\right),\ \text{SMALL}\right)} $$ $$ r_\text{flux} = \frac{\lVert \Gamma_F \partial_n \phi_F + q_J \rVert_2} {\max\left(\min\left(\lVert \Gamma_F \partial_n \phi_F \rVert_2,\ \lVert q_J \rVert_2\right),\ \text{SMALL}\right)} $$

with $q_J = \Gamma_J \partial_n \phi_J$ interpolated onto side $F$, and with the neighbour quantity always interpolated onto the evaluating side. These are compared with maxJumpRes / maxFluxRes in multiRegionProperties. If the interface is not coupled (see coupled below), both residuals are 0.

Implementation

defaultInterface only implements the pure virtuals of regionInterfaceType (correct(), getMinDeltaT(), info()) as no-ops. Everything below is base-class behaviour.

Construction (regionInterfaceTypeList::reset): for each entry of partitionedCoupledPatches (and monolithicCoupledPatches) in constant/regionInterfaceProperties, the two patches of coupledPatchPair are looked up. One interface object is created per entry of the interfaceType list, all on the same patch pair. The first pair entry becomes side A and the second becomes side B.
Naming: the interface name is <regionA><PatchA><RegionB><PatchB><InterfaceType>, where every part after the first is capitalised. For example, the tutorial gives batteryRegionToNegTabNegTabRegionToCellFromNegDefaultInterface. This name appears in the log and in the DNA residual output.
interfaceKey: the interface is also an interfaceKey, an unordered pair of words. Equality is symmetric ((a,b) == (b,a)) and the hash is the sum of the two word hashes. The interface object itself is keyed by the two patch names. The coupled-field tables of regionInterfaceTypeList are keyed by (<regionA><patchA>, <regionB><patchB>).
Global patches: on construction, a globalPolyPatch is built for each side. It is a copy of the patch reconstructed in full on every processor, which is what makes the mapping work in parallel. The mapping object is created at the same time (interfaceToInterface()), so that a directMap can read its maps on restart.
Field transfer: the BCs call interpolateFacesFromA/B (and the point variants). These convert the patch field to the global patch, transfer it with the selected interfaceToInterfaceMapping, and scatter it back to the local patch. Only scalar and vector fields have specialisations. Other types hit a notImplemented fallback.
Update per BC evaluation: every coupled BC calls regionInterfaceType::update() in its updateCoeffs(). This function rebuilds the global patches after a topology change (mesh changing but not moving), updates the finite-area curvature if an faMesh exists, then calls correct(), which is a no-op for defaultInterface.
Update per time step: multiRegionSystem::preSolve() calls regionInterfaceTypeList::update(). For interfaces whose mesh A is changing, this rebuilds the mapping and global patches at the frequency set by interpolatorUpdateFrequency (and always after a topology change), then calls info().
Time step: getMinDeltaT() returns GREAT, so defaultInterface never limits the time step.

Interface-to-interface mapping

The mapping is selected globally for all interfaces by the top-level keyword interfaceTransferMethod in regionInterfaceProperties. It is not set per interface entry. The default is AMI. The matching <method>Coeffs sub-dictionary is read with subDict, so it must exist even when it is empty. Neither AMI nor directMap reads any keyword from it.

Method	Class (`src/numerics/interfaceToInterfaceMappings`)	Behaviour
`AMI` (default)	`amiInterfaceToInterfaceMapping`	Wraps `amiZoneInterpolation` (face-area weighted, `requireMatch` on, `lowWeightCorrection -1`) on the global patches; non-conformal patches allowed. Prints the max face-centre mapping error (`interface-to-interface face error`) on construction.
`directMap`	`directMapInterfaceToInterfaceMapping`	One-to-one face/point map for conformal patches; fatal error if face or point counts differ. Faces/points are matched by centre/position within `0.001 * min edge length`. Maps (`zoneAToZoneBFaceMap_<patchA>_to_<patchB>`, …) are written to and re-read from the time directory.
`RBF`	`rbfInterfaceToInterfaceMapping`	Radial basis function interpolation. Disabled: commented out in `src/multiRegionSystem/Make/files` (needs Eigen), so not selectable.

Generic coupled boundary conditions

genericRegionCoupledJump<Type> (derived from fixedValue) and genericRegionCoupledFlux<Type> (derived from fixedGradient) are the base classes of all partitioned coupling BCs. Both are registered for scalar and vector, but their valueJump() / fluxJump() are notImplemented, so they cannot be used directly in a case. regionCoupledScalarJump / regionCoupledScalarFlux are the concrete scalar versions and the only coupled BCs that do not need a specific interface type. All other regionCoupled* BCs (regionCoupledTemperatureJump, regionCoupledVelocityValue, regionCoupledTraction, …) cast the interface to heatTransferInterface, capillaryInterface, fsiInterface, etc.

Behaviour shared by both generic BCs:

The owning interface is found from the BC’s interfaceType list (only the first entry is used) and the local region/patch name. It is a fatal error if no interface or more than one interface of that type contains the patch. The neighbour region and patch are taken from the matched interface.
The neighbour field is looked up under the same name as the local field.
If the interface is not coupled, updateCoeffs() returns early and the BC keeps its last value or gradient.
After the new value (jump side) or gradient (flux side) is set, it is relaxed by the BC’s acceleration model (src/numerics/acceleration).
diffCoeff() takes the diffusivity named by diffusivity from a volScalarField of that name in the local region if one exists. Otherwise it reads a dimensionedScalar of that name from the region’s transportProperties. For a field named pKin the diffusivity is forced to 1.
Snapping the gradient (snGrad, jump side) and evaluating the patch value (flux side) use the cell gradient (grad(<field>) if registered, otherwise fvc::grad) for the optional non-orthogonal (nonOrthCorr) and second-order (secondOrder) corrections.

Keyword	Side	Default	Description
`type`	both	—	`regionCoupledScalarJump` or `regionCoupledScalarFlux`
`interfaceType`	both	required	List of interface type names, e.g. `(defaultInterface)`; only the first is used
`diffusivity`	both	`word::null`	Name of the diffusivity (`volScalarField` or `transportProperties` entry). Effectively required: the flux side always needs it, and the jump side needs it to supply its flux to the flux side
`jumpCoefficient`	jump	`word::null` (→ $c = 1$)	Name of a `volScalarField` or `transportProperties` entry giving $c$
`neighbourFieldName`	both	local field name	Read and written, but not used by the generic jump/flux evaluation, which always uses the local field name
`accType`	both	`fixed`	Acceleration model: `fixed`, `aitken`, `IQNILS`
`relax`	both	`1.0`	(Initial) relaxation factor
`couplingReuse`	both	`0`	`IQNILS` only: number of previous time steps reused
`nonOrthCorr`	both	`false`	Non-orthogonal correction
`secondOrder`	both	`false`	Second-order patch gradient / value
`value`	both	read if present	Initial patch value
`gradient`	flux	read if present	Initial patch gradient

Coupled Fields

Field	Required boundary conditions (side A / side B)	Description
any `volScalarField` present in both regions under the same name	`regionCoupledScalarJump` / `regionCoupledScalarFlux` (either order)	Generic continuity + flux conservation, optional partition coefficient
`T` (tutorial)	`regionCoupledScalarJump` (battery) / `regionCoupledScalarFlux` (tab)	Temperature, `diffusivity "k"`
`phiNeg` (tutorial)	`regionCoupledScalarJump` (battery) / `regionCoupledScalarFlux` (negative tab)	Negative-electrode potential, `diffusivity "sigmaNeg"` / `"sigma"`
`phiPos` (tutorial)	`regionCoupledScalarFlux` (battery) / `regionCoupledScalarJump` (positive tab)	Positive-electrode potential, `diffusivity "sigmaPos"` / `"sigma"`

The flux side casts the neighbour patch field to genericRegionCoupledJump, so the BCs must be one jump and one flux. Two flux BCs fail with a bad cast. A field listed in coupledFields that is missing in one of the regions is skipped by the DNA residual check (couplesField()). That is why the tutorial can list phiPos and phiNeg on both tab interfaces, although each tab region holds only one of them.

Compatible Region Types

Region type (side A)	Region type (side B)	Notes
`NTGK`	`conductPotentialTemperature`	Tested in tutorial: `phiPos`/`phiNeg` and `T`
any region that assembles the field in `setCoupledEqns()`	any such region	The field must exist under the same name on both sides and the `diffusivity` must be resolvable in each region. Not covered by a tutorial

laplacianFluid lists defaultInterface for T in its coupling table, but no tutorial uses that combination (untested).

Case Setup

`regionInterfaceProperties` entry

From tutorials/electrochemistry/NTGKBatteryWithTabs/constant/regionInterfaceProperties:

partitionedCoupledPatches
(
 cellToNegTab
 {
 interfaceType (defaultInterface);

 coupledPatchPair
 (
 (batteryRegion toNegTab)
 (negTabRegion toCellFromNeg)
 );

 coupledFields
 (
 phiPos
 phiNeg
 T
 );

 defaultInterfaceCoeffs
 {}
 }

 cellToPosTab
 {
 // same, with (batteryRegion toPosTab) (posTabRegion toCellFromPos)
 }
);

monolithicCoupledPatches
();

curvatureCorrectedSurfacePatches 0();

interpolatorUpdateFrequency 0;

interfaceTransferMethod directMap;

directMapCoeffs
{}

Interface-entry keywords:

Keyword	Default	Description
`interfaceType`	required	List of interface types; one interface object per entry is built on the same patch pair
`coupledPatchPair`	required	`((regionA patchA) (regionB patchB))`; exactly two entries, otherwise a fatal error
`coupledFields`	required	Field names coupled through this patch pair; their union across all entries defines the partitioned-coupled fields
`coupled`	`true`	Switch the interface coupling on or off
`couplingStartTime`	`0`	If `coupled false` and this value is > 0, coupling is switched on once `time >= couplingStartTime`
`<interfaceType>Coeffs`	—	Not read by `defaultInterface`. Kept for consistency with other interface types

Top-level keywords (shared by all interfaces):

Keyword	Default	Description
`partitionedCoupledPatches`	required	List of partitioned interface entries
`monolithicCoupledPatches`	required	List of monolithic interface entries (may be empty: `()`)
`curvatureCorrectedSurfacePatches`	required	`faPatch` names for curvature correction at wedge axes (used only when an `faMesh` exists); `0()` otherwise
`interpolatorUpdateFrequency`	`1`	Rebuild mapping/global patches every N time steps on changing meshes; `0` disables periodic rebuild
`interfaceTransferMethod`	`AMI`	`AMI` or `directMap` (see above)
`<method>Coeffs`	required	Sub-dictionary for the chosen method; may be empty

regionInterfaceProperties is not read in singleRegionMode.

`multiRegionProperties` DNA entry

From the same tutorial:

regions
(
 (batteryRegion (NTGK) )
 (negTabRegion (conductPotentialTemperature) )
 (posTabRegion (conductPotentialTemperature) )
);

DNA
{
 phiPos
 {
 maxCoupleIter 50;

 residualControl
 {
 maxJumpRes 1e-05;
 outputJumpResField no;
 maxFluxRes 1e-05;
 outputFluxResField no;
 }
 }

 phiNeg { maxCoupleIter 25; residualControl { maxJumpRes 1e-05; maxFluxRes 1e-05; } }
 T { maxCoupleIter 10; residualControl { maxJumpRes 1e-05; maxFluxRes 1e-05; } }
}

maxCoupleIter defaults to 1. Either both maxJumpRes and maxFluxRes, or a single maxIntRes, may be given. defaultInterface does not override normIntRes(), which returns 0, so use maxJumpRes / maxFluxRes.

Boundary conditions

Jump side, 0/batteryRegion/orig/partitioned/T:

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

Flux side, 0/negTabRegion/orig/partitioned/T:

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

Flux side with an initial gradient, 0/batteryRegion/orig/partitioned/phiPos:

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

On a patch where a field is not coupled (e.g. phiNeg on the battery’s toPosTab), use an ordinary BC such as zeroGradient.

Known Limitations

No interface physics: correct() and info() are empty and the defaultInterfaceCoeffs dictionary is never read. Any jump or source at the interface must come from the BCs. With the generic BCs, this is limited to a constant or field-valued partition coefficient (jumpCoefficient) and a zero flux jump.
Scalar fields only in practice: field transfer is specialised only for scalar and vector. The only concrete BCs usable with defaultInterface are regionCoupledScalarJump / regionCoupledScalarFlux. The generic vector BCs have notImplemented jumps, and all vector regionCoupled* BCs require capillaryInterface, fsiInterface or a mass-transfer interface. Coupling a vector field via defaultInterface would need a new BC.
Same field name on both sides: the generic BCs always look up the neighbour field under the local field name. neighbourFieldName is ignored there.
Global mapping choice: interfaceTransferMethod and its Coeffs sub-dictionary are top-level keywords. All interfaces in a case share one mapping method. directMap requires conformal patches. RBF is not compiled.
Only the first BC interfaceType is used: if several interface types are listed on one patch, the BC binds to the first. A patch may belong to at most one interface of a given type.
Neighbour detection by patch name only (interfaceToInterfaceCoupleManager::nbrPatch()/nbrMesh()/interpolateFromNbrField()): the local patch is compared with patchA by name only, without the region. If both sides of an interface use the same patch name, side B would identify itself as A and couple to itself (inferred from the code, untested). Give the two patches different names.
diffusivity "v" handling is ineffective (inferred from the code): diffCoeff() renames "v" to "rho" before it checks for "v" to take the reciprocal, so the reciprocal is never applied.
Monolithic coupling not available: monolithicCoupledPatches is parsed, but the monolithic solve in multiRegionSystem::solve() is commented out.
Residual control requires generic BCs: if neither patch field derives from genericRegionCoupledJump / genericRegionCoupledFlux, a warning is printed and the residual is set to GREAT. The DNA loop then always runs to maxCoupleIter (inferred).

Tutorials

Tutorial	Description
`tutorials/electrochemistry/NTGKBatteryWithTabs`	`NTGK` battery cell coupled to a negative and a positive `conductPotentialTemperature` tab via two `defaultInterface` entries (`phiPos`, `phiNeg`, `T`; `directMap`; `./Allrun -p -S`)

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: 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

multiPhysicsFoam – Generic

Docs: defaultInterface

Overview

Interface Conditions

Jump condition

Flux condition

Interface residuals

Implementation

Interface-to-interface mapping

Generic coupled boundary conditions

Coupled Fields

Compatible Region Types

Case Setup

regionInterfaceProperties entry

multiRegionProperties DNA entry

Boundary conditions

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

`regionInterfaceProperties` entry

`multiRegionProperties` DNA entry