From 99509675423b79b551d7447cb7c0bc5794ade421 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 24 Nov 2025 08:15:29 -0600 Subject: [PATCH 1/3] update docs --- .../user_guide/inputs/chemical_reactions.rst | 2 +- .../user_guide/inputs/fluid_model.rst | 9 +++-- .../user_guide/inputs/initial_conditions.rst | 8 ++-- .../user_guide/inputs/model_options.rst | 15 +++---- .../user_guide/inputs/output/ascent.rst | 24 +++++++----- .../user_guide/inputs/output/plotting.rst | 38 +++++------------- .../user_guide/inputs/solids_model.rst | 39 ++++++++++--------- docs/source_docs/user_guide/introduction.rst | 8 ++-- .../user_guide/run-time_inputs.rst | 8 ++-- 9 files changed, 69 insertions(+), 82 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index aa4b6f7..4289016 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -27,7 +27,7 @@ The following inputs are defined using the prefix ``chemistry``: | | |tol_eq| | | | | | | | | +--------------------------+---------------------------------------------------------+----------+----------------+ -| solids.update_type | How to update solids quantities due to chemical | | ConstantVolume | +| solids.update_type | How to update solids quantities due to chemical | String | ConstantVolume | | | reactions. | | | | | | | | | | Options: | | | diff --git a/docs/source_docs/user_guide/inputs/fluid_model.rst b/docs/source_docs/user_guide/inputs/fluid_model.rst index cbbfe2e..198894b 100644 --- a/docs/source_docs/user_guide/inputs/fluid_model.rst +++ b/docs/source_docs/user_guide/inputs/fluid_model.rst @@ -8,10 +8,11 @@ The following inputs are defined using the prefix ``fluid``: +--------------------------------------------+-------------------------------------------------------------+--------+----------+ | | Description | Type | Default | +============================================+=============================================================+========+==========+ -| solve | Specify the name of the fluid or set to ``None`` to disable | String | "None" | -| | the fluid solver. The name assigned to the fluid solver is | | | -| | used to specify fluid properties and initial and boundary | | | -| | conditions. It is common to use the name ``fluid``. | | | +| solve | Specify the name of the fluid or set to empty string or | String | None | +| | ``None`` to disable the fluid solver. The name assigned to | | | +| | the fluid solver is used to specify fluid properties and | | | +| | initial and boundary conditions. It is common to use the | | | +| | name ``fluid``. | | | +--------------------------------------------+-------------------------------------------------------------+--------+----------+ diff --git a/docs/source_docs/user_guide/inputs/initial_conditions.rst b/docs/source_docs/user_guide/inputs/initial_conditions.rst index fa19cfd..579419c 100644 --- a/docs/source_docs/user_guide/inputs/initial_conditions.rst +++ b/docs/source_docs/user_guide/inputs/initial_conditions.rst @@ -44,7 +44,7 @@ using the compound prefix ``ic.[region_name].[fluid_name]``: +------------------------+------------------------------------------------------------------------+-------------+-----------+ | temperature | Fluid temperature | Real | 0 | +------------------------+------------------------------------------------------------------------+-------------+-----------+ -| species.[species_name] | Mass fraction of ``species_name`` | Real | 0 | +| species.[species_name] | Mass fraction of ``species_name``. Species must be a fluid species. | Real | 0 | +------------------------+------------------------------------------------------------------------+-------------+-----------+ @@ -90,7 +90,7 @@ please refer to :ref:`ReferenceParticleDistributions `_ has been integrated into MFIX-Exa for *in situ* visualization. +MFIX-Exa must be built with Ascent support to use this feature. + +The following inputs must be preceded by the prefix ``mfix`` and control frequency of the Ascent pipeline. + +----------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | @@ -16,13 +21,12 @@ format (for debugging). +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -`Ascent `_ has been integrated into MFIX-Exa for *in situ* visualization. -For codes that have been built with Ascent support, the following input must be preceded by the prefix -``ascent``, -and specifies the ascent actions for fluid and/or particles. The frequency which these are called -is controlled by `ascent_int` or `ascent_per_approx`, see above. Note that if an ascent pipeline -is being included in a GPU build/run, then you must enable managed memory, -i.e., set `amrex.the_arena_is_managed = true`. +The following input must be preceded by the prefix ``ascent``, +and specifies the Ascent actions for fluid and/or particles. The frequency which these are called +is controlled by ``ascent_int`` or ``ascent_per_approx``, see above. Note that if an Ascent pipeline +is being included in a GPU build/run, then you must enable managed memory,i.e., set +``amrex.the_arena_is_managed = true``. + +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | diff --git a/docs/source_docs/user_guide/inputs/output/plotting.rst b/docs/source_docs/user_guide/inputs/output/plotting.rst index d408dbf..7ec117b 100644 --- a/docs/source_docs/user_guide/inputs/output/plotting.rst +++ b/docs/source_docs/user_guide/inputs/output/plotting.rst @@ -4,7 +4,7 @@ Plotfiles and other output ========================== The following inputs must be preceded by the prefix ``mfix`` and control frequency and naming of plotfile generation as well -as whether the EB geometry or level set should be written, and if the particles should be written out in Ascii +as whether the EB geometry or level set should be written, and if the particles should be written out in ASCII format (for debugging). +----------------------+-----------------------------------------------------------------------+-------------+-----------+ @@ -20,23 +20,17 @@ format (for debugging). +----------------------+-----------------------------------------------------------------------+-------------+-----------+ | plot_file | Prefix to use for plotfile output | String | plt | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -| par_ascii_file | Prefix to use for ascii particle output | String | par | +| par_ascii_file | Prefix to use for ASCII particle output | String | par | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -| par_ascii_int | Frequency of ascii particle output; | Int | -1 | -| | if -1 then no particle ascii files will be written | | | +| par_ascii_int | Frequency of ASCII particle output; | Int | -1 | +| | if -1 then no particle ASCII files will be written | | | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -| par_ascii_per_approx | Time period of the ascii particle output (approximate); | Real | -1 | -| | if -1 then particle ascii files will not be written at this frequency | | | +| par_ascii_per_approx | Time period of the ASCII particle output (approximate); | Real | -1 | +| | if -1 then particle ASCII files will not be written at this frequency | | | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ | file_digits | Number of digits to use in plotfile (plt[0-9]+) and checkpoint | Int | 5 | | | (chk[0-9]+) filenames. | | | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -| ascent_int | Frequency of ascent pipeline; | Int | -1 | -| | if -1 then ascent will not be called. | | | -+----------------------+-----------------------------------------------------------------------+-------------+-----------+ -| ascent_per_approx | Time period of the ascent pipeline (approximate); | Real | -1 | -| | if -1 then ascent will not be called. | | | -+----------------------+-----------------------------------------------------------------------+-------------+-----------+ The following inputs must be preceded by the prefix ``mfix`` and control which variables will be written in plotfiles. @@ -98,22 +92,6 @@ The following inputs must be preceded by the prefix ``mfix`` and control whether +----------------------+--------------------------------------------------------------------------+-------------+-----------+ -`Ascent `_ has been integrated into MFIX-Exa for *in situ* visualization. -For codes that have been built with Ascent support, the following input must be preceded by the prefix -``ascent`` -and specifies the ascent actions for fluid and/or particles. The frequency which these are called -is controlled by `ascent_int` or `ascent_per_approx`, see above. Note that if an ascent pipeline -is being included in a GPU build/run, then you must enable managed memory, -i.e., set `amrex.the_arena_is_managed = true`. - -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+=====================+=======================================================================+=============+===========+ -| actions | yaml file of the ascent actions (ex. ascent_actions.yaml). If no file | String | | -| | name is provided, then calls to Ascent are skipped. | | | -+---------------------+-----------------------------------------------------------------------+-------------+-----------+ - - The following inputs must be preceded by the prefix ``mfix.solids`` and allow to write additional plotfiles which contain only solids variables in specific regions at fixed timesteps or approximated simulation times. All these parameters are user-defined. @@ -178,3 +156,7 @@ region. mfix.solids.my_region.plot_int = 10 mfix.solids.my_region.plt_vel_p = 1 + + +`Ascent` has been integrated into MFIX-Exa for *in situ* visualization. +See :ref:`Ascent` for details. diff --git a/docs/source_docs/user_guide/inputs/solids_model.rst b/docs/source_docs/user_guide/inputs/solids_model.rst index aabca8b..4921217 100644 --- a/docs/source_docs/user_guide/inputs/solids_model.rst +++ b/docs/source_docs/user_guide/inputs/solids_model.rst @@ -6,7 +6,7 @@ Solids model Solids settings --------------- -Enabling the SOLIDS solver and specifying options common to both DEM and PIC +Enabling the solids solver and specifying options common to both DEM and PIC models. The following inputs are defined with the prefix ``solids``: +------------------------------------------+-------------------------------------------------------------+----------+----------+ @@ -42,15 +42,14 @@ models. The following inputs are defined with the prefix ``solids``: | reference_temperature | Reference temperature used for specific enthalpy. | Real | 0 | +------------------------------------------+-------------------------------------------------------------+----------+----------+ | species | Specify which species can constitute | Strings | None | -| | the solids phase [defined species must | | | -| | be a subset of the species.solve | | | -| | arguments]. | | | +| | the solids phase. Defined species must | | | +| | be a subset of the species defined in ``species.solve`` | | | +------------------------------------------+-------------------------------------------------------------+----------+----------+ -| newton_solver.absolute_tol | Define absolute tolerance for damped Newton solver | Real | 1.e-6 | +| newton_solver.absolute_tol | Define absolute tolerance for damped Newton solver. | Real | 1.e-6 | +------------------------------------------+-------------------------------------------------------------+----------+----------+ -| newton_solver.relative_tol | Define relative tolerance for damped Newton solver | Real | 1.e-6 | +| newton_solver.relative_tol | Define relative tolerance for damped Newton solver. | Real | 1.e-6 | +------------------------------------------+-------------------------------------------------------------+----------+----------+ -| newton_solver.max_iterations | Define max number of iterations for damped Newton solver | Int | 100 | +| newton_solver.max_iterations | Define max number of iterations for damped Newton solver. | Int | 100 | +------------------------------------------+-------------------------------------------------------------+----------+----------+ | thermal_conductivity | Specify which thermal conductivity model to use for solids. | String | constant | | | Options: | | | @@ -155,17 +154,19 @@ Enabling the DEM solver and specifying model options. The following keys must b The following inputs use the DEM type names specified using the `dem.solve` input to define restitution coefficients and -are proceeded with the prefix ``dem.restitution_coeff``. These must be defined for all solid-solid and solid-wall combinations. - -+-------------------------+-------------------------------------------------------------------------+----------+-----------+ -| | Description | Type | Default | -+=========================+=========================================================================+==========+===========+ -| [solid0].[solid1] | Specifies the restitution coefficient between solid0 and solid1. Here | Real | 0 | -| | the order is not important and could be defined as [solid1].[solid0] | | | -+-------------------------+-------------------------------------------------------------------------+----------+-----------+ -| [solid0].wall | Specifies the restitution coefficient between solid0 and the wall. | Real | 0 | -| | Order is not important and this could be defined as wall.[solid0] | | | -+-------------------------+-------------------------------------------------------------------------+----------+-----------+ +are proceeded with the prefix ``dem.restitution_coeff``. These must be defined for all DEM solid-solid and solid-wall combinations. + ++--------------------------+-------------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++==========================+=========================================================================+==========+===========+ +| [dem_solid].[dem_solid2] | Specifies the restitution coefficient between DEM solids. | Real | 0 | +| | Order is not important and this could be defined as | | | +| |``[dem_solid2].[dem_solid]``. If both are defined they must be equal. | | | ++--------------------------+-------------------------------------------------------------------------+----------+-----------+ +| [dem_solid].wall | Specifies the restitution coefficient between solid and the wall. | Real | 0 | +| | Order is not important and this could be defined as | | | +| |``wall.[dem_solid]``. If both are defined they must be equal. | | | ++--------------------------+-------------------------------------------------------------------------+----------+-----------+ Below is an example for specifying the inputs for two DEM solids. @@ -242,7 +243,7 @@ The following inputs are defined with the prefix ``pic``: +------------------------------------+-------------------------------------------------------------------------+----------+-----------+ | | Description | Type | Default | +====================================+=========================================================================+==========+===========+ -| solve | Specified name(s) of the PIC types or None to disable the PIC solver. | Strings | "None" | +| solve | Specified name(s) of the PIC types or None to disable the PIC solver. | Strings | None | +------------------------------------+-------------------------------------------------------------------------+----------+-----------+ | close_pack | Solids volume fraction at close pack, :math:`\varepsilon_{cp}`. | Real | 0.55 | | | Below this threshold, the solid stress tensor has minimal impact. | | | diff --git a/docs/source_docs/user_guide/introduction.rst b/docs/source_docs/user_guide/introduction.rst index ebc27e6..3ec0718 100644 --- a/docs/source_docs/user_guide/introduction.rst +++ b/docs/source_docs/user_guide/introduction.rst @@ -12,12 +12,12 @@ time discretizations differ. Specifically, - Fluid velocity is defined at cell centers; pressure is defined at nodes. - The advection algorithm includes an intermediate MAC projection for - face-centered advection velocities + face-centered advection velocities. - Incompressibility of the fluid is imposed through the use of a projection at - the end of the time step + the end of the time step. - The representation of the complex geometry includes mesh refinement around the fluid-solid interface, which is represented used the embedded boundary, or - cut-cell approach + cut-cell approach. - Parallelization via flat MPI, OpenMP, hybrid MPI/OpenMP, or MPI/MPI. - Porting of MFIX-Exa to GPUs is in progress. - Parallel I/O using AMReX native I/O or HDF5. @@ -29,5 +29,3 @@ MFIX-Exa heavily leverages `AMReX`_ which is also supported by ECP as part of the AMReX Co-Design Center. .. _AMReX: https://amrex-codes.github.io/ - - diff --git a/docs/source_docs/user_guide/run-time_inputs.rst b/docs/source_docs/user_guide/run-time_inputs.rst index f355078..ba96555 100644 --- a/docs/source_docs/user_guide/run-time_inputs.rst +++ b/docs/source_docs/user_guide/run-time_inputs.rst @@ -41,14 +41,14 @@ keywords such as ``mfix``, ``amr``, ``geometry``, ``nodal_proj`` etc. inputs/initialization inputs/time_stepping - inputs/domain - inputs/geometry inputs/mesh_and_gridding - inputs/multigrid_solvers inputs/model_options + inputs/multigrid_solvers + inputs/domain + inputs/geometry + inputs/species inputs/fluid_model inputs/solids_model - inputs/species inputs/chemical_reactions inputs/regions inputs/initial_conditions -- GitLab From 6fd8974585f7a388fbc79cf53e9fc9416dc1d9dd Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 24 Nov 2025 09:41:42 -0600 Subject: [PATCH 2/3] update docs --- nonexistent-keys.txt | 20 +++++++++++++++++--- undocumented-keys.txt | 14 +------------- 2 files changed, 18 insertions(+), 16 deletions(-) diff --git a/nonexistent-keys.txt b/nonexistent-keys.txt index 9ec8f04..72a209e 100644 --- a/nonexistent-keys.txt +++ b/nonexistent-keys.txt @@ -1,12 +1,27 @@ -csg.geometry_filename +# This group may be incorrect +bc.[region_name].[solid_name].bins +bc.[region_name].[solid_name].density.custom +bc.[region_name].[solid_name].density.max +bc.[region_name].[solid_name].density.mean +bc.[region_name].[solid_name].density.min +bc.[region_name].[solid_name].density.std +bc.[region_name].[solid_name].diameter +bc.[region_name].[solid_name].diameter.constant +bc.[region_name].[solid_name].diameter.custom +bc.[region_name].[solid_name].diameter.max +bc.[region_name].[solid_name].diameter.mean +bc.[region_name].[solid_name].diameter.min +bc.[region_name].[solid_name].diameter.std +bc.[region_name].[solid_name].massflow +bc.[region_name].[solid_name].type ic.[region_name].[solid_name].bins ic.[region_name].[solid_name].type + mac_proj.bottom_maxiter mac_proj.bottom_verbose mac_proj.maxiter mac_proj.verbose mfix.deposition_diffusion_coeff -mfix.godunov_ppm mfix.plt_T_p mfix.plt_drag_p mfix.plt_omega_p @@ -27,4 +42,3 @@ nodal_proj.bottom_maxiter nodal_proj.bottom_verbose nodal_proj.maxiter nodal_proj.verbose -stl.geometry_filename \ No newline at end of file diff --git a/undocumented-keys.txt b/undocumented-keys.txt index 9ac9c76..0b4dd2c 100644 --- a/undocumented-keys.txt +++ b/undocumented-keys.txt @@ -1,12 +1,5 @@ [fluid_name].trac0 -bc.[region_name].[solid_name].density -bc.[region_name].[solid_name].density.constant -bc.[region_name].[solid_name].species.[species_name] -bc.[region_name].[solid_name].temperature -bc.[region_name].[solid_name].velocity -bc.[region_name].[solid_name].volflow -bc.[region_name].[solid_name].volfrac -bc.[region_name].solids +amrex.use_gpu_aware_mpi catalyst.catalyst_on_restart catalyst.enabled catalyst.implementation @@ -48,7 +41,6 @@ mfix.deposition.filter.constant mfix.deposition.filter.variable mfix.deposition.filter.variable.min_eps mfix.geom_chk_ccse_regtest -mfix.geometry_filename mfix.monitors.[monitor_name].count mfix.overstep_end_time mfix.particle_sorting_bin @@ -81,12 +73,8 @@ mfix.solids.[region_name].plt_ptype mfix.solids.[region_name].plt_vm_coeff mfix.sort_particle_int mfix.stop_for_unused_inputs -mfix.tag.grad_rho -mfix.tag.regions -mfix.tag.rho mfix.test_tracer_conservation mfix.use_new_depdt_algo -mfix.use_ppm particles.reduceGhostParticles pic2dem.convert stl.internal_flow -- GitLab From a9e7fc5c67ed201c60e2b7b84a8a47aba35ae2d4 Mon Sep 17 00:00:00 2001 From: Charles G Waldman Date: Mon, 24 Nov 2025 09:44:21 -0600 Subject: [PATCH 3/3] Update docs, change section order --- docs/source_docs/user_guide/inputs/solids_model.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/solids_model.rst b/docs/source_docs/user_guide/inputs/solids_model.rst index 4921217..1436464 100644 --- a/docs/source_docs/user_guide/inputs/solids_model.rst +++ b/docs/source_docs/user_guide/inputs/solids_model.rst @@ -161,11 +161,11 @@ are proceeded with the prefix ``dem.restitution_coeff``. These must be defined f +==========================+=========================================================================+==========+===========+ | [dem_solid].[dem_solid2] | Specifies the restitution coefficient between DEM solids. | Real | 0 | | | Order is not important and this could be defined as | | | -| |``[dem_solid2].[dem_solid]``. If both are defined they must be equal. | | | +| | ``[dem_solid2].[dem_solid]``. If both are defined they must be equal. | | | +--------------------------+-------------------------------------------------------------------------+----------+-----------+ | [dem_solid].wall | Specifies the restitution coefficient between solid and the wall. | Real | 0 | | | Order is not important and this could be defined as | | | -| |``wall.[dem_solid]``. If both are defined they must be equal. | | | +| | ``wall.[dem_solid]``. If both are defined they must be equal. | | | +--------------------------+-------------------------------------------------------------------------+----------+-----------+ Below is an example for specifying the inputs for two DEM solids. -- GitLab