.. _InputsBoundaryConditions:

Boundary conditions
===================


General boundary conditions
---------------------------

The following inputs are defined using the prefix ``bc``:

+---------------------+--------------------------------------------------------------------------+-------------+-----------+
|                     | Description                                                              |   Type      | Default   |
+=====================+==========================================================================+=============+===========+
| regions             | Regions used to define boundary conditions.                              |  Strings    | None      |
+---------------------+--------------------------------------------------------------------------+-------------+-----------+
| delp_dir            | Direction for specified pressure drop. Note that this direction          |  Int        | 0         |
|                     | should also be periodic.                                                 |             |           |
+---------------------+--------------------------------------------------------------------------+-------------+-----------+
| delp                | Pressure drop (Pa)                                                       |  Real       | 0         |
+---------------------+--------------------------------------------------------------------------+-------------+-----------+
| po_no_par_out       | Force particles to bounce back rather than exiting at pressure outflows. |  Int        | 0         |
+---------------------+--------------------------------------------------------------------------+-------------+-----------+

The type of the boundary conditions in the BC region must be defined with the prefix ``bc``:

+---------------------+-----------------------------------------------------------------------+-------------+-----------+
|                     | Description                                                           |   Type      | Default   |
+=====================+=======================================================================+=============+===========+
| [region_name]       | Specify boundary condition type.                                      |  String     |  None     |
|                     |                                                                       |             |           |
|                     | Options:                                                              |             |           |
|                     |                                                                       |             |           |
|                     | * ``pi``  - pressure inflow                                           |             |           |
|                     | * ``po``  - pressure outflow                                          |             |           |
|                     | * ``mi``  - mass inflow                                               |             |           |
|                     | * ``eb``  - embedded boundary - for inhomogeneous Dirichlet BCs       |             |           |
|                     |              of temperature or fluid velocity (mass inflow) on the    |             |           |
|                     |              contained EBs                                            |             |           |
+---------------------+-----------------------------------------------------------------------+-------------+-----------+



Fluid settings
~~~~~~~~~~~~~~

For each boundary condition region, the fluid inputs are defined
using the prefix ``bc.[region_name].[fluid_name]``:


+------------------------+------------------------------------------------------------------------+-------------+-----------+
|                        | Description                                                            |   Type      | Default   |
+========================+========================================================================+=============+===========+
| volfrac                | Volume fraction [required if bc type is ``mi``]                        | Real        | 0         |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| density                | Fluid density [required if bc type is ``mi`` or ``pi``]                | Real        | 0         |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| pressure               | Fluid pressure [required if bc type is ``po' or ``pi``]                | Real        | 0         |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| temperature            | Fluid temperature [required if bc type is ``mi`` or ``pi``]            | Real        | 0         |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| velocity               | Velocity components [required if bc type is ``mi``                     | Reals       | 0 0 0     |
|                        | and ``volflow`` or ``massflow`` not specified]                         |             |           |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| volflow                | Volumetric flow rate [required if bc type is ``mi``                    | Real        | 0         |
|                        | and ``velocity`` or ``massflow`` not specified]                        |             |           |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| massflow               | Mass flow rate [required if bc type is ``mi``                          | Real        | 0         |
|                        | and ``velocity`` or ``volflow`` not specified]                         |             |           |
+------------------------+------------------------------------------------------------------------+-------------+-----------+
| species.[species_name] | Species `species_name` mass fraction [required if `solve_species`=1    | Real        | 0         |
|                        | and bc type is ``mi`` or ``pi``]                                       |             |           |
+------------------------+------------------------------------------------------------------------+-------------+-----------+

Note that for a ``mi`` only one of ``velocity`` or ``volflow`` or ``massflow`` should be specified.
Additionally, velocity can be specified as a vector or a scalar, the latter of which is applied
normal to the inflow plane, as with volflow and massflow.

Below is an example for specifying boundary conditions for fluid (``fluid``).

.. code-block:: none

   bc.regions = inflow outflow

   bc.inflow = mi
   bc.inflow.fluid.volfrac     =  1.0
   bc.inflow.fluid.density     =  1.0
   bc.inflow.fluid.velocity    =  0.015  0.0  0.0
   bc.inflow.fluid.temperature =  300
   bc.inflow.fluid.species.O2  =  0.0
   bc.inflow.fluid.species.CO  =  0.5
   bc.inflow.fluid.species.CO2 =  0.5

   bc.outflow = po

   bc.outflow.fluid.pressure =  0.0


