multiPhysicsFoam – Partitioned

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