From e1ec0e4776bbc3f01dd45acad6d91e4fffae0c51 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Fri, 12 Jan 2024 08:45:02 -0500 Subject: [PATCH 1/3] Start of major reorg of docs --- docs/source_docs/EB_Chapter.rst | 2 +- .../ManagingGridHierarchy_Chapter.rst | 2 +- docs/source_docs/Particles_Chapter.rst | 2 +- docs/source_docs/conf.py | 18 +- .../fluids/FluidTimeDiscretization.rst | 2 +- docs/source_docs/index.rst | 28 +- docs/source_docs/inputs/InputsCoupling.rst | 283 ------------- .../inputs/InputsDiscretization.rst | 42 -- docs/source_docs/inputs/InputsHypre.rst | 83 ---- docs/source_docs/inputs/InputsVerbosity.rst | 15 - docs/source_docs/qb/index.rst | 2 +- .../Hpc.rst => references/hpc.rst} | 6 +- .../hpc/Bridges2.rst | 0 .../hpc/Crusher.rst | 0 .../hpc/Delta.rst | 0 .../hpc/Frontier.rst | 0 .../hpc/Joule2.rst | 0 .../hpc/Perlmutter.rst | 0 .../hpc/Polaris.rst | 0 .../hpc/Summit.rst | 0 docs/source_docs/references/units.rst | 51 +++ .../InputsPICtoDEM.rst => tools/pic2dem.rst} | 0 .../inputs/InputsProblemDefinition.rst | 124 +----- .../user_guide/inputs/advanced.rst | 48 +++ .../user_guide/inputs/boundary_conditions.rst | 194 +++++++++ .../user_guide/inputs/chemical_reactions.rst | 30 ++ .../user_guide/inputs/fluid_model.rst | 76 ++++ .../user_guide/inputs/geometry_and_eb.rst | 33 ++ .../inputs/images}/centroid.jpg | Bin .../inputs/images}/dpvm.jpg | Bin .../inputs/images}/square_dpvm.jpg | Bin .../user_guide/inputs/images/transient-bc.png | Bin 0 -> 36417 bytes .../inputs/images}/trilinear.jpg | Bin .../user_guide/inputs/initial_conditions.rst | 215 ++++++++++ .../inputs/initialization.rst} | 29 +- .../inputs/mesh_and_gridding.rst} | 108 +++-- .../user_guide/inputs/model_options.rst | 397 ++++++++++++++++++ .../inputs/multigrid-solvers.rst} | 165 ++++++-- docs/source_docs/user_guide/inputs/output.rst | 13 + .../user_guide/inputs/output/ascent.rst | 31 ++ .../inputs/output/checkpointing.rst} | 4 +- .../inputs/output/monitors.rst} | 47 --- .../inputs/output/plotfiles.rst} | 0 .../user_guide/inputs/output/spatial_avgs.rst | 42 ++ .../user_guide/inputs/regions_defs.rst | 26 ++ .../user_guide/inputs/solids_model.rst | 133 ++++++ .../user_guide/inputs/species_defs.rst | 105 +++++ .../inputs/time-stepping.rst} | 103 +++-- .../introduction.rst} | 2 + .../quick-start.rst} | 9 +- .../quick_start}/BuildingMFIX.rst | 0 .../quick_start}/FirstSimulation.rst | 0 .../quick_start}/Paraview.rst | 12 +- .../quick_start}/Visualization.rst | 2 +- .../quick_start}/images/paraview_all.png | Bin .../images/paraview_browse_plt.png | Bin .../quick_start}/images/paraview_cells.png | Bin .../images/paraview_cells_threshold.png | Bin .../quick_start}/images/paraview_eb.png | Bin .../quick_start}/images/paraview_pt_gauss.png | Bin .../images/paraview_pt_gauss_opts.png | Bin .../quick_start}/images/paraview_reader.png | Bin .../run-time_inputs.rst} | 33 +- 63 files changed, 1763 insertions(+), 754 deletions(-) delete mode 100644 docs/source_docs/inputs/InputsCoupling.rst delete mode 100644 docs/source_docs/inputs/InputsDiscretization.rst delete mode 100644 docs/source_docs/inputs/InputsHypre.rst delete mode 100644 docs/source_docs/inputs/InputsVerbosity.rst rename docs/source_docs/{getting_started/Hpc.rst => references/hpc.rst} (90%) rename docs/source_docs/{getting_started => references}/hpc/Bridges2.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Crusher.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Delta.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Frontier.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Joule2.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Perlmutter.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Polaris.rst (100%) rename docs/source_docs/{getting_started => references}/hpc/Summit.rst (100%) create mode 100644 docs/source_docs/references/units.rst rename docs/source_docs/{inputs/InputsPICtoDEM.rst => tools/pic2dem.rst} (100%) rename docs/source_docs/{ => user_guide}/inputs/InputsProblemDefinition.rst (89%) create mode 100644 docs/source_docs/user_guide/inputs/advanced.rst create mode 100644 docs/source_docs/user_guide/inputs/boundary_conditions.rst create mode 100644 docs/source_docs/user_guide/inputs/chemical_reactions.rst create mode 100644 docs/source_docs/user_guide/inputs/fluid_model.rst create mode 100644 docs/source_docs/user_guide/inputs/geometry_and_eb.rst rename docs/source_docs/{inputs/figures => user_guide/inputs/images}/centroid.jpg (100%) rename docs/source_docs/{inputs/figures => user_guide/inputs/images}/dpvm.jpg (100%) rename docs/source_docs/{inputs/figures => user_guide/inputs/images}/square_dpvm.jpg (100%) create mode 100644 docs/source_docs/user_guide/inputs/images/transient-bc.png rename docs/source_docs/{inputs/figures => user_guide/inputs/images}/trilinear.jpg (100%) create mode 100644 docs/source_docs/user_guide/inputs/initial_conditions.rst rename docs/source_docs/{inputs/InputsInitialization.rst => user_guide/inputs/initialization.rst} (63%) rename docs/source_docs/{inputs/InputsLoadBalancing.rst => user_guide/inputs/mesh_and_gridding.rst} (82%) create mode 100644 docs/source_docs/user_guide/inputs/model_options.rst rename docs/source_docs/{inputs/InputsMultigrid.rst => user_guide/inputs/multigrid-solvers.rst} (53%) create mode 100644 docs/source_docs/user_guide/inputs/output.rst create mode 100644 docs/source_docs/user_guide/inputs/output/ascent.rst rename docs/source_docs/{inputs/InputsCheckpoint.rst => user_guide/inputs/output/checkpointing.rst} (99%) rename docs/source_docs/{inputs/InputsMonitors.rst => user_guide/inputs/output/monitors.rst} (89%) rename docs/source_docs/{inputs/InputsPlotFiles.rst => user_guide/inputs/output/plotfiles.rst} (100%) create mode 100644 docs/source_docs/user_guide/inputs/output/spatial_avgs.rst create mode 100644 docs/source_docs/user_guide/inputs/regions_defs.rst create mode 100644 docs/source_docs/user_guide/inputs/solids_model.rst create mode 100644 docs/source_docs/user_guide/inputs/species_defs.rst rename docs/source_docs/{inputs/InputsTimeStepping.rst => user_guide/inputs/time-stepping.rst} (57%) rename docs/source_docs/{Introduction.rst => user_guide/introduction.rst} (99%) rename docs/source_docs/{GettingStarted_Chapter.rst => user_guide/quick-start.rst} (80%) rename docs/source_docs/{getting_started => user_guide/quick_start}/BuildingMFIX.rst (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/FirstSimulation.rst (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/Paraview.rst (89%) rename docs/source_docs/{getting_started => user_guide/quick_start}/Visualization.rst (94%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_all.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_browse_plt.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_cells.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_cells_threshold.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_eb.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_pt_gauss.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_pt_gauss_opts.png (100%) rename docs/source_docs/{getting_started => user_guide/quick_start}/images/paraview_reader.png (100%) rename docs/source_docs/{Inputs_Chapter.rst => user_guide/run-time_inputs.rst} (73%) diff --git a/docs/source_docs/EB_Chapter.rst b/docs/source_docs/EB_Chapter.rst index 328a0c8..677a2b9 100644 --- a/docs/source_docs/EB_Chapter.rst +++ b/docs/source_docs/EB_Chapter.rst @@ -10,7 +10,7 @@ refining the computational meshes near walls. .. toctree:: - :maxdepth: 1 + :maxdepth: 0 :caption: Contents: eb/EBWalls diff --git a/docs/source_docs/ManagingGridHierarchy_Chapter.rst b/docs/source_docs/ManagingGridHierarchy_Chapter.rst index 0ded985..17a8acb 100644 --- a/docs/source_docs/ManagingGridHierarchy_Chapter.rst +++ b/docs/source_docs/ManagingGridHierarchy_Chapter.rst @@ -32,7 +32,7 @@ tiles to OpenMP threads. See in the AMReX documentation for more about tiling. .. toctree:: - :maxdepth: 1 + :maxdepth: 0 grid/GridCreation grid/DualGrid diff --git a/docs/source_docs/Particles_Chapter.rst b/docs/source_docs/Particles_Chapter.rst index 0a3ce79..f23d319 100644 --- a/docs/source_docs/Particles_Chapter.rst +++ b/docs/source_docs/Particles_Chapter.rst @@ -20,7 +20,7 @@ particle-particle, particle-fluid, and particle-wall interactions. .. toctree:: - :maxdepth: 1 + :maxdepth: 0 :caption: Contents: particles/ParticleBasics diff --git a/docs/source_docs/conf.py b/docs/source_docs/conf.py index 46f5b55..b07a662 100644 --- a/docs/source_docs/conf.py +++ b/docs/source_docs/conf.py @@ -34,7 +34,8 @@ import sphinx_rtd_theme extensions = ['sphinx.ext.mathjax', 'sphinx.ext.githubpages', 'sphinx.ext.viewcode', - 'sphinx_tabs.tabs'] + 'sphinx_tabs.tabs', + 'sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['ytemplates'] @@ -95,7 +96,20 @@ html_theme = 'sphinx_rtd_theme' # further. For a list of options available for each theme, see the # documentation. # -# html_theme_options = {} +html_theme_options = { + 'logo_only': False, + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + 'vcs_pageview_mode': '', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 3, + 'includehidden': True, + 'titles_only': False +} + # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, diff --git a/docs/source_docs/fluids/FluidTimeDiscretization.rst b/docs/source_docs/fluids/FluidTimeDiscretization.rst index 2654ad8..e1e8265 100644 --- a/docs/source_docs/fluids/FluidTimeDiscretization.rst +++ b/docs/source_docs/fluids/FluidTimeDiscretization.rst @@ -4,7 +4,7 @@ Time Discretization .. toctree:: - :maxdepth: 1 + :maxdepth: 0 FluidTimeStep Slopes diff --git a/docs/source_docs/index.rst b/docs/source_docs/index.rst index 78d9cbf..7d9dc38 100644 --- a/docs/source_docs/index.rst +++ b/docs/source_docs/index.rst @@ -1,11 +1,11 @@ .. MFIX-Exa documentation master file, created Thu Aug 2 12:19:39 2018. .. warning:: - This documentation is a work in progress. - It is reasonably complete and hopefully useful + This documentation is a work in progress. + It is reasonably complete and hopefully useful but is likely error prone and in places misleading. - Please report any errors to the - `MFIX-Exa User Forum `_. + Please report any errors to the + `MFIX-Exa User Forum `_. Welcome to MFIX-Exa's documentation! @@ -42,30 +42,38 @@ To get started with MFIX-Exa, follow the user guide sections: :maxdepth: 1 :caption: User guide: - Introduction - GettingStarted_Chapter - Inputs_Chapter - ManagingGridHierarchy_Chapter + Introduction + Quick start guide + Run-time inputs To learn more about the implementation, follow the following reference sections: .. toctree:: - :maxdepth: 1 + :maxdepth: 0 :caption: Reference: + references/units Fluids_Chapter Particles_Chapter EB_Chapter + references/hpc Debugging +.. toctree:: + :maxdepth: 0 + :caption: Tools: + + tools/pic2dem + The following section detail the testing and benchmarks used to ensure solutions and performance: .. toctree:: - :maxdepth: 1 + :maxdepth: 0 :caption: Tests and Benchmarks: + ManagingGridHierarchy_Chapter RunningTestSuite RegressionTesting CITests diff --git a/docs/source_docs/inputs/InputsCoupling.rst b/docs/source_docs/inputs/InputsCoupling.rst deleted file mode 100644 index ad026f0..0000000 --- a/docs/source_docs/inputs/InputsCoupling.rst +++ /dev/null @@ -1,283 +0,0 @@ -Interphase Coupling -=================== - -Deposition scheme ------------------ - -The following inputs must be preceded by "mfix." - -+----------------------------+---------------------------------------------------+--------+-------------+ -| | Description | Type | Default | -+============================+===================================================+========+=============+ -| deposition_scheme | The algorithm that will be used to deposit | String | 'trilinear' | -| | particles quantities to the Eulerian grid. | | | -| | Available methods are: | | | -| | | | | -| | * 'centroid' | | | -| | * 'trilinear' | | | -| | * 'true-dpvm' divided particle volume method | | | -| | * 'trilinear-dpvm-square' dpvm with square filter | | | -+----------------------------+---------------------------------------------------+--------+-------------+ -| deposition_scale_factor | The deposition scale factor. Only applies to | Real | 1.0 | -| | 'true-dpvm' and 'trilinear-dpvm-square' methods. | | | -| | Its value must be in the interval [0, dx/2], | | | -| | where dx is the cell edge size. | | | -+----------------------------+---------------------------------------------------+--------+-------------+ -| deposition_diffusion_coeff | If a positive value is set, a diffusion equation | Real | -1.0 | -| | with this diffusion coefficient is solved to | | | -| | smooth deposited quantities. | | | -+----------------------------+---------------------------------------------------+--------+-------------+ - -In the following subsections, the four possible deposition methods are briefly -described and illustrated. - - -Centroid -~~~~~~~~ -In the centroid deposition scheme, particles' quantities are deposited only to -the Eulerian grid cell to which the particle's center belongs. - -.. raw:: latex - - \begin{center} - - .. _fig:basics:amrgrids: - -.. figure:: ./figures/centroid.jpg - :height: 2in - - Example of centroid deposition. - -.. raw:: latex - - \end{center} - - -Trilinear -~~~~~~~~~ -In the trilinear deposition scheme, particles' quantities are deposited linearly -to the eight Eulerian grid cells that surround its center. - -.. raw:: latex - - \begin{center} - - .. _fig:basics:amrgrids: - -.. figure:: ./figures/trilinear.jpg - :height: 2in - - Example of trilinear deposition. - -.. raw:: latex - - \end{center} - - -Divided Particle Volume Method (DPVM) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In the DPVM method, particles' quantities are deposited to the Eulerian grid -cells that they intersect, and the deposition weights are equal to the -percentage of the particle' volume that intersects the given cell. - -.. raw:: latex - - \begin{center} - - .. _fig:basics:amrgrids: - -.. figure:: ./figures/dpvm.jpg - :height: 2in - - Example of dpvm deposition. - -.. raw:: latex - - \end{center} - - -Square DPVM -~~~~~~~~~~~ -In the square DPVM method, particles' quantities are deposited to the Eulerian -grid similarly to the DPVM method, but with a filter applied to the deposition -scheme. - -.. raw:: latex - - \begin{center} - - .. _fig:basics:amrgrids: - -.. figure:: ./figures/square_dpvm.jpg - :height: 2in - - Example of square dpvm deposition. - -.. raw:: latex - - \end{center} - - -Drag ----- - -The following inputs must be preceded by "mfix." - -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+===================+=======================================================================+=============+===========+ -| drag_type | Which drag model to use | String | None | -+-------------------+-----------------------------------------------------------------------+-------------+-----------+ - -The options currently supported in mfix are :cpp:`WenYu`, :cpp:`Gidaspow`, :cpp:`BVK2`, or :cpp:`UserDrag`. - -If one of these is not specified, the code will abort with - -.. highlight:: c++ - -:: - - amrex::Abort::0::"Don't know this drag type!!! - -The drag models are defined in src/src_des/des_drag_K.H - -If the user wishes to use their own drag model, they must - - * specify :cpp:`mfix.drag_type = UserDrag` in the inputs file - - * provide the code in the ComputeDragUser routine in a local usr_drag.cpp file. - An example can be found in tests/DEM06-x. - -With the variables defined as follows: - - .. code:: shell - - /* - * \brief Returns: the calculated drag coefficient. - * - * Inputs: - * EPg - gas volume fraction - * Mug - gas laminar viscosity - * ROpg - gas density * EP_g - * vrel - magnitude of gas-solids relative velocity - * DPM - particle diameter of solids phase M - * DPA - average particle diameter - * PHIS - solids volume fraction of solids phases - * fvelx - x component of the fluid velocity at the particle position - * fvely - y component of the fluid velocity at the particle position - * fvelz - z component of the fluid velocity at the particle position - * i, j, k - particle cell indices - * pid - particle id number - */ - -The :cpp:`WenYu` model is defined as - - .. code:: shell - - RE = (Mug > 0.0) ? DPM*vrel*ROPg/Mug : DEMParams::large_number; - - if (RE <= 1000.0) - { - C_d = (24.0/(RE+DEMParams::small_number)) * (1.0 + 0.15*std::pow(RE, 0.687)); - } - else - { - C_d = 0.44; - } - - if (RE < DEMParams::eps) return 0.0; - return 0.75 * C_d * vrel * ROPg * std::pow(EPg, -2.65) / DPM; - -The :cpp:`Gidaspow` model is defined as - - .. code:: shell - - ROg = ROPg / EPg; - - RE = (Mug > 0.0) ? DPM*vrel*ROPg/Mug : DEMParams::large_number; - - // Dense phase - EPg <= 0.8 - Ergun = 150.0*(1.0 - EPg)*Mug / (EPg*DPM*DPM) + 1.75*ROg*vrel/DPM; - - // Dilute phase - EPg > 0.8 - if (RE <= 1000.0) - { - C_d = (24.0/(RE+DEMParams::small_number)) * (1.0 + 0.15*std::pow(RE, 0.687)); - } - else - { - C_d = 0.44; - } - - WenYu = 0.75*C_d*vrel*ROPg*std::pow(EPg, -2.65) / DPM; - - // switch function - PHI_gs = atan(150.0*1.75*(EPg - 0.8))/M_PI / DPM; - - // blend the models - if (RE < DEMParams::eps) return 0.0; - return (1.0 - PHI_gs)*Ergun + PHI_gs*WenYu; - -The :cpp:`BVK2` model is defined as - - .. code:: shell - - amrex::Real RE = (Mug > 0.0) ? DPA*vrel*ROPg/Mug : DEMParams::large_number; - - if (RE > DEMParams::eps) - { - oEPgfour = 1.0 / EPg / EPg / EPg / EPg; - - // eq(9) BVK J. fluid. Mech. 528, 2005 - // (this F_Stokes is /= of Koch_Hill by a factor of ep_g) - F_Stokes = 18.0*Mug*EPg/DPM/DPM; - - F = 10.0*PHIS/EPg/EPg + EPg*EPg*(1.0 + 1.5*sqrt(PHIS)); - - F += RE*(0.11*PHIS*(1.0+PHIS) - 4.56e-3*oEPgfour + - std::pow(RE, -0.343)*(0.169*EPg + 6.44e-2*oEPgfour)); - - // F += 0.413*RE/(24.0*EPg*EPg) * - // (1.0/EPg + 3.0*EPg*PHIS + 8.4/std::pow(RE, 0.343)) / - // (1.0 + std::pow(10.0, 3.0*PHIS)/std::pow(RE, 0.5 + 2.0*PHIS)); - - return F*F_Stokes; - } - else - { - return 0.0; - } - - - -Heat Transfer Coefficient -------------------------- - - -The following inputs must be preceded by "mfix." - -+-------------------+---------------------------------+-------------+--------------+ -| | Description | Type | Default | -+===================+=================================+=============+==============+ -| convection_type | Which HTC model to use | String | RanzMarshall | -+-------------------+---------------------------------+-------------+--------------+ - -The options currently supported in mfix are :cpp:`RanzMarshall` (default) and :cpp:`Gunn`. -In both models the HTC is determined from a Nusslet number corelation. - -The RanzMarshall Nusselt number correlation is defined as: - - .. code:: shell - - amrex::Real N_Nu = 2.0 + 0.6 * std::sqrt(N_Re) * std::pow(N_Pr, 0.333); - - -The Gunn Nusselt number correlation is defined as: - - .. code:: shell - - amrex::Real N_Nu = - (7 - 10*EPg + 5*EPg*EPg)*(1 + .7*std::pow(N_Re, 0.2)*std::cbrt(N_Pr)) - + (1.33 - 2.4*EPg + 1.2*EPg*EPg)*std::pow(N_Re, 0.7)*std::cbrt(N_Pr); - - diff --git a/docs/source_docs/inputs/InputsDiscretization.rst b/docs/source_docs/inputs/InputsDiscretization.rst deleted file mode 100644 index 9d91fd7..0000000 --- a/docs/source_docs/inputs/InputsDiscretization.rst +++ /dev/null @@ -1,42 +0,0 @@ -.. sec:InputsDiscretization: - -Discretization -============== - -The following inputs must be preceded by "mfix." - -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| Key | Description | Type | Default | -+=================================+=======================================================================+=============+==============+ -| advection_type | Predictor-Corrector Method of Lines ("mol") or Godunov ("godunov") | String | Godunov | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| redistribution_type | Use flux ("FluxRedist"), state ("StateRedist") or no ("NoRedist") | | | -| | redistribution | String | StateRedist | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| redistribute_before_nodal_proj | Redistribute the velocity field before the nodal projection | Bool | True | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| redistribute_nodal_proj | Redistribute the velocity field after the nodal projection | Bool | False | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| use_drag_coeff_in_proj_gp | Algebraically consistent p coeff in proj or (default) simplified form | Bool | False | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| use_drag_in_godunov | Include a drag term in the Godunov flux or (default) not | Bool | False | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| correction_small_volfrac | Threshold volume fraction for correcting small cell velocity | | | -| | at the end of the predictor and corrector | Real | 1.e-4 | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| deposition_redist_type | Redistribute excess solids using max packing ("MaxPack") or state | | | -| | ("StateRedist") algorithms. | String | MaxPack | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| deposition_redist_vfrac | The threshold cell volume fraction when using "StateRedist" | | | -| | for deposition redistribution. | Real | 0.1 | -+---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ - -Notes: The code was originally developed with MOL and FluxRedist. Preliminary -tests show that the new single-step Godunov method is roughly twice as fast as -the predictor-corrector MOL at the same time step (e.g., CFL limited to 0.5). -Further, the Godunov method allows for roughly twice the time step, CFL should -be limited to 0.9 for stability. Finally, it is recommended that the Godunov -method be used in conjunction with StateRedist. While not fully vetted, early -tests also show increased stability in complex geometries for a StateRedist- -Godunov scheme compared to the previous FluxRedist-MOL scheme. - diff --git a/docs/source_docs/inputs/InputsHypre.rst b/docs/source_docs/inputs/InputsHypre.rst deleted file mode 100644 index 2d4e792..0000000 --- a/docs/source_docs/inputs/InputsHypre.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _Chap:InputsHypre: - -Hypre Inputs -============= - -The following inputs control the hypre settings and are read directly -by AMReX when we use hypre as the bottom solver, i.e., when -:cpp:`nodal_proj.bottom_solver = hypre` and/or when -:cpp:`mac_proj.bottom_solver = hypre` (see :ref:`Chap:InputsMultigrid`) -These settings must be preceded by the hypre_namespace setting corresponding -to the solver (see :ref:`Chap:InputsMultigrid`). - -NOTE: By default, the MAC and nodal projections use the same settings -specified with the namespace :cpp:`hypre`, however the solvers can be configured -separately by specifying :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace`. - -When not using the default namespace :cpp:`hypre`, additional restrictions apply: - -#. Both :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be set. - -#. :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be unique. - - -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| | Description | Type | Default | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| verbose | Verbosity of hypre | Int | 0 | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| adjust_singular_matrix | Should be true if the problem to be solved has singular matrix | Bool | false | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| hypre_solver | Type of hypre solver | String | BoomerAMG | -| | | | | -| | Options are BoomerAMG, GMRES, COGMRES, LGMRES, FlexGMRES, BiCGSTAB, | | | -| | PCG or Hybrid | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| hypre_preconditioner | Type of preconditioner | String | none | -| | | | | -| | Options are BoomerAMG or euclid | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| recompute_preconditioner | Recompute preconditioner during runs | Bool | true | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| write_matrix_files | Write out matrix into text files | Bool | false | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| overwrite_existing_matrix_files | Over-write existing matrix files | Bool | false | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_verbose | Verbosity of BoomerAMG preconditioner | Int | 0 | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_logging | When using BoomerAMG preconditioner | Int | 0 | -| | | | | -| | See HYPRE_BoomerAMGSetLogging | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_coarsen_type | When using BoomerAMG preconditioner | Int | 6 | -| | | | | -| | See HYPRE_BoomerAMGSetCoarsenType | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_cycle_type | When using BoomerAMG preconditioner | Int | 1 | -| | | | | -| | See HYPRE_BoomerAMGSetCycleType | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_relax_type | When using BoomerAMG preconditioner | Int | 6 | -| | | | | -| | See HYPRE_BoomerAMGSetRelaxType | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_relax_order | When using BoomerAMG preconditioner | Int | 1 | -| | | | | -| | See HYPRE_BoomerAMGSetRelaxOrder | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_num_sweeps | When using BoomerAMG preconditioner | Int | 2 | -| | | | | -| | See HYPRE_BoomerAMGSetNumSweeps | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_max_levels | When using BoomerAMG preconditioner | Int | 20 | -| | | | | -| | See HYPRE_BoomerAMGSetMaxLevels | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_strong_threshold | When using BoomerAMG preconditioner | Real | 0.57 | -| | | | | -| | See HYPRE_BoomerAMGSetStrongThreshold | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_interp_type | When using BoomerAMG preconditioner | Int | 0 | -| | | | | -| | HYPRE_BoomerAMGSetInterpType | | | -+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ diff --git a/docs/source_docs/inputs/InputsVerbosity.rst b/docs/source_docs/inputs/InputsVerbosity.rst deleted file mode 100644 index 26906f5..0000000 --- a/docs/source_docs/inputs/InputsVerbosity.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _Chap:InputsVerbosity: - -Verbosity -========= - -The following inputs must be preceded by "mfix." - -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| | Description | Type | Default | -+======================+=======================================================================+=============+==============+ -| verbose | Verbosity in MFIX-Exa routines | Int | 0 | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| ooo_debug | If true then print the name of the routine we are in | Bool | False | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ - diff --git a/docs/source_docs/qb/index.rst b/docs/source_docs/qb/index.rst index fe9081e..686fcca 100644 --- a/docs/source_docs/qb/index.rst +++ b/docs/source_docs/qb/index.rst @@ -17,7 +17,7 @@ can be seen in the .. toctree:: - :maxdepth: 1 + :maxdepth: 0 hcs granRT diff --git a/docs/source_docs/getting_started/Hpc.rst b/docs/source_docs/references/hpc.rst similarity index 90% rename from docs/source_docs/getting_started/Hpc.rst rename to docs/source_docs/references/hpc.rst index 337fc8c..cd56c6f 100644 --- a/docs/source_docs/getting_started/Hpc.rst +++ b/docs/source_docs/references/hpc.rst @@ -9,7 +9,7 @@ Follow the guide here instead of the generic instructions. .. toctree:: :caption: DOE Systems - :maxdepth: 1 + :maxdepth: 0 hpc/Frontier hpc/Summit @@ -20,14 +20,14 @@ Follow the guide here instead of the generic instructions. .. toctree:: :caption: NSF Systems - :maxdepth: 1 + :maxdepth: 0 hpc/Delta hpc/Bridges2 .. toctree:: :caption: NETL Systems - :maxdepth: 1 + :maxdepth: 0 hpc/Joule2 diff --git a/docs/source_docs/getting_started/hpc/Bridges2.rst b/docs/source_docs/references/hpc/Bridges2.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Bridges2.rst rename to docs/source_docs/references/hpc/Bridges2.rst diff --git a/docs/source_docs/getting_started/hpc/Crusher.rst b/docs/source_docs/references/hpc/Crusher.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Crusher.rst rename to docs/source_docs/references/hpc/Crusher.rst diff --git a/docs/source_docs/getting_started/hpc/Delta.rst b/docs/source_docs/references/hpc/Delta.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Delta.rst rename to docs/source_docs/references/hpc/Delta.rst diff --git a/docs/source_docs/getting_started/hpc/Frontier.rst b/docs/source_docs/references/hpc/Frontier.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Frontier.rst rename to docs/source_docs/references/hpc/Frontier.rst diff --git a/docs/source_docs/getting_started/hpc/Joule2.rst b/docs/source_docs/references/hpc/Joule2.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Joule2.rst rename to docs/source_docs/references/hpc/Joule2.rst diff --git a/docs/source_docs/getting_started/hpc/Perlmutter.rst b/docs/source_docs/references/hpc/Perlmutter.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Perlmutter.rst rename to docs/source_docs/references/hpc/Perlmutter.rst diff --git a/docs/source_docs/getting_started/hpc/Polaris.rst b/docs/source_docs/references/hpc/Polaris.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Polaris.rst rename to docs/source_docs/references/hpc/Polaris.rst diff --git a/docs/source_docs/getting_started/hpc/Summit.rst b/docs/source_docs/references/hpc/Summit.rst similarity index 100% rename from docs/source_docs/getting_started/hpc/Summit.rst rename to docs/source_docs/references/hpc/Summit.rst diff --git a/docs/source_docs/references/units.rst b/docs/source_docs/references/units.rst new file mode 100644 index 0000000..55159b0 --- /dev/null +++ b/docs/source_docs/references/units.rst @@ -0,0 +1,51 @@ +System of Units +=============== + +MFIX-Exa adopts the International System of Units (SI). Simulations have to be +set up accordingly. In the following table we provide a list of some of the +physical quantities we can specify in the input file and their correspondent +units. + ++----------------------------+-----------------------------------------+ +| Physical quantity | MFIX-Exa SI unit | ++============================+=========================================+ +| amount of substance | mole [:math:`mol`] | ++----------------------------+-----------------------------------------+ +| length | meter [:math:`m`] | ++----------------------------+-----------------------------------------+ +| mass | kilogram [:math:`kg`] | ++----------------------------+-----------------------------------------+ +| time | second [:math:`s`] | ++----------------------------+-----------------------------------------+ +| force | Newton [:math:`N`] | ++----------------------------+-----------------------------------------+ +| temperature | Kelvin [:math:`K`] | ++----------------------------+-----------------------------------------+ +| pressure | Pascal [:math:`Pa`] | ++----------------------------+-----------------------------------------+ +| energy | Joule [:math:`J`] | ++----------------------------+-----------------------------------------+ +| power | Watt [:math:`W`] | ++----------------------------+-----------------------------------------+ +| density | [:math:`kg \cdot m^{-3}`] | ++----------------------------+-----------------------------------------+ +| velocity | [:math:`m \cdot s^{-1}`] | ++----------------------------+-----------------------------------------+ +| dynamic viscosity | [:math:`Pa \cdot s`] | ++----------------------------+-----------------------------------------+ +| diffusivity | [:math:`m^2 \cdot s^{-1}`] | ++----------------------------+-----------------------------------------+ +| specific heat capacity | [:math:`J \cdot kg^{-1} \cdot K^{-1}`] | ++----------------------------+-----------------------------------------+ +| thermal conductivity | [:math:`W \cdot m^{-1} \cdot K^{-1}`] | ++----------------------------+-----------------------------------------+ +| spring coefficient | [:math:`N \cdot m^{-1}`] | ++----------------------------+-----------------------------------------+ +| molecular weight | [:math:`kg \cdot mol^{-1}`] | ++----------------------------+-----------------------------------------+ +| heat of formation | [:math:`J \cdot kg^{-1}`] | ++----------------------------+-----------------------------------------+ +| chemical reaction rate | [:math:`mol \cdot m^{-3} \cdot s^{-1}`] | ++----------------------------+-----------------------------------------+ + + diff --git a/docs/source_docs/inputs/InputsPICtoDEM.rst b/docs/source_docs/tools/pic2dem.rst similarity index 100% rename from docs/source_docs/inputs/InputsPICtoDEM.rst rename to docs/source_docs/tools/pic2dem.rst diff --git a/docs/source_docs/inputs/InputsProblemDefinition.rst b/docs/source_docs/user_guide/inputs/InputsProblemDefinition.rst similarity index 89% rename from docs/source_docs/inputs/InputsProblemDefinition.rst rename to docs/source_docs/user_guide/inputs/InputsProblemDefinition.rst index 4b34859..f5c60f5 100644 --- a/docs/source_docs/inputs/InputsProblemDefinition.rst +++ b/docs/source_docs/user_guide/inputs/InputsProblemDefinition.rst @@ -6,90 +6,8 @@ specify the settings of the problem at hand. The input file must be passed as first argument to the MFIX-Exa executable. -System of Units ---------------- - -MFIX-Exa adopts the International System of Units (SI). Simulations have to be -set up accordingly. In the following table we provide a list of some of the -physical quantities we can specify in the input file and their correspondent -units. - -+----------------------------+-----------------------------------------+ -| Physical quantity | MFIX-Exa SI unit | -+============================+=========================================+ -| amount of substance | mole [:math:`mol`] | -+----------------------------+-----------------------------------------+ -| length | meter [:math:`m`] | -+----------------------------+-----------------------------------------+ -| mass | kilogram [:math:`kg`] | -+----------------------------+-----------------------------------------+ -| time | second [:math:`s`] | -+----------------------------+-----------------------------------------+ -| force | Newton [:math:`N`] | -+----------------------------+-----------------------------------------+ -| temperature | Kelvin [:math:`K`] | -+----------------------------+-----------------------------------------+ -| pressure | Pascal [:math:`Pa`] | -+----------------------------+-----------------------------------------+ -| energy | Joule [:math:`J`] | -+----------------------------+-----------------------------------------+ -| power | Watt [:math:`W`] | -+----------------------------+-----------------------------------------+ -| density | [:math:`kg \cdot m^{-3}`] | -+----------------------------+-----------------------------------------+ -| velocity | [:math:`m \cdot s^{-1}`] | -+----------------------------+-----------------------------------------+ -| dynamic viscosity | [:math:`Pa \cdot s`] | -+----------------------------+-----------------------------------------+ -| diffusivity | [:math:`m^2 \cdot s^{-1}`] | -+----------------------------+-----------------------------------------+ -| specific heat capacity | [:math:`J \cdot kg^{-1} \cdot K^{-1}`] | -+----------------------------+-----------------------------------------+ -| thermal conductivity | [:math:`W \cdot m^{-1} \cdot K^{-1}`] | -+----------------------------+-----------------------------------------+ -| spring coefficient | [:math:`N \cdot m^{-1}`] | -+----------------------------+-----------------------------------------+ -| molecular weight | [:math:`kg \cdot mol^{-1}`] | -+----------------------------+-----------------------------------------+ -| heat of formation | [:math:`J \cdot kg^{-1}`] | -+----------------------------+-----------------------------------------+ -| chemical reaction rate | [:math:`mol \cdot m^{-3} \cdot s^{-1}`] | -+----------------------------+-----------------------------------------+ - - -Mesh settings -------------- - -There are some settings we can specify for the mesh and the automatic mesh -refinement algorithm. These settings must be preceded by "amr." in the input -file. - -+-------------------+---------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+===================+=====================================================================+=============+===========+ -| n_cell | Number of cells at level 0 in each coordinate direction | Ints | 0 0 0 | -+-------------------+---------------------------------------------------------------------+-------------+-----------+ -| max_level | Maximum level of refinement allowed (0 when single-level) | Int | 0 | -+-------------------+---------------------------------------------------------------------+-------------+-----------+ - - -Geometry settings ------------------ - -The following inputs must be preceded by "geometry." -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+=================+=======================================================================+=============+===========+ -| coord_sys | 0 for Cartesian | Int | 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| is_periodic | 1 for true, 0 for false (one value for each coordinate direction) | Ints | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_lo | Low corner of physical domain (physical not index space) | Reals | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_hi | High corner of physical domain (physical not index space) | Reals | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ MFIX-Exa settings @@ -101,14 +19,6 @@ The following inputs must be preceded by "mfix." +------------------------+-------------------------------------------------------------------+----------+---------------------+ | | Description | Type | Default | +========================+===================================================================+==========+=====================+ -| geometry | Which type of amrex EB geometry are we using? | String | | -| | | | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ -| geometry_filename | The CSG file that defines the EB geometry | String | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ -| levelset__refinement | Refinement factor of levelset resolution relative to level 0 | Int | 1 | -| | resolution | | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ | gravity | Gravity vector (e.g., mfix.gravity = -9.81 0.0 0.0) [required] | Reals | 0 0 0 | +------------------------+-------------------------------------------------------------------+----------+---------------------+ | advect_density | Switch for turning ON (1) or OFF (0) fluid density evolution | Int | 0 | @@ -743,10 +653,10 @@ Below is an example for specifying boundary conditions for a fluid `myfluid`. 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: +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 @@ -758,12 +668,12 @@ by replacing: bc.inflow.my_fluid.temperature = 4.0 500 bc.inflow.my_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. +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. Boundary Conditions on Embedded Boundaries @@ -777,7 +687,7 @@ tridimensional). We recall that, on the remaining part of the EBs, homogeneous Neumann boundary conditions are assumed by default. In the following table there is a list of the possible entries for EB boundary -conditions. Each entry must be preceded by `bc.[region0].` +conditions. Each entry must be preceded by `bc.[region0].` +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | @@ -853,12 +763,12 @@ Below is an example where only specific cells are imposed a velocity in the x-di bc.eb-flow.my_fluid.velocity = 0.1 0.0 0.0 -Constraints +Constraints ----------- -Additional constraints may be imposed on problems which are under-determined by IBCs, -typically occurring in periodic domains. Currently, only particle constraints are supported. -The prefix `particles.` should be applied to all input keywords listed below. +Additional constraints may be imposed on problems which are under-determined by IBCs, +typically occurring in periodic domains. Currently, only particle constraints are supported. +The prefix `particles.` should be applied to all input keywords listed below. +---------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | @@ -881,7 +791,7 @@ For the `mean_velocity` constraint, the following inputs can be defined. | mean_velocity_z | mean particle velocity in dir=2 | Real | Undefined | +------------------------+------------------------------------------------------------------------+-------------+-----------+ -Below is an example for zero mean particle velocity in all three directions. +Below is an example for zero mean particle velocity in all three directions. .. code-block:: none @@ -890,4 +800,4 @@ Below is an example for zero mean particle velocity in all three directions. particles.constraint.mean_velocity_x = 0. particles.constraint.mean_velocity_y = 0. particles.constraint.mean_velocity_z = 0. - + diff --git a/docs/source_docs/user_guide/inputs/advanced.rst b/docs/source_docs/user_guide/inputs/advanced.rst new file mode 100644 index 0000000..7ce68e8 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/advanced.rst @@ -0,0 +1,48 @@ +.. _Chap:InputsVerbosity: + +Advanced +======== + +Testing / debugging +------------------- + +The following inputs must be preceded by "mfix." + ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++========================+=======================================================================+=============+==============+ +| verbose | Verbosity in MFIX-Exa routines | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| ooo_debug | If true then print the name of the routine we are in | Bool | False | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| only_print_grid_report | Do not time-march the simulation. Simply generate the grid report | Bool | False | +| | and exit. | | False | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ + + +The following inputs must be preceded by "amrex." + ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++========================+=======================================================================+=============+==============+ +| fpe_trap_invalid | Abort if an invalid floating point exception is encountered. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| fpe_trap_zero | Abort if a division by zero is computed. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| fpe_trap_overflow | Abort if and overflow is detected. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ + +GPU memory +---------- + +The following inputs must be preceded by "amrex." + ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++========================+=======================================================================+=============+==============+ +| the _arena_is_managed | Abort if an invalid floating point exception is encountered. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| abort_on_out_of_gpu_memory | rt if a division by zero is computed. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| the_area_init_size | Abort if and overflow is detected. | Int | 0 | ++------------------------+-----------------------------------------------------------------------+-------------+--------------+ diff --git a/docs/source_docs/user_guide/inputs/boundary_conditions.rst b/docs/source_docs/user_guide/inputs/boundary_conditions.rst new file mode 100644 index 0000000..67d2291 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/boundary_conditions.rst @@ -0,0 +1,194 @@ +Boundary Conditions +=================== + + +General boundary conditions +--------------------------- + +The following inputs are defined using the ``bc`` prefix. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| regions | Regions used to define boundary conditions. | String | None | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +The type of the boundary conditions in the BC region must be defined. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| [region] | Used to define boundary condition type. Available options include: | String | None | +| | | | | +| | * 'pi' for pressure inflow BC type | | | +| | * 'po' for pressure outflow BC type | | | +| | * 'mi' for mass inflow BC type | | | +| | * 'nsw' for no-slip wall BC type | | | +| | * 'eb' for inhomogeneous Dirichlet BCs of temperature or fluid | | | +| | velocity (mass inflow) on the contained EBs | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| po_no_par_out | Let particles exit (default) or bounce-back at pressure outflows | Int | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +Fluid settings +~~~~~~~~~~~~~~ + +For each boundary condition region, the fluid inputs are defined +using the ``bc.[region].[fluid]`` prefix. + + ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++========================+========================================================================+=============+===========+ +| volfrac | Volume fraction [required if bc_region_type='mi'] | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| density | Fluid density [required if bc_region_type='mi' or 'pi'] | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| pressure | Fluid pressure [required if bc_region_type='po' or 'pi'] | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| temperature | Fluid temperature [required if bc_region_type='mi' or 'pi'] | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| velocity | Velocity components [required if bc_region_type='mi'] | Reals | 0 0 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| delp_dir | Direction for specified pressure drop. Note that this direction | Int | 0 | +| | should also be periodic. | | | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| delp | Pressure drop (Pa) | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| species.[species0] | Species 'species0' mass fraction [required if solve_species=1 | Real | 0 | +| | and bc_region_type='mi' or 'pi']. | | | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ + +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 + + +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 + +Embedded boundary options +------------------------- + +In MFIX-Exa it is possible to set boundary conditions on the embedded +boundaries. For instance, it is possible to set inhomogeneous Dirichlet boundary +conditions for the fluid temperature variable on the subpart of the embedded +boundaries which is contained in the BC region (which in this case has to be +tridimensional). We recall that, on the remaining part of the EBs, homogeneous +Neumann boundary conditions are assumed by default. + +In the following table there is a list of the possible entries for EB boundary +conditions. Each entry must be preceded by `bc.[region0].` + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| eb.temperature | Inhomogeneous Dirichlet BC value for temperature on EBs contained in | Real | 0.0 | +| | the (tridimensional) region [required if advect_enthalpy=1 and | | | +| | bc_region_type='eb']. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +Below is an example for specifying boundary conditions for a fluid `myfluid`. + +.. code-block:: none + + bc.regions = hot-wall + + bc.hot-walls = eb + bc.hot-walls.eb.temperature = 800 + +In addition to the temperature, it is possible to set an inflow condition for fluid +on an embedeed boundary. We recall that, on the remaining part of the EBs, +no slip velocity conditions are assumed by default. + +In the following table there is a list of the possible entries for inflow EB boundary +conditions. Each entry must be preceded by `bc.[region0].` Like traditional mass +inflows, the fluid temperature, pressure, and species composition must be +provided when appropriate. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| fluid.velocity | (Required if not `volflow`) Inflow fluid velocity on EB faces | Reals | 0 0 0 | +| | contained in the (tridimensional) region. | | | +| | Note that if only one value is specified, that is assumed to | | | +| | be the magnitude in the direction of the EB face's normal. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| fluid.volflow | (Required if not `velocity`) Inflow BC for fluid volumetric flow | Real | 0 | +| | rate in the (tridimensional) region. The flow is assumed to be | | | +| | normal to the EB surface in the region. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| fluid.volfrac | (Required) Volume fraction. | Real | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| eb.normal | (Optional) When specified, only cells with EB face normal that is | Reals | 0 0 0 | +| | parallel and opposite in direction to the specified values | | | +| | are imposed with the inflow velocity. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| eb.normal_tol | (Optional) Used in conjunction with `eb.normal`. It determines the | Real | 0 | +| | tolerance (in degrees) for choosing cells with a specific normal. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +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 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 diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst new file mode 100644 index 0000000..73111dd --- /dev/null +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -0,0 +1,30 @@ +Chemical Reactions +================== + +Enabling the Chemical Reactions solver and specifying model options. + ++-------------------------+----------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++=========================+======================================================================+==========+===========+ +| chemistry.solve | Specified name(s) of the chemical reactions types or None to disable | String | None | +| | the reactions solver. | | | ++-------------------------+----------------------------------------------------------------------+----------+-----------+ + +The following inputs must be preceded by the "chemistry." prefix + ++------------------------+---------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++========================+=========================================================+==========+===========+ +| [reaction0].reaction | Chemical formula for the given reaction. The string | String | None | +| | given as input must not contain white spaces and | | | +| | the reaction direction has to be specified as '-->' | | | +| | or '<--'. Chemical species phases must be defined as | | | +| | '(g)' for the fluid phase or '(s)' for the solid phase. | | | ++------------------------+---------------------------------------------------------+----------+-----------+ + +.. code-block:: none + + chemistry.solve = my_reaction0 my_reaction1 + + my_reaction0.reaction = Fe2O3(s)+CO(g)-->2.FeO(s)+CO2(g) + my_reaction1.reaction = FeO(s)+0.25O2(g)-->0.5Fe2O3(s) diff --git a/docs/source_docs/user_guide/inputs/fluid_model.rst b/docs/source_docs/user_guide/inputs/fluid_model.rst new file mode 100644 index 0000000..caa8449 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/fluid_model.rst @@ -0,0 +1,76 @@ +Fluid model +=========== + +Enabling the fluid solver and specifying fluid model options. +The following inputs must be preceded by the given to the fluid solver e.g., "fluid." + ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| | Description | Type | Default | ++==========================================+==========================================================+========+==========+ +| solve | Specify the names of the fluids or None to disable the | String | None | +| | fluid solver. The name assigned to the fluid solver is | | | +| | used to specify fluids inputs. | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| molecular_weight | Value of constant fluid molecular weight | Real | 0 | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| viscosity | Specify which viscosity model to use for fluid | String | None | +| | [required]. Available options include: | | | +| | | | | +| | * 'constant' for constant viscosity model | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| viscosity.constant | Value of constant fluid viscosity [required if | Real | 0 | +| | viscosity_model='constant']. | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| specific_heat | Specify which specific heat model to use for fluid | String | None | +| | [required if advect_enthalpy]. Available options | | | +| | include: | | | +| | | | | +| | * 'constant' for constant specific heat model | | | +| | * 'mixture' required when fluid is a mixture of species | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| specific_heat.constant | Value of constant fluid specific heat [required if | Real | 0 | +| | specific_heat_model='constant']. | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| thermal_conductivity | Specify which thermal conductivity model to use for | String | None | +| | fluid [required if advect_enthalpy=1]. available | | | +| | options include: | | | +| | | | | +| | * 'constant' for constant thermal conductivity model | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| thermal_conductivity.constant | Value of constant fluid thermal conductivity [required | Real | 0 | +| | if thermal_conductivity_model='constant']. | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| thermodynamic_pressure | Value of the thermodynamic pressure [required if the | Real | 0 | +| | constraint type is IdealGasClosedSystem] | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| reference_temperature | Value of the reference temperature used for specific | Real | 0 | +| | enthalpy | Real | 0 | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| species | Specify which species can constitute the fluid phase | String | None | +| | [defined species must be a subset of the species.solve | | | +| | arguments] | | | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| newton_solver.absolute_tol | Define absolute tolerance for Damped-Newton solver | Real | 1.e-8 | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| newton_solver.relative_tol | Define relative tolerance for Damped-Newton solver | Real | 1.e-8 | ++------------------------------------------+----------------------------------------------------------+--------+----------+ +| newton_solver.max_iterations | Define max number of iterations for Damped-Newton solver | int | 500 | ++------------------------------------------+----------------------------------------------------------+--------+----------+ + +Below is an example for specifying fluid solver model options. + +.. code-block:: none + + fluid.solve = my_fluid + + fluid.viscosity = constant + fluid.viscosity.constant = 1.8e-5 + + fluid.reference_temperature = 298.15 + + fluid.thermal_conductivity = constant + fluid.thermal_conductivity.constant = 0.024 + + fluid.specific_heat = mixture + + fluid.species = O2 CO CO2 diff --git a/docs/source_docs/user_guide/inputs/geometry_and_eb.rst b/docs/source_docs/user_guide/inputs/geometry_and_eb.rst new file mode 100644 index 0000000..4995604 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/geometry_and_eb.rst @@ -0,0 +1,33 @@ +.. sec:InputsGeomAndEB: + +Geometry and EB +=============== + +The following inputs must be preceded by "geometry." + ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=================+=======================================================================+=============+===========+ +| coord_sys | 0 for Cartesian | Int | 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| is_periodic | 1 for true, 0 for false (one value for each coordinate direction) | Ints | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| prob_lo | Low corner of physical domain (physical not index space) | Reals | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| prob_hi | High corner of physical domain (physical not index space) | Reals | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ + + +The following inputs must be preceded by "mfix." + ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| | Description | Type | Default | ++========================+===================================================================+==========+=====================+ +| geometry | Which type of amrex EB geometry are we using? | String | | +| | | | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| geometry_filename | The CSG file that defines the EB geometry | String | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| levelset__refinement | Refinement factor of levelset resolution relative to level 0 | Int | 1 | +| | resolution | | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ diff --git a/docs/source_docs/inputs/figures/centroid.jpg b/docs/source_docs/user_guide/inputs/images/centroid.jpg similarity index 100% rename from docs/source_docs/inputs/figures/centroid.jpg rename to docs/source_docs/user_guide/inputs/images/centroid.jpg diff --git a/docs/source_docs/inputs/figures/dpvm.jpg b/docs/source_docs/user_guide/inputs/images/dpvm.jpg similarity index 100% rename from docs/source_docs/inputs/figures/dpvm.jpg rename to docs/source_docs/user_guide/inputs/images/dpvm.jpg diff --git a/docs/source_docs/inputs/figures/square_dpvm.jpg b/docs/source_docs/user_guide/inputs/images/square_dpvm.jpg similarity index 100% rename from docs/source_docs/inputs/figures/square_dpvm.jpg rename to docs/source_docs/user_guide/inputs/images/square_dpvm.jpg diff --git a/docs/source_docs/user_guide/inputs/images/transient-bc.png b/docs/source_docs/user_guide/inputs/images/transient-bc.png new file mode 100644 index 0000000000000000000000000000000000000000..1b5d38cb6d3d38e4142fe78d866120c93eb59c01 GIT binary patch literal 36417 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 0). | | | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| n_cell | Number of cells at level 0 in each coordinate direction | Ints | 0 0 0 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ + +Grids +^^^^^ -The following inputs must be preceded by "mfix." and determine how often we regrid. +The following inputs must be preceded by "amr." and determine how we create the grids. +----------------------+-----------------------------------------------------------------------+-------------+-----------+ | | Description | Type | Default | +======================+=======================================================================+=============+===========+ -| regrid_int | How often to regrid (in number of steps at level 0) | Int | -1 | -| | if regrid_int = -1 then no regridding will occur | | | +| max_grid_size_x | Maximum number of cells at level 0 in each grid in x-direction | Int | 32 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| max_grid_size_y | Maximum number of cells at level 0 in each grid in y-direction | Int | 32 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| max_grid_size_z | Maximum number of cells at level 0 in each grid in z-direction | Int | 32 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| blocking_factor_x | Each grid must be divisible by blocking_factor_x in x-direction | Int | 8 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| blocking_factor_y | Each grid must be divisible by blocking_factor_y in y-direction | Int | 8 | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| blocking_factor_z | Each grid must be divisible by blocking_factor_z in z-direction | Int | 8 | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ -The following inputs must be preceded by "fabarray_mfiter." and determine how we create the logical tiles: - -+----------------------+-----------------------------------------------------------------------+----------+-------------+ -| | Description | Type | Default | -+======================+=======================================================================+==========+=============+ -| tile_size | Maximum number of cells in each direction for (logical) tiles | IntVect | 1024000 | -| | (3D CPU-only) | | 1024000,8,8 | -+----------------------+-----------------------------------------------------------------------+----------+-------------+ The following inputs must be preceded by "particles." @@ -64,12 +65,31 @@ The following inputs must be preceded by "particles." | max_grid_size_z | Maximum number of cells at level 0 in each grid in z-direction | Int | 32 | | | for grids in the ParticleBoxArray if dual_grid is true. | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ + +Tiles +^^^^^ + +The following inputs must be preceded by "fabarray_mfiter." and determine how we create the logical tiles: + ++----------------------+-----------------------------------------------------------------------+----------+-------------+ +| | Description | Type | Default | ++======================+=======================================================================+==========+=============+ +| tile_size | Maximum number of cells in each direction for (logical) tiles | IntVect | 1024000 | +| | (3D CPU-only) | | 1024000,8,8 | ++----------------------+-----------------------------------------------------------------------+----------+-------------+ + +The following inputs must be preceded by "particles." + ++----------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++======================+=======================================================================+=============+==============+ | tile_size | Maximum number of cells in each direction for (logical) tiles | IntVect | 1024000,8,8 | | | in the ParticleBoxArray if dual_grid is true. | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| reduceGhostParticles | Remove unused ghost particles from communication, | Bool | True | -| | only supported by GPU build | | | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ + + +Load balancing +-------------- Note that when running a granular simulation, i.e., no fluid phase, :cpp:`mfix.dual_grid` must be 0. Hence, the :cpp:`particles.max_grid_size` (in each direction) have no meaning. Therefore the fluid grid and tile @@ -83,6 +103,9 @@ The following inputs must be preceded by "mfix." and determine how we load balan +======================+=======================================================================+=============+==============+ | dual_grid | If true then use the "dual_grid" approach for load balancing | Bool | False | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ +| regrid_int | How often to regrid (in number of steps at level 0) | Int | -1 | +| | if regrid_int = -1 then no regridding will occur | | | ++----------------------+-----------------------------------------------------------------------+-------------+--------------+ | load_balance_fluid | Only relevant if (dual_grid); if so do we also regrid mesh data | Int | 0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | load_balance_type | What strategy to use for load balancing | String | KnapSack | @@ -109,11 +132,24 @@ The following inputs must be preceded by "mfix." and determine how we load balan | | disjoined grids | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -\* The greedy partitioning algorithm uses the tolerances to set the expected -workload range for each rank but doesn't strictly enforce them. The algorithm -creates a partition as balance as possible even if the partition doesn't +\* The greedy partitioning algorithm uses the tolerances to set the expected +workload range for each rank but doesn't strictly enforce them. The algorithm +creates a partition as balance as possible even if the partition doesn't meet the tolerances. -To allow a user to verify the breakdown of fluid grids created before running a full simulation, an input option, -:cpp:`mfix.only_print_grid_report` is supported. By default, it is :cpp:`False`. When set to :cpp:`True`, the run uses +To allow a user to verify the breakdown of fluid grids created before running a full simulation, an input option, +:cpp:`mfix.only_print_grid_report` is supported. By default, it is :cpp:`False`. When set to :cpp:`True`, the run uses minimal memory to print the grid coverage report and exits immediately after that. + + +.. todo:: Is this needed anymore? + + The following inputs must be preceded by "particles." + + +----------------------+-----------------------------------------------------------------------+-------------+--------------+ + | | Description | Type | Default | + +======================+=======================================================================+=============+==============+ + | reduceGhostParticles | Remove unused ghost particles from communication, | Bool | True | + | | only supported by GPU build | | | + +----------------------+-----------------------------------------------------------------------+-------------+--------------+ + diff --git a/docs/source_docs/user_guide/inputs/model_options.rst b/docs/source_docs/user_guide/inputs/model_options.rst new file mode 100644 index 0000000..63cc06c --- /dev/null +++ b/docs/source_docs/user_guide/inputs/model_options.rst @@ -0,0 +1,397 @@ +Model options +============= + +In this section it is described how the input file can be configured in order to +specify the settings of the problem at hand. The input file must be +passed as first argument to the MFIX-Exa executable. + + +The following inputs must be preceded by "mfix." + ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| | Description | Type | Default | ++========================+===================================================================+==========+=====================+ +| gravity | Gravity vector (e.g., mfix.gravity = -9.81 0.0 0.0) [required] | Reals | 0 0 0 | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| advect_density | Switch for turning ON (1) or OFF (0) fluid density evolution | Int | 0 | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| advect_enthalpy | Switch for turning ON (1) or OFF (0) fluid temperature evolution | Int | 0 | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| solve_species | Switch for turning ON (1) or OFF (0) fluid species mass fraction | Int | 0 | +| | evolution | | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| constraint_type | Select which constraint to apply to the problem. | String | IncompressibleFluid | +| | Available options include: | | | +| | | | | +| | * 'incompressiblefluid' for incompressibility constraint | | | +| | * 'idealgasopensystem' for Ideal Gas-Open System constraint | | | +| | * 'idealgasclosedsystem' for Ideal Gas-Closed System constraint | | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ + + +Fluid discretization +-------------------- + +The following inputs must be preceded by "mfix." + ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| Key | Description | Type | Default | ++=================================+=======================================================================+=============+==============+ +| advection_type | Predictor-Corrector Method of Lines ("mol") or Godunov ("godunov") | String | Godunov | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| redistribution_type | Use flux ("FluxRedist"), state ("StateRedist") or no ("NoRedist") | | | +| | redistribution | String | StateRedist | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| redistribute_before_nodal_proj | Redistribute the velocity field before the nodal projection | Bool | True | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| redistribute_nodal_proj | Redistribute the velocity field after the nodal projection | Bool | False | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| use_drag_coeff_in_proj_gp | Algebraically consistent p coeff in proj or (default) simplified form | Bool | False | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| use_drag_in_godunov | Include a drag term in the Godunov flux or (default) not | Bool | False | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| correction_small_volfrac | Threshold volume fraction for correcting small cell velocity | | | +| | at the end of the predictor and corrector | Real | 1.e-4 | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ + +Notes: The code was originally developed with MOL and FluxRedist. Preliminary +tests show that the new single-step Godunov method is roughly twice as fast as +the predictor-corrector MOL at the same time step (e.g., CFL limited to 0.5). +Further, the Godunov method allows for roughly twice the time step, CFL should +be limited to 0.9 for stability. Finally, it is recommended that the Godunov +method be used in conjunction with StateRedist. While not fully vetted, early +tests also show increased stability in complex geometries for a StateRedist- +Godunov scheme compared to the previous FluxRedist-MOL scheme. + + +Additional constraitns +---------------------- + +Additional constraints may be imposed on problems which are under-determined by IBCs, +typically occurring in periodic domains. Currently, only particle constraints are supported. +The prefix `particles.` should be applied to all input keywords listed below. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| constraint | Constraint type. Available options include: | String | None | +| | | | | +| | * 'mean_velocity' | | | +| | | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +For the `mean_velocity` constraint, the following inputs can be defined. + ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++========================+========================================================================+=============+===========+ +| mean_velocity_x | mean particle velocity in dir=0 | Real | Undefined | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| mean_velocity_y | mean particle velocity in dir=1 | Real | Undefined | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| mean_velocity_z | mean particle velocity in dir=2 | Real | Undefined | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ + +Below is an example for zero mean particle velocity in all three directions. + +.. code-block:: none + + particles.constraint = "mean_velocity" + + particles.constraint.mean_velocity_x = 0. + particles.constraint.mean_velocity_y = 0. + particles.constraint.mean_velocity_z = 0. + + +Deposition scheme +----------------- + +The following inputs must be preceded by "mfix." + ++----------------------------+---------------------------------------------------+--------+-------------+ +| | Description | Type | Default | ++============================+===================================================+========+=============+ +| deposition_scheme | The algorithm that will be used to deposit | String | 'trilinear' | +| | particles quantities to the Eulerian grid. | | | +| | Available methods are: | | | +| | | | | +| | * 'centroid' | | | +| | * 'trilinear' | | | +| | * 'true-dpvm' divided particle volume method | | | +| | * 'trilinear-dpvm-square' dpvm with square filter | | | ++----------------------------+---------------------------------------------------+--------+-------------+ +| deposition_scale_factor | The deposition scale factor. Only applies to | Real | 1.0 | +| | 'true-dpvm' and 'trilinear-dpvm-square' methods. | | | +| | Its value must be in the interval [0, dx/2], | | | +| | where dx is the cell edge size. | | | ++----------------------------+---------------------------------------------------+--------+-------------+ +| deposition_diffusion_coeff | If a positive value is set, a diffusion equation | Real | -1.0 | +| | with this diffusion coefficient is solved to | | | +| | smooth deposited quantities. | | | ++----------------------------+---------------------------------------------------+--------+-------------+ + +In the following subsections, the four possible deposition methods are briefly +described and illustrated. + + +Centroid +~~~~~~~~ +In the centroid deposition scheme, particles' quantities are deposited only to +the Eulerian grid cell to which the particle's center belongs. + +.. raw:: latex + + \begin{center} + + .. _fig:basics:amrgrids: + +.. figure:: ./images/centroid.jpg + :height: 2in + + Example of centroid deposition. + +.. raw:: latex + + \end{center} + + +Trilinear +~~~~~~~~~ +In the trilinear deposition scheme, particles' quantities are deposited linearly +to the eight Eulerian grid cells that surround its center. + +.. raw:: latex + + \begin{center} + + .. _fig:basics:amrgrids: + +.. figure:: ./images/trilinear.jpg + :height: 2in + + Example of trilinear deposition. + +.. raw:: latex + + \end{center} + + +Divided Particle Volume Method (DPVM) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +In the DPVM method, particles' quantities are deposited to the Eulerian grid +cells that they intersect, and the deposition weights are equal to the +percentage of the particle' volume that intersects the given cell. + +.. raw:: latex + + \begin{center} + + .. _fig:basics:amrgrids: + +.. figure:: ./images/dpvm.jpg + :height: 2in + + Example of dpvm deposition. + +.. raw:: latex + + \end{center} + + +Square DPVM +~~~~~~~~~~~ +In the square DPVM method, particles' quantities are deposited to the Eulerian +grid similarly to the DPVM method, but with a filter applied to the deposition +scheme. + +.. raw:: latex + + \begin{center} + + .. _fig:basics:amrgrids: + +.. figure:: ./images/square_dpvm.jpg + :height: 2in + + Example of square dpvm deposition. + +.. raw:: latex + + \end{center} + + + + +The following inputs must be preceded by "mfix." + ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| Key | Description | Type | Default | ++=================================+=======================================================================+=============+==============+ +| deposition_redist_type | Redistribute excess solids using max packing ("MaxPack") or state | | | +| | ("StateRedist") algorithms. | String | MaxPack | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| deposition_redist_vfrac | The threshold cell volume fraction when using "StateRedist" | | | +| | for deposition redistribution. | Real | 0.1 | ++---------------------------------+-----------------------------------------------------------------------+-------------+--------------+ + + + +Drag models +----------- + +The following inputs must be preceded by "mfix." + ++-------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++===================+=======================================================================+=============+===========+ +| drag_type | Which drag model to use | String | None | ++-------------------+-----------------------------------------------------------------------+-------------+-----------+ + +The options currently supported in mfix are :cpp:`WenYu`, :cpp:`Gidaspow`, :cpp:`BVK2`, or :cpp:`UserDrag`. + +If one of these is not specified, the code will abort with + +.. highlight:: c++ + +:: + + amrex::Abort::0::"Don't know this drag type!!! + +The drag models are defined in src/src_des/des_drag_K.H + +If the user wishes to use their own drag model, they must + + * specify :cpp:`mfix.drag_type = UserDrag` in the inputs file + + * provide the code in the ComputeDragUser routine in a local usr_drag.cpp file. + An example can be found in tests/DEM06-x. + +With the variables defined as follows: + + .. code:: shell + + EPg - gas volume fraction + Mug - gas laminar viscosity + ROpg - gas density * EP_g + vrel - magnitude of gas-solids relative velocity + DPM - particle diameter of solids phase M + DPA - average particle diameter + PHIS - solids volume fraction of solids phases + fvelx - x component of the fluid velocity at the particle position + fvely - y component of the fluid velocity at the particle position + fvelz - z component of the fluid velocity at the particle position + i, j, k - particle cell indices + pid - particle id number + + +The :cpp:`WenYu` model is defined as + + .. code:: shell + + RE = (Mug > 0.0) ? DPM*vrel*ROPg/Mug : DEMParams::large_number; + + if (RE <= 1000.0) + { + C_d = (24.0/(RE+DEMParams::small_number)) * (1.0 + 0.15*std::pow(RE, 0.687)); + } + else + { + C_d = 0.44; + } + + if (RE < DEMParams::eps) return 0.0; + return 0.75 * C_d * vrel * ROPg * std::pow(EPg, -2.65) / DPM; + +The :cpp:`Gidaspow` model is defined as + + .. code:: shell + + ROg = ROPg / EPg; + + RE = (Mug > 0.0) ? DPM*vrel*ROPg/Mug : DEMParams::large_number; + + // Dense phase - EPg <= 0.8 + Ergun = 150.0*(1.0 - EPg)*Mug / (EPg*DPM*DPM) + 1.75*ROg*vrel/DPM; + + // Dilute phase - EPg > 0.8 + if (RE <= 1000.0) + { + C_d = (24.0/(RE+DEMParams::small_number)) * (1.0 + 0.15*std::pow(RE, 0.687)); + } + else + { + C_d = 0.44; + } + + WenYu = 0.75*C_d*vrel*ROPg*std::pow(EPg, -2.65) / DPM; + + // switch function + PHI_gs = atan(150.0*1.75*(EPg - 0.8))/M_PI / DPM; + + // blend the models + if (RE < DEMParams::eps) return 0.0; + return (1.0 - PHI_gs)*Ergun + PHI_gs*WenYu; + +The :cpp:`BVK2` model is defined as + + .. code:: shell + + amrex::Real RE = (Mug > 0.0) ? DPA*vrel*ROPg/Mug : DEMParams::large_number; + + if (RE > DEMParams::eps) + { + oEPgfour = 1.0 / EPg / EPg / EPg / EPg; + + // eq(9) BVK J. fluid. Mech. 528, 2005 + // (this F_Stokes is /= of Koch_Hill by a factor of ep_g) + F_Stokes = 18.0*Mug*EPg/DPM/DPM; + + F = 10.0*PHIS/EPg/EPg + EPg*EPg*(1.0 + 1.5*sqrt(PHIS)); + + F += RE*(0.11*PHIS*(1.0+PHIS) - 4.56e-3*oEPgfour + + std::pow(RE, -0.343)*(0.169*EPg + 6.44e-2*oEPgfour)); + + // F += 0.413*RE/(24.0*EPg*EPg) * + // (1.0/EPg + 3.0*EPg*PHIS + 8.4/std::pow(RE, 0.343)) / + // (1.0 + std::pow(10.0, 3.0*PHIS)/std::pow(RE, 0.5 + 2.0*PHIS)); + + return F*F_Stokes; + } + else + { + return 0.0; + } + + + +Heat transfer coefficients +-------------------------- + + +The following inputs must be preceded by "mfix." + ++-------------------+---------------------------------+-------------+--------------+ +| | Description | Type | Default | ++===================+=================================+=============+==============+ +| convection_type | Which HTC model to use | String | RanzMarshall | ++-------------------+---------------------------------+-------------+--------------+ + +The options currently supported in mfix are :cpp:`RanzMarshall` (default) and :cpp:`Gunn`. +In both models the HTC is determined from a Nusslet number corelation. + +The RanzMarshall Nusselt number correlation is defined as: + + .. code:: shell + + amrex::Real N_Nu = 2.0 + 0.6 * std::sqrt(N_Re) * std::pow(N_Pr, 0.333); + + +The Gunn Nusselt number correlation is defined as: + + .. code:: shell + + amrex::Real N_Nu = + (7 - 10*EPg + 5*EPg*EPg)*(1 + .7*std::pow(N_Re, 0.2)*std::cbrt(N_Pr)) + + (1.33 - 2.4*EPg + 1.2*EPg*EPg)*std::pow(N_Re, 0.7)*std::cbrt(N_Pr); + + diff --git a/docs/source_docs/inputs/InputsMultigrid.rst b/docs/source_docs/user_guide/inputs/multigrid-solvers.rst similarity index 53% rename from docs/source_docs/inputs/InputsMultigrid.rst rename to docs/source_docs/user_guide/inputs/multigrid-solvers.rst index 6caaad5..9a6b9a0 100644 --- a/docs/source_docs/inputs/InputsMultigrid.rst +++ b/docs/source_docs/user_guide/inputs/multigrid-solvers.rst @@ -1,15 +1,19 @@ .. _Chap:InputsMultigrid: -Multigrid Inputs -================ +Multigrid solvers +================= -The following inputs can be set directly in the AMReX solver classes but we -set them via the MFIX-Exa routines because we may want different inputs for the -different solvers called by MFIX-Exa. -NOTE: the nodal solver settings are read in directly by AMReX, -the MAC and diffusion settings by MFIX-Exa. +The following inputs can be set directly in the AMReX solver classes but we +set them via the MFIX-Exa routines because we may want different inputs for the +different solvers called by MFIX-Exa. -These control the nodal projection and must be preceded by "nodal_proj.": +Nodal projection +---------------- + +NOTE: the nodal solver settings are read in directly by AMReX, +the MAC and diffusion settings by MFIX-Exa. + +These control the nodal projection and must be preceded by "nodal_proj.": +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | @@ -18,30 +22,34 @@ These control the nodal projection and must be preceded by "nodal_proj.": +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_verbose | Verbosity of BiCGStab solver in nodal projection | Int | 0 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_rtol | Relative tolerance in nodal projection | Real | 1.e-11 | +| mg_rtol | Relative tolerance in nodal projection | Real | 1.e-11 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_atol | Absolute tolerance in nodal projection | Real | 1.e-14 | +| mg_atol | Absolute tolerance in nodal projection | Real | 1.e-14 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| maxiter | Maximum number of iterations in the nodal projection | Int | 100 | +| maxiter | Maximum number of iterations in the nodal projection | Int | 100 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bottom_maxiter | Maximum number of iterations in the nodal projection | Int | 100 | +| bottom_maxiter | Maximum number of iterations in the nodal projection | Int | 100 | | | bottom solver if using bicg, cg, bicgcg or cgbicg | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_max_coarsening_level | Maximum number of coarser levels to allowin the nodal projection | Int | 100 | +| mg_max_coarsening_level | Maximum number of coarser levels to allowin the nodal projection | Int | 100 | | | If set to 0, the bottom solver will be called at the current level | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_solver | Which bottom solver to use in the nodal projection | String | bicgcg | -| | | | | -| | Options are bicgcg, bicgstab, cg, cgbicg, smoother or hypre | | | +| | | | | +| | Options are bicgcg, bicgstab, cg, cgbicg, smoother or hypre | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | hypre_namespace | Namespace to use in the nodal projection when using hypre | String | hypre | -| | to control hypre specific settings. It can be any string. | | | +| | to control hypre specific settings. It can be any string. | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | hypre_interface | Which interface to use in the nodal projection when using hypre | String | ij | -| | | | | -| | Options are ij, semi_structured or structured | | | +| | | | | +| | Options are ij, semi_structured or structured | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ + +MAC projection +-------------- + These control the MAC projection and must be preceded by "mac_proj.": +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ @@ -51,32 +59,36 @@ These control the MAC projection and must be preceded by "mac_proj.": +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_verbose | Verbosity of BiCGStab solver in MAC projection | Int | 0 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_rtol | Relative tolerance in MAC projection | Real | 1.e-11 | +| mg_rtol | Relative tolerance in MAC projection | Real | 1.e-11 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_atol | Absolute tolerance in MAC projection | Real | 1.e-14 | +| mg_atol | Absolute tolerance in MAC projection | Real | 1.e-14 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| maxiter | Maximum number of iterations in the MAC projection | Int | 200 | +| maxiter | Maximum number of iterations in the MAC projection | Int | 200 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bottom_maxiter | Maximum number of iterations in the MAC projection | Int | 200 | +| bottom_maxiter | Maximum number of iterations in the MAC projection | Int | 200 | | | bottom solver if using bicg, cg, bicgcg or cgbicg | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_max_coarsening_level | Maximum number of coarser levels to allow in the MAC projection | Int | 100 | +| mg_max_coarsening_level | Maximum number of coarser levels to allow in the MAC projection | Int | 100 | | | If set to 0, the bottom solver will be called at the current level | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_solver | Which bottom solver to use in the MAC projection | String | bicgcg | -| | | | | -| | Options are bicgcg, bicgstab, cg, cgbicg, smoother or hypre | | | +| | | | | +| | Options are bicgcg, bicgstab, cg, cgbicg, smoother or hypre | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | hypre_namespace | Namespace to use in the MAC projection when using hypre | String | hypre | -| | to control hypre specific settings. It can be any string. | | | +| | to control hypre specific settings. It can be any string. | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | hypre_interface | Which interface to use in the MAC projection when using hypre | String | ij | -| | | | | -| | Options are ij, semi_structured or structured | | | +| | | | | +| | Options are ij, semi_structured or structured | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -NOTE: If the :cpp:`nodal_proj` and :cpp:`mac_proj` :cpp:`hypre_namespace`'s are set, they must be distinct unless set to -:cpp:`hypre`, in which case the default behavior is recovered in which case hypre settings apply to all solvers. +NOTE: If the :cpp:`nodal_proj` and :cpp:`mac_proj` :cpp:`hypre_namespace`'s are set, they must be distinct unless set to +:cpp:`hypre`, in which case the default behavior is recovered in which case hypre settings apply to all solvers. + + +Diffusion +--------- These control the diffusion solver and must be preceded by "diffusion.": @@ -87,9 +99,9 @@ These control the diffusion solver and must be preceded by "diffusion.": +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_verbose | Verbosity of BiCGStab solver in diffusion solve | Int | 0 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_rtol | Relative tolerance in diffusion solve | Real | 1.e-11 | +| mg_rtol | Relative tolerance in diffusion solve | Real | 1.e-11 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_atol | Absolute tolerance in diffusion solve | Real | 1.e-14 | +| mg_atol | Absolute tolerance in diffusion solve | Real | 1.e-14 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | maxiter | Maximum number of iterations in diffusion solve | Int | 100 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ @@ -100,6 +112,91 @@ These control the diffusion solver and must be preceded by "diffusion.": | | If set to 0, the bottom solver will be called at the current level | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_solver | Which bottom solver to use in the diffusion solve | String | bicgcg | -| | | | | -| | Options are bicgcg, bicgstab, cg, cgbicg, or smoother | | | +| | | | | +| | Options are bicgcg, bicgstab, cg, cgbicg, or smoother | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ + + + +Hypre Settings +-------------- + +The following inputs control the hypre settings and are read directly +by AMReX when we use hypre as the bottom solver, i.e., when +:cpp:`nodal_proj.bottom_solver = hypre` and/or when +:cpp:`mac_proj.bottom_solver = hypre` (see :ref:`Chap:InputsMultigrid`) +These settings must be preceded by the hypre_namespace setting corresponding +to the solver (see :ref:`Chap:InputsMultigrid`). + +NOTE: By default, the MAC and nodal projections use the same settings +specified with the namespace :cpp:`hypre`, however the solvers can be configured +separately by specifying :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace`. + +When not using the default namespace :cpp:`hypre`, additional restrictions apply: + +#. Both :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be set. + +#. :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be unique. + + ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| verbose | Verbosity of hypre | Int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| adjust_singular_matrix | Should be true if the problem to be solved has singular matrix | Bool | false | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| hypre_solver | Type of hypre solver | String | BoomerAMG | +| | | | | +| | Options are BoomerAMG, GMRES, COGMRES, LGMRES, FlexGMRES, BiCGSTAB, | | | +| | PCG or Hybrid | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| hypre_preconditioner | Type of preconditioner | String | none | +| | | | | +| | Options are BoomerAMG or euclid | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| recompute_preconditioner | Recompute preconditioner during runs | Bool | true | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| write_matrix_files | Write out matrix into text files | Bool | false | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| overwrite_existing_matrix_files | Over-write existing matrix files | Bool | false | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_verbose | Verbosity of BoomerAMG preconditioner | Int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_logging | When using BoomerAMG preconditioner | Int | 0 | +| | | | | +| | See HYPRE_BoomerAMGSetLogging | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_coarsen_type | When using BoomerAMG preconditioner | Int | 6 | +| | | | | +| | See HYPRE_BoomerAMGSetCoarsenType | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_cycle_type | When using BoomerAMG preconditioner | Int | 1 | +| | | | | +| | See HYPRE_BoomerAMGSetCycleType | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_relax_type | When using BoomerAMG preconditioner | Int | 6 | +| | | | | +| | See HYPRE_BoomerAMGSetRelaxType | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_relax_order | When using BoomerAMG preconditioner | Int | 1 | +| | | | | +| | See HYPRE_BoomerAMGSetRelaxOrder | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_num_sweeps | When using BoomerAMG preconditioner | Int | 2 | +| | | | | +| | See HYPRE_BoomerAMGSetNumSweeps | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_max_levels | When using BoomerAMG preconditioner | Int | 20 | +| | | | | +| | See HYPRE_BoomerAMGSetMaxLevels | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_strong_threshold | When using BoomerAMG preconditioner | Real | 0.57 | +| | | | | +| | See HYPRE_BoomerAMGSetStrongThreshold | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_interp_type | When using BoomerAMG preconditioner | Int | 0 | +| | | | | +| | HYPRE_BoomerAMGSetInterpType | | | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ + diff --git a/docs/source_docs/user_guide/inputs/output.rst b/docs/source_docs/user_guide/inputs/output.rst new file mode 100644 index 0000000..4b9bad4 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/output.rst @@ -0,0 +1,13 @@ +Output +====== + +Stuff here? + +.. toctree:: + :maxdepth: 0 + + output/checkpointing + output/plotfiles + output/monitors + output/ascent + output/spatial_avgs diff --git a/docs/source_docs/user_guide/inputs/output/ascent.rst b/docs/source_docs/user_guide/inputs/output/ascent.rst new file mode 100644 index 0000000..a2272c9 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/output/ascent.rst @@ -0,0 +1,31 @@ +Ascent +------ + +The following inputs must be preceded by "mfix." and control frequency and naming of plotfile generation as well +as whether the EB geometry or level set should be written out, and if the particles should be written out in Ascii +format (for debugging). + ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++======================+=======================================================================+=============+===========+ +| 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. | | | ++----------------------+-----------------------------------------------------------------------+-------------+-----------+ + + +`Ascent `_ has been integrated into MFIX-Exa for *in situ* visualization. +For codes that have been built with Ascent support, the following inputs must be preceded by "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. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ diff --git a/docs/source_docs/inputs/InputsCheckpoint.rst b/docs/source_docs/user_guide/inputs/output/checkpointing.rst similarity index 99% rename from docs/source_docs/inputs/InputsCheckpoint.rst rename to docs/source_docs/user_guide/inputs/output/checkpointing.rst index 6bd0a6d..d555842 100644 --- a/docs/source_docs/inputs/InputsCheckpoint.rst +++ b/docs/source_docs/user_guide/inputs/output/checkpointing.rst @@ -1,7 +1,7 @@ .. _Chap:InputsCheckpoint: -Checkpoint/Restart -================== +Checkpointing +============= The following inputs must be preceded by "mfix." and control checkpoint/restart. diff --git a/docs/source_docs/inputs/InputsMonitors.rst b/docs/source_docs/user_guide/inputs/output/monitors.rst similarity index 89% rename from docs/source_docs/inputs/InputsMonitors.rst rename to docs/source_docs/user_guide/inputs/output/monitors.rst index c19fa58..d2ac4cb 100644 --- a/docs/source_docs/inputs/InputsMonitors.rst +++ b/docs/source_docs/user_guide/inputs/output/monitors.rst @@ -1,50 +1,3 @@ -.. _Chap:InputsMonitors: - -Spatial averages -================ - -The following inputs must be preceded by "mfix." and control whether to compute -spatial averages, and how often to output the results. n is the number of -spatial averages implicitly defined by the size of avg_region_x_w. - -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+==================+=======================================================================+=============+===========+ -| avg_int | Interval, in number of CFD dt's, to write output | Int | -1 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_file | Base file name which is appended with the data type (vel_p, p_g, | String | avg_region| -| | ep_g or vel_g), the number of this type of averaging, and the .csv | | | -| | file extension | | | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_ep_g | Average and save fluid-phase volume fraction (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_p_g | Average and save fluid-phase pressure (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_vel_g | Average and save fluid-phase velocity (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_T_g | Average and save fluid-phase temperature (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_ro_p | Average and save particle density (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_vel_p | Average and save particle velocity (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_T_p | Average and save particle temperature (if 1) | n*Int | 0 | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_x_w | Lower bound of averaging region in x-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_x_e | Upper bound of averaging region in x-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_y_s | Lower bound of averaging region in y-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_y_n | Upper bound of averaging region in y-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_z_b | Lower bound of averaging region in z-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ -| avg_region_z_t | Upper bound of averaging region in z-direction | n*Real | None | -+------------------+-----------------------------------------------------------------------+-------------+-----------+ - - - Monitors ======== diff --git a/docs/source_docs/inputs/InputsPlotFiles.rst b/docs/source_docs/user_guide/inputs/output/plotfiles.rst similarity index 100% rename from docs/source_docs/inputs/InputsPlotFiles.rst rename to docs/source_docs/user_guide/inputs/output/plotfiles.rst diff --git a/docs/source_docs/user_guide/inputs/output/spatial_avgs.rst b/docs/source_docs/user_guide/inputs/output/spatial_avgs.rst new file mode 100644 index 0000000..437d120 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/output/spatial_avgs.rst @@ -0,0 +1,42 @@ +Spatial averages +---------------- + +The following inputs must be preceded by "mfix." and control whether to compute +spatial averages, and how often to output the results. n is the number of +spatial averages implicitly defined by the size of avg_region_x_w. + ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++==================+=======================================================================+=============+===========+ +| avg_int | Interval, in number of CFD dt's, to write output | Int | -1 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_file | Base file name which is appended with the data type (vel_p, p_g, | String | avg_region| +| | ep_g or vel_g), the number of this type of averaging, and the .csv | | | +| | file extension | | | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_ep_g | Average and save fluid-phase volume fraction (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_p_g | Average and save fluid-phase pressure (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_vel_g | Average and save fluid-phase velocity (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_T_g | Average and save fluid-phase temperature (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_ro_p | Average and save particle density (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_vel_p | Average and save particle velocity (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_T_p | Average and save particle temperature (if 1) | n*Int | 0 | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_x_w | Lower bound of averaging region in x-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_x_e | Upper bound of averaging region in x-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_y_s | Lower bound of averaging region in y-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_y_n | Upper bound of averaging region in y-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_z_b | Lower bound of averaging region in z-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ +| avg_region_z_t | Upper bound of averaging region in z-direction | n*Real | None | ++------------------+-----------------------------------------------------------------------+-------------+-----------+ diff --git a/docs/source_docs/user_guide/inputs/regions_defs.rst b/docs/source_docs/user_guide/inputs/regions_defs.rst new file mode 100644 index 0000000..c0c5a51 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/regions_defs.rst @@ -0,0 +1,26 @@ +Regions definitions +=================== + +Regions are used to define sections of the domain. They may be either boxes, planes or points. They are used in building initial condition regions. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| mfix.regions | Names given to regions. | String | None | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| regions.[region].lo | Low corner of physical region (physical, not index space) | Reals | 0 0 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| regions.[region].hi | High corner of physical region (physical, not index space) | Reals | 0 0 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +Below is an example for specifying two regions. + +.. code-block:: none + + 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.riser.lo = 0.0000 0.0000 0.0000 + regions.riser.hi = 0.1000 0.2784 0.2784 diff --git a/docs/source_docs/user_guide/inputs/solids_model.rst b/docs/source_docs/user_guide/inputs/solids_model.rst new file mode 100644 index 0000000..101679d --- /dev/null +++ b/docs/source_docs/user_guide/inputs/solids_model.rst @@ -0,0 +1,133 @@ +Solids model +============ + +Solids settings +--------------- + +Enabling the SOLIDS solver and specifying options common to both DEM and PIC +models. The following inputs must be preceded by the "solids." root + ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| | Description | Type | Default | ++==========================================+=============================================================+==========+==========+ +| types | Specified name(s) of the SOLIDS types or None to disable | String | None | +| | the SOLIDS solver. The user defined names are used to | | | +| | specify DEM and/or PIC model inputs. | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| molecular_weight | Value of constant solid molecular | Real | 0 | +| | weight | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| specific_heat | Specify which specific heat model to | String | None | +| | use for solid. Available options | | | +| | include: | | | +| | | | | +| | * 'constant' for constant specific heat | | | +| | model | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| specific_heat.constant | Value of species molecular weight. | Real | 0 | +| | [required if fluid.specific_heat = | | | +| | 'constant']. | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| reference_temperature | Value of the reference temperature used | Real | 0 | +| | for specific enthalpy | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| species | Specify which species can constitute | String | None | +| | the fluid phase [defined species must | | | +| | be a subset of the species.solve | | | +| | arguments]. | | | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ +| 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.max_iterations | Define max number of iterations for Damped-Newton solver | int | 100 | ++------------------------------------------+-------------------------------------------------------------+----------+----------+ + +Below is an example for specifying the solids solver model options. + +.. code-block:: none + + solids.types = my_solid0 my_solid1 + + solids.reference_temperature = 298.15 + + solids.specific_heat = mixture + + solids.species = Fe2O3 FeO + + +DEM model settings +------------------ + +Enabling the DEM solver and specifying model options. + ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++=========================+=========================================================================+==========+===========+ +| dem.solve | Specified name(s) of the DEM types or None to disable the DEM solver. | String | None | +| | The user defined names are used to specify DEM model inputs. | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.friction_coeff.pp | Friction coefficient :: particle to particle collisions [required] | Real | 0 | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.friction_coeff.pw | Friction coefficient :: particle to wall collisions [required] | Real | 0 | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.spring_const.pp | Normal spring constant :: particle to particle collisions [required] | Real | 0 | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.spring_const.pw | Normal spring constant :: particle to wall collisions [required] | Real | 0 | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.spring_tang_fac.pp | Tangential-to-normal spring constant factor :: particle to particle | Real | 0 | +| | collisions [required] | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.spring_tang_fac.pw | Tangential-to-normal spring constant factor :: particle to wall | Real | 0 | +| | collisions [required] | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.damping_tang_fac.pp | Factor relating the tangential damping coefficient to the normal | Real | 0 | +| | damping coefficient :: particle to particle collisions [required] | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ +| dem.damping_tang_fac.pw | Factor relating the tangential damping coefficient to the normal | Real | 0 | +| | damping coefficient :: particle to wall collisions [required] | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ + +The following inputs use the DEM type names specified using the `dem.solve` input to define restitution coefficients and +are proceeded with `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] | | | ++-------------------------+-------------------------------------------------------------------------+----------+-----------+ + +Below is an example for specifying the inputs for two DEM solids. + +.. code-block:: none + + dem.solve = sand char + + dem.friction_coeff.pp = 0.25 + dem.friction_coeff.pw = 0.15 + + dem.spring_const.pp = 100.0 + dem.spring_const.pw = 100.0 + + dem.spring_tang_fac.pp = 0.2857 + dem.spring_tang_fac.pw = 0.2857 + + dem.damping_tang_fac.pp = 0.5 + dem.damping_tang_fac.pw = 0.5 + + dem.restitution_coeff.sand.sand = 0.85 + dem.restitution_coeff.sand.char = 0.88 + dem.restitution_coeff.char.char = 0.90 + + dem.restitution_coeff.sand.wall = 0.85 + dem.restitution_coeff.char.wall = 0.89 + + +PIC model settings +------------------ + +.. todo:: Add PIC inputs diff --git a/docs/source_docs/user_guide/inputs/species_defs.rst b/docs/source_docs/user_guide/inputs/species_defs.rst new file mode 100644 index 0000000..9abd71a --- /dev/null +++ b/docs/source_docs/user_guide/inputs/species_defs.rst @@ -0,0 +1,105 @@ +Species definitions +=================== + + +Enabling the species mass fraction solver and specifying species model options. + ++----------------------+-------------------------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++======================+=========================================================================+==========+===========+ +| species.solve | Specified name of the species or None to disable the species solver. | String | None | +| | The name assigned to the species solver is used to specify species | | | +| | inputs. | | | ++----------------------+-------------------------------------------------------------------------+----------+-----------+ + + +The following inputs must be preceded by the "species." prefix + ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| | Description | Type | Default | ++===========================================+=======================================================+==========+===========+ +| [specie0].molecular_weight | Value of species molecular weight. [required if | Real | 0 | +| | fluid.molecular_weight='mixture']. | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| diffusivity | Specify which diffusivity model to use for species | String | None | +| | [required]. | | | +| | Available options include: | | | +| | | | | +| | * 'constant' for constant diffusivity model | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| diffusivity.constant | Value of constant species diffusivity. [required if | Real | 0 | +| | diffusivity_model='constant']. | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| specific_heat | Specify which specific heat model to use for species | String | None | +| | [required if fluid.molecular_weight='mixture']. | | | +| | Available options include: | | | +| | | | | +| | * 'constant' for constant specific heat model | | | +| | * 'nasa7-poly' for NASA7 Polynomials model | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| [specie0].specific_heat.constant | Value of constant species diffusivity. [required if | Real | 0 | +| | diffusivity model='constant']. | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| [specie0].specific_heat.NASA7.a[i] | Value of i-th coefficient, with i=0,..,6 for NASA7 | Real | 0 | +| | polynomial coefficient [required if specific heat | | | +| | model='NASA7-Poly']. | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ +| [specie0].enthalpy_of_formation | Value of constant enthalpy of formation. [required if | Real | 0 | +| | specific heat model='constant']. | | | ++-------------------------------------------+-------------------------------------------------------+----------+-----------+ + +Below is an example for specifying species solver model options. + +.. code-block:: none + + species.solve = O2 CO CO2 Fe2O3 FeO + + species.diffusivity = constant + species.diffusivity.constant = 1.9e-5 + + species.specific_heat = NASA7-poly + + # Oxygen + species.O2.molecular_weight = 31.99880e-3 + species.O2.specific_heat.NASA7.a0 = 3.78245636E+00 3.66096065E+00 + species.O2.specific_heat.NASA7.a1 = -2.99673416E-03 6.56365811E-04 + species.O2.specific_heat.NASA7.a2 = 9.84730201E-06 -1.41149627E-07 + species.O2.specific_heat.NASA7.a3 = -9.68129509E-09 2.05797935E-11 + species.O2.specific_heat.NASA7.a4 = 3.24372837E-12 -1.29913436E-15 + species.O2.specific_heat.NASA7.a5 = -1.06394356E+03 -1.21597718E+03 + + # Carbon monoxide + species.CO.molecular_weight = 28.01040e-3 + species.CO.specific_heat.NASA7.a0 = 3.57953350E+00 3.04848590E+00 + species.CO.specific_heat.NASA7.a1 = -6.10353690E-04 1.35172810E-03 + species.CO.specific_heat.NASA7.a2 = 1.01681430E-06 -4.85794050E-07 + species.CO.specific_heat.NASA7.a3 = 9.07005860E-10 7.88536440E-11 + species.CO.specific_heat.NASA7.a4 = -9.04424490E-13 -4.69807460E-15 + species.CO.specific_heat.NASA7.a5 = -1.43440860E+04 -1.42661170E+04 + + # Carbon dioxide + species.CO2.molecular_weight = 44.00980e-3 + species.CO2.specific_heat.NASA7.a0 = 2.35681300E+00 4.63651110E+00 + species.CO2.specific_heat.NASA7.a1 = 8.98412990E-03 2.74145690E-03 + species.CO2.specific_heat.NASA7.a2 = -7.12206320E-06 -9.95897590E-07 + species.CO2.specific_heat.NASA7.a3 = 2.45730080E-09 1.60386660E-10 + species.CO2.specific_heat.NASA7.a4 = -1.42885480E-13 -9.16198570E-15 + species.CO2.specific_heat.NASA7.a5 = -4.83719710E+04 -4.90249040E+04 + + # Hematite + species.Fe2O3.molecular_weight = 159.68820e-3 + species.Fe2O3.specific_heat.NASA7.a0 = 1.52218166E-01 2.09445369E+01 + species.Fe2O3.specific_heat.NASA7.a1 = 6.70757040E-02 0.00000000E+00 + species.Fe2O3.specific_heat.NASA7.a2 = -1.12860954E-04 0.00000000E+00 + species.Fe2O3.specific_heat.NASA7.a3 = 9.93356662E-08 0.00000000E+00 + species.Fe2O3.specific_heat.NASA7.a4 = -3.27580975E-11 0.00000000E+00 + species.Fe2O3.specific_heat.NASA7.a5 = -1.01344092E+05 -1.07936580E+05 + + # Wustite + species.FeO.molecular_weight = 71.84440e-3 + species.FeO.specific_heat.NASA7.a0 = 3.68765953E+00 1.81588527E+00 + species.FeO.specific_heat.NASA7.a1 = 1.09133433E-02 1.70742829E-02 + species.FeO.specific_heat.NASA7.a2 = -1.61179493E-05 -2.39919190E-05 + species.FeO.specific_heat.NASA7.a3 = 1.06449256E-08 1.53690046E-08 + species.FeO.specific_heat.NASA7.a4 = -2.39514915E-12 -3.53442390E-12 + species.FeO.specific_heat.NASA7.a5 = -3.34867527E+04 -3.30239565E+04 diff --git a/docs/source_docs/inputs/InputsTimeStepping.rst b/docs/source_docs/user_guide/inputs/time-stepping.rst similarity index 57% rename from docs/source_docs/inputs/InputsTimeStepping.rst rename to docs/source_docs/user_guide/inputs/time-stepping.rst index b2b1489..0daa939 100644 --- a/docs/source_docs/inputs/InputsTimeStepping.rst +++ b/docs/source_docs/user_guide/inputs/time-stepping.rst @@ -3,13 +3,7 @@ Time Stepping ============= -Note that if both are specified, both criteria -are used and the simulation still stop when the first criterion is hit. In the case of unsteady flow, -the simulation will stop when either the number of steps reaches max_step or time reaches stop_time. -In the case of unsteady flow, the simulation will stop when either the tolerance (difference between -subsequent steps) is reached or the number of iterations reaches the maximum number specified. - -The following inputs must be preceded by "mfix.": +The following inputs must be preceded by ``mfix``: +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | Key | Description | Type | Default | @@ -18,15 +12,19 @@ The following inputs must be preceded by "mfix.": +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | stop_time | Maximum time to reach (s) | Real | -1.0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| fixed_dt | Should we use a fixed timestep? | Int | 0 | +| fixed_dt | Flag to use a fixed time step | Int | 0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| cfl | CFL constraint (dt < cfl * dx / u) if fixed_dt not 1 | Real | 0.5 | +| cfl | CFL constraint (dt < cfl * dx / u) | Real | See note | +| | | | | +| | * Defaults to 0.5 if ``mfix.advection_type = MOL`` | | | +| | * Defaults to 0.9 if ``mfix.advection_type = Godunov`` | | | +| | * ignored if ``mfix.fixed_dt = 1`` | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| dt_min | Abort if dt gets smaller than this value | Real | 1.e-6 | +| dt_min | Abort if ``dt`` gets smaller than this value | Real | 1.e-6 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| dt_max | Maximum value of dt if calculating with cfl | Real | 1.e14 | +| dt_max | Maximum value of ``dt`` if ``fixed_dt`` is not 1 | Real | 1.e14 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| tcoll_ratio | DEM timestep equals the min collision time divided by this value | Real | 50.0 | +| 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 | "" | | | almost reached the limit (approaching is computed by considering the | | | @@ -37,8 +35,11 @@ The following inputs must be preceded by "mfix.": | | folder, makes the code stop and perform a clean exit | | | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -The following inputs must be preceded by "mfix." and are only relevant if running a problem to steady state. -Currently, the criterion for setting "steady_state" to true is if "dt" is undefined in mfix.dat +In the case of unsteady flow, the simulation will stop when either the number of steps +reaches ``max_step`` or time reaches ``stop_time``. + + +The following inputs must be preceded by ``mfix`` and are only relevant if running a problem to steady state. +-----------------------+-----------------------------------------------------------------------+-------------+------------+ | Key | Description | Type | Default | @@ -53,52 +54,70 @@ Currently, the criterion for setting "steady_state" to true is if "dt" is undefi +-----------------------+-----------------------------------------------------------------------+-------------+------------+ Setting the Time Step ---------------------- +~~~~~~~~~~~~~~~~~~~~~ There are several ways that the inputs are used to determine what time step is used in the evolution of the fluid-particle system in MFIX-Exa. -1. In a pure particle case, the :cpp:`mfix.fixed_dt`, if specified, is only used to determine the frequency -of outputs, it has no effect on the "dtsolid" used in the particle evaluation. If you do not specify a positive -value of :cpp:`mfix.fixed_dt` then the code will abort. + +.. rubric:: Particle-only simulations + +In a pure-particle, no-fluid case, ``mfix.fixed_dt`` is required, however it is used only +to determine the frequency of outputs and has no effect on the time step used in the +particle solve. If a positive value is not specified for ``mfix.fixed_dt`` then the +code will abort. .. highlight:: c++ :: - amrex::Abort::0::If running particle-only must specify fixed_dt in the inputs file !!! + amrex::abort::0::if running particle-only must specify fixed_dt in the inputs file !!! + +The particle time step `dtsolid` is determined by computing the collision time `tcoll` +from particle properties, then setting + +.. highlight:: c++ + +:: + + dtsolid = tcoll / tcoll_ratio + + +.. rubric:: Fluid-only simulations + +In fluid-only simulations, setting ``mfix.fixed_dt`` in the inputs file causes the +fluid advance to used a constant (fixed) time step. If ``mfix.fixed_dt`` is left +undefined, then an appropriate time step is computed using the advective CFL condition. + +.. caution:: + + **The time step based on the advective CFL condition is always computed.** + + * If the computed ``dt`` is smaller than ``mfix.fixed_dt`` for a fixed + time step simulation, the simulation aborts with the message: -The particle time step "dtsolid" is determined by computing the collision time "tcoll" from particle properties, -then setting "dtsolid" to be "tcoll / 50". + .. highlight:: c++ -2. In a pure fluid case, there are two options: + :: - * If you want to fix the dt, simply set :cpp:`mfix.fixed_dt = XXX` and the fluid time - step will always be that number. + amrex::Abort::0::"Fixed dt is too large for fluid solve !!! - * If you want to let the code determine the appropriate time step using the advective CFL - condition, then set :cpp:`mfix.cfl = 0.7` for example, and the fluid time step will - be computed to be dt = 0.7 * dx / max(vel). - * If dt as computed in the compute_dt routine is smaller than the user-specified - :cpp:`mfix.dt_min` then the code will abort: + * If the computed ``dt`` is smaller than ``mfix.dt_min`` for a variable + time step simulation, the simulation aborts with the message: - .. highlight:: c++ + .. highlight:: c++ - :: + :: - amrex::Abort::0::"Current dt is smaller than dt_min !!! + amrex::Abort::0::"Current dt is smaller than dt_min !!! - * If dt as computed in the compute_dt routine is larger than the user-specified - :cpp:`mfix.dt_max` then dt will be set to the minimum of its computed value and dt_max + * If the computed ``dt`` is larger than ``mfix.dt_max`` for a variable + time step simulation, then ``dt`` is set to ``dt_max`` - * Note that the cfl defaults to 0.5 so it does not have to be set in the inputs file. If neither - :cpp:`mfix.cfl` nor :cpp:`fixed_dt` is set, then default value of cfl will be used. - If :cpp:`mfix.fixed_dt` is set, then it will override the cfl option whether - :cpp:`mfix.cfl` is set or not. -These options apply to steady state calculations as well as unsteady runs. +.. rubric:: Coupled fluid-particle simulations -3. In a coupled particle-fluid case, dt is determined as in the pure-fluid case. In this case - the particle time step "subdt" is first computed as in the particle-only case ("dtsolid"), - then is adjusted so that an integral number of particle steps fit into a single fluid time step. +In a coupled particle-fluid case, dt is determined as in the pure-fluid case. In this case +the particle time step "subdt" is first computed as in the particle-only case ("dtsolid"), +then is adjusted so that an integral number of particle steps fit into a single fluid time step. diff --git a/docs/source_docs/Introduction.rst b/docs/source_docs/user_guide/introduction.rst similarity index 99% rename from docs/source_docs/Introduction.rst rename to docs/source_docs/user_guide/introduction.rst index d72ed54..ebc27e6 100644 --- a/docs/source_docs/Introduction.rst +++ b/docs/source_docs/user_guide/introduction.rst @@ -29,3 +29,5 @@ 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/GettingStarted_Chapter.rst b/docs/source_docs/user_guide/quick-start.rst similarity index 80% rename from docs/source_docs/GettingStarted_Chapter.rst rename to docs/source_docs/user_guide/quick-start.rst index 030b653..0fafc9e 100644 --- a/docs/source_docs/GettingStarted_Chapter.rst +++ b/docs/source_docs/user_guide/quick-start.rst @@ -26,8 +26,9 @@ the simulations results. .. toctree:: :maxdepth: 1 + :caption: FUCK THIS: + :hidden: - Building MFIX-Exa - Running your first simulation - Visualizing simulation results - HPC + Building MFIX-Exa + Running your first simulation + Visualizing results diff --git a/docs/source_docs/getting_started/BuildingMFIX.rst b/docs/source_docs/user_guide/quick_start/BuildingMFIX.rst similarity index 100% rename from docs/source_docs/getting_started/BuildingMFIX.rst rename to docs/source_docs/user_guide/quick_start/BuildingMFIX.rst diff --git a/docs/source_docs/getting_started/FirstSimulation.rst b/docs/source_docs/user_guide/quick_start/FirstSimulation.rst similarity index 100% rename from docs/source_docs/getting_started/FirstSimulation.rst rename to docs/source_docs/user_guide/quick_start/FirstSimulation.rst diff --git a/docs/source_docs/getting_started/Paraview.rst b/docs/source_docs/user_guide/quick_start/Paraview.rst similarity index 89% rename from docs/source_docs/getting_started/Paraview.rst rename to docs/source_docs/user_guide/quick_start/Paraview.rst index 7e8fcf6..05d66ff 100644 --- a/docs/source_docs/getting_started/Paraview.rst +++ b/docs/source_docs/user_guide/quick_start/Paraview.rst @@ -19,7 +19,7 @@ in ``Pipeline Browser`` and press ``Apply`` on the properties tab. The embedded boundary will now be visible in the 3D viewer. The color and opacity of the embedded boundary can be changed on the properties tab. -.. image:: /getting_started/images/paraview_eb.png +.. image:: /user_guide/quick_start/images/paraview_eb.png Visualize the particles @@ -34,18 +34,18 @@ select the directory group corresponding to the specified prefix. In this example, the director group is displayed as ``plt...``. If only one plot directory has been written, select the ``plt#####`` directory. Press ``OK``. -.. image:: /getting_started/images/paraview_browse_plt.png +.. image:: /user_guide/quick_start/images/paraview_browse_plt.png A dialog will popup asking what reader to use. Select the ``AMReX/BoxLib Particles Reader`` and press ``OK``. -.. image:: /getting_started/images/paraview_reader.png +.. image:: /user_guide/quick_start/images/paraview_reader.png Press ``Apply`` on the properties tab to read the files. To actually see the particles, change the ``Representation`` from the default ``Surface`` to ``Point Gaussian``. The particles should now be visible in the 3D view. -.. image:: /getting_started/images/paraview_pt_gauss.png +.. image:: /user_guide/quick_start/images/paraview_pt_gauss.png On the properties tab, the radius of the particles can be changed by moving the slider or editing the value in the ``Gaussian Radius`` field. The particles can @@ -63,10 +63,10 @@ properties tab, select which variables to read (make sure to select ``ep_g``, we will use this later) and select apply. Under the Coloring section select ``ep_g`` to color the cells by this value. -.. image:: /getting_started/images/paraview_cells.png +.. image:: /user_guide/quick_start/images/paraview_cells.png You can open the embedded boundary, particle, and fluid data simultaneously, and change the opacities of the embedded boundary and fluid data to visualize all the data simultaneously. -.. image:: /getting_started/images/paraview_all.png +.. image:: /user_guide/quick_start/images/paraview_all.png diff --git a/docs/source_docs/getting_started/Visualization.rst b/docs/source_docs/user_guide/quick_start/Visualization.rst similarity index 94% rename from docs/source_docs/getting_started/Visualization.rst rename to docs/source_docs/user_guide/quick_start/Visualization.rst index 5212d74..c8bc4f8 100644 --- a/docs/source_docs/getting_started/Visualization.rst +++ b/docs/source_docs/user_guide/quick_start/Visualization.rst @@ -9,6 +9,6 @@ to use the tools. .. toctree:: - :maxdepth: 1 + :maxdepth: 0 Paraview diff --git a/docs/source_docs/getting_started/images/paraview_all.png b/docs/source_docs/user_guide/quick_start/images/paraview_all.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_all.png rename to docs/source_docs/user_guide/quick_start/images/paraview_all.png diff --git a/docs/source_docs/getting_started/images/paraview_browse_plt.png b/docs/source_docs/user_guide/quick_start/images/paraview_browse_plt.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_browse_plt.png rename to docs/source_docs/user_guide/quick_start/images/paraview_browse_plt.png diff --git a/docs/source_docs/getting_started/images/paraview_cells.png b/docs/source_docs/user_guide/quick_start/images/paraview_cells.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_cells.png rename to docs/source_docs/user_guide/quick_start/images/paraview_cells.png diff --git a/docs/source_docs/getting_started/images/paraview_cells_threshold.png b/docs/source_docs/user_guide/quick_start/images/paraview_cells_threshold.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_cells_threshold.png rename to docs/source_docs/user_guide/quick_start/images/paraview_cells_threshold.png diff --git a/docs/source_docs/getting_started/images/paraview_eb.png b/docs/source_docs/user_guide/quick_start/images/paraview_eb.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_eb.png rename to docs/source_docs/user_guide/quick_start/images/paraview_eb.png diff --git a/docs/source_docs/getting_started/images/paraview_pt_gauss.png b/docs/source_docs/user_guide/quick_start/images/paraview_pt_gauss.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_pt_gauss.png rename to docs/source_docs/user_guide/quick_start/images/paraview_pt_gauss.png diff --git a/docs/source_docs/getting_started/images/paraview_pt_gauss_opts.png b/docs/source_docs/user_guide/quick_start/images/paraview_pt_gauss_opts.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_pt_gauss_opts.png rename to docs/source_docs/user_guide/quick_start/images/paraview_pt_gauss_opts.png diff --git a/docs/source_docs/getting_started/images/paraview_reader.png b/docs/source_docs/user_guide/quick_start/images/paraview_reader.png similarity index 100% rename from docs/source_docs/getting_started/images/paraview_reader.png rename to docs/source_docs/user_guide/quick_start/images/paraview_reader.png diff --git a/docs/source_docs/Inputs_Chapter.rst b/docs/source_docs/user_guide/run-time_inputs.rst similarity index 73% rename from docs/source_docs/Inputs_Chapter.rst rename to docs/source_docs/user_guide/run-time_inputs.rst index e2a1dd5..597d3d8 100644 --- a/docs/source_docs/Inputs_Chapter.rst +++ b/docs/source_docs/user_guide/run-time_inputs.rst @@ -36,18 +36,23 @@ values for setting up a problem. Pay special attention to any prefixes for the keywords such as ``mfix``, ``amr``, ``geometry``, ``nodal_proj`` etc. .. toctree:: - :maxdepth: 1 - + :maxdepth: 0 + :hidden: + :titlesonly: + + inputs/initialization + inputs/time-stepping + inputs/geometry_and_eb + inputs/mesh_and_gridding + inputs/multigrid-solvers + inputs/model_options + inputs/species_defs + inputs/fluid_model + inputs/solids_model + inputs/chemical_reactions + inputs/regions_defs + inputs/initial_conditions + inputs/boundary_conditions + inputs/output + inputs/advanced inputs/InputsProblemDefinition - inputs/InputsCoupling - inputs/InputsTimeStepping - inputs/InputsDiscretization - inputs/InputsInitialization - inputs/InputsLoadBalancing - inputs/InputsMultigrid - inputs/InputsHypre - inputs/InputsPlotFiles - inputs/InputsCheckpoint - inputs/InputsMonitors - inputs/InputsPICtoDEM - inputs/InputsVerbosity -- GitLab From ccd2a4883ef5976766ffc2529219949932818fdc Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Fri, 12 Jan 2024 11:04:57 -0500 Subject: [PATCH 2/3] Improve time step docs --- .../user_guide/inputs/time-stepping.rst | 159 ++++++++++-------- 1 file changed, 90 insertions(+), 69 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/time-stepping.rst b/docs/source_docs/user_guide/inputs/time-stepping.rst index 0daa939..afec60b 100644 --- a/docs/source_docs/user_guide/inputs/time-stepping.rst +++ b/docs/source_docs/user_guide/inputs/time-stepping.rst @@ -1,9 +1,96 @@ .. sec:InputsTimeStepping: -Time Stepping +Time stepping ============= -The following inputs must be preceded by ``mfix``: +There are several ways that the inputs are used to determine the time step of particle-only, +fluid-only, and coupled fluid-particle systems. + +.. rubric:: Fluid-only simulations + +In fluid-only simulations, setting ``mfix.fixed_dt`` causes the fluid to advance with a +fixed (constant) time step. If ``mfix.fixed_dt`` is not defined, then an appropriate time +step is computed based on the advective CFL condition. + +.. caution:: + + **The adaptive time step based on the advective CFL condition is always computed + and is stronly recommended for most cases.** + + * For a fixed time step simiulation, if the computed step size is smaller than + ``mfix.fixed_dt`` for a fixed, the simulation aborts with the message: + + .. highlight:: c++ + + :: + + amrex::Abort::0::"Fixed dt is too large for fluid solve !!! + + + * For simulations using the adaptive time step: + + * If the computed time step is larger than ``mfix.dt_max``, then the + time step is set to ``dt_max`` + + * If the computed time step is smaller than ``mfix.dt_min``, then the + simulation aborts with the message: + + .. highlight:: c++ + + :: + + amrex::Abort::0::"Current dt is smaller than dt_min !!! + +.. rubric:: Particle-only DEM simulations + +In particle-only DEM simulations, the time step used to advance particles, ``dtsolid``, +is determined by computing the collision time ``tcoll`` from particle properties, then dividing +the result by the number of steps per collision, ``tcoll_ratio``: + +.. highlight:: c++ + +:: + + dtsolid = tcoll / tcoll_ratio; + +.. note:: + + ``mfix.fixed_dt`` must be defined for particle-only DEM simulations, however it is only + used to determine the frequency of outputs and has no effect on the particle advance. If + a positive value is not specified for ``mfix.fixed_dt``, then the code aborts with the + following message: + + .. highlight:: c++ + + :: + + amrex::abort::0::if running particle-only must specify fixed_dt in the inputs file !!! + + +.. rubric:: Coupled fluid-DEM simulations + +In a coupled fluid-DEM simulation, the fluid time step, ``dt``, and the particle time step, +``dtsolid``, are computed the same as in fluid-only and DEM-only simulations, respectively. +If ``dt < dtsolid``, then the particle sub-time step, ``subdt``, is set to the fluid time +step and one particle advance is taken. However, if ``dt > dtsolid`` (which is usually the +case), then the number of sub-steps needed for DEM particles to advance the same total time +as the fluid, ``nsubsteps``, is computed by dividing ``dt`` by ``dtsolid`` and the particle +sub-time step is computed by dividing ``dt`` by ``nsubsteps``. + +.. highlight:: c++ + +:: + + int nsubsteps = 1; + amrex::Real subdt = dt; + + if (dt > dtsolid) { + nsubsteps = amrex::Math::ceil(dt / dtsolid); + subdt = dt / nsubsteps; + } + + +The following inputs are defined using the ``mfix`` prefix. +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | Key | Description | Type | Default | @@ -39,7 +126,7 @@ In the case of unsteady flow, the simulation will stop when either the number of reaches ``max_step`` or time reaches ``stop_time``. -The following inputs must be preceded by ``mfix`` and are only relevant if running a problem to steady state. +The following inputs are defined using the ``mfix`` prefix and are only relevant if running a steady state simulation. +-----------------------+-----------------------------------------------------------------------+-------------+------------+ | Key | Description | Type | Default | @@ -53,71 +140,5 @@ The following inputs must be preceded by ``mfix`` and are only relevant if runni | steady_state_maxiter | Maximum number of allowed iterations to converge to steady state | Int | 100000000 | +-----------------------+-----------------------------------------------------------------------+-------------+------------+ -Setting the Time Step -~~~~~~~~~~~~~~~~~~~~~ - -There are several ways that the inputs are used to determine what time step -is used in the evolution of the fluid-particle system in MFIX-Exa. - - -.. rubric:: Particle-only simulations - -In a pure-particle, no-fluid case, ``mfix.fixed_dt`` is required, however it is used only -to determine the frequency of outputs and has no effect on the time step used in the -particle solve. If a positive value is not specified for ``mfix.fixed_dt`` then the -code will abort. - -.. highlight:: c++ - -:: - - amrex::abort::0::if running particle-only must specify fixed_dt in the inputs file !!! - -The particle time step `dtsolid` is determined by computing the collision time `tcoll` -from particle properties, then setting - -.. highlight:: c++ - -:: - - dtsolid = tcoll / tcoll_ratio - - -.. rubric:: Fluid-only simulations - -In fluid-only simulations, setting ``mfix.fixed_dt`` in the inputs file causes the -fluid advance to used a constant (fixed) time step. If ``mfix.fixed_dt`` is left -undefined, then an appropriate time step is computed using the advective CFL condition. - -.. caution:: - - **The time step based on the advective CFL condition is always computed.** - - * If the computed ``dt`` is smaller than ``mfix.fixed_dt`` for a fixed - time step simulation, the simulation aborts with the message: - - .. highlight:: c++ - - :: - - amrex::Abort::0::"Fixed dt is too large for fluid solve !!! - - - * If the computed ``dt`` is smaller than ``mfix.dt_min`` for a variable - time step simulation, the simulation aborts with the message: - - .. highlight:: c++ - - :: - - amrex::Abort::0::"Current dt is smaller than dt_min !!! - - * If the computed ``dt`` is larger than ``mfix.dt_max`` for a variable - time step simulation, then ``dt`` is set to ``dt_max`` - -.. rubric:: Coupled fluid-particle simulations -In a coupled particle-fluid case, dt is determined as in the pure-fluid case. In this case -the particle time step "subdt" is first computed as in the particle-only case ("dtsolid"), -then is adjusted so that an integral number of particle steps fit into a single fluid time step. -- GitLab From e96166d7650967147a50e8099b8fed2158645c62 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 17 Jan 2024 11:42:12 -0500 Subject: [PATCH 3/3] Split domand and geometry --- .../user_guide/inputs/boundary_conditions.rst | 2 + docs/source_docs/user_guide/inputs/domain.rst | 29 ++++++ .../user_guide/inputs/geometry.rst | 92 +++++++++++++++++++ .../user_guide/inputs/geometry_and_eb.rst | 33 ------- .../user_guide/inputs/regions_defs.rst | 2 + .../user_guide/run-time_inputs.rst | 3 +- 6 files changed, 127 insertions(+), 34 deletions(-) create mode 100644 docs/source_docs/user_guide/inputs/domain.rst create mode 100644 docs/source_docs/user_guide/inputs/geometry.rst delete mode 100644 docs/source_docs/user_guide/inputs/geometry_and_eb.rst diff --git a/docs/source_docs/user_guide/inputs/boundary_conditions.rst b/docs/source_docs/user_guide/inputs/boundary_conditions.rst index 67d2291..bd5a0d2 100644 --- a/docs/source_docs/user_guide/inputs/boundary_conditions.rst +++ b/docs/source_docs/user_guide/inputs/boundary_conditions.rst @@ -1,3 +1,5 @@ +.. _InputsBoundaryConditions: + Boundary Conditions =================== diff --git a/docs/source_docs/user_guide/inputs/domain.rst b/docs/source_docs/user_guide/inputs/domain.rst new file mode 100644 index 0000000..f1a1933 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/domain.rst @@ -0,0 +1,29 @@ +.. _InputsDomain: + +Defining the domain +=================== + +All simulations, whether using an embedded boundary (EB) or not, are specified on a simple cuboid domain. The +low and high corners of the cuboid are defined by the ``prob_lo`` and ``prob_hi`` inputs. + +The following inputs are defined using the ``geometry`` prefix. + ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=================+=======================================================================+=============+===========+ +| coord_sys | Coordinate system used in simulation. Only Cartesian coordinates | Int | 0 | +| | (``coord_sys = 0``) are supported. | | | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| is_periodic | 1 for true, 0 for false (one value for each coordinate direction) | Int | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| prob_lo | Low corner of physical domain (physical not index space) | Reals | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ +| prob_hi | High corner of physical domain (physical not index space) | Reals | 0 0 0 | ++-----------------+-----------------------------------------------------------------------+-------------+-----------+ + +.. attention:: + + MFIX-Exa geometry restrictions: + + * There is **no support** for 1D or 2D simulation domains. + * Cartesian is the **only supported** coordinate system. diff --git a/docs/source_docs/user_guide/inputs/geometry.rst b/docs/source_docs/user_guide/inputs/geometry.rst new file mode 100644 index 0000000..cf6a04e --- /dev/null +++ b/docs/source_docs/user_guide/inputs/geometry.rst @@ -0,0 +1,92 @@ +.. _InputsGeometry: + +Specifying a geometry +===================== + +The following inputs are defined using the ``mfix`` prefix. + ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| | Description | Type | Default | ++========================+===================================================================+==========+=====================+ +| geometry | Select a predefined EB geometry | String | '' | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| geometry_filename | The CSG file that defines the EB geometry | String | '' | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ +| levelset__refinement | Refinement factor of levelset resolution relative to level 0 | Int | 1 | +| | resolution | | | ++------------------------+-------------------------------------------------------------------+----------+---------------------+ + +Most simulations require a user to specify some kind of geometry. For example, the geometry could be a basic cylinder used to +model flow inside a pipe, or it may be an irregularly shaped solid to study external flow around a bluff body, or the geometry +may be the proposed design of a complex, multi-stage chemical reactor undergoing performance assessment. In the following sections, +several options for specifying a geometry are described. + +.. caution:: + + Any domain extent that is not periodic or defined as a Dirichlet or Neumann :ref:`boundary condition` + must be fully covered. To state this another way, if a domain extent is not periodic or an inflow or outflow boundary condition, + then it should be excluded from (outside of) the domain by the embedded boundary geometry. + + +Pre-defined geometries +---------------------- + +The ``mfix.geometry`` input is used to choose one of the basic pre-defined geometries, or to +select the option to use a user-defined geometry constructed from native AMReX implicit functions. + + +Constructive solid geometry +--------------------------- + +Use the ``mfix.geometry_filename`` input to select a *constructive solid geometry (CSG)* that defines +the system geometry. + + +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`. + diff --git a/docs/source_docs/user_guide/inputs/geometry_and_eb.rst b/docs/source_docs/user_guide/inputs/geometry_and_eb.rst deleted file mode 100644 index 4995604..0000000 --- a/docs/source_docs/user_guide/inputs/geometry_and_eb.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. sec:InputsGeomAndEB: - -Geometry and EB -=============== - -The following inputs must be preceded by "geometry." - -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+=================+=======================================================================+=============+===========+ -| coord_sys | 0 for Cartesian | Int | 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| is_periodic | 1 for true, 0 for false (one value for each coordinate direction) | Ints | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_lo | Low corner of physical domain (physical not index space) | Reals | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ -| prob_hi | High corner of physical domain (physical not index space) | Reals | 0 0 0 | -+-----------------+-----------------------------------------------------------------------+-------------+-----------+ - - -The following inputs must be preceded by "mfix." - -+------------------------+-------------------------------------------------------------------+----------+---------------------+ -| | Description | Type | Default | -+========================+===================================================================+==========+=====================+ -| geometry | Which type of amrex EB geometry are we using? | String | | -| | | | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ -| geometry_filename | The CSG file that defines the EB geometry | String | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ -| levelset__refinement | Refinement factor of levelset resolution relative to level 0 | Int | 1 | -| | resolution | | | -+------------------------+-------------------------------------------------------------------+----------+---------------------+ diff --git a/docs/source_docs/user_guide/inputs/regions_defs.rst b/docs/source_docs/user_guide/inputs/regions_defs.rst index c0c5a51..d57bd97 100644 --- a/docs/source_docs/user_guide/inputs/regions_defs.rst +++ b/docs/source_docs/user_guide/inputs/regions_defs.rst @@ -1,3 +1,5 @@ +.. _InputsRegions: + Regions definitions =================== diff --git a/docs/source_docs/user_guide/run-time_inputs.rst b/docs/source_docs/user_guide/run-time_inputs.rst index 597d3d8..80fdc8b 100644 --- a/docs/source_docs/user_guide/run-time_inputs.rst +++ b/docs/source_docs/user_guide/run-time_inputs.rst @@ -42,7 +42,8 @@ keywords such as ``mfix``, ``amr``, ``geometry``, ``nodal_proj`` etc. inputs/initialization inputs/time-stepping - inputs/geometry_and_eb + inputs/domain + inputs/geometry inputs/mesh_and_gridding inputs/multigrid-solvers inputs/model_options -- GitLab