Below is an example for specifying a normal inflow velocity magnitude for a region `eb-flow`.

.. code-block:: none

   bc.regions = eb-flow

   bc.eb-flow = eb

   bc.eb-flow.my_fluid.volfrac  = 1.0
   bc.eb-flow.my_fluid.velocity = 0.1

Below is an example where only specific cells are imposed a velocity inflow in the x-direction.

.. code-block:: none

   bc.regions = eb-flow

   bc.eb-flow = eb

   bc.eb-flow.eb.normal_tol = 3.0
   bc.eb-flow.eb.normal =  0.9848  0.0000  0.1736  # 10 deg

   bc.eb-flow.my_fluid.volfrac  = 1.0
   bc.eb-flow.my_fluid.velocity = 0.1  0.0  0.0


.. _InputsBCSolids:

Solids settings
~~~~~~~~~~~~~~~

For each inflow boundary condition region, general solids inputs are defined using the prefix ``bc.[region_name]``:

+----------------------+------------------------------------------------------------------+-------------+-----------+
|                      | Description                                                      |   Type      | Default   |
+======================+==================================================================+=============+===========+
| solids               | Name of solid type in BC region.  Only one solid is allowed in   | String      | None      |
|                      | an BC region.                                                    |             |           |
+----------------------+------------------------------------------------------------------+-------------+-----------+

.. warning::

   Mass inflow boundary conditions, ``bc.[region_name] = mi``, only support PIC parcels. EB inflow boundary conditions,
   ``bc.[region_name] = eb``, support DEM particles and PIC parcels.

For inflow boundary conditions , the solid inputs are defined using the prefix ``bc.[region_name].[solid_name]``:
Note that diameter distributions must define a weighting type,
please refer to :ref:`ReferenceParticleDistributions <ReferenceParticleDistributions>`.

+------------------------+-----------------------------------------------------------------------+-------------+-----------+
|                        | Description                                                           |   Type      | Default   |
+========================+=======================================================================+=============+===========+
| volfrac                | Volume fraction                                                       | Real        | 0         |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| temperature            | Temperature                                                           | Real        | 0         |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| species.[species_name] | Mass fraction of ``species_name``                                     | Real        | 0         |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| velocity               | Velocity components                                                   | Reals       | 0 0 0     |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| volflow                | Volumetric flow rate.                                                 | Real        | 0         |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| massflow               | Mass flow rate.                                                       | Real        | 0         |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter               | Method to specify particle diameter in the IC region. This is         | String      | None      |
|                        | only used for auto-generated particles.                               |             |           |
|                        |                                                                       |             |           |
|                        | Options:                                                              |             |           |
|                        |                                                                       |             |           |
|                        | * ``constant``  -  specified constant                                 |             |           |
|                        | * ``uniform``   -  uniform distribution                               |             |           |
|                        | * ``normal``    -  normal distribution                                |             |           |
|                        | * ``custom``    -  user-defined distribution                          |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| type                   | Distribution weighting.                                               | String      | N/A       |
|                        |                                                                       |             |           |
|                        | Options:                                                              |             |           |
|                        |                                                                       |             |           |
|                        | * ``number-weighted``                                                 |             |           |
|                        | * ``volume-weighted``                                                 |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| bins                   | Number of bins used when discretizing the distribution to approximate | Int         | 64        |
|                        | the number of particles within an initial condition region.           |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.constant      | Monodisperse (single valued) particle diameter.                       | Real        | 0         |
|                        | Required for ``constant`` distributions.                              |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.mean          | Distribution mean.                                                    | Real        | 0         |
|                        | Required for ``normal`` distributions.                                |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.std           | Distribution standard deviation.                                      | Real        | 0         |
|                        | Required for ``normal`` distributions.                                |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.min           | Minimum diameter to clip distribution.                                | Real        | 0         |
|                        | Required for ``normal`` distributions and ``uniform`` distributions.  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.max           | Maximum diameter to clip distribution.                                | Real        | 0         |
|                        | Required for ``normal`` distributions and ``uniform`` distributions.  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| diameter.custom        | File name that specifies either the cumulative or probability         | String      | None      |
|                        | distribution. Required for ``custom`` distributions.                  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density                | Method to specify particle density in the IC region. This is          | String      | None      |
|                        | only used for auto-generated particles.                               |             |           |
|                        |                                                                       |             |           |
|                        | Options:                                                              |             |           |
|                        |                                                                       |             |           |
|                        | * ``constant``  -  specified constant                                 |             |           |
|                        | * ``uniform``   -  uniform distribution                               |             |           |
|                        | * ``normal``    -  normal distribution                                |             |           |
|                        | * ``custom``    -  user-defined distribution                          |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.constant       | Monodisperse (single valued) particle density.                        | Real        | 0         |
|                        | Required for ``constant`` distributions.                              |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.mean           | Distribution mean.                                                    | Real        | 0         |
|                        | Required for ``normal`` distributions.                                |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.std            | Distribution standard deviation.                                      | Real        | 0         |
|                        | Required for ``normal`` distributions.                                |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.min            | Minimum diameter to clip distribution.                                | Real        | 0         |
|                        | Required for ``normal`` distributions and ``uniform`` distributions.  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.max            | Maximum diameter to clip distribution.                                | Real        | 0         |
|                        | Required for ``normal`` distributions and ``uniform`` distributions.  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+
| density.custom         | File name that specifies either the cumulative or probability         | String      | None      |
|                        | distribution. Required for ``custom`` distributions.                  |             |           |
+------------------------+-----------------------------------------------------------------------+-------------+-----------+


