diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 03ab11881e4ffd2632784bea2f8fb426b48a3877..a9b2533517f6b78f63bcfa06137c3471b3e774cd 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -31,7 +31,7 @@ docs:codespell: image: sphinxdoc/sphinx:latest script: - pip install codespell - - codespell --ignore-words-list strack,HEP --enable-colors --quiet-level 2 docs/source_docs/ docs/picvva/ + - codespell --ignore-words-list oint,strack,HEP --enable-colors --quiet-level 2 docs/source_docs/ docs/picvva/ stage: build-docs tags: - docker diff --git a/docs/source_docs/index.rst b/docs/source_docs/index.rst index 2425d5a9b0fbe647fb864990e59a09d83c47eff1..2660b328691bdbdc86bf67663165391d3c78f398 100644 --- a/docs/source_docs/index.rst +++ b/docs/source_docs/index.rst @@ -46,6 +46,15 @@ To get started with MFIX-Exa, follow the user guide sections: Quick start guide Run-time inputs +Tutorials provide complete example cases and explain the major setup choices: + +.. toctree:: + :maxdepth: 1 + :caption: Tutorials: + + tutorials/index + + To learn more about the implementation, follow the following reference sections: diff --git a/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-drag-coeff.png b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-drag-coeff.png new file mode 100644 index 0000000000000000000000000000000000000000..e480cbbf27dd1bcd366636eb1f47865d3e20155f Binary files /dev/null and b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-drag-coeff.png differ diff --git a/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-lift-coeff.png b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-lift-coeff.png new file mode 100644 index 0000000000000000000000000000000000000000..9fc0628bd1270a360c911723d6dab0e357c200ee Binary files /dev/null and b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder-lift-coeff.png differ diff --git a/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder.png b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder.png new file mode 100644 index 0000000000000000000000000000000000000000..058a5902d27dca568d019fb632a2c61409b9bc1e Binary files /dev/null and b/docs/source_docs/tutorials/incompressible-fluid/images/steady-flow-around-cylinder.png differ diff --git a/docs/source_docs/tutorials/incompressible-fluid/steady-flow-around-cylinder.rst b/docs/source_docs/tutorials/incompressible-fluid/steady-flow-around-cylinder.rst new file mode 100644 index 0000000000000000000000000000000000000000..1d331d0baae0d8f3152df3c76f656ad1f7e2e460 --- /dev/null +++ b/docs/source_docs/tutorials/incompressible-fluid/steady-flow-around-cylinder.rst @@ -0,0 +1,211 @@ +.. _TutorialSteadyFlowAroundCylinder: + +Steady Flow Around a Cylinder +============================= + +This tutorial sets up fluid flow around a fixed circular cylinder based +on the work of Schäfer et al. (1996). This is a steady, low-Reynolds-number +cylinder-flow example that uses MFIX-Exa's embedded-boundary geometry. + +Features +-------- + +* Incompressible fluid with no particles. +* Steady-state advance +* Quasi-2D domain using a thin, periodic spanwise direction. +* Cylinder represented by a predefined embedded boundary. +* Velocity inlet, pressure outlet, no-slip walls, and a periodic spanwise direction. +* Plotfile output for velocity, pressure, and EB volume fraction. +* Report output for the EB drag force. + +Case description +---------------- + +The flow enters from the low-:math:`x=0.` boundary and exits at the +high-:math:`x=2.46` boundary. The low-:math:`y=-0.20` and high-:math:`y=0.21` +boundaries are no-slip walls. The cylinder has a radius of :math:`0.05` m and +is located at :math:`x=0.2`, :math:`y=0.` so that it is slightly off-centered +with respect to channel height. To mimic the original setup, the channel is +thin and periodic in :math:`z`. + +The tutorial uses + +.. math:: + + \rho = 1,\qquad \mu = 0.001,\qquad D = 0.1, + +with the inlet velocity defined by + +.. math:: + + u(x=0,y) = \frac{1.2(y+0.2)(0.21-y)}{0.41^2} . + + +Defining the mean velocity as :math:`\overline{u} = 2u(x=0,y=0.41/2-0.2)/3 = 0.2`, + +.. math:: + + Re = \frac{\rho \overline{u} D}{\mu} = 20. + +At this Reynolds number the wake should approach a steady, slightly-asymmetric state. + + +Important input sections +------------------------ + +The mesh is a long box with a periodic :math:`z` direction: + +.. code-block:: text + + geometry.is_periodic = 0 0 1 + geometry.prob_lo = 0.00 -0.20 -0.205 + geometry.prob_hi = 2.46 0.21 0.205 + + amr.n_cell = 192 32 32 + +The cylinder is a predefined embedded boundary. The +``cylinder.internal_flow = false`` setting means the flow is outside the +cylinder, not inside a pipe and the ``cylinder.height = -1.0`` means that +the cylinder is infinitely long: + +.. code-block:: text + + mfix.geometry = "cylinder" + + cylinder.internal_flow = false + cylinder.radius = 0.05 + cylinder.height = -1.0 + cylinder.direction = 2 + cylinder.center = 0.2 0.0 0.0 + +The low- and high-:math:`y` faces are no-slip walls. The low-:math:`x` face +is a mass inflow and the high-:math:`x` face is a pressure outlet: + +.. code-block:: text + + bc.regions = bottom_wall top_wall inflow outflow + + bc.bottom_wall = no-slip + bc.top_wall = no-slip + + bc.inflow = mi + bc.inflow.fluid.density = 1.0 + bc.inflow.fluid.inflow_type = velocity + bc.inflow.fluid.velocity = "1.2*(y+0.2)*(0.21-y)/0.1681" + + bc.outflow = po + bc.outflow.pressure = 101325.0 + + +The case is run with the pseudo steady-state time advance with a tolerance +of :math:`1.0e-6` and 50,000 maximum iterations. The maximum time step size +is set to ensure :math:`\Delta t \sim (\Delta x)^2`. + +.. code-block:: text + + mfix.steady_state = 1 + + mfix.steady_state_tol = 1.0e-6 + mfix.steady_state_maxiter = 50000 + + mfix.dt_max = 1.64e-4 + +.. note:: + + The complete input file is located in the MFIX-Exa source directory as + ``tutorials/incompressible-fluid/inputs.steady-around-cylinder`` + + +Post-Processing +--------------- + +The run writes an AMReX plotfile named ``plt*`` every 5000 iterations into a directory, +``io``, in the run directory. Each plot file saves the fluid: + +* velocity field, ``vel_g``, +* pressure, ``p_g``, and +* embedded-boundary volume fraction, ``volfrac``. + +The plotfile data can be viewed in ParaView, VisIt, or any other AMReX-compatible +post-processing tool. For visualization, load the final ``plt*`` directory and +display the velocity magnitude on a slice normal to the spanwise direction. Overlaying +velocity vectors helps show the acceleration around the cylinder and the steady +wake behind it. + +.. _fig_steady_flow_around_cylinder_vel_mag: + +.. figure:: ./images/steady-flow-around-cylinder.png + :width: 85% + :align: center + :alt: Image showing the steady-state velocity magnitude as a color field and 2D vector field at slices in y axis direction. + + Velocity magnitude and selected vector field at steady state. + + +The setup also enables the **Embedded Boundary (EB) drag report** for the +EB surface captured by the ``eb_cyl`` region. This report region encloses the +physical cylinder so that the EB surface is included in the integration; it does +not redefine the cylinder geometry used by the flow solver. + +.. code-block:: text + + regions = ... eb_cyl + + regions.eb_cyl.shape = cylinder + regions.eb_cyl.cylinder.radius = 0.075 + regions.eb_cyl.cylinder.start = 0.2 0.0 -0.205 + regions.eb_cyl.cylinder.end = 0.2 0.0 0.205 + + mfix.reports.eb_drag.regions = eb_cyl + + mfix.reports.eb_drag.eb_cyl.int = 500 + +This report calculates the total aerodynamic force by integrating the fluid's +pressure and shear stress over the captured surface: + +.. math:: + + \vec{F} = \oint \left[-p\vec{n} + \vec{\tau} \cdot \vec{n} \right] dA + +The report output is written every 500 iterations and contains the force +components on the embedded boundary. For this two-dimensional benchmark, the +streamwise force :math:`F_x` is used to compute the drag coefficient and the +cross-stream force :math:`F_y` is used to compute the lift coefficient: + +.. math:: + + C_D = \frac{2 F_x}{\rho \overline{u}^2 D}, \qquad + C_L = \frac{2 F_y}{\rho \overline{u}^2 D}. + +Here :math:`D=0.1` is the cylinder diameter and :math:`\overline{u}=0.2` is the +mean inlet velocity. At convergence, the coefficients should level off to +nearly constant values, indicating that the steady-state solve has reached the +expected asymmetric wake. + + + +.. _fig_steady_flow_around_cylinder_drag_coeffs: + + +.. list-table:: + :widths: 50 50 + :class: borderless + + * - .. figure:: ./images/steady-flow-around-cylinder-drag-coeff.png + :width: 100% + :alt: Figure showing the evolution of the drag coefficient versus iteration + + Drag coefficient vs iteration + - .. figure:: ./images/steady-flow-around-cylinder-lift-coeff.png + :width: 100% + :alt: Figure showing the evolution of the lift coefficient versus iteration + + Lift coefficient vs iteration + + +Extensions +---------- + +* Refine ``amr.n_cell`` to run a uniformly finer mesh. +* Enable mesh refinement by increasing ``amr.max_level`` to refine the mesh near the embedded boundary +* Run at higher Reynolds number for longer times to observe unsteady vortex shedding. diff --git a/docs/source_docs/tutorials/index.rst b/docs/source_docs/tutorials/index.rst new file mode 100644 index 0000000000000000000000000000000000000000..50a096dd7bd59a8d14ba3de4e62ec845d585110f --- /dev/null +++ b/docs/source_docs/tutorials/index.rst @@ -0,0 +1,10 @@ +Incompressible Fluid +==================== + +These tutorials describe complete MFIX-Exa cases and the main input choices +used to build them. + +.. toctree:: + :maxdepth: 1 + + incompressible-fluid/steady-flow-around-cylinder