Port more documentation from the wiki

docs/sphinx/ChollaExamples/2D-Rayleigh-Taylor/2D-Rayleigh-Taylor.md

@@ -0,0 +1,64 @@
+# 2D Rayleigh-Taylor Test
+
+This test demonstrates the mixing resulting from a dense fluid placed on top of a less dense fluid. The bottom half of the grid is given of density of 1.0 while the top has a value of 2.0. Y velocities across the grid are set as a small pertubation tapering off from the center. For both halves, pressure is initialized as decreasing with increasing y position. Gamma is set to 1.4. This test is performed with the static gravity build (`cholla/builds/make.type.static_grav`) and Van Leer integrator.
+Full initial conditions can be found in `cholla/src/grid/initial_conditions.cpp`under `Rayleigh_Taylor()`. 
+
+## Parameter file:
+
+This parameter file can be found in [examples/2D/Rayleigh_Taylor.txt](https://github.com/cholla-hydro/cholla/blob/main/examples/2D/Rayleigh_Taylor.txt) on the `dev` branch.
+```
+#
+# Parameter File for the 2D Rayleigh-Taylor test.
+#
+
+######################################
+# number of grid cells in the x dimension
+nx=200
+# number of grid cells in the y dimension
+ny=400
+# number of grid cells in the z dimension
+nz=1
+# final output time
+tout=5.0
+# time interval for output
+outstep=0.05
+# value of gamma
+gamma=1.4
+# name of initial conditions
+init=Rayleigh_Taylor
+#static gravity flag
+custom_grav=2
+# domain properties
+xmin=0.0
+ymin=0.0
+zmin=0.0
+xlen=0.33333333
+ylen=1.0
+zlen=1.0
+# type of boundary conditions
+xl_bcnd=1
+xu_bcnd=1
+yl_bcnd=2
+yu_bcnd=2
+zl_bcnd=0
+zu_bcnd=0
+# path to output directory
+outdir=./
+```
+To run on main:
+You must add the following lines to `src/gravity/static_grav.h` under the function `inline __device__ void calc_g_2D()`:
+```
+*gx = 0;
+*gy = -1;
+```
+Any other values assigned to `*gx` and `*gy` should be commented out.  
+
+Upon completion, you should obtain 101 output files. The initial, intermediate, 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`. 
+:::{figure} rayleigh_taylor_2D_xy.png
+Rayleigh-Taylor test solution from Cholla.
+::: 
+
+This is comparable to the solution from Liska & Wendroff (2003):
+:::{figure} liska203-rayleigh-taylor.png
+Rayleigh-Taylor test solution from Liska & Wendroff (2003).
+:::

docs/sphinx/ChollaExamples/index.md

@@ -8,5 +8,6 @@ Continue porting me from the [wiki](https://github.com/cholla-hydro/cholla/wiki/
 :maxdepth: 1
 
 1D-123-Test/overview
+2D-Rayleigh-Taylor/2D-Rayleigh-Taylor
 :::
 

docs/sphinx/Physics/Cosmology.md

@@ -0,0 +1,5 @@
+# Cosmology
+
+:::{todo}
+Add documentation for cosmology. A description of the cosmology implementation can be found in [Villasenor et al. (2021)](https://ui.adsabs.harvard.edu/abs/2021ApJ...912..138V/abstract).
+:::

docs/sphinx/Physics/Dual-Energy-Formalism.md

@@ -12,7 +12,7 @@ Problems arise in simulations with large Mach numbers (such as cosmological simu
 
 The solution to this numerical problem is to use the "dual-energy formalism" (more details are provided in [Bryan+ 2014](https://ui.adsabs.harvard.edu/abs/2014ApJS..211...19B)). The core idea is to track an extra separately-advected "thermal energy" field at each cell-location, in addition to the total energy field and use this "thermal energy" field in cases where {math}`(E - E_{\rm thermal})` provides insufficient precision. 
 
-The dual-energy formalism is parameterized by two parameters, {math}`\eta_1` and {math}`\eta_2`. It's easiest to understand their meaning by discussing how they are used. The [Bryan+ 2014](https://ui.adsabs.harvard.edu/abs/2014ApJS..211...19B) paper describes two main steps:
+The dual-energy formalism is parameterized by two parameters, {math}`\eta_1` and {math}`\eta_2`. It's easiest to understand their meaning by discussing how they are used. The [Bryan+2014](https://ui.adsabs.harvard.edu/abs/2014ApJS..211...19B) paper describes two main steps:
 1. During a given timestep, when we want to compute thermal pressure, we compare quotient of the "thermal energy" field divided by {math}`E` to {math}`\eta_1`.
     - When the ratio is smaller than {math}`\eta_1` we use the "thermal energy" field. When it exceeds {math}`\eta_1`, we use {math}`(E-E_{\rm kinetic})`.
     - In effect, {math}`\eta_1` directly parameterizes the precision where the dual-energy formalism kicks in.
@@ -21,7 +21,7 @@ The dual-energy formalism is parameterized by two parameters, {math}`\eta_1` and
     - To motivate this step, it's important to understand that when we separately advect the "thermal energy" and add the {math}`-p(\nabla \cdot {\bf v})\Delta t/ \rho` source term, we are effectively ignoring the effects of shock heating.
     - Consequently, we might want to overwrite the "thermal energy" to capture the effects of shock heating. 
     - The precise condition that dictates when we overwrite the "thermal energy" field involves a comparison of {math}`\eta_2` and the values in neighboring cells. When {math}`\eta_2` is too high, we would effectively exclude shock-heating from weaker shocks. When {math}`\eta_2` is too low we may include spurious heating that is introduced by the truncation error of {math}`(E-E_{\rm kinetic})`.
-    - **NOTE:** [Bryan+ 2014](https://ui.adsabs.harvard.edu/abs/2014ApJS..211...19B) call this step "synchronization" - we find that name somewhat confusing since it may imply a bidirectional update (updating both "thermal energy" and {math}`E`).
+    - **NOTE:** [Bryan+2014](https://ui.adsabs.harvard.edu/abs/2014ApJS..211...19B) call this step "synchronization" - we find that name somewhat confusing since it may imply a bidirectional update (updating both "thermal energy" and {math}`E`).
 
 In practice, Cholla does something slightly different:
 1. It implements step 1 exactly as described above.

docs/sphinx/Physics/Feedback.md

@@ -0,0 +1,9 @@
+# Particle-based Feedback
+
+Models supernova (SN) feedback from star cluster particles as a Poisson processes following the prescription in [Kim & Ostriker (2015)](https://ui.adsabs.harvard.edu/abs/2015ApJ...815...67K/abstract). Energy or momentum is injected into the interstellar medium depending on whether the SN is sufficiently numerically resolved.
+
+## Required Compilation Flags
+* `SUPERNOVA` - Supernova rate (SNR) information from a Starburst99 generated *.snr file can be read in by specifying the path as the value of the `snr_filename` parameter.  If this parameter is not set, then a default constant SNR is used.  The default SNR corresponds to 1 supernova per {math}`100~\mathrm{M}_\odot` of cluster mass, spread out over 36 Myr, starting when the cluster is 4 Myr old.  A sample Starburst99 file is included in the source code at `src/particles/starburst99_snr.txt`.  The sample represents a {math}`10^6~\mathrm{M}_\odot` fixed mass cluster, created using a Kroupa initial mass function, and with an {math}`8~\mathrm{M}_\odot` supernova cutoff.
+* `PARTICLES_GPU` - Particle-based feedback requires that the particle data be on the GPUs.
+* `PARTICLE_AGE` - Feedback varies with cluster age.
+* `PARTICLE_IDS` - Cluster IDs are used to prevent possible correlations or biases when generating random numbers used by the feedback algorithm.

docs/sphinx/Physics/Gravity.md

@@ -0,0 +1,48 @@
+# Static Gravity
+
+Static gravity is activated using the ```STATIC_GRAV``` macro, and is used in several of the example problems provided with Cholla. Static gravity is a simple prescription that does not require any other gravity flags, but does require the input file parameter "custom_grav" to specify the analytic function that will be applied (dev branch only). Static gravity is applied as momentum and energy source terms in [src/hydro/hydro_cuda.cu](https://github.com/cholla-hydro/cholla/blob/dev/src/hydro/hydro_cuda.cu) and the analytic functions are defined in [src/gravity/static_grav.h](https://github.com/cholla-hydro/cholla/blob/dev/src/gravity/static_grav.h). As of 10-27-2023 on the main branch, the static gravitational field is hard-coded to provide a Milky Way-like model or an M82-like model. On the dev branch, the input parameter flags correspond to:
+
+**1D:**
+* 1: a MW-like Miyamoto-Nagai disk + NFW halo potential (assumed z = 0)
+
+**2D:**
+* 1: Gresho vortex
+* 2: Rayleigh-Taylor instability
+* 3: A 2D Keplerin disk
+* 4: A MW-like Kuzmin disk + NFW halo potential (assumed z = 0)
+
+**3D:**
+* 1: A MW-like Miyamoto-Nagai disk + NFW halo potential
+* 2: An M82-like Miyamoto-Nagai disk + NFW halo potential
+
+
+## Self Gravity: FFT-based
+
+In addition to static gravity, Cholla has an FFT-based self gravity solver. Only one or the other may be used. The self-gravity solver is turned on with the ```GRAVITY``` macro in the makefile. The default behavior in the [make.type.gravity](https://github.com/cholla-hydro/cholla/blob/dev/builds/make.type.gravity) build (and builds that depend on it) is also to turn on the ```GRAVITY_GPU``` macro, which ensures that gravity fields reside on the GPU (required for gpu-based MPI communications), and the ```PARIS``` macro, which specifies that the Poisson solve will be carried out on the GPU by the cuFFT or rocFFT libraries. Cholla does also have CPU-based gravity solvers, although they are not currently maintained. Definitions of other macros options associated with the gravity solver are given below.
+
+Macro flags associated with self-gravity:
+
+```GRAVITY```: Turns on self-gravity. Necessary for particle-only simulations.
+
+```GRAVITY_GPU```: Specifies that fields required by gravity are allocated on the GPU.
+
+```PARIS```: Use the Paris 3D GPU-based Poisson solver to calculate the gravitational potential on a periodic domain.
+
+```GRAVITY_5_POINTS_GRADIENT```: Use a 5-point stencil to calculate the gradient of the potential for gravity source terms (default behavior is a 3-point stencil)
+
+```GRAVITY_ANALYTIC_COMP```: Add an analytic component to the gravitational potential. As of 10-27-2023, this is hard-coded to a Milky Way galaxy model in the function `Setup_Analytic_Potential` from [gravity_functions.cpp](https://github.com/cholla-hydro/cholla/blob/dev/src/gravity/gravity_functions.cpp). 
+
+```PARIS_3PT```: Use a 3-point gradient for the divergence operator approximation in Paris (default behavior is to use a spectral method)
+
+```PARIS_5PT```: Use a 5-point gradient for the divergence operator approximation in Paris
+
+```PARIS_GALACTIC```: Use the Paris Poisson solver on a domain with analytic boundaries set to match the selected model in the DiskGalaxy class. As of 10-27-2023, this is hard-coded to a Milky Way galaxy model in the function `Compute_Gravitational_Potential` from [gravity_functions.cpp](https://github.com/cholla-hydro/cholla/blob/dev/src/gravity/gravity_functions.cpp) and in `Compute_Potential_Isolated_Boundary` from [gravity_boundaries.cpp](https://github.com/cholla-hydro/cholla/blob/dev/src/gravity/gravity_boundaries.cpp).
+
+```PARIS_GALACTIC_3PT```: Same as above but for the analytic boundary version
+
+```PARIS_GALACTIC_5PT```: Same as above but for the analytic boundary version
+
+```PARIS_GALACTIC_TEST```: Turn on to test whether Paris returns the same gravitational potential as the SOR solver. Doesn't work with GRAVITY_GPU, should probably be deprecated.
+
+## Self Gravity: SOR based
+To-do: Describe the SOR solver

docs/sphinx/Physics/Particles.md

@@ -0,0 +1,5 @@
+# Particles
+
+:::{todo}
+Add documentation for particles. A description of the particle implementation can be found in [Villasenor et al. (2021)](https://ui.adsabs.harvard.edu/abs/2021ApJ...912..138V/abstract).
+:::

docs/sphinx/Physics/index.md

@@ -8,7 +8,11 @@ Port over more from the wiki
 :maxdepth: 1
 
 CoolingChemistry.md
+Cosmology.md
 Dual-Energy-Formalism.md
 Dust.md
+Feedback.md
+Gravity.md
 MHD.md
+Particles.md
 :::