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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 dI-XBYKmqB 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 literal 0 HcmV?d00001 diff --git a/docs/source_docs/inputs/figures/trilinear.jpg b/docs/source_docs/user_guide/inputs/images/trilinear.jpg similarity index 100% rename from docs/source_docs/inputs/figures/trilinear.jpg rename to docs/source_docs/user_guide/inputs/images/trilinear.jpg diff --git a/docs/source_docs/user_guide/inputs/initial_conditions.rst b/docs/source_docs/user_guide/inputs/initial_conditions.rst new file mode 100644 index 0000000..8293348 --- /dev/null +++ b/docs/source_docs/user_guide/inputs/initial_conditions.rst @@ -0,0 +1,215 @@ +Initial Conditions +================== + +The following inputs are defined using the ``ic`` prefix. + ++-----------------------+------------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=======================+========================================================================+=============+===========+ +| regions | Regions used to define initial conditions. | String | None | ++-----------------------+------------------------------------------------------------------------+-------------+-----------+ +| allow_regions_overlap | Flag for allowing the user to decide whether particles will be | Bool | 1 (yes) | +| | generated/initialized more than once on the areas where the IC regions | | | +| | have an intersection | | | ++-----------------------+------------------------------------------------------------------------+-------------+-----------+ +| ranking_type | IC regions are sorted during initialization. This input lets the user | String | Inputs | +| | decide the ranking criterion, which can be one of the following: | | | +| | | | | +| | * inputs -- the order in the inputs file | | | +| | * volume -- the volume of each IC region | | | +| | * priority -- the priority value provided by the user in the inputs | | | ++-----------------------+------------------------------------------------------------------------+-------------+-----------+ + + +Fluid settings +~~~~~~~~~~~~~~ + +For each initial condition region, the fluid inputs are defined +using the ``ic.[region].[fluid]`` compound prefix. + ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++========================+========================================================================+=============+===========+ +| volfrac | Volume fraction [required] | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| density | Fluid density | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| temperature | Fluid temperature | Real | 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| velocity | Velocity components | Reals | 0 0 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ +| species.[species0] | Mass fraction of 'species0' | Reals | 0 0 0 | ++------------------------+------------------------------------------------------------------------+-------------+-----------+ + + + +Solids settings +~~~~~~~~~~~~~~~ + +For each initial condition region, general solids inputs are defined +using the ``ic.[region]`` compound prefix. + ++----------------------+------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++======================+==================================================================+=============+===========+ +| solids | Name of solid type in IC region -- only one solid is allowed in | String | None | +| | an IC region. | | | ++----------------------+------------------------------------------------------------------+-------------+-----------+ +| packing | Specifies how auto-generated particles are placed in the IC | String | None | +| | region: | | | +| | | | | +| | * hcp -- hex-centered packing | | | +| | * pseudo_random -- random packing using a fixed random seed | | | +| | * random -- random packing (not repeatable) | | | +| | * oneper -- one particle per cell | | | +| | * eightper -- eight particles per cell | | | +| | * n-cube -- n^3 particles per cell where n is an integer | | | +| | | | | +| | (NOTE: oneper is equivalent to 1-cube and eightper to 2-cube) | | | ++----------------------+------------------------------------------------------------------+-------------+-----------+ +| priority | Priority value for IC regions ranking as described above | Int | Max | ++----------------------+------------------------------------------------------------------+-------------+-----------+ + +For each initial condition region, the solid inputs are defined +using the ``ic.[region].[solid]`` compound prefix. + ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++=====================+=======================================================================+=============+===========+ +| volfrac | Volume fraction | Real | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| temperature | temperature | Real | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| species.[species0] | Mass fraction of 'species0' | Real | 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| velocity | Velocity components | Reals | 0 0 0 | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter | Method to specify particle diameter in the IC region. This is | String | None | +| | only used for auto-generated particles. Available options include: | | | +| | | | | +| | * 'constant' -- specified constant | | | +| | * 'uniform' -- uniform distribution | | | +| | * 'normal' -- normal distribution | | | +| | * 'custom' -- user defined distribution | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.constant | Monodisperse (single valued) particle diameter. | Real | 0 | +| | Required for ``constant`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.mean | Distribution mean. | Real | 0 | +| | Required for ``normal`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.std | Distribution standard deviation. | Real | 0 | +| | Required for ``normal`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.min | Minimum diameter to clip distribution. | Real | 0 | +| | Required for ``normal`` distributions and ``uniform`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.max | Maximum diameter to clip distribution. | Real | 0 | +| | Required for ``normal`` distributions and ``uniform`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| diameter.custom | File name that specifies either the cumulative or probability | String | None | +| | distribution. Required for ``custom`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density | Method to specify particle density in the IC region. This is | String | None | +| | only used for auto-generated particles. Available options include: | | | +| | | | | +| | * 'constant' -- specified constant | | | +| | * 'uniform' -- uniform distribution | | | +| | * 'normal' -- normal distribution | | | +| | * 'custom' -- user defined distribution | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.constant | Monodisperse (single valued) particle density. | Real | 0 | +| | Required for ``constant`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.mean | Distribution mean. | Real | 0 | +| | Required for ``normal`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.std | Distribution standard deviation. | Real | 0 | +| | Required for ``normal`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.min | Minimum diameter to clip distribution. | Real | 0 | +| | Required for ``normal`` distributions and ``uniform`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.max | Maximum diameter to clip distribution. | Real | 0 | +| | Required for ``normal`` distributions and ``uniform`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ +| density.custom | File name that specifies either the cumulative or probability | String | None | +| | distribution. Required for ``custom`` distributions. | | | ++---------------------+-----------------------------------------------------------------------+-------------+-----------+ + +The following inputs must be preceded by ``mfix``: + ++----------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++======================+=======================================================================+=============+==============+ +| particle_init_type | How do we initialize the particles? "Auto" vs AsciiFile | String | AsciiFile | ++----------------------+-----------------------------------------------------------------------+-------------+--------------+ + + +The following inputs must be preceded by ``particles``: + ++--------------------+---------------------------------------------------------------------------+-------------+-----------+ +| | Description | Type | Default | ++====================+===========================================================================+=============+===========+ +| removeOutOfRange | Flag to remove particles at initialization that are touching a wall | Int | 1 | ++--------------------+---------------------------------------------------------------------------+-------------+-----------+ + + +Below is an example for specifying an initial condition for a fluid (``fluid``) and one solid (``solid0``). + +.. code-block:: none + + mfix.particle_init_type = Auto + + particles.removeOutOfRange = 1 + + ic.regions = bed0 bed1 + + ic.bed0.fluid.volfrac = 0.725 + ic.bed0.fluid.density = 1.0 + ic.bed0.fluid.velocity = 0.015 0.00 0.00 + ic.bed0.fluid.temperature = 383.0 + ic.bed0.fluid.species.CO = 0.3 + ic.bed0.fluid.species.CO2 = 0.2 + ic.bed0.fluid.species.O2 = 0.5 + + ic.bed0.solids = my_solid0 + + ic.bed0.packing = pseudo_random + + ic.bed0.my_solid0.volfrac = 0.275 + ic.bed0.my_solid0.temperature = 400.0 + ic.bed0.my_solid0.species.Fe2O3 = 0.4 + ic.bed0.my_solid0.species.FeO = 0.6 + + ic.bed0.my_solid0.velocity = 0.00 0.00 0.00 + + ic.bed0.my_solid0.diameter = constant + ic.bed0.my_solid0.diameter.constant = 100.0e-6 + + ic.bed0.my_solid0.density = constant + ic.bed0.my_solid0.density.constant = 1000.0 + + ic.bed1.fluid.volfrac = 0.925 + ic.bed1.fluid.density = 1.0 + ic.bed1.fluid.velocity = 0.015 0.00 0.00 + ic.bed1.fluid.temperature = 383.0 + ic.bed1.fluid.species.CO = 0.5 + ic.bed1.fluid.species.CO2 = 0.5 + ic.bed1.fluid.species.O2 = 0.0 + + ic.bed1.solids = solid0 + ic.bed1.packing = pseudo_random + + ic.bed1.solid0.volfrac = 0.075 + ic.bed1.solid0.temperature = 450.0 + ic.bed1.solid0.species.Fe2O3 = 0.0 + ic.bed1.solid0.species.FeO = 1.0 + + ic.bed1.solid0.velocity = 0.10 0.00 0.00 + + ic.bed1.solid0.diameter = constant + ic.bed1.solid0.diameter.constant = 110.0e-6 + + ic.bed1.solid0.density = constant + ic.bed1.solid0.density.constant = 900.0 diff --git a/docs/source_docs/inputs/InputsInitialization.rst b/docs/source_docs/user_guide/inputs/initialization.rst similarity index 63% rename from docs/source_docs/inputs/InputsInitialization.rst rename to docs/source_docs/user_guide/inputs/initialization.rst index e2c4184..d57f102 100644 --- a/docs/source_docs/inputs/InputsInitialization.rst +++ b/docs/source_docs/user_guide/inputs/initialization.rst @@ -3,38 +3,31 @@ Initialization ============== -The following inputs must be preceded by "mfix." and determine how we initialize a calculation: +The following inputs must be preceded by ``mfix`` and determine how we initialize a calculation: +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | +======================+=======================================================================+=============+==============+ -| restart | If set, then restart from this file rather than from scratch | String | None | +| do_initial_proj | Preform an initial projection | Bool | True | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| repl_x | Replicate initial data by this factor in the x-direction | Int | 1 | +| initial_iterations | Number of pressure iterations to execute before time-marching | Int | 3 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| repl_y | Replicate initial data by this factor in the y-direction | Int | 1 | + + +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| repl_z | Replicate initial data by this factor in the z-direction | Int | 1 | +| | Description | Type | Default | ++======================+=======================================================================+=============+==============+ +| restart | If set, then restart from this file rather than from scratch | String | None | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -The following inputs must be preceded by "mfix." and determine how we initialize a calculation: +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | +======================+=======================================================================+=============+==============+ +| repl_x | Replicate initial data by this factor in the x-direction | Int | 1 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| particle_init_type | How do we initialize the particles? "Auto" vs AsciiFile | String | AsciiFile | -+----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| do_initial_proj | Should we do the initial projection? | Bool | True | +| repl_y | Replicate initial data by this factor in the y-direction | Int | 1 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| initial_iterations | How many pressure iterations before starting the first timestep | Int | 3 | +| repl_z | Replicate initial data by this factor in the z-direction | Int | 1 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ - -The following inputs must be preceded by "particles.": - -+--------------------+---------------------------------------------------------------------------+-------------+-----------+ -| | Description | Type | Default | -+====================+===========================================================================+=============+===========+ -| removeOutOfRange | Should we remove particles at initialization that are touching the wall | Int | 1 | -+--------------------+---------------------------------------------------------------------------+-------------+-----------+ diff --git a/docs/source_docs/inputs/InputsLoadBalancing.rst b/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst similarity index 82% rename from docs/source_docs/inputs/InputsLoadBalancing.rst rename to docs/source_docs/user_guide/inputs/mesh_and_gridding.rst index f7c386e..96f6d3f 100644 --- a/docs/source_docs/inputs/InputsLoadBalancing.rst +++ b/docs/source_docs/user_guide/inputs/mesh_and_gridding.rst @@ -1,27 +1,22 @@ -.. role:: cpp(code) - :language: c++ +.. sec:InputsMeshAndGridding: -.. _Chap:InputsLoadBalancing: +Mesh and gridding +================= -Gridding and Load Balancing -=========================== +Mesh, grids and tiles +--------------------- -The following inputs must be preceded by "amr." and determine how we create the grids. +Mesh +^^^^ + +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 | +======================+=======================================================================+=============+===========+ -| 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 | +| max_level | Maximum level of refinement allowed (0 when single-level) | Int | 0 | +----------------------+-----------------------------------------------------------------------+-------------+-----------+ | grid_eff | Threshold value to ensure grids do not contain too large a fraction | Real | 0.7 | | | of un-tagged cells. | | | @@ -31,24 +26,30 @@ The following inputs must be preceded by "amr." and determine how we create the | | to ensure coarse/fine boundaries are not too close to tagged cells. | | | | | Applicable only when mesh refinement is enabled ("max_level" > 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