From 7ac6e826c1452470b6e6ee46db34c07f42a458a0 Mon Sep 17 00:00:00 2001 From: Justin Weber Date: Thu, 11 Jun 2020 17:51:39 -0400 Subject: [PATCH] re-org docs, add info --- README.md | 43 +++++++++++---- docs/source/{EB.rst => EB_Chapter.rst} | 2 +- docs/source/Fluids_Chapter.rst | 4 +- docs/source/GettingStarted.rst | 13 ----- docs/source/GettingStarted_Chapter.rst | 11 ++++ docs/source/Inputs_Chapter.rst | 52 +++++++++++++++---- docs/source/Particles_Chapter.rst | 8 +-- docs/source/{ => eb}/EBWalls.rst | 0 .../{ => fluids}/BuildingMacVelocities.rst | 0 docs/source/{ => fluids}/FluidEquations.rst | 0 .../{ => fluids}/FluidTimeDiscretization.rst | 0 docs/source/{ => fluids}/FluidTimeStep.rst | 0 docs/source/{ => fluids}/Slopes.rst | 0 .../{ => getting_started}/BuildingCMake.rst | 0 .../{ => getting_started}/BuildingGMake.rst | 0 .../{ => getting_started}/Structure.rst | 0 docs/source/index.rst | 26 +++++++--- docs/source/{ => inputs}/InputsCheckpoint.rst | 0 docs/source/{ => inputs}/InputsDrag.rst | 0 .../{ => inputs}/InputsInitialization.rst | 0 .../{ => inputs}/InputsLoadBalancing.rst | 0 docs/source/{ => inputs}/InputsMonitors.rst | 0 docs/source/{ => inputs}/InputsMultigrid.rst | 0 docs/source/{ => inputs}/InputsPlotFiles.rst | 0 .../{ => inputs}/InputsProblemDefinition.rst | 0 .../{ => inputs}/InputsTimeStepping.rst | 28 +++++----- docs/source/{ => inputs}/InputsVerbosity.rst | 0 .../source/{ => particles}/ParticleBasics.rst | 0 docs/source/{ => particles}/ParticleFluid.rst | 0 docs/source/{ => particles}/ParticleWalls.rst | 0 .../{ => particles}/ParticlesOnGpus.rst | 0 31 files changed, 128 insertions(+), 59 deletions(-) rename docs/source/{EB.rst => EB_Chapter.rst} (96%) delete mode 100644 docs/source/GettingStarted.rst create mode 100644 docs/source/GettingStarted_Chapter.rst rename docs/source/{ => eb}/EBWalls.rst (100%) rename docs/source/{ => fluids}/BuildingMacVelocities.rst (100%) rename docs/source/{ => fluids}/FluidEquations.rst (100%) rename docs/source/{ => fluids}/FluidTimeDiscretization.rst (100%) rename docs/source/{ => fluids}/FluidTimeStep.rst (100%) rename docs/source/{ => fluids}/Slopes.rst (100%) rename docs/source/{ => getting_started}/BuildingCMake.rst (100%) rename docs/source/{ => getting_started}/BuildingGMake.rst (100%) rename docs/source/{ => getting_started}/Structure.rst (100%) rename docs/source/{ => inputs}/InputsCheckpoint.rst (100%) rename docs/source/{ => inputs}/InputsDrag.rst (100%) rename docs/source/{ => inputs}/InputsInitialization.rst (100%) rename docs/source/{ => inputs}/InputsLoadBalancing.rst (100%) rename docs/source/{ => inputs}/InputsMonitors.rst (100%) rename docs/source/{ => inputs}/InputsMultigrid.rst (100%) rename docs/source/{ => inputs}/InputsPlotFiles.rst (100%) rename docs/source/{ => inputs}/InputsProblemDefinition.rst (100%) rename docs/source/{ => inputs}/InputsTimeStepping.rst (92%) rename docs/source/{ => inputs}/InputsVerbosity.rst (100%) rename docs/source/{ => particles}/ParticleBasics.rst (100%) rename docs/source/{ => particles}/ParticleFluid.rst (100%) rename docs/source/{ => particles}/ParticleWalls.rst (100%) rename docs/source/{ => particles}/ParticlesOnGpus.rst (100%) diff --git a/README.md b/README.md index 3652b64..542d4ce 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 4786a36..f7e1bc2 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 f65ccf2..4edad6d 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 ea78ff5..0000000 --- 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 0000000..486b51e --- /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 20de996..2df1840 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 2465434..ebcd0d5 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 9dc5462..f7e454f 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 74b7d1d..9b26f3e 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 -- GitLab