diff --git a/README.md b/README.md index 3652b64f93c9cd98c38a840ea6d2d7db32dbcdec..542d4ce6438f61863c8400d7cb1de53aab50af41 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,42 @@ # MFIX-Exa -This is the public face of the MFiX-Exa project. +This is the public face of the MFiX-Exa project, hosting the documentation, +gallery of results, etc. The website is: https://amrex-codes.github.io/MFIX-Exa/ -The code for now lives at NETL; instructions for how to get access to the code -will be given below. +## Editing -This repo is designed to host the documentation, gallery of results, etc. +The documentation source is in `docs/source/` and the html source for the cover +page is in `docs/webroot/`. -## Editing +:warning: **Do not push any edits to the `gh-pages` branch** as these will be +overwritten. Instead, commit your changes to the `master` branch, and the +`gh-pages` branch will be updated automatically a few minutes later. + +### Documentation + +The documentation is built using +[sphinx](https://www.sphinx-doc.org/en/master/). The `docs/source/config.py` +file contains the settings for building this documentation. The documentation +can be built locally by: + +1. Install sphinx: + +```shell +> pip install sphinx sphinx_rtd_theme +``` + +2. Build the documentation: + +```shell +> mkdir build +> sphinx-build -b html docs/source/ build +``` + +The HTML pages will now be located in the `build` directory. Open the +`index.html` with your favorite browser: -Do not push any edits to the `gh-pages` branch as these will be overwritten. -Instead, commit your changes to the `master` branch, and the `gh-pages` branch -will be updated automatially a few minutes later. The documentation source is -in `docs/source/` and the html source for the cover page is in `docs/webroot/`. +```shell +> firefox build/index.html +``` ### Doxygen diff --git a/docs/source/EB.rst b/docs/source/EB_Chapter.rst similarity index 96% rename from docs/source/EB.rst rename to docs/source/EB_Chapter.rst index 4786a36a69f11de6c0bce4edbb73ed14f4b50ed7..f7e1bc2c977bcfce1c24a68a246fc8dfa3f77800 100644 --- a/docs/source/EB.rst +++ b/docs/source/EB_Chapter.rst @@ -13,4 +13,4 @@ refining the computational meshes near walls. :maxdepth: 1 :caption: Contents: - EBWalls + eb/EBWalls diff --git a/docs/source/Fluids_Chapter.rst b/docs/source/Fluids_Chapter.rst index f65ccf2ad1ed485b83a1e411ed0bf2f592258c88..4edad6dbae166017696d9c24c681266f5eeb9df0 100644 --- a/docs/source/Fluids_Chapter.rst +++ b/docs/source/Fluids_Chapter.rst @@ -8,5 +8,5 @@ Solving the Fluid Equations .. toctree:: - FluidEquations - FluidTimeDiscretization + fluids/FluidEquations + fluids/FluidTimeDiscretization diff --git a/docs/source/GettingStarted.rst b/docs/source/GettingStarted.rst deleted file mode 100644 index ea78ff5ad5d52dd5f6e5df4336f4cc798e14bf11..0000000000000000000000000000000000000000 --- a/docs/source/GettingStarted.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _Chap:GettingStarted: - -Getting Started -=============== - -.. toctree:: - :maxdepth: 1 - - Structure - BuildingCMake - BuildingGMake - RunningTestSuite - RegressionTesting diff --git a/docs/source/GettingStarted_Chapter.rst b/docs/source/GettingStarted_Chapter.rst new file mode 100644 index 0000000000000000000000000000000000000000..7033b61256424a34baa70f82acc285a776b9fa45 --- /dev/null +++ b/docs/source/GettingStarted_Chapter.rst @@ -0,0 +1,32 @@ +.. _Chap:GettingStarted: + +Getting Started +=============== + +The MFiX-Exa source code currently lives in NETL's +`gitlab repository `_. The repository +can be cloned by using git: + +.. code-block:: shell + + > git clone https://mfix.netl.doe.gov/gitlab/exa/mfix.git + > cd mfix + + +.. note:: + + Access to the repository is currently restricted to project members. As the + code matures, a distribution mechanism will be developed. + +Once you have obtained the source code, the following sections describe the +source code contents, compiling, running a simple simulation, and visualizing +the simulations results. + +.. toctree:: + :maxdepth: 1 + + Source directory overview + Compiling with CMake + Compiling with GMake + Running your first simulation + Visualizing simulation results diff --git a/docs/source/Inputs_Chapter.rst b/docs/source/Inputs_Chapter.rst index 20de996627a8f99e2ad3708bb090c77c7496036e..2df1840b61e7135a7a18a9284cf37e93edd81449 100644 --- a/docs/source/Inputs_Chapter.rst +++ b/docs/source/Inputs_Chapter.rst @@ -3,16 +3,48 @@ Run-time Inputs =============== +Run-time inputs are used to control the simulation setup such as the grid, +solver settings, geometry, boundary conditions etc. These `` = `` +pairs are saved in a text file, with any file name, that is passed to the +MFiX-Exa executable at run time: + +.. code-block:: shell + + ./mfix my_project.inputs + +.. note:: + Traditionally, input files have been named ``inputs``. However, it is + recommended that you provide a descriptive name with an extension of + ``.inputs`` such as ``fluid_bed.inputs`` + +The input text file looks something like this: + +.. code-block:: + + # Run settings + mfix.stop_time = 10.0 # inline comment + + # Solver settings + nodal_proj.verbose = 0 + nodal_proj.maxiter = 1000 + +where comments are denoted with a ``#``. If a value is not specified for a key, +the default value will be used. + +The following sections contain information addressing the input keywords and +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 - InputsProblemDefinition - InputsDrag - InputsTimeStepping - InputsInitialization - InputsLoadBalancing - InputsMultigrid - InputsPlotFiles - InputsCheckpoint - InputsMonitors - InputsVerbosity + Units, mesh, geometry, species, fluid, DEM, regions, inital and boundary conditions + Particle drag + inputs/InputsTimeStepping + inputs/InputsInitialization + inputs/InputsLoadBalancing + inputs/InputsMultigrid + inputs/InputsPlotFiles + inputs/InputsCheckpoint + inputs/InputsMonitors + inputs/InputsVerbosity diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index ceb038b50f51f6a9987251751cca52dcad53fc0b..cab86ec711b8e51671c1abd4455394110205c1f5 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -1,38 +1,31 @@ -MFiX-Exa Introduction -===================== +Introduction +============ MFiX-Exa is a new massively parallel code for computing multiphase -flow in which solid particles interact with the gas surrounding them. - -It is built on top of AMReX, a publicly available software framework designed for building -massively parallel block-structured adaptive mesh refinement (AMR) +flow in which solid particles interact with the gas surrounding them. It is +built on top of `AMReX`_, a publicly available software framework designed for +building massively parallel block-structured adaptive mesh refinement (AMR) applications. -MFiX-Exa relies on the same fundamental physics as in MFIX but the spatial and +MFiX-Exa relies on the same fundamental physics as in MFiX but the spatial and time discretizations differ. Specifically, - Fluid velocity is defined at cell centers; pressure is defined at nodes. - -- The advection algorithm includes an intermediate MAC projection for face-centered advection velocities - -- Incompressibility of the fluid is imposed through the use of a projection at the - end of the time step - -- The representation of the complex geometry includes mesh refinement around the - fluid-solid interface, which is represented used the embedded boundary, or +- The advection algorithm includes an intermediate MAC projection for + face-centered advection velocities +- Incompressibility of the fluid is imposed through the use of a projection at + the end of the time step +- The representation of the complex geometry includes mesh refinement around + the fluid-solid interface, which is represented used the embedded boundary, or cut-cell approach - -- Parallelization via flat MPI, OpenMP, hybrid MPI/OpenMP, or MPI/MPI. - +- Parallelization via flat MPI, OpenMP, hybrid MPI/OpenMP, or MPI/MPI. - Porting of MFiX-Exa to GPUs is in progress. - - Parallel I/O using AMReX native I/O or HDF5. - - Plotfile format supported by AmrVis, VisIt, ParaView, and yt. -MFiX-Exa is being developed at NETL and LBNL as part of the U.S. Department of Energy's -Exascale Computing Project (ECP). - -MFiX-Exa heavily leverages AMReX (see https://amrex-codes.github.io/) which is also supported by -ECP as part of the AMReX Co-Design Center. +MFiX-Exa is being developed at NETL and LBNL as part of the U.S. Department of +Energy's `Exascale Computing Project (ECP) `_ +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/ManagingGridHierarchy_Chapter.rst b/docs/source/ManagingGridHierarchy_Chapter.rst index 90adcfbe8009e48031b60049fc251319c48d129a..6896e2e8f840801d49296e3753a35d55dd3900cc 100644 --- a/docs/source/ManagingGridHierarchy_Chapter.rst +++ b/docs/source/ManagingGridHierarchy_Chapter.rst @@ -4,34 +4,34 @@ Gridding and Load Balancing =========================== -MFiX-Exa has a great deal of flexibility when it comes to how to decompose the +MFiX-Exa has a great deal of flexibility when it comes to how to decompose the computational domain into individual rectangular grids, and how to distribute -those grids to MPI ranks. There can be grids of different sizes, +those grids to MPI ranks. There can be grids of different sizes, more than one grid per MPI rank, and different strategies for distributing the grids to MPI ranks. We use the phrase "load balancing" here to refer to the combined process of grid creation (and re-creation when regridding) and distribution of grids to MPI ranks. -See :ref:`sec:grid_creation` for grids are created, i.e. how the :cpp:`BoxArray` on which +See :ref:`sec:grid_creation` for grids are created, i.e. how the :cpp:`BoxArray` on which :cpp:`MultiFabs` will be built is defined at each level. See :ref:`sec:load_balancing` for the strategies AMReX supports for distributing -grids to MPI ranks, i.e. defining the :cpp:`DistributionMapping` with which -:cpp:`MultiFabs` at that level will be built. +grids to MPI ranks, i.e. defining the :cpp:`DistributionMapping` with which +:cpp:`MultiFabs` at that level will be built. MFiX-Exa also allows for the "dual grid approach", in which mesh and particle data are allocated -on different box layouts with different mappings to MPI ranks. This option is enabled +on different box layouts with different mappings to MPI ranks. This option is enabled by setting :cpp:`amr.dual_grid = 1` in the inputs file. See :ref:`sec:dual_grid` for more about this approach. -When running on multicore machines with OpenMP, we can also control the distribution of -work by setting the size of grid tiles (by defining :cpp:`fabarray.mfiter_tile_size`), and if relevant, of -particle tiles (by defining :cpp:`particle.tile_size`). We can also specify the strategy for assigning +When running on multicore machines with OpenMP, we can also control the distribution of +work by setting the size of grid tiles (by defining :cpp:`fabarray.mfiter_tile_size`), and if relevant, of +particle tiles (by defining :cpp:`particle.tile_size`). We can also specify the strategy for assigning tiles to OpenMP threads. See :ref:`sec:basics:mfiter:tiling:` for more about tiling. .. toctree:: :maxdepth: 1 - GridCreation - DualGrid - LoadBalancing + grid/GridCreation + grid/DualGrid + grid/LoadBalancing diff --git a/docs/source/Particles_Chapter.rst b/docs/source/Particles_Chapter.rst index 2465434ac9c48086aed61eee7be5aa8bfe391ef2..ebcd0d5985ba8d006cc05cd5969181611e7f6990 100644 --- a/docs/source/Particles_Chapter.rst +++ b/docs/source/Particles_Chapter.rst @@ -23,7 +23,7 @@ particle-particle, particle-fluid, and particle-wall interactions. :maxdepth: 1 :caption: Contents: - ParticleBasics - ParticleFluid - ParticleWalls - ParticlesOnGpus + particles/ParticleBasics + particles/ParticleFluid + particles/ParticleWalls + particles/ParticlesOnGpus diff --git a/docs/source/EBWalls.rst b/docs/source/eb/EBWalls.rst similarity index 100% rename from docs/source/EBWalls.rst rename to docs/source/eb/EBWalls.rst diff --git a/docs/source/BuildingMacVelocities.rst b/docs/source/fluids/BuildingMacVelocities.rst similarity index 100% rename from docs/source/BuildingMacVelocities.rst rename to docs/source/fluids/BuildingMacVelocities.rst diff --git a/docs/source/FluidEquations.rst b/docs/source/fluids/FluidEquations.rst similarity index 100% rename from docs/source/FluidEquations.rst rename to docs/source/fluids/FluidEquations.rst diff --git a/docs/source/FluidTimeDiscretization.rst b/docs/source/fluids/FluidTimeDiscretization.rst similarity index 100% rename from docs/source/FluidTimeDiscretization.rst rename to docs/source/fluids/FluidTimeDiscretization.rst diff --git a/docs/source/FluidTimeStep.rst b/docs/source/fluids/FluidTimeStep.rst similarity index 100% rename from docs/source/FluidTimeStep.rst rename to docs/source/fluids/FluidTimeStep.rst diff --git a/docs/source/Slopes.rst b/docs/source/fluids/Slopes.rst similarity index 100% rename from docs/source/Slopes.rst rename to docs/source/fluids/Slopes.rst diff --git a/docs/source/BuildingCMake.rst b/docs/source/getting_started/BuildingCMake.rst similarity index 100% rename from docs/source/BuildingCMake.rst rename to docs/source/getting_started/BuildingCMake.rst diff --git a/docs/source/BuildingGMake.rst b/docs/source/getting_started/BuildingGMake.rst similarity index 100% rename from docs/source/BuildingGMake.rst rename to docs/source/getting_started/BuildingGMake.rst diff --git a/docs/source/getting_started/FirstSimulation.rst b/docs/source/getting_started/FirstSimulation.rst new file mode 100644 index 0000000000000000000000000000000000000000..87032b44a64fd5bd9404a6d4935cfca19e894b72 --- /dev/null +++ b/docs/source/getting_started/FirstSimulation.rst @@ -0,0 +1,4 @@ +First Simulation +================ + +TODO: Develop simple tutorial. diff --git a/docs/source/getting_started/Paraview.rst b/docs/source/getting_started/Paraview.rst new file mode 100644 index 0000000000000000000000000000000000000000..615fb3114e4335a053793c269484f2574e9375e3 --- /dev/null +++ b/docs/source/getting_started/Paraview.rst @@ -0,0 +1,80 @@ +Using Paraview +============== + +`Paraview `_ is an opensource visualization tool +developed by `Kitware `_. It provides an intuit and +feature rich tool for visualizing simulation data. Kitware provides pre-built +binaries that can be `downloaded here `_. + + +Visualize the embedded boundary +------------------------------- + +The solver will save the embedded boundary if ``mfix.write_eb_surface = true`` +is set in the inputs file as parallel VTP file named ``eb.pvtp``. The individual +parts corresponding to different grids are saved as ``eb_########.vtp`` files. +To open the ``eb.pvtp`` file, press the open button, browse to the simulation +directory, select the ``eb.pvtp`` file, and press ``OK``. The ``eb.pvtp`` will +be displayed in the ``Pipeline Browser``. Make sure the ``eb.pvtp`` is selected +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 + + +Visualize the particles +----------------------- + +The solver will write plot files if one of the write frequency options is set +(``amr.plot_int``, ``amr.plot_per_exact``, or ``amr.plot_per_approx``) in +directories that are prefixed with the prefix specified in the inputs file +(``amr.plot_file = 'plt'``). To visualize these particles in Paraview, press +the open button. In the file dialog, browse to the simulation directory and +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 + +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 + +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 + +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 +be colored by different variables by selecting the variable in the drop down. +Additionally, if a group of plot files was opened, the simulation can be +"played" by pressing the play button. + +.. image:: /getting_started/images/paraview_pt_gauss_opts.png + +Visualize the cells +------------------- + +Following the same method to visualize the particles, the cells can be +visualized. The major difference is when the dialog asking what read to use +is displayed, select the ``AMReX/BoxLib Grid Reader`` and press ``OK``. On the +properties tab, select which variables to read (make sure to select ``ep_g``, +we will use this later) and select apply. + +.. image:: /getting_started/images/paraview_cells.png + +If the simulation has ghost cells, we can remove these cells by applying a +threshold filter. With the ``plt*`` object selected in the Pipeline Browser, +press the ``Threshold`` button. With the ``Threshold1`` object selected in the +Pipeline Browser, select ``ep_g`` as the Scalar, change the Minimum value to +be a little larger than 0 (such as 0.01), and press ``Apply``. All the ghost +cells should now be removed because ``ep_g`` in the ghost cell is exactly 0 and +the normal cells should not have a ``ep_g`` less than maximum packing. You can +still color the cells by any of the field variables while keeping the threshold +variable as ``ep_g``. + +.. image:: /getting_started/images/paraview_cells_threshold.png diff --git a/docs/source/Structure.rst b/docs/source/getting_started/Structure.rst similarity index 100% rename from docs/source/Structure.rst rename to docs/source/getting_started/Structure.rst diff --git a/docs/source/getting_started/Visualization.rst b/docs/source/getting_started/Visualization.rst new file mode 100644 index 0000000000000000000000000000000000000000..c2a3f185263e126c2b0c24e6cf074c7cd63ea3b7 --- /dev/null +++ b/docs/source/getting_started/Visualization.rst @@ -0,0 +1,14 @@ +.. _Chap:Visualization: + +Visualization +============= + +There are several programs that can be used to visualize results produced by +an MFiX-Exa simulation. Please see the following sections for details on how +to use the tools. + + +.. toctree:: + :maxdepth: 1 + + Paraview diff --git a/docs/source/getting_started/images/paraview_browse_plt.png b/docs/source/getting_started/images/paraview_browse_plt.png new file mode 100644 index 0000000000000000000000000000000000000000..aea9998151e80f29608aec0f7768cebc6303f5b5 Binary files /dev/null and b/docs/source/getting_started/images/paraview_browse_plt.png differ diff --git a/docs/source/getting_started/images/paraview_cells.png b/docs/source/getting_started/images/paraview_cells.png new file mode 100644 index 0000000000000000000000000000000000000000..fa646713ebf8e71c32154cf0c313d8cafe8a3ca5 Binary files /dev/null and b/docs/source/getting_started/images/paraview_cells.png differ diff --git a/docs/source/getting_started/images/paraview_cells_threshold.png b/docs/source/getting_started/images/paraview_cells_threshold.png new file mode 100644 index 0000000000000000000000000000000000000000..26830345e5e357d313a44facdc8ddee3e1261372 Binary files /dev/null and b/docs/source/getting_started/images/paraview_cells_threshold.png differ diff --git a/docs/source/getting_started/images/paraview_eb.png b/docs/source/getting_started/images/paraview_eb.png new file mode 100644 index 0000000000000000000000000000000000000000..d83129d414d3513ea5909dc6ad19631c3056d9b3 Binary files /dev/null and b/docs/source/getting_started/images/paraview_eb.png differ diff --git a/docs/source/getting_started/images/paraview_pt_gauss.png b/docs/source/getting_started/images/paraview_pt_gauss.png new file mode 100644 index 0000000000000000000000000000000000000000..79a2b7ed5ac86c3fd78a02a5e3bf628ea6975ee3 Binary files /dev/null and b/docs/source/getting_started/images/paraview_pt_gauss.png differ diff --git a/docs/source/getting_started/images/paraview_pt_gauss_opts.png b/docs/source/getting_started/images/paraview_pt_gauss_opts.png new file mode 100644 index 0000000000000000000000000000000000000000..44ccdbfb6f3fe260ee347972b8abe53ff84eb61a Binary files /dev/null and b/docs/source/getting_started/images/paraview_pt_gauss_opts.png differ diff --git a/docs/source/getting_started/images/paraview_reader.png b/docs/source/getting_started/images/paraview_reader.png new file mode 100644 index 0000000000000000000000000000000000000000..785a05f41561dad0be9b361bca1ac9c69b8ac750 Binary files /dev/null and b/docs/source/getting_started/images/paraview_reader.png differ diff --git a/docs/source/DualGrid.rst b/docs/source/grid/DualGrid.rst similarity index 100% rename from docs/source/DualGrid.rst rename to docs/source/grid/DualGrid.rst diff --git a/docs/source/GridCreation.rst b/docs/source/grid/GridCreation.rst similarity index 100% rename from docs/source/GridCreation.rst rename to docs/source/grid/GridCreation.rst diff --git a/docs/source/LoadBalancing.rst b/docs/source/grid/LoadBalancing.rst similarity index 100% rename from docs/source/LoadBalancing.rst rename to docs/source/grid/LoadBalancing.rst diff --git a/docs/source/images/particle_banner.png b/docs/source/images/particle_banner.png new file mode 100644 index 0000000000000000000000000000000000000000..15f3d7f71de27bd734ac514ad622cd956354fe81 Binary files /dev/null and b/docs/source/images/particle_banner.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 9dc5462bfcbf7223bbb930d943e2b00aa5738729..da5ad6472669c7c902256a30254c2157917c0100 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,36 +1,68 @@ -.. MFiX-EXA documentation master file, created by - sphinx-quickstart on Thu Aug 2 12:19:39 2018. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. MFiX-EXA documentation master file, created Thu Aug 2 12:19:39 2018. Welcome to MFiX-EXA's documentation! ==================================== -MFiX-Exa is a new multiphase modeling tool for the exascale. It -combines kernels from the existing MFiX code with the AMReX framework. +MFiX-Exa is a new multiphase computational fluid dynamics (CFD) modeling tool +that can take advantage of massively parallel high performance computers (HPC) +with the goal of scaling well at exascale. It combines the underlying physics +from the existing `MFiX `_ code with the +`AMReX `_ framework, creating the next +generation, high performance, multiphase CFD workhorse. -MFiX-Exa is under active development as part of the MFiX-Exa -application project in DOE's Exascale Computing Project. +.. image:: /images/particle_banner.png -All of MFiX-Exa's development is done in the NETL gitlab repository, with +MFiX-Exa is under active development as part of the MFiX-Exa +application project in DOE's +`Exascale Computing Project (ECP) `_. All of +MFiX-Exa's development is done in the +`NETL gitlab repository `_, with active development in the develop branch. Changes are merged into the master branch at the beginning of each month. +When mature, this project will provide a modern multi-level multi-grid fluid +solver with chemistry, heat transfer, complex geometry, and two particle models: + +1. **Discrete particle method (DEM)** - Each particle is modeled as a sphere, + resolving all particle collisions +2. **Particle in cell method (PIC)** - Particles are group in parcels and see + other parcels through a stress gradient. + +To get started with MFiX-Exa, follow the user guide sections: + .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: User guide: Introduction - GettingStarted + GettingStarted_Chapter Inputs_Chapter ManagingGridHierarchy_Chapter + + +To learn more about the implementation, follow the following reference sections: + +.. toctree:: + :maxdepth: 1 + :caption: Reference: + Fluids_Chapter Particles_Chapter - EB + EB_Chapter + Debugging + +The following section detail the testing and benchmarks used to ensure solutions +and performance: + +.. toctree:: + :maxdepth: 1 + :caption: Tests and Benchmarks: + + RunningTestSuite + RegressionTesting CITests NightlyTests qb/index - Debugging Notice ------ diff --git a/docs/source/InputsCheckpoint.rst b/docs/source/inputs/InputsCheckpoint.rst similarity index 100% rename from docs/source/InputsCheckpoint.rst rename to docs/source/inputs/InputsCheckpoint.rst diff --git a/docs/source/InputsDrag.rst b/docs/source/inputs/InputsDrag.rst similarity index 100% rename from docs/source/InputsDrag.rst rename to docs/source/inputs/InputsDrag.rst diff --git a/docs/source/InputsInitialization.rst b/docs/source/inputs/InputsInitialization.rst similarity index 100% rename from docs/source/InputsInitialization.rst rename to docs/source/inputs/InputsInitialization.rst diff --git a/docs/source/InputsLoadBalancing.rst b/docs/source/inputs/InputsLoadBalancing.rst similarity index 100% rename from docs/source/InputsLoadBalancing.rst rename to docs/source/inputs/InputsLoadBalancing.rst diff --git a/docs/source/InputsMonitors.rst b/docs/source/inputs/InputsMonitors.rst similarity index 100% rename from docs/source/InputsMonitors.rst rename to docs/source/inputs/InputsMonitors.rst diff --git a/docs/source/InputsMultigrid.rst b/docs/source/inputs/InputsMultigrid.rst similarity index 100% rename from docs/source/InputsMultigrid.rst rename to docs/source/inputs/InputsMultigrid.rst diff --git a/docs/source/InputsPlotFiles.rst b/docs/source/inputs/InputsPlotFiles.rst similarity index 100% rename from docs/source/InputsPlotFiles.rst rename to docs/source/inputs/InputsPlotFiles.rst diff --git a/docs/source/InputsProblemDefinition.rst b/docs/source/inputs/InputsProblemDefinition.rst similarity index 99% rename from docs/source/InputsProblemDefinition.rst rename to docs/source/inputs/InputsProblemDefinition.rst index 554614c881d7f4c357156eace7060060b063e16d..7accc63b3e45ef28ad566495b2f8e53fca9b051e 100644 --- a/docs/source/InputsProblemDefinition.rst +++ b/docs/source/inputs/InputsProblemDefinition.rst @@ -109,7 +109,7 @@ The following inputs must be preceded by "mfix." Species model settings --------------------- +---------------------- Enabling the species mass fraction solver and specifying species model options. diff --git a/docs/source/InputsTimeStepping.rst b/docs/source/inputs/InputsTimeStepping.rst similarity index 92% rename from docs/source/InputsTimeStepping.rst rename to docs/source/inputs/InputsTimeStepping.rst index 74b7d1d8fa76b78de5965c1eba550d65372631c8..9b26f3ed8261de2f8f793df3d7e232ccd27cca81 100644 --- a/docs/source/InputsTimeStepping.rst +++ b/docs/source/inputs/InputsTimeStepping.rst @@ -3,18 +3,20 @@ Time Stepping ============= -The following inputs must be preceded by "mfix." Note that if both are specified, both criteria +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``. + +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| | Description | Type | Default | +| Key | Description | Type | Default | +======================+=======================================================================+=============+==============+ | max_step | Maximum number of time steps to take | Int | -1 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ -| stop_time | Maximum time to reach | Real | -1.0 | +| stop_time | Maximum time to reach (s) | Real | -1.0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ | fixed_dt | Should we use a fixed timestep? | Int | 0 | +----------------------+-----------------------------------------------------------------------+-------------+--------------+ @@ -31,7 +33,7 @@ The following inputs must be preceded by "mfix" and are only relevant if running Currently, the criterion for setting "steady_state" to true is if "dt" is undefined in mfix.dat +-----------------------+-----------------------------------------------------------------------+-------------+------------+ -| | Description | Type | Default | +| Key | Description | Type | Default | +=======================+=======================================================================+=============+============+ | steady_state | Are we running a steady-state calculation? | Int | 0 | +-----------------------+-----------------------------------------------------------------------+-------------+------------+ @@ -42,11 +44,11 @@ Currently, the criterion for setting "steady_state" to true is if "dt" is undefi | steady_state_maxiter | Maximum number of allowed iterations to converge to steady state | Int | 100000000 | +-----------------------+-----------------------------------------------------------------------+-------------+------------+ -Setting the Time Step +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. +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 @@ -64,13 +66,13 @@ then setting "dtsolid" to be "tcoll / 50". 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. + step will always be that number. * 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.5 * dx / max(vel). - * If dt as computed in the compute_dt routine is smaller than the user-specified + * If dt as computed in the compute_dt routine is smaller than the user-specified ```mfix.dt_min``` then the code will abort: .. highlight:: c++ @@ -79,16 +81,16 @@ then setting "dtsolid" to be "tcoll / 50". 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 + * If dt as computed in the compute_dt routine is larger than the user-specified ```mfix.dt_max``` then dt will be set to the minimum of its computed value and 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 + 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. +These options apply to steady state calculations as well as unsteady runs. 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"), + 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/InputsVerbosity.rst b/docs/source/inputs/InputsVerbosity.rst similarity index 100% rename from docs/source/InputsVerbosity.rst rename to docs/source/inputs/InputsVerbosity.rst diff --git a/docs/source/ParticleBasics.rst b/docs/source/particles/ParticleBasics.rst similarity index 100% rename from docs/source/ParticleBasics.rst rename to docs/source/particles/ParticleBasics.rst diff --git a/docs/source/ParticleFluid.rst b/docs/source/particles/ParticleFluid.rst similarity index 100% rename from docs/source/ParticleFluid.rst rename to docs/source/particles/ParticleFluid.rst diff --git a/docs/source/ParticleWalls.rst b/docs/source/particles/ParticleWalls.rst similarity index 100% rename from docs/source/ParticleWalls.rst rename to docs/source/particles/ParticleWalls.rst diff --git a/docs/source/ParticlesOnGpus.rst b/docs/source/particles/ParticlesOnGpus.rst similarity index 100% rename from docs/source/ParticlesOnGpus.rst rename to docs/source/particles/ParticlesOnGpus.rst