Transient boundary conditions
-----------------------------

Velocity, temperature, and pressure boundary conditions may also be specified as a
function of time simply by adding a new column. The time value is entered in the
new first column. We can make the `mi` boundary condition above time-dependent
by replacing:

.. code-block:: none

   bc.inflow.fluid.velocity    =  0.0  0.0    0.0  0.0
   bc.inflow.fluid.velocity    =  3.0  0.015  0.0  0.0

   bc.inflow.fluid.temperature =  0.0  300
   bc.inflow.fluid.temperature =  2.99 300
   bc.inflow.fluid.temperature =  3.0  500
   bc.inflow.fluid.temperature =  4.0  500
   bc.inflow.fluid.temperature =  4.01 300

In the above example, the inflow velocity is accelerated from zero to its
final value over a period of three seconds. Linear interpolation is used in
between discrete time values and held constant at the last time value. The
temperature sees an abrupt spike from 300 up to 500 at t = 3s and then back
down again after 4s. Note that the timestep is not adjusted to sync with
transient BCs.

.. image:: ./images/transient-bc.png

Thermal boundary conditions
---------------------------

Boundary conditions can be applied to embedded boundaries (EBs). For example, a constant wall temperature can be
imposed on the entire EB or restricted to a specific region.

To apply a boundary condition to only a portion of an EB, a face normal vector and tolerance can be specified. This
allows the condition to be applied only to EB faces whose normals align with the specified direction within a given
angular tolerance. The following inputs are defined using the prefix ``bc.[region_name].eb``:

+--------------------+-----------------------------------------------------------------------+-------------+-----------+
|                    | Description                                                           |   Type      | Default   |
+====================+=======================================================================+=============+===========+
| normal             | [Optional] Specifies the target face normal direction. Only EB faces  | Reals       | 0 0 0     |
|                    | whose normals are parallel (within the specified tolerance) will have |             |           |
|                    | the boundary condition applied.                                       |             |           |
+--------------------+-----------------------------------------------------------------------+-------------+-----------+
| normal_tol         | [Optional] Angular tolerance (in degrees) used with ``eb.normal`` to  | Real        | 0         |
|                    | select EB faces. A value of 0 requires exact alignment.               |             |           |
+--------------------+-----------------------------------------------------------------------+-------------+-----------+


The following table lists the thermal boundary condition options that can be applied to embedded boundaries (EBs), with
inputs defined using the prefix ``bc.[region_name].eb``.

+----------------------+-----------------------------------------------------------------------+-------------+-----------+
|                      | Description                                                           |   Type      | Default   |
+======================+=======================================================================+=============+===========+
| temperature          | Specify a wall temperature model for the embedded boundary.           | String      | adiabatic |
|                      |                                                                       |             |           |
|                      | Options:                                                              |             |           |
|                      |                                                                       |             |           |
|                      | * ``adiabatic`` - no heat flux through the wall                       |             |           |
|                      | * ``constant`` - impose a constant temperature along the EB.          |             |           |
|                      | * ``CHT-1D`` - compute a temperature for the wall using the 1D        |             |           |
|                      |   conjugate heat transfer model.                                      |             |           |
|                      |                                                                       |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+
| temperature.constant | Constant wall temperature.                                            | Real        | None      |
|                      | A valid is required for ``constant`` EB temperature model.            |             |           |
+----------------------+-----------------------------------------------------------------------+-------------+-----------+

