From da816bce45ded7b5e2ee056496ae307f425590c4 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 14 Jan 2026 12:10:07 -0500 Subject: [PATCH 1/4] Initial pass at adding region shape docs --- .../source_docs/user_guide/inputs/regions.rst | 69 ++++++++++++++++--- 1 file changed, 60 insertions(+), 9 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/regions.rst b/docs/source_docs/user_guide/inputs/regions.rst index 5b5cfef..e2fe905 100644 --- a/docs/source_docs/user_guide/inputs/regions.rst +++ b/docs/source_docs/user_guide/inputs/regions.rst @@ -3,16 +3,33 @@ Region definitions ================== -Regions are used to define sections of the domain. They may be either boxes, planes or points. They are used in defining initial and boundary conditions. +Regions are used to define sections of the domain and are used in defining initial and boundary conditions. + ++-----------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=============================+=======================================================================+=============+===========+ +| mfix.regions | Names given to regions. | Strings | None | ++-----------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| regions.[region_name].shape | Region shape: | String | None | +| | Options: | | | +| | | | | +| | * ``box`` | | | +| | * ``cylinder`` | | | +| | * ``sphere`` | | | ++-----------------------------+-----------------------------------------------------------------------+-------------+-----------+ + + +Box +~~~ + +For each region, the inputs are defined using the compound prefix ``region.[region_name].box``: +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +==========================+=======================================================================+=============+===========+ -| mfix.regions | Names given to regions. | Strings | None | +| lo | Low corner of physical region (physical, not index space) | Reals | 0 0 0 | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| regions.[region_name].lo | Low corner of physical region (physical, not index space) | Reals | 0 0 0 | -+--------------------------+-----------------------------------------------------------------------+-------------+-----------+ -| regions.[region_name].hi | High corner of physical region (physical, not index space) | Reals | 0 0 0 | +| hi | High corner of physical region (physical, not index space) | Reals | 0 0 0 | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ Below is an example for specifying two regions. @@ -21,8 +38,42 @@ Below is an example for specifying two regions. mfix.regions = full-domain riser - regions.full-domain.lo = 0.0000 0.0000 0.0000 - regions.full-domain.hi = 3.7584 0.2784 0.2784 + regions.full-domain.shape = box + regions.full-domain.box.lo = 0.0000 0.0000 0.0000 + regions.full-domain.box.hi = 3.7584 0.2784 0.2784 + + regions.riser.shape = box + regions.riser.box.lo = 0.0000 0.0000 0.0000 + regions.riser.box.hi = 0.1000 0.2784 0.2784 + + + +Cylinder +~~~~~~~~ + +For each region, the inputs are defined using the compound prefix ``region.[region_name].cylinder``: + ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==========================+=======================================================================+=============+===========+ +| radius | cylinder radius | Real | 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| start | Coordinates of the cylinder's bottom cap | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| end | Coordinates of the cylinder's top cap | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ + + +Sphere +~~~~~~ + +For each region, the inputs are defined using the compound prefix ``region.[region_name].sphere``: + ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==========================+=======================================================================+=============+===========+ +| radius | cylinder radius | Real | 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| center | Coordinates of the sphere's center | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ - regions.riser.lo = 0.0000 0.0000 0.0000 - regions.riser.hi = 0.1000 0.2784 0.2784 -- GitLab From 7820e1dcbf384b53270431e92957cf1bd1debc0e Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 21 Jan 2026 09:40:00 -0500 Subject: [PATCH 2/4] Fix keyword error --- docs/source_docs/user_guide/inputs/regions.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/regions.rst b/docs/source_docs/user_guide/inputs/regions.rst index e2fe905..fbfa74f 100644 --- a/docs/source_docs/user_guide/inputs/regions.rst +++ b/docs/source_docs/user_guide/inputs/regions.rst @@ -22,7 +22,7 @@ Regions are used to define sections of the domain and are used in defining initi Box ~~~ -For each region, the inputs are defined using the compound prefix ``region.[region_name].box``: +For each region, the inputs are defined using the compound prefix ``regions.[region_name].box``: +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | @@ -51,7 +51,7 @@ Below is an example for specifying two regions. Cylinder ~~~~~~~~ -For each region, the inputs are defined using the compound prefix ``region.[region_name].cylinder``: +For each region, the inputs are defined using the compound prefix ``regions.[region_name].cylinder``: +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | @@ -67,7 +67,7 @@ For each region, the inputs are defined using the compound prefix ``region.[regi Sphere ~~~~~~ -For each region, the inputs are defined using the compound prefix ``region.[region_name].sphere``: +For each region, the inputs are defined using the compound prefix ``regions.[region_name].sphere``: +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | -- GitLab From 0b2fc6a1966a06ae84f5fb2925e3ffe3746ddbe1 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 21 Jan 2026 15:22:39 -0500 Subject: [PATCH 3/4] Add addition shapes --- .../source_docs/user_guide/inputs/regions.rst | 49 ++++++++++++++++++- 1 file changed, 47 insertions(+), 2 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/regions.rst b/docs/source_docs/user_guide/inputs/regions.rst index fbfa74f..4f0e384 100644 --- a/docs/source_docs/user_guide/inputs/regions.rst +++ b/docs/source_docs/user_guide/inputs/regions.rst @@ -16,6 +16,9 @@ Regions are used to define sections of the domain and are used in defining initi | | * ``box`` | | | | | * ``cylinder`` | | | | | * ``sphere`` | | | +| | * ``plane`` | | | +| | * ``disk`` | | | +| | * ``point`` | | | +-----------------------------+-----------------------------------------------------------------------+-------------+-----------+ @@ -56,7 +59,7 @@ For each region, the inputs are defined using the compound prefix ``regions.[reg +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +==========================+=======================================================================+=============+===========+ -| radius | cylinder radius | Real | 0 | +| radius | cylinder radius | Real | None | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | start | Coordinates of the cylinder's bottom cap | Reals | 0 0 0 | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ @@ -72,8 +75,50 @@ For each region, the inputs are defined using the compound prefix ``regions.[reg +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +==========================+=======================================================================+=============+===========+ -| radius | cylinder radius | Real | 0 | +| radius | Cylinder radius | Real | None | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ | center | Coordinates of the sphere's center | Reals | 0 0 0 | +--------------------------+-----------------------------------------------------------------------+-------------+-----------+ + +Plane +~~~~~ + +For each region, the inputs are defined using the compound prefix ``regions.[region_name].plane``: + ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==========================+=======================================================================+=============+===========+ +| lo | Low corner of physical region (physical, not index space) | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| hi | High corner of physical region (physical, not index space) | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ + + + +Disk +~~~~ + +For each region, the inputs are defined using the compound prefix ``regions.[region_name].disk``: + ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==========================+=======================================================================+=============+===========+ +| radius | Disk radius | Real | None | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| center | Coordinates of the disk's center | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| normal | Surface normal | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ + + +Point +~~~~~ + +For each region, the inputs are defined using the compound prefix ``regions.[region_name].point``: + ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==========================+=======================================================================+=============+===========+ +| center | Coordinate of point | Reals | 0 0 0 | ++--------------------------+-----------------------------------------------------------------------+-------------+-----------+ -- GitLab From 2ca75ffa73a2c0bf05a442fe77cfb5ffdf56194b Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Sat, 24 Jan 2026 10:10:36 -0500 Subject: [PATCH 4/4] Updates for region shapes --- .../user_guide/inputs/boundary_conditions.rst | 5 +- .../user_guide/inputs/geometry.rst | 51 ------------------- .../user_guide/inputs/initial_conditions.rst | 3 +- .../user_guide/inputs/output/plotting.rst | 3 +- .../user_guide/inputs/output/reports.rst | 10 ++-- .../user_guide/inputs/porous_media.rst | 3 +- 6 files changed, 16 insertions(+), 59 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/boundary_conditions.rst b/docs/source_docs/user_guide/inputs/boundary_conditions.rst index 322adba..f327480 100644 --- a/docs/source_docs/user_guide/inputs/boundary_conditions.rst +++ b/docs/source_docs/user_guide/inputs/boundary_conditions.rst @@ -12,7 +12,10 @@ The following inputs are defined using the prefix ``bc``: +---------------------+--------------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +=====================+==========================================================================+=============+===========+ -| regions | Regions used to define boundary conditions. | Strings | None | +| regions | Regions used to define boundary conditions. Supported shapes for | Strings | None | +| | mass inflow, pressure inflow, and pressure outflow include ``plane`` | | | +| | and ``disk``. Embedded‑boundary regions support ``box``, ``cylinder``, | | | +| | and ``sphere`` shapes. | | | +---------------------+--------------------------------------------------------------------------+-------------+-----------+ | delp_dir | Direction for specified pressure drop. Note that this direction | Int | 0 | | | should also be periodic. | | | diff --git a/docs/source_docs/user_guide/inputs/geometry.rst b/docs/source_docs/user_guide/inputs/geometry.rst index 63582d8..21b38a5 100644 --- a/docs/source_docs/user_guide/inputs/geometry.rst +++ b/docs/source_docs/user_guide/inputs/geometry.rst @@ -287,57 +287,6 @@ The ``generic`` geometry option is used to select the user-programed embedded bo the documentation may include a tutorial to better demonstrate this capability. -.. _InputsGeometry_Regions_and_BCs: - -Regions and boundary conditions -------------------------------- - -Simple geometries can be created by combining planar :ref:`regions` and no-slip wall -:ref:`boundary conditions`. The ``mfix.geometry`` and ``mfix.geometry_file`` -inputs should remain undefined when using this method. - -In the following example, the domain is periodic in the *x-* and *z-* directions; therefore, -walls only need to cover the low and high *xz* faces. First, ``wall1`` and ``wall2`` are defined -in the ``regions`` section, then they are used to specify two no-slip wall boundary conditions. - -.. code-block:: bash - :caption: Example geometry created using regions and boundary conditions. - :name: define_geometry_with_regions - - # Define periodicity and domain extents - # ------------------------------------------------------------- - geometry.coord_sys = 0 - geometry.is_periodic = 1 0 1 - geometry.prob_lo = 0. 0. 0. - geometry.prob_hi = 0.01 0.01 0.005 - - # Define two planar regions - # ------------------------------------------------------------- - mfix.regions = wall1 wall2 - - regions.wall1.lo = 0.000 1.25e-6 0.000 - regions.wall1.hi = 0.010 1.25e-6 0.005 - - regions.wall2.lo = 0.000 9.99875e-3 0.000 - regions.wall2.hi = 0.010 9.99875e-3 0.005 - - # Use the regions to define no-slip wall boundaries - # ------------------------------------------------------------- - bc.regions = wall1 wall2 - - bc.wall1 = nsw - bc.wall1.normal = 0.0 1.0 0.0 - - bc.wall2 = nsw - bc.wall2.normal = 0.0 -1.0 0.0 - -.. caution:: - - It is highly recommended that planar regions not be defined coincident to domain - boundaries. It is better to specify planes slightly offset from the domain as - demonstrated in the :ref:`above example`. - - .. _InputsGeometry_CSG: Constructive solid geometry (CSG) diff --git a/docs/source_docs/user_guide/inputs/initial_conditions.rst b/docs/source_docs/user_guide/inputs/initial_conditions.rst index b9273d8..8c85ec2 100644 --- a/docs/source_docs/user_guide/inputs/initial_conditions.rst +++ b/docs/source_docs/user_guide/inputs/initial_conditions.rst @@ -6,7 +6,8 @@ The following inputs are defined using the prefix ``ic``: +-----------------------+------------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +=======================+========================================================================+=============+===========+ -| regions | Regions used to define initial conditions. | Strings | None | +| regions | Regions used to define initial conditions. Supported region shapes | Strings | None | +| | include a ``box``, ``cylinder``, and ``sphere``. | | | +-----------------------+------------------------------------------------------------------------+-------------+-----------+ | allow_regions_overlap | If enabled, particles will be generated/initialized more than once | Int | 1 | | | on areas where the IC regions intersect. This only applied to particle | | | diff --git a/docs/source_docs/user_guide/inputs/output/plotting.rst b/docs/source_docs/user_guide/inputs/output/plotting.rst index 60216b9..c23f8ce 100644 --- a/docs/source_docs/user_guide/inputs/output/plotting.rst +++ b/docs/source_docs/user_guide/inputs/output/plotting.rst @@ -72,7 +72,8 @@ contain only solids variables in specific regions at fixed timesteps or approxim +--------------------------------+-----------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +================================+=================================================================+=============+===========+ -| regions | Specify regions that will be used for plotfiles. | Strings | | +| regions | Regions used when generating plotfiles. The only supported | Strings | None | +| | region shape for plotfile output is ``box``. | | | +--------------------------------+-----------------------------------------------------------------+-------------+-----------+ | [region_name] | Specify which solids phases will be plotted. | Strings | | +--------------------------------+-----------------------------------------------------------------+-------------+-----------+ diff --git a/docs/source_docs/user_guide/inputs/output/reports.rst b/docs/source_docs/user_guide/inputs/output/reports.rst index f69bc63..0f58bb8 100644 --- a/docs/source_docs/user_guide/inputs/output/reports.rst +++ b/docs/source_docs/user_guide/inputs/output/reports.rst @@ -55,11 +55,13 @@ that is output every 50 time steps. The ``right-side`` report is a PSD consistin # ------------------------------------------------------------- mfix.regions = ... left right - regions.left.lo = 0.00 0.00 0.00 - regions.left.hi = 0.05 0.10 0.10 + regions.left.shape = box + regions.left.box.lo = 0.00 0.00 0.00 + regions.left.box.hi = 0.05 0.10 0.10 - regions.right.lo = 0.05 0.00 0.00 - regions.right.hi = 0.10 0.10 0.10 + regions.right.shape = box + regions.right.box.lo = 0.05 0.00 0.00 + regions.right.box.hi = 0.10 0.10 0.10 # Define two particle size distribution reports # ------------------------------------------------------------- diff --git a/docs/source_docs/user_guide/inputs/porous_media.rst b/docs/source_docs/user_guide/inputs/porous_media.rst index 6ab3c1f..41a1935 100644 --- a/docs/source_docs/user_guide/inputs/porous_media.rst +++ b/docs/source_docs/user_guide/inputs/porous_media.rst @@ -18,7 +18,8 @@ The following inputs are defined using the prefix ``pm``: +-------------------------------+------------------------------------------------------------------------------+----------+-----------+ | | Description | Type | Default | +===============================+==============================================================================+==========+===========+ -| regions | Regions used to define porous media. | Strings | None | +| regions | Regions used to define porous media. Supported region shapes include | Strings | None | +| | ``box``, ``cylinder``, and ``sphere``. | | | +-------------------------------+------------------------------------------------------------------------------+----------+-----------+ | [region_name].volfrac | Solids volume fraction of the porous media region. | Real | None | +-------------------------------+------------------------------------------------------------------------------+----------+-----------+ -- GitLab