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..486b51eddcf62eba95df9dad30eca5c9a465cf2f --- /dev/null +++ b/docs/source/GettingStarted_Chapter.rst @@ -0,0 +1,11 @@ +.. _Chap:GettingStarted: + +Getting Started +=============== + +.. toctree:: + :maxdepth: 1 + + getting_started/Structure + getting_started/BuildingCMake + getting_started/BuildingGMake 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/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/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/index.rst b/docs/source/index.rst index 9dc5462bfcbf7223bbb930d943e2b00aa5738729..f7e454f0a454a245389b33f2796ba382392e887d 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,28 +9,40 @@ 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 under active development as part of the MFiX-Exa -application project in DOE's Exascale Computing Project. +MFiX-Exa is under active development as part of the MFiX-Exa +application project in DOE's Exascale Computing Project. -All of MFiX-Exa's development is done in the NETL gitlab repository, with +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. .. toctree:: :maxdepth: 1 - :caption: Contents: + :caption: User guide: Introduction - GettingStarted + GettingStarted_Chapter Inputs_Chapter ManagingGridHierarchy_Chapter + +.. toctree:: + :maxdepth: 1 + :caption: Reference: + Fluids_Chapter Particles_Chapter - EB + EB_Chapter + Debugging + +.. 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 100% rename from docs/source/InputsProblemDefinition.rst rename to docs/source/inputs/InputsProblemDefinition.rst 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