Merge pull request #15 from VirtualPlanetaryLaboratory/dev

Dev

Author: RoryBarnes

examples/AtMescKepler-36/README.rst

@@ -4,6 +4,8 @@ Kepler-36 Atmospheric Escape
 Overview
 --------
 
+Loss of a hydrogen envelope due to stellar XUV stripping.
+
 ===================   ============
 **Date**              06/28/18
 **Author**            Rodrigo Luger
@@ -13,9 +15,13 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/kepler36>`_
 ===================   ============
 
-A reproduction of Figure 3 in Lopez and Fortney (2013) :cite:`LopezFortney2013`
-using **VPLANET**.
-
+Hydrogen-rich planets that are close to their host star can lose significant mass
+as the XUV radiation from the host star imparts enough energy for individual atoms
+to acheive escape velocity. In this example, **VPLANET** simulates atmmospheric loss
+for the case of Kepler-36 b, which is considerably smaller in radius than its very
+nearby companions, Kepler-36 c. :cite:`LopezFortney2013` argue that this extreme
+radius dichotomy can be explained by XUV winds, and **VPLANET** reproduces that
+result, see Figure 3 in Lopez and Fortney (2013).
 
 To run this example
 -------------------

examples/BinaryTides/README.rst

@@ -1,12 +1,12 @@
 Evolution of Tight Stellar Binaries
-=====================
-
-.. todo:: **@dflemin3**: This example is broken as it does not match ZB89. This is issue #54.
-
+===================================
 
 Overview
 --------
 
+Orbital circularization of short-period binary stars due to radial contraction on
+the pre-main sequence and tidal torques.
+
 ===================   ============
 **Date**              07/25/18
 **Author**            David Fleming
@@ -16,8 +16,12 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/zahn>`_
 ===================   ============
 
-This script produces a reproduction of Figure 1 of Zahn and Bouchet (1989)
-:cite:`ZahnBouchet89` using a coupled **EQTIDE** and **STELLAR** **VPLANET** run.
+As stars form, they contract onto the main sequence, and those in binary star systems
+can also experience tidal torques on the rotation and orbit. As tidal torques scale
+with stellar radius to the 5th power, the torques can be very strong early on. This
+early tidal evolution circularizes binary star orbits for orbital periods less than
+~8 days, which is observed :cite::Meibom05. This example reproduce Figure 1 of
+Zahn and Bouchet (1989) :cite:`ZahnBouchet89` using **EQTIDE** and **STELLAR**.
 
 To run this example
 -------------------

examples/CassiniStates/CassiniStatesSection.png

@@ -4,7 +4,7 @@ Cassini States
 Overview
 --------
 
-.. todo:: **@deitrr**: This example is broken. The same figure is produced twice.
+A planetary system can damping into a Cassini state.
 
 ===================   ============
 **Date**              07/25/18
@@ -16,10 +16,14 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/cassini>`_
 ===================   ============
 
-This example shows how a planetary system can damp into a Cassini state, in which
+A damped orbital-rotational system can enter a "Cassini state," in which
 a planet's rotational axis, orbital axis, and the local total angular momentum
-vector are all coplanar.
-
+vector are all coplanar. In this case, we consider a system in which tides from the
+star damp the rotation rate, obliquity, semi-major axis and orbital eccentricity.
+Tides tend to damp the rotational axis so that it is perpendicular to the orbital
+plane, but perturbations from other planets drive the obliquity to higher values.
+Over time, the systems settles in a damped-drived state in which the obliquity is
+non-zero, but also not oscillating. This example is modeled after Winn & Holman (2005).
 
 To run this example
 -------------------

examples/CassiniStates/README.rst

@@ -103,7 +103,7 @@
 obl1 = np.arctan2(np.sin(inc),1-alpha/g)
 y1 = -np.sin(obl1)
 
-plt.figure(figsize=(8,8))
+fig=plt.figure(figsize=(8,8))
 plt.contour(Y,X,H.T,50,colors='0.5')
 plt.contour(Y,X,H.T,levels=[1.00005*H4],colors='k')
 plt.plot(xc,yc,'-',color='0.5')

examples/CassiniStates/makeplot.py

@@ -4,6 +4,9 @@ Orbital Damping in the CoRoT-7 System
 Overview
 --------
 
+Orbital damping into the "fixed-point solution" in which two planets' major axes
+circulate with the same frequency.
+
 ===================   ============
 **Date**              9/12/18
 **Author**            David Fleming
@@ -14,8 +17,10 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/corot7>`_
 ===================   ============
 
-Using vplanet's distorb, eqtide, and stellar modules to simulate the tidal damping
-and apsidal locking of CoRoT-7 b and c examined by :cite::Rodriguez11.
+In a planetary system consisting of two or more planets and in which at least one
+experiences damping, the orbits will evolve such that the eccentricity cycles stop
+and the major axes evolve in lock stop. This "fixed point solution" :cite::`WuGoldreich02`
+is reproduced below for the case of CoRoT-7 b and c as examined by :cite::Rodriguez11.
 
 To run this example
 -------------------

examples/Corot-7/README.rst

@@ -1,10 +1,11 @@
 EarthInterior
 ==========
 
-
 Overview
 --------
 
+Evolution of Earth's interior.
+
 ===================   ============
 **Date**              10/03/18
 **Author**            Peter Driscoll
@@ -13,6 +14,10 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/EarthInterior>`_
 ===================   ============
 
+This example shows the thermal and magnetic evolution of Earth's interior from
+**THERMINT** and **RADHEAT**. The model is 1-D and many free parameters have been
+tuned to reproduce Earth's current properties. Earth is divided in a core, mantle,
+and crust. The evolution depends only on the temperature of the core and mantle.
 
 
 To run this example

examples/EarthInterior/EarthInterior1.png

@@ -18,7 +18,11 @@ case appears suspect. Forward integrations with eqtide are stable.
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/EarthMoonTides>`_
 ===================   ============
 
-
+The Earth and its Moon tidally interact such that moon is currently receding from
+the Earth, whose rotational frequency is decreasing. As is well known, the equilibrium
+tide model, using the Earth's modern tidal Q value of 12, predicts the Moon-forming impact occurred about 1.5 Gyr ago, instead of
+4.5 Gyr. **VPLANET** reproduces this classic result, which can be reconciled by
+assuming the Earth's average value of Q is closer to 35 (Barnes 2017).
 
 To run this example
 -------------------