Updating Documented Examples

docs/sphinx/ChollaExamples/1D-Shu-Osher/overview.md

@@ -0,0 +1,52 @@
+# 1D Shu and Osher test
+This test (Shu & Osher, 1989) highlights the ability of a code to resolve small scale smooth flow and shocks simultaneously. Further, it shows how lower resolution solutions can cut off some of the amplitude of maxima due to the slope limiters. Parameters are from Stone et al., 2008, Section 8.1. The test consists of left and right states separated at x = -0.8. On the left, density is set to 3.857143, pressure to 10.33333, and velocity to 2.629369. On the right, density is sinusoidally varying: $\rho(x)$ =  1.0 + 0.2 $\sin(5.0\pi x)$. Pressure is set to 1.0 and the velocity is 0.0. Gamma is set to 1.4. This test is performed with the hydro build (`cholla/builds/make.type.hydro`). Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `Shu_Osher()`.  
+
+**Important:** This test must be run with diode boundaries [disabled](https://github.com/alwinm/cholla/tree/main-diode) in order to perform as expected (thank you @alwinm!). This branch also uses the Van Leer integrator.
+
+## Parameter file: (**modified** from `cholla/examples/1D/Shu_Osher.txt`)
+Modified to add yl_bcnd, yu_bcnd, zl_bcnd, and zu_bcnd=0. Xmin changed to -1.0 and xlen to 2.0.
+```
+# Parameter File for the Shu-Osher shock tube test, originally from
+#     Shu & Osher, 1989. These parameters are from Stone et al., 2008, Section 8.1
+#
+
+######################################
+# number of grid cells in the x dimension
+nx=200
+# number of grid cells in the y dimension
+ny=1
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=0.47
+# time interval for output
+outstep=0.47
+# value of gamma
+gamma=1.4
+# name of initial conditions
+init=Shu_Osher
+# domain properties
+xmin=-1.0
+ymin=0.0
+zmin=0.0
+xlen=2.0
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=3
+xu_bcnd=3
+yl_bcnd=0
+yu_bcnd=0
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+```
+Upon completion, you should obtain 2 output files. The initial and final density, pressure, and velocity (in code units) of the solution is shown below (pink dots) plotted over high resolution solution with 4000 cells (purple line). Examples of how to extract and plot data can be found in `cholla/python_scripts/plot_sod.ipynb`.  
+
+:::{figure} two_times.png
+
+With the diode disabled, this solution does match that of Schneider and Robertson 2015 and Stone et al. 2008, shown below:
+
+<img src="./images/stone2008shu-osher.png" width="600" />   
+

docs/sphinx/ChollaExamples/1D-Square-Wave/overview.md

@@ -0,0 +1,81 @@
+# 1D Square Wave
+This test initializes a square wave density pertubation. The setup consists of an initial density and pressure of 1.0 and 0.01, respectively. A square wave is initialized with amplitude 1.5. Gamma is set to 1.666666666666667. This test was performed with the hydro build (`cholla/builds/make.type.hydro`) and Van Leer integrator. Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `Square_Wave()`. 
+
+## Parameter file: (modified from`cholla/examples/1D/square_wave.txt`)
+Modified to add yl_bcnd, yu_bcnd, zl_bcnd, and zu_bcnd=0
+```
+#
+# Parameter File for square wave test
+#
+
+################################################
+# number of grid cells in the x dimension
+nx=100
+# number of grid cells in the y dimension
+ny=1
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=1.0
+# time interval for output
+outstep=0.01
+n_hydro=1
+# name of initial conditions
+init=Square_Wave
+# size of domain
+xmin=0.0
+ymin=0.0
+zmin=0.0
+xlen=1.0
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=1
+xu_bcnd=1
+yl_bcnd=0
+yu_bcnd=0
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+
+#################################################
+# Parameters for square wave 
+# initial density 
+rho=1.0
+# velocity in the x direction 
+vx=1.0
+# velocity in the y direction
+vy=0
+# velocity in the z direction
+vz=0
+# initial pressure 
+P=0.01
+# relative amplitude of overdense region 
+A=1.5
+# value of gamma
+gamma=1.666666666666667
+```
+Upon completion, you should obtain 101 output files. We can obtain the evolution of the density (here at 10 fps). Pressure is constant to the $10^{-14}$ level. Examples of how to extract and plot data can be found in `cholla/python_scripts/plot_sod.ipynb`.  
+
+
+:::{video} square-docs.mp4
+    :width: 640
+    :height: 480
+    :autoplay:
+    :loop:
+    :align: center
+:::
+
+We see a square waveform of amplitude 1.5 propagating rightwards.  
+
+If the wave is left to propagate for an extended period of time, we observe a rapid breakdown in the structure. This breakdown is much fast with the Van Leer integrator than with the Simple integrator:
+
+Van Leer:
+
+<img src="https://github.com/user-attachments/assets/52248416-8606-43e8-bac5-8d4179581785" width="682" height="452" />
+
+Simple:
+
+https://github.com/evazlimen/cholla-example-tests/assets/109487593/7e45ec1c-0d61-452f-abc9-eeb2f1eb0024
+

docs/sphinx/ChollaExamples/1D-Strong-Shock/overview.md

@@ -0,0 +1,68 @@
+# 1D Strong Shock
+This test is similar to the Sod shock tube but has higher initial pressure and density differences. This shows the ability of a code to limit oscillatory behavior in areas of high density and pressure contrasts. The setup consists of a density and pressure of 10.0 and 100.0, respectively, for 0 \< x \< 0.5 and density= pressure = 1.0 for 0.5 \< x \< 1.0. Gamma is set to 1.4. This test was performed with the hydro build (`cholla/builds/make.type.hydro`) and Van Leer integrator. Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `Riemann()`. 
+
+## Parameter file: (modified from`cholla/examples/1D/strong_shock.txt`)
+Modified to add yl_bcnd, yu_bcnd, zl_bcnd, and zu_bcnd=0
+```
+#
+# Parameter File for 1D strong shock test
+#
+
+################################################
+# number of grid cells in the x dimension
+nx=100
+# number of grid cells in the y dimension
+ny=1
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=0.07
+# time interval for output
+outstep=0.07
+# name of initial conditions
+init=Riemann
+# domain properties
+xmin=0.0
+ymin=0.0
+zmin=0.0
+xlen=1.0
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=3
+xu_bcnd=3
+yl_bcnd=0
+yu_bcnd=0
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+
+#################################################
+# Parameters for 1D Riemann problems
+# density of left state
+rho_l=10.0
+# velocity of left state
+vx_l=0.0
+vy_l=0.0
+vz_l=0.0
+# pressure of left state
+P_l=100.0
+# density of right state
+rho_r=1.0
+# velocity of right state
+vx_r=0.0
+vy_r=0.0
+vz_r=0.0
+# pressure of right state
+P_r=1.0
+# location of initial discontinuity
+diaph=0.5
+# value of gamma
+gamma=1.4
+```
+Upon completion, you should obtain two output files.  The initial and final density, pressure, and velocity (in code units) of the solution is shown below (pink dots) plotted over the exact solution (purple line). Examples of how to extract and plot data can be found in cholla/python_scripts/plot_sod.ipynb.  
+
+:::figure{two_times.png}
+
+We see a rarefaction expanding from just after the initial discontinuity, followed by a contact discontinuity at x =0.75 and a shock at x = 0.85. There is very slight oscillatory behavior around x = 0.7 but it is limited.

docs/sphinx/ChollaExamples/1d-blast/overview.md

@@ -0,0 +1,52 @@
+# 1D Blast Wave
+This test is designed to assess the performance of a code near strong shocks and contact discontinuities. Parameters are derived from Woodward & Collela, 1984. The test consists of three regions. For x < 0.1, pressure is set to 1000.0. For x > 0.9, pressure is set to 100. Everywhere else, pressure is set to 0.01. Density is set to 1.0 everywhere and velocity everywhere is zero. Gamma is set to 1.4. This test is performed with the hydro build (`cholla/builds/make.type.hydro`) and Van Leer integrator. Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `Blast_1D()`. 
+
+## Parameter file: (`cholla/examples/1D/blast_1D.txt`)
+```
+#
+# Parameter File for the 1D interacting blast wave test from
+#     Woodward & Collela, 1984. See also Stone et al., 2008, Section 8.1
+#
+
+######################################
+# number of grid cells in the x dimension
+nx=400
+# number of grid cells in the y dimension
+ny=1
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=0.038
+# time interval for output
+outstep=0.00038
+# value of gamma
+gamma=1.4
+# name of initial conditions
+init=Blast_1D
+# domain properties
+xmin=0.0
+ymin=0.0
+zmin=0.0
+xlen=1.0
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=2
+xu_bcnd=2
+yl_bcnd=0
+yu_bcnd=0
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+```
+Upon completion, you should obtain 101 output files. The initial and final density, pressure, and velocity (in code units) of the solution is shown below.  Examples of how to extract and plot data can be found in `cholla/python_scripts/plot_sod.ipynb`.  
+
+
+We see a contact discontinuity around x = 0.6 followed by a shock at x = 0.65 and a rarefaction fan. We have a contact discontinuity just past x = 0.75 cells and a shock at x = 0.85. 
+
+:::{figure} two_times.png
+
+We can also obtain the evolution (here at 10 fps):
+
+

docs/sphinx/ChollaExamples/2d-khd/overview.md

@@ -0,0 +1,57 @@
+# 2D Discontinuous Kelvin-Helmholtz Test
+This test highlights the ability of a code to resolve mixing caused by shear flows, emphasizing the importance of an efficient, high order reconstuction method and a fast code. The level of mixing increases with the resolution. See Chandrasekhar 1961. It consists of a high density region (density = 1 and x velocity = 0.5) in the middle third of the grid sandwiched between two low density regions (density = 1 and x velocity = -0.5). Y-velocities are perturbed by a sine wave of amplitude 0.1. Pressure is 2.5 everywhere and gamma is set to 1.666667. Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `KH()`.This test is performed with the default hydro build (`cholla/builds/make.type.hydro`) and Van Leer integrator.  
+
+
+## Parameter file: (`cholla/examples/2D/KH_discontinuous_2D.txt`)
+```
+#
+# Parameter File for the 2D discontinuous Kelvin-Helmholtz test.
+#
+
+######################################
+# number of grid cells in the x dimension
+nx=256
+# number of grid cells in the y dimension
+ny=256
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=2.0
+# time interval for output
+outstep=0.01
+n_hydro=1
+# value of gamma
+gamma=1.666667
+# name of initial conditions
+init=KH
+# domain properties
+xmin=0.0
+ymin=0.0
+zmin=0.0
+xlen=1.0
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=1
+xu_bcnd=1
+yl_bcnd=1
+yu_bcnd=1
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+```
+Upon completion, you should obtain 201 output files. The initial and final density and pressure (in code units) is shown below. Examples of how to plot projections and slices can be found in `cholla/python_scripts/Projection_Slice_Tutorial.ipynb`.  
+Density:  
+<img src="./images/2dkh-discontinuous_density_xy.png" width="1200" />  
+Pressure:  
+<img src="./images/2dkh-discontinuous_pressure_xy.png" width="1200" />  
+
+We see even on a relatively low resolution grid, significant shear mixing has occured. An evolution of the density at 10 fps is seen [[here|/images/kh-discont-d.mp4]]:  
+
+We can compare Cholla (left) to the results of the [Athena](https://www.astro.princeton.edu/~jstone/Athena/tests/kh/kh.html) code (right), on a 512x512 grid at t = 1.00. Density is shown on a linear color map between 0.9 and 2.1  
+<img src="./images/2d_khdiscontinuous_512density_xy.gif" width="400" />  
+<img src="./images/athena-kh.t=1.gif" width="400" />  
+
+
+

docs/sphinx/ChollaExamples/index.md

@@ -8,5 +8,10 @@ Continue porting me from the [wiki](https://github.com/cholla-hydro/cholla/wiki/
 :maxdepth: 1
 
 1D-123-Test/overview
+1d-blast/overview
+1D-Shu-Osher/overview
+1D-Square-Wave/overview
+1D-Strong-Shock/overview
+2d-khd/overview
 :::
 

docs/sphinx/conf.py

@@ -36,6 +36,7 @@
     'breathe',
     'myst_parser',
     'nbsphinx',
+    'sphinxcontrib.video',
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
     'sphinx.ext.napoleon',

pyproject.toml

@@ -31,7 +31,8 @@ docs = [
     'nbsphinx',
     'sphinx',
     'sphinx-inline-tabs',
-    'sphinx-autodoc-typehints'
+    'sphinx-autodoc-typehints',
+    'sphinxcontrib.video'
 ]
 test = ['pytest']
 dev = [