Merge pull request #15 from VirtualPlanetaryLaboratory/dev

Dev

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/README.rst

@@ -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/makeplot.py

@@ -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/Corot-7/README.rst

@@ -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/EarthInterior/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/EarthMoonTides/README.rst

@@ -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
 -------------------

examples/GalHabit/README.rst

@@ -4,7 +4,8 @@ Galactic Evolution
 Overview
 --------
 
-.. todo:: **@deitrr**: Change system names in vpl.in.
+Orbital evolution of objects in wide (>10,000 AU) orbits due to galactic migration,
+the galactic tide, and passing field stars.
 
 ===================   ============
 **Date**              07/25/18
@@ -14,7 +15,10 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/galhabit>`_
 ===================   ============
 
-An example of galactic migration and perturbations from passing stars.
+Wide orbits are subject to torques from the galactic tide, as well as impulses from
+passing stars. Complicating the evolution is the possibility of migration, in which
+stars can migrate multiple kpc from their birth location. This example shows that
+evolution for an M dwarf orbiting a Sun-like star.
 
 To run this example
 -------------------

examples/IoHeat/README.rst

@@ -1,10 +1,12 @@
 IoHeat
 ==========
 
-
 Overview
 --------
 
+Surface energy flux on Io due to tidal dissipation according the the eqtide-CPL
+model.
+
 ===================   ============
 **Date**              07/25/18
 **Author**            Rory Barnes
@@ -13,8 +15,12 @@ Overview
 **Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/IoHeat>`_
 ===================   ============
 
-Surface energy flux on Io due to tidal dissipation according the the eqtide-CPL
-model.
+This example reproduces the surface energy flux on Io over a range of eccentricity
+and obliquity. It also shows how to use vspace, a script in this repository that
+can generate input files across a parameter range. vspace will create a large
+number of directories, each of which has 3 input files. In this example, the makeplot
+script will run each individual trial, gather the results, and create the summary
+plot below. The yellow strip corresponds to the observed heat flow of Io :cite::Veeder04.
 
 
 To run this example

examples/Kepler-16/README.rst

@@ -1,9 +1,11 @@
-Circumbinary planet
-===================
+Kepler-16
+=========
 
 Overview
 --------
 
+Orbital evolution of circumbinary planet Kepler-16 b.
+
 ===================   ============
 **Date**              07/24/18
 **Author**            David Fleming
@@ -13,7 +15,9 @@ Overview
 ===================   ============
 
 
-An example of the orbital evolution of circumbinary planet Kepler-16 b.
+The orbital evolution of Kepler-16 b, a circumbinary planet, ir shown in this example
+using the semi-analytic model of Leeung & Lee (2013). The orbit is non-Keplerian
+due to the changing positions of the host stars.
 
 
 To run this example

examples/MagneticBraking/README.rst

@@ -1,20 +1,23 @@
-Stellar evolution
+Magnetic Braking
 =================
 
 Overview
 --------
 
-.. todo:: Change ranges to [0.075, 0.2, 0.4, 0.6, 0.8, 1.0, 1.2, 1.4, 2]??
+Rotational evolution of stars due to magnetic effects.
 
 ===================   ============
-**Date**              07/25/18
-**Author**            Rodrigo Luger
+**Date**              10/21/18
+**Author**            David Fleming
 **Modules**           stellar
 **Approx. runtime**   2 minutes
-**Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/stellar>`_
+**Source code**       `GitHub <https://github.com/VirtualPlanetaryLaboratory/vplanet-private/tree/master/examples/MagneticBraking>`_
 ===================   ============
 
-Stellar evolution for stars between 0.1 and 1.0 solar masses.
+Rotation period evolution for 0.1 and 1.0 Msun stars due to stellar
+evolution and magnetic braking.  We compare the how our different available
+magnetic braking laws (Reiners & Mohanty (2012), Repetto & Nelemans (2014),
+and Matt et al. (2015)) impact the rotation period evolution.
 
 
 To run this example
@@ -28,10 +31,9 @@ To run this example
 Expected output
 ---------------
 
-.. figure:: MainSequence.png
+.. figure:: MagneticBraking.png
    :width: 600px
    :align: center
 
-   Evolution of the radius, luminosity, temperature, and period of stars
-   of different masses according to the Baraffe (2015) :cite:`Baraffe15`
-   stellar evolution tracks.
+   Rotation period evolution for a 0.1 and 1 Msun star due to stellar evolution
+   (Baraffe et al. (2015)) and one of the 3 available magnetic braking laws.