The conjugate heat transfer model approximates heat transfer through the embedded boundary using one-dimensional,
steady-state conduction. The external environment is treated as a thermal reservoir with a constant temperature
in both space and time. This approach is illustrated in :numref:`fig_conjugate_heat_transfer_bc`, where heat flows
through a series of thermal resistances: from the fluid to the inner wall surface, through the wall, and finally
to the environment. The direction of heat transfer---into or out of the system---is governed by the temperature
gradient between the fluid and the surroundings.

.. _fig_conjugate_heat_transfer_bc:

.. figure:: ./images/CHT-1D.png
   :height: 2in
   :align: center
   :alt: Schematic of the conjugate heat transfer boundary condition.

   Schematic of the conjugate heat transfer boundary condition.

An effective resistance is calculated based on the convective heat transfer coefficient between the fluid
and wall, :math:`h_{int}`, conduction through the wall with thickness :math:`L_w` and thermal conductivity
:math:`\kappa_w`, and convective heat transfer from the exterior wall to the environment :math:`h_{ext}`.

.. math::

   R_{eff} = \left( \frac{1}{h_{int}} + \frac{L_w}{\kappa_w} + \frac{1}{h_{ext}} \right)^{-1}

The interior wall temperature is determined by balancing the heat flux contributions from internal
convection, wall conduction, and external convection, resulting in a closed-form expression based
on the effective thermal resistance of the system.

.. math::

   T_{w,int} = T_f - \frac{1}{h_{int}}\left[ \frac{T_f - T_{\infty}}{R_{eff}} \right]


The model settings are defined using the prefix ``bc.[region_name].eb.temperature.CHT-1D``:

.. |avg_T| replace:: :math:`T = \varepsilon_f T_f + (1-\varepsilon_f) \overline{T}_p`

.. |avg_Tp| replace:: :math:`\overline{T}_p = \left( {\sum_p^{N_p} T_p V_p} \right) / \left( {\sum_p^{N_p} V_p} \right)`

+----------------------------+------------------------------------------------------------------------+-------------+-----------+
|                            | Description                                                            |   Type      | Default   |
+============================+========================================================================+=============+===========+
| T_env                      | Environment temperature                                                | Real        | None      |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+
| h_int                      | Heat Transfer Coefficient (fluid–wall, internal)                       | Real        | None      |
|                            |                                                                        |             |           |
|                            | Specifies the convective heat transfer coefficient [W/m² K] between    |             |           |
|                            | the fluid and adjacent solid walls (EBs) located within the interior   |             |           |
|                            | of the computational domain.                                           |             |           |
|                            |                                                                        |             |           |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+
| h_ext                      | Heat Transfer Coefficient (wall-environment, external)                 | Real        | None      |
|                            |                                                                        |             |           |
|                            | Specifies the convective heat transfer coefficient [W/m² K] between    |             |           |
|                            | the wall and the external environment.                                 |             |           |
|                            |                                                                        |             |           |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+
| wall.conductivity          | The thermal conductivity of the wall.                                  | Real        | None      |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+
| wall.thickness             | Wall thickness.                                                        | Real        | None      |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+
| phase_averaged_temperature | Use a phase averaged temperature for simulations containing particles. | Bool        | false     |
|                            | The phase averaged temperature is computed as the volume fraction      |             |           |
|                            | weighted sum of the fluid and averaged particle temperatures.          |             |           |
|                            |                                                                        |             |           |
|                            |   |avg_T|                                                              |             |           |
|                            |                                                                        |             |           |
|                            | The averaged particle temperature is computed by depositing the        |             |           |
|                            | volume-averaged particle temperature to the grid.                      |             |           |
|                            |                                                                        |             |           |
|                            |   |avg_Tp|                                                             |             |           |
+----------------------------+------------------------------------------------------------------------+-------------+-----------+


Below is an example for specifying a constant temperature boundary condition in the ``hot-walls`` region.

.. code-block:: none

   bc.regions = hot-wall

   bc.hot-walls = eb
   bc.hot-walls.eb.temperature = constant
   bc.hot-walls.eb.temperature.constant = 800
