Updating Documented Examples

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

@@ -0,0 +1,23 @@
+# 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()`.  
+
+
+## Parameter file: ({repository-file}`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.
+
+:::{literalinclude} parameter-file.txt
+:::
+
+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. Examples of how to extract and plot data can be found in `cholla/python_scripts/plot_sod.ipynb`.  
+
+:::{figure} shu-osher.png
+
+
+With the diode disabled, this solution does match that of Schneider and Robertson 2015 and Stone et al. 2008, shown below:
+
+:::{figure} schneider-robertson-2015.png
+:width: 500px
+:align: center
+:::
+
+

docs/sphinx/ChollaExamples/1D-Shu-Osher/parameter-file.txt

@@ -0,0 +1,36 @@
+#
+# 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=./

docs/sphinx/ChollaExamples/1D-Sod/overview.md

@@ -0,0 +1,68 @@
+# 1D Sod Shock Tube
+This test highlights the ability of a code to resolve shocks and contact discontinuities over a narrow region. Parameters from Sod (1978). The setup consists of a density and pressure of 1.0 for x \< 0 and 0.1 for x \> 0.5. 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: ({repository-file}`examples/1D/sod.txt`)
+```
+#
+# Parameter File for 1D Sod Shock tube
+#
+
+################################################
+# 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.2
+# time interval for output
+outstep=0.2
+# 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=1.0
+# velocity of left state
+vx_l=0.0
+vy_l=0.0
+vz_l=0.0
+# pressure of left state
+P_l=1.0
+# density of right state
+rho_r=0.1
+# velocity of right state
+vx_r=0.0
+vy_r=0.0
+vz_r=0.0
+# pressure of right state
+P_r=0.1
+# 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, velocity, and internal energy (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`.  
+
+:::{figure} sod-initial-final.png
+:::
+
+We see a rarefaction wave propagating away from the initial discontinuity, a contact discontinuity at x = 0.7, and a shock at x =0.9. 

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

@@ -0,0 +1,67 @@
+# 1D Sound Wave
+This test initializes a compression/rarefaction wave across the grid. The setup consists of an initial density and pressure of 1.0 and 0.6, respectively. A sound wave is initialized as a sinusoidal wave with amplitude 1e-4 and wavelength of 1.0. 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 `Sound_Wave()`. 
+
+## Parameter file: ({repository-file}`examples/1D/sound_wave.txt`)
+Modified to add yl_bcnd, yu_bcnd, zl_bcnd, and zu_bcnd=0
+```
+#
+# Parameter File for sound wave test
+#
+
+################################################
+# number of grid cells in the x dimension
+nx=128
+# 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.05
+# time interval for output
+outstep=0.01
+# name of initial conditions
+init=Sound_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=./sowvout
+
+#################################################
+# Parameters for linear wave problems
+# initial density
+rho=1.0
+# velocity in the x direction
+vx=0
+# velocity in the y direction
+vy=0
+# velocity in the z direction
+vz=0
+# initial pressure
+P=0.6
+# amplitude of perturbing oscillations
+A=1e-4
+# value of gamma
+gamma=1.666666666666667
+
+```
+Upon completion, you should obtain five output files. By changing the outstep to 0.005, we can obtain the evolution of the density, pressure, velocity, and internal energy (here at 4 fps).  Examples of how to extract and plot data can be found in `cholla/python_scripts/plot_sod.ipynb`.  
+
+:::{video} soundwave-new.mp4
+    :width: 700
+    :height: 500
+    :align: center
+    :autoplay:
+    :loop:
+:::

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

@@ -0,0 +1,77 @@
+# 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: ({repository-file}`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. 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 faster 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" />
+

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

@@ -0,0 +1,69 @@
+# 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: ({repository-file}`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.. Examples of how to extract and plot data can be found in cholla/python_scripts/plot_sod.ipynb.  
+
+:::{figure} snapshots_strongshock.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.