Merge pull request #38 from chowland/add_docs

Add docs

.github/workflows/docs.yml

@@ -5,19 +5,28 @@ name: Deploy documentation
 
 on:
   push:
-    branches: [ main ]
-  pull_request:
-    branches: [ main ]
+    branches: 
+      - main
+
+permissions:
+  contents: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v2
-
-      - uses: actions/setup-python@v2
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
         with:
           python-version: 3.x
+
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
 
       - run: pip install mkdocs-material mkdocs-macros-plugin
 

.gitignore

@@ -11,4 +11,7 @@ tmp
 examples/*/*.svg
 examples/*/*.ipynb
 *.ipynb_checkpoints
-*.out
+*.out
+tools/*.svg
+tools/*.png
+tools/*.mp4

Makefile

@@ -10,7 +10,7 @@ FLAVOUR=GNU
 # MARENOSTRUM (Intel): fabric intel mkl impi hdf5 fftw szip
 # SUPERMUC (Intel): fftw hdf5
 # DISCOVERER:
-#	GNU: hdf5/1/1.14/latest-gcc-openmpi fftw/3/latest-gcc-openmpi lapack
+#	GNU: hdf5/1/1.14/1.14.0-gcc-openmpi fftw/3/latest-gcc-openmpi lapack
 #	Intel: hdf5/1/1.14/latest-intel-openmpi fftw/3/latest-gcc-openmpi mkl
 
 #=======================================================================
@@ -50,10 +50,8 @@ ifeq ($(MACHINE),DISCOVERER)
 endif
 ifeq ($(MACHINE),SNELLIUS)
 	ifeq ($(FLAVOUR),GNU)
-		FC += -O2 -march=znver1 -mtune=znver1 -mfma -mavx2 -m3dnow -fomit-frame-pointer
 		LDFLAGS = -lfftw3 -lopenblas -ldl
 	else
-		FC += -align array64byte -fma -ftz -fomit-frame-pointer
 		LDFLAGS = -lfftw3 -qmkl=sequential
 	endif
 endif

README.md

@@ -8,25 +8,27 @@
 
 AFiD has the following prerequisites that must be installed to compile and run the program:
 - A parallel HDF5 library wrapping an MPI implementation and a Fortran 90 compiler
-- The numerical BLAS and LAPACK libraries (or Intel MKL)
+- The numerical LAPACK library (or Intel MKL)
 - FFTW3 (*not* the MKL implementation)
 
 On Ubuntu, these prerequisites can be installed using the single line command
 ```
-sudo apt install build-essential gfortran libblas-dev liblapack-dev libhdf5-mpich-dev libfftw3-dev
+sudo apt install build-essential gfortran liblapack-dev libhdf5-mpich-dev libfftw3-dev
 ```
 AFiD can then be compiled simply by running `make`.
-The [Makefile](./Makefile) contains a `MACHINE` variable that the user can modify to reflect the libraries installed (e.g. setting it to `PC_INTEL` to ensure the MKL libraries and Intel compiler options are used).
-Presets are also available for a collection of European HPC systems.
+The [Makefile](./Makefile) contains a `MACHINE` variable and a `FLAVOUR` variable that the user can modify to reflect the libraries installed (e.g. setting `FLAVOUR=Intel` ensures the MKL libraries and Intel compiler options are used).
+Presets are also available for a collection of European HPC systems using the `MACHINE` variable.
 
 ## Code description
 
 ### Key features
 - Third-order Runge-Kutta time stepping
 - Finite-differences calculate spatial derivatives on staggered velocity grid
 - Pencil MPI decomposition based on the 2DECOMP&FFT library
-- Hermite interpolation between two decoupled grids for multiple resolution
-- Optional phase-field model to simulate the flow around melting objects
+- Cubic Hermite interpolation between two decoupled grids for multiple resolution
+- Phase-field model to simulate the flow around melting objects following [Hester et al. (2020)](https://doi.org/10.1098/rspa.2020.0508)
+- Immersed boundary method for fixed objects following [Fadlun et al. (2000)](https://doi.org/10.1006/jcph.2000.6484)
+- A simple moisture model for a rapidly condensing vapour field following [Vallis et al. (2019)](https://doi.org/10.1017/jfm.2018.954)
 
 AFiD is a highly parallel application for simulating canonical flows in a channel domain.
 More technical details can be found in [van der Poel et al (2015)](https://doi.org/10.1016/j.compfluid.2015.04.007).
@@ -41,7 +43,6 @@ One key difference from the original version of AFiD is that the scalar fields a
 This staggered grid provides more flexibility for applications with different gravitational axes.
 
 The refined grid can also be used to evolve a phase-field variable to model the melting and dissolving of immersed solid objects.
-This implementation is currently under development.
 
 ## Contributing
 If you would like to contribute to bug fixing/feature development/documentation, please create a new branch, commit your changes and then submit a pull request.

docs/convergence.md

@@ -35,7 +35,7 @@ where $T$ is the simulation output, $T_a$ is the analytic solution, and $t_f=10$
   </figcaption>
 </figure> -->
 
-## 2-D Taylor-Green vortex
+<!-- ## 2-D Taylor-Green vortex
 **To be completed**
 
 To test the convergence of the combined advection and diffusion, we consider the velocity field associated with a decaying, advected Taylor-Green vortex.
@@ -46,13 +46,13 @@ $$
 v = -\sin(z-Wt)\cos(y) e^{-2\nu t}, \qquad w = W + \cos(z - Wt)\sin(y) e^{-2\nu t} ,
 $$
 
-where $W$ is a uniform constant advection, and $\nu=(Pr/Ra)^{1/2}$ is the dimensionless viscosity (or inverse Reynolds number) determined by the input parameters $Ra$ and $Pr$.
+where $W$ is a uniform constant advection, and $\nu=(Pr/Ra)^{1/2}$ is the dimensionless viscosity (or inverse Reynolds number) determined by the input parameters $Ra$ and $Pr$. -->
 
 ## Phase-field model: 1-D Stefan problem
 
 Now we perform a convergence test for the phase-field model used to simulate liquid-solid phase transitions.
 We consider the problem of a liquid phase freezes from a cold boundary and a solidification front moves across the domain.
-As for the melting problem on the validation page LINK THIS, the analytic solution for the phase boundary height is
+As for the melting problem on the [validation page](phasefield_validation.md), the analytic solution for the phase boundary height is
 
 $$
 h(t) = 2\Lambda \sqrt{(t+t_0)/Pe_T} ,

docs/examples/ddc.md

@@ -1 +1,3 @@
-# Double-diffusive convection
+# Double-diffusive convection
+
+*Coming soon*

docs/examples/rbc.md

@@ -1 +1,65 @@
-# Rayleigh-Bénard Convection
+# Rayleigh-Bénard Convection
+
+One of the simplest setups we can consider is the Rayleigh-Bénard problem, where fluid is contained between two stationary parallel plates which are held at fixed temperatures.
+If the lower plate is maintained at a higher temperature than the upper plate, then density differences due to temperature can drive convection in the domain.
+Stronger thermal driving, characterised by a larger Rayleigh number, drives a stronger flow.
+
+In MuRPhFi, we can take advantage of the multiple resolution grid to efficiently simulate this problem at high $Pr$.
+Since `temp` on the coarse grid and `sal` on the refined grid evolve according to the same equations (up to a different $Pr$), we can treat `sal` as $-\theta/\Delta$ for the dimensionless temperature of the system.
+We set `activeT=0` to remove the effect of `temp` on the buoyancy and run the simulation.
+
+## 2D Visualization
+
+Here, we show the results for $Ra=10^8$, $Pr=10$.
+The simulation was run with a resolution of $128^3$ on the coarse grid for velocity, and a resolution of $384^3$ on the refined grid for "temperature".
+First, we use the script `parallel_movie.py` to produce a visualisation of a vertical slice of the "temperature" field `sal`:
+
+<video width="100%" controls>
+  <source src="../../assets/RBC.mp4" type="video/mp4">
+</video>
+
+## Statistics
+
+We can then dive into the statistics output in `means.h5` to calculate the dimensionless heat flux due to the convection, the Nusselt number $Nu$, and the Reynolds number $Re$.
+The following are produced from the script `plot_time_series.py`.
+
+## Nusselt number
+
+In Rayleigh-Bénard convection, there are a number of ways to calculate the Nusselt number, all of which should be equivalent (in a time-averaged sense) in a well-resolved, statistically steady state.
+Firstly, we can measure the conductive heat flux at the top and bottom plates:
+
+$$
+{Nu}_\mathrm{pl} = \frac{H}{\Delta} \left.\frac{\partial \theta}{\partial z} \right|_{z=0}, \qquad Nu_\mathrm{pu} = \frac{H}{\Delta} \left.\frac{\partial \theta}{\partial z} \right|_{z=H}
+$$
+
+The volume average of the heat flux will give us another definition, computed as the sum of conductive and convective contributions:
+
+$$
+Nu_\mathrm{vol} = 1 + \frac{\langle w'\theta'\rangle}{\kappa \Delta/H}
+$$
+
+Substituting this into the equations for kinetic energy $\langle|\boldsymbol{u}|^2\rangle$ and temperature variance $\langle\theta^2\rangle$ provide two further definitions, linked to the volume-averaged dissipation rates:
+
+$$
+Nu_\varepsilon = 1 + \langle \partial_i u_j \partial_i u_j \rangle / (U_f/H)^2, \qquad
+Nu_\chi = \langle |\nabla \theta|^2 \rangle / (\Delta/H)^2 .
+$$
+
+![Nusselt numbers](../figures/Nusselt.svg){ width="100%" }
+
+### Reynolds number
+
+Since there is no imposed flow and no volume-averaged mean flow in Rayleigh-Bénard convection, we use the volume-averaged kinetic energy $\mathcal{K}$ to compute a Reynolds number.
+With this approach, we can also separately compute Reynolds numbers based on the vertical kinetic energy $\langle w^2\rangle$ and on the horizontal kinetic energy $\langle u^2 + v^2\rangle$.
+
+As in the Nusselt number plot above, we appear to converge to a statistically steady state for $t \geq 75 H/U_f$ after the initial transient behaviour.
+
+![Reynolds number](../figures/Reynolds.svg){ width="100%" }
+
+## 3D Visualization
+
+Finally, we can use the saved 3D snapshots to make a volume rendering of the temperature field.
+This snapshot highlights the narrow plume structures driving the large-scale circulation at high $Pr$.
+The image has been produced using ParaView.
+
+![Volume rendering](../assets/RBC_Pr10_square.jpg){ width="100%" }