examples/MagneticBraking/a_matt.in

@@ -2,6 +2,7 @@
 sName	                  a_matt
 saModules	          stellar
 dMass                     0.1
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          matt
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/a_reiners.in

@@ -2,6 +2,7 @@
 sName	                  a_reiners
 saModules	          stellar
 dMass                     0.1
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          reiners
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/a_sk.in

@@ -2,6 +2,7 @@
 sName	                  a_sk
 saModules	          stellar
 dMass                     0.1
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          skumanich
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/b_matt.in

@@ -2,6 +2,7 @@
 sName	                  b_matt
 saModules	          stellar
 dMass                     1.0
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          matt
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/b_reiners.in

@@ -2,6 +2,7 @@
 sName	                  b_reiners
 saModules	          stellar
 dMass                     1.0
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          reiners
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/b_sk.in

@@ -2,6 +2,7 @@
 sName	                  b_sk
 saModules	          stellar
 dMass                     1.0
+dAge                      5.0e6
 sStellarModel             baraffe
 sMagBrakingModel          skumanich
 bHaltEndBaraffeGrid       1 

examples/MagneticBraking/makeplot.py

@@ -0,0 +1,67 @@
+"""
+This script produces a figure comparing VPLanet's various magnetic braking
+implementations.
+
+David P. Fleming, University of Washington, 2018
+"""
+
+from __future__ import division, print_function
+
+import matplotlib.pyplot as plt
+import matplotlib as mpl
+import numpy as np
+import sys
+
+# Check correct number of arguments
+if (len(sys.argv) != 2):
+    print('ERROR: Incorrect number of arguments.')
+    print('Usage: '+sys.argv[0]+' <pdf | png>')
+    exit(1)
+if (sys.argv[1] != 'pdf' and sys.argv[1] != 'png'):
+    print('ERROR: Unknown file format: '+sys.argv[1])
+    print('Options are: pdf, png')
+    exit(1)
+
+# Make the plot!
+mpl.rcParams['figure.figsize'] = (9,8)
+mpl.rcParams['font.size'] = 18.0
+
+ms = ["a_matt", "a_reiners", "a_sk"]
+gs = ["b_matt", "b_reiners", "b_sk"]
+labels = ["Matt et al. (2015)", "Reiners & Mohanty (2012)",
+          "Repetto & Nelemans (2014)"]
+colors = ["C0", "C1", "C2"]
+
+fig, ax = plt.subplots()
+
+# saOutputOrder Time -TotEn -TotAngMom -Luminosity -Radius Temperature -RotPer -LXUVTot RadGyra
+
+for ii in range(len(ms)):
+    # Load in data
+    m = np.genfromtxt("system." + ms[ii] + ".forward")
+    g = np.genfromtxt("system." + gs[ii] + ".forward")
+
+    # Plot!
+    ax.plot(m[:,0], m[:,6], lw=3, ls="-", color=colors[ii])
+    ax.plot(g[:,0], g[:,6], lw=3, ls="--", color=colors[ii])
+
+# Annotate
+ax.plot([500], [500], lw=3, ls="-", color="C0", label="Matt et al. (2015)")
+ax.plot([500], [500], lw=3, ls="-", color="C1", label="Reiners & Mohanty (2012)")
+ax.plot([500], [500], lw=3, ls="-", color="C2", label="Repetto & Nelemans (2014)")
+ax.plot([500], [500], lw=3, ls="-", color="C7", label="M = 0.1 M$_{\odot}$")
+ax.plot([500], [500], lw=3, ls="--", color="C7", label="M = 1 M$_{\odot}$")
+
+# Format plot
+ax.set_xlim(1.0e6, 5.0e9)
+ax.set_ylim(0.1, 70)
+ax.set_xscale("log")
+ax.set_yscale("log")
+ax.set_xlabel("Time [yr]")
+ax.set_ylabel("Rotation Period [d]")
+ax.legend(loc="best", fontsize=12)
+
+if (sys.argv[1] == 'pdf'):
+    plt.savefig('MagneticBraking.pdf', bbox_inches="tight", dpi=600)
+if (sys.argv[1] == 'png'):
+    plt.savefig('MagneticBraking.png', bbox_inches="tight", dpi=600)

examples/MagneticBraking/vpl.in

@@ -13,7 +13,7 @@ iDigits                   6
 dMinValue                 1e-10
 bDoForward                1
 bVarDt                    1
-dEta                      0.001
+dEta                      0.01
 dStopTime                 5e9
 dOutputTime               1e6