From 2b46278847f16f69c283614c0a18529d8a377c76 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Tue, 3 Mar 2026 10:59:48 -0600 Subject: [PATCH 1/2] run doc_scanner, update undocumented-keys --- .../references/grid/GridCreation.rst | 37 +++++++++---------- docs/source_docs/tools/pic2dem.rst | 4 +- docs/source_docs/user_guide/inputs/domain.rst | 2 +- undocumented-keys.txt | 1 - 4 files changed, 21 insertions(+), 23 deletions(-) diff --git a/docs/source_docs/references/grid/GridCreation.rst b/docs/source_docs/references/grid/GridCreation.rst index a2087e7..d340808 100644 --- a/docs/source_docs/references/grid/GridCreation.rst +++ b/docs/source_docs/references/grid/GridCreation.rst @@ -9,44 +9,44 @@ Grid Creation ------------- -To run MFIX-Exa you must specify :cpp:`n_cell` in the inputs file -- +To run MFIX-Exa you must specify :cpp:`n_cell` in the inputs file -- this is the number of cells spanning the domain in each coordinate direction at level 0. -Users often specify :cpp:`max_grid_size` as well. The default load balancing algorithm then divides the +Users often specify :cpp:`max_grid_size` as well. The default load balancing algorithm then divides the domain in every direction so that each grid is no longer than :cpp:`max_grid_size` in that direction. If not specified by the user, :cpp:`max_grid_size` defaults to 128 in 2D and 32 in 3D (in each coordinate direction). -Another popular input is :cpp:`blocking_factor`. The value of :cpp:`blocking_factor` -constrains grid creation in that in that each grid must be divisible by :cpp:`blocking_factor`. +Another popular input is :cpp:`blocking_factor`. The value of :cpp:`blocking_factor` +constrains grid creation in that in that each grid must be divisible by :cpp:`blocking_factor`. Note that both the domain (at each level) and :cpp:`max_grid_size` must be divisible by :cpp:`blocking_factor` If not specified by the user, :cpp:`blocking_factor` defaults to 8 in each coordinate direction. -The typical purpose of :cpp:`blocking_factor` is to ensure that the grids will be +The typical purpose of :cpp:`blocking_factor` is to ensure that the grids will be sufficiently coarsenable for good multigrid performance. -There is one more default behavior to be aware of. There is a boolean :cpp:`refine_grid_layout` -that defaults to true but can be over-ridden at run-time. -If :cpp:`refine_grid_layout` is true and the number of grids created is less than the number of processors +There is one more default behavior to be aware of. There is a boolean :cpp:`refine_grid_layout` +that defaults to true but can be overridden at runtime. +If :cpp:`refine_grid_layout` is true and the number of grids created is less than the number of processors (Ngrids < Nprocs), then grids will be further subdivided until Ngrids >= Nprocs. -Caveat: if subdividing the grids to achieve Ngrids >= Nprocs would violate the -:cpp:`blocking_factor` criterion then additional grids are not created and the -number of grids will remain less than the number of processors +Caveat: if subdividing the grids to achieve Ngrids >= Nprocs would violate the +:cpp:`blocking_factor` criterion then additional grids are not created and the +number of grids will remain less than the number of processors. Note that :cpp:`n_cell` must be given as three separate integers, one for each coordinate direction. -However, :cpp:`max_grid_size` and :cpp:`blocking_factor` can be specified as a single value -applying to all coordinate directions, or as separate values for each direction. +However, :cpp:`max_grid_size` and :cpp:`blocking_factor` can be specified as a single value +applying to all coordinate directions, or as separate values for each direction. - - if :cpp:`max_grid_size` (or :cpp:`blocking_factor`) is specified as multiple integers then the first + - if :cpp:`max_grid_size` (or :cpp:`blocking_factor`) is specified as multiple integers then the first integer applies to level 0, the second to level 1, etc. If you don't specify as many integers as there are levels, the final value will be used for the remaining levels. - - if different values of :cpp:`max_grid_size` (or :cpp:`blocking_factor`) are wanted for each coordinate direction, - then :cpp:`max_grid_size_x`, :cpp:`max_grid_size_y` and :cpp:`max_grid_size_z` - (or :cpp:`blocking_factor_x`, :cpp:`blocking_factor_y` and :cpp:`blocking_factor_z`) must be used. + - if different values of :cpp:`max_grid_size` (or :cpp:`blocking_factor`) are wanted for each coordinate direction, + then :cpp:`max_grid_size_x`, :cpp:`max_grid_size_y` and :cpp:`max_grid_size_z` + (or :cpp:`blocking_factor_x`, :cpp:`blocking_factor_y` and :cpp:`blocking_factor_z`) must be used. If you don't specify as many integers as there are levels, the final value will be used for the remaining levels. - - note that :cpp:`max_grid_size` is just an upper bound; with :cpp:`n_cell = 48` + - note that :cpp:`max_grid_size` is just an upper bound; with :cpp:`n_cell = 48` and :cpp:`max_grid_size = 32`, we will typically have one grid of length 32 and one of length 16. The grid creation process at level 0 proceeds as follows (if not using the KD-tree approach): @@ -61,4 +61,3 @@ The grid creation process at level 0 proceeds as follows (if not using the KD-tr #. Next, if :cpp:`refine_grid_layout = true` and there are more processors than grids at this level, then the grids at this level are further divided until Ngrids >= Nprocs (unless doing so would violate the :cpp:`blocking_factor` criterion). - diff --git a/docs/source_docs/tools/pic2dem.rst b/docs/source_docs/tools/pic2dem.rst index ccdd9bf..66e3cf0 100644 --- a/docs/source_docs/tools/pic2dem.rst +++ b/docs/source_docs/tools/pic2dem.rst @@ -34,8 +34,8 @@ The following inputs must be preceded by "pic2dem.": | | will be generated in that cell | | | +------------------------+---------------------------------------------------+--------+---------+ | eps_overflow | An artifact, like a knob, for the user to force | Real | 1.0 | -| | over-production (if value > 1), or | | | -| | under-production (if value < 1) of DEM particles | | | +| | overproduction (if value > 1), or | | | +| | underproduction (if value < 1) of DEM particles | | | +------------------------+---------------------------------------------------+--------+---------+ | small_volfrac | This input gives the possibility to set a small | Real | 0. | | | volfrac value just for the DEM refined case, | | | diff --git a/docs/source_docs/user_guide/inputs/domain.rst b/docs/source_docs/user_guide/inputs/domain.rst index baf6614..5b41cc9 100644 --- a/docs/source_docs/user_guide/inputs/domain.rst +++ b/docs/source_docs/user_guide/inputs/domain.rst @@ -64,7 +64,7 @@ The result is a uniform mesh spacing of :math:`0.125` *m* in all three direction .. _inputs_mesh_ex: .. code-block:: bash - :caption: Snippet of intpus for mesh example. This is not a complete input file. + :caption: Snippet of inptus for mesh example. This is not a complete input file. # Define periodicity and domain extents # ------------------------------------------------------------- diff --git a/undocumented-keys.txt b/undocumented-keys.txt index 271defb..f491834 100644 --- a/undocumented-keys.txt +++ b/undocumented-keys.txt @@ -23,7 +23,6 @@ hopper.direction hopper.funnel_height hopper.funnel_radius hopper.orifice_radius -ic.[region_name].granular_temperature mfix.advect_momentum mfix.advect_tracer mfix.agg_grid_size -- GitLab From 0b4a269393e2c229223e3f15819f9e9196871321 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Tue, 3 Mar 2026 14:10:34 -0600 Subject: [PATCH 2/2] add a few keys --- .../qualitative_bencharks/biseg.rst | 59 +++++++++---------- .../user_guide/inputs/output/plotting.rst | 6 ++ .../user_guide/inputs/time_stepping.rst | 11 +++- 3 files changed, 42 insertions(+), 34 deletions(-) diff --git a/docs/source_docs/test_benchmarks/qualitative_bencharks/biseg.rst b/docs/source_docs/test_benchmarks/qualitative_bencharks/biseg.rst index 3fa6569..fd0fa0c 100644 --- a/docs/source_docs/test_benchmarks/qualitative_bencharks/biseg.rst +++ b/docs/source_docs/test_benchmarks/qualitative_bencharks/biseg.rst @@ -1,48 +1,45 @@ .. _Chap:QB:biseg: -Bidisperse Segregation -====================== +Bidisperse segregation +====================== -In this simple test conducted at NETL, a uniform, random mixture -of nylon +In this simple test conducted at NETL, a uniform, random mixture +of nylon (:math:`d_p = 3.19` mm, :math:`\rho_p = 1130` kg/m\ :sup:`3` \) -and ceramic +and ceramic (:math:`d_p = 4.25` mm, :math:`\rho_p = 2580` kg/m\ :sup:`3` \) -particles. When fluidized, the smaller, lighter nylon particles -(:math:`U_{mf} \approx 1.1` m/s) segregate out of the mixture to the top, +particles. When fluidized, the smaller, lighter nylon particles +(:math:`U_{mf} \approx 1.1` m/s) segregate out of the mixture to the top, with the larger, heavier ceramic particles (:math:`U_{mf} \approx 1.8` m/s) -remaining at the bottom. The batch segregation test was conducted in -a small bed with a square cross-section of side length 60.325 mm. -Similar to previous observations of fluidized segregation of -bidisperse mixtures [GLMK03]_, the optimal separation was found to -occur just above the larger of the two minimum fluidization velocities. -Below the larger :math:`U_{mf}`, lack of fluidization inhibits particle -movement and too much above :math:`U_{mf}` vigorous bubbling promotes -mixture in the bed. +remaining at the bottom. The batch segregation test was conducted in +a small bed with a square cross-section of side length 60.325 mm. +Similar to previous observations of fluidized segregation of +bidisperse mixtures [GLMK03]_, the optimal separation was found to +occur just above the larger of the two minimum fluidization velocities. +Below the larger :math:`U_{mf}`, lack of fluidization inhibits particle +movement and too much above :math:`U_{mf}` vigorous bubbling promotes +mixture in the bed. The optimal batch segregation experiment is simulated with MFIX-Exa 19.08 -discretized onto a :math:`8 \times 24 \times 8` mesh. No-slip walls are +discretized onto a :math:`8 \times 24 \times 8` mesh. No-slip walls are set at vertical domain extents with a mass inflow and pressure outflow at -bottom and top, respectively. The :cpp:`Gidaspow` drag law is applied. -A defluidization curve of all ceramic particles was traced to find -:math:`U_{mf} \approx 1.9` m/s, close to the experimental value. The inflow +bottom and top, respectively. The :cpp:`Gidaspow` drag law is applied. +A defluidization curve of all ceramic particles was traced to find +:math:`U_{mf} \approx 1.9` m/s, close to the experimental value. The inflow velocity is set to `2.0` m/s. The image below shows the simulated segregation -(inset) occurs much more rapidly than observed experimentally. In this case, -as the nylon particles begin to leave the mixture, the ceramic particles -defluidize. In the final state, the ceramic particles are essentially static -with a fluidized layer of nylon particles floating on top, in contrast to the -experiment, in which the full bed showed signs of fluidization. Investigation -into the over-segregation in this case is on-going. - +(inset) occurs much more rapidly than observed experimentally. In this case, +as the nylon particles begin to leave the mixture, the ceramic particles +defluidize. In the final state, the ceramic particles are essentially static +with a fluidized layer of nylon particles floating on top, in contrast to the +experiment, in which the full bed showed signs of fluidization. Investigation +into the oversegregation in this case is ongoing. + .. figure:: figs/netl_biseg_1908_small.png :width: 16cm :align: center - :alt: Sim comparison to bidisperse segregation experiment at NETL + :alt: Sim comparison to bidisperse segregation experiment at NETL Comparison of experiment and MFIX-Exa simulaton for rapid segregation - of a bi-disperse particle mixture. - - - + of a bi-disperse particle mixture. diff --git a/docs/source_docs/user_guide/inputs/output/plotting.rst b/docs/source_docs/user_guide/inputs/output/plotting.rst index c23f8ce..bdab758 100644 --- a/docs/source_docs/user_guide/inputs/output/plotting.rst +++ b/docs/source_docs/user_guide/inputs/output/plotting.rst @@ -31,12 +31,18 @@ The following inputs must be preceded by the prefix ``mfix`` and control which v +=====================+=======================================================================+=============+===========+ | plt_regtest | Plot all variables (overrides all other plot flags). | Int | 0 | +---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| plt_cp_g | Plot fluid specific heat. | Int | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| plt_cp_gk | Plot specific heat for each fluid species. | Int | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ | plt_drag_p | Plot particle drag force. | Int | 0 | +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | plt_ep_g | Plot fluid volume fraction. | Int | 1 | +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | plt_gradp_g | Plot fluid pressure gradient. | Int | 0 | +---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| plt_h_g | Plot fluid enthalpy. | Int | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ | plt_mu_g | Plot fluid molecular viscosity. | Int | 0 | +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | plt_omega_p | Plot particle angular velocity. | Int | 0 | diff --git a/docs/source_docs/user_guide/inputs/time_stepping.rst b/docs/source_docs/user_guide/inputs/time_stepping.rst index b91d44d..93b6fae 100644 --- a/docs/source_docs/user_guide/inputs/time_stepping.rst +++ b/docs/source_docs/user_guide/inputs/time_stepping.rst @@ -99,6 +99,12 @@ The following inputs are defined using the prefix ``mfix``: +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | stop_time | Maximum time to reach (s). | Real | -1.0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ +| overstep_end_time | If set, the time step computed by the CFL condition is used for the | Int | 0 | +| | last time step, allowing the simulation to slightly overstep the | | | +| | simulation stop time. | | | +| | By default, the last time step of a transient simulation is truncated | | | +| | to ensure the end time equals ``mfix.stop_time``. | | | ++----------------------+-----------------------------------------------------------------------+-------------+--------------+ | fixed_dt | If > 0, use a fixed time step. | Real | 0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | dt_min | Abort if ``dt`` gets smaller than this value. | Real | 1.e-6 | @@ -107,12 +113,12 @@ The following inputs are defined using the prefix ``mfix``: +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | tcoll_ratio | DEM time step equals the min collision time divided by this value. | Real | 50.0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| walltime_limit | Runtime limit specified with format HH:MM:SS. When the runtime has | String | "" | +| walltime_limit | Runtime limit specified with format HH:MM:SS. When the runtime has | String | | | | almost reached the limit (approaching is computed by considering the | | | | | average runtime needed for each step), then the simulation ends and | | | | | a clean exit is performed. | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| clean_exit | The name of a file that, if found in the run | String | "" | +| clean_exit | The name of a file that, if found in the run | String | | | | folder, makes the solver stop and perform a clean exit. | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ @@ -135,4 +141,3 @@ The following inputs are defined using the prefix ``mfix`` and are only relevant .. sec:InputsInitialization - -- GitLab