Merge pull request #2 from VirtualPlanetaryLaboratory/master

Merge v1.0.0

.ci/travis.sh

@@ -13,7 +13,7 @@ if ! command -v conda > /dev/null; then
 fi
 
 # Display some info
-conda info -a
+#conda info -a
 
 # Install docs stuff
 pip install sphinx==1.8.4

.gitignore

@@ -42,6 +42,7 @@ vplanet.egg-info
 gcov/*
 *.o
 *.so
+*.valgrind
 
 # Documentation
 docs/.build

Contributors.md

@@ -0,0 +1,40 @@
+# VPLanet Contributors
+
+`VPLanet` has been developed by a team of scientists with a broad range of
+expertise. This file records who is responsible for which aspects of the code.
+
+**Rory Barnes** is the lead developer who conceived the project,
+implemented the matrices and vectors of function pointers, designed
+the I/O scheme, and maintains this repository. He also wrote most of the top-level files, such as vplanet.h,
+control.c, body.c, evolve.c, etc. He wrote most of EqTide and RadHeat.
+He can be reached at [email protected].
+
+**Russell Deitrick** wrote the DistOrb, DistRot, GalHabit and POISE modules, as
+well as VSPACE.
+
+**Rodrigo Luger** wrote the AtmEsc and STELLAR modules, as well as the accompanying
+VPLOT resource. He also designed this repository, including setting up the continuous
+integration and calculating code coverage.
+
+**David Fleming** wrote the BINARY module and has contributed to the development
+of STELLAR, AtmEsc, and EqTide. He also wrote BigPlanet.
+
+**Hayden Smotherman** wrote SpiNBody and has contributed to various subroutines
+that have signficantly increased the efficiency of the executable.
+
+**Peter Driscoll** developed the ThermInt module, contributed to RadHeat, and
+connected them both to EqTide.
+
+**Thomas Quinn** assisted in the development of DistOrb, DistRot, and GalHabit. He
+also found many bugs with valgrind and address-sanitizer.
+
+**Diego McDonald** added the Lehmer-Catling model to AtmEsc.
+
+**Benjamin Guyer** assisted in the coupling of EqTide and ThermInt.
+
+**Caitlyn Wilhelm** added forced eccentricity and obliquity oscillations to
+POISE, and assisted in debugging it.
+
+**Rodolfo Garcia** assisted in AtmEsc and ThermInt development.
+
+**Patrick Barth** assisted in AtmEsc development.

INSTALL

@@ -1,54 +1,4 @@
 ***** INSTALL *****
 
-This file provides a description of how to install the software necessary to
-simulate the examples in this repository.
-
-1. Ensure you have installed the following:
-    A. A C compiler, e.g. gcc, clang, etc.
-    B. Python 3.x [Note that this version should be the python in your PATH]
-        N.B. We recommend installing python via anaconda
-    C. matplotlib v1.4.0 or higher
-
-2. Clone the repository from GitHub:
-      > git clone https://github.com/VirtualPlanetaryLaboratory/vplanet.git
-   Compile the code:
-      > make opt
-
-3. At this point you should be able to run the code on one of the examples. To
-   verify it's working, execute the following commands:
-   > cd examples/EarthInterior
-   > vplanet vpl.in
-
-   This should create files called earth.earth.forward earth.log that contain
-   results from the simulation that you can check. This example recreates the
-   thermal and magnetic evolution of Earth and should require about 1 second.
-
-4. VPLanet has its own plotting package which can streamline your research. This
-   package is not required, but you can only reproduce the plots in this
-   repository exactly if you install it. There are two ways to install it, via
-   pip, or cloning from GitHub:
-   > pip install vplot
-   OR
-   > git clone https://github.com/VirtualPlanetaryLaboratory/vplot.git
-   > cd vplot
-   > python setup.py install --user
-   We recommend installing as administrator, which can be completed by changing
-      the last command to
-   > sudo python setup.py develop
-
-5. If you encountered no errors, then everything should be setup. To quickly
-    determine if it worked, execute the following from the vplanet directory:
-
-    > cd examples/EarthInterior
-    > vplanet vpl.in
-    > python makeplot.py png
-
-    These commands require less than 1 minute and should create 2 png figures
-      identical to those in the examples/EarthInterior directory.
-
-6. If you did encounter errors, it is probably because either a) vplanet is not
-    in your PATH, b) the proper version of python is not in your PATH, c) you do
-    not have the proper version of python installed, or d) you need to update
-    matplotlib. If you have followed these instructions exactly and still cannot
-    generate the EarthInterior png files, please contact Rory Barnes at
-    [email protected].
+To install VPLanet, please follow the instructions in the documantation:
+https://virtualplanetarylaboratory.github.io/vplanet/index.html.

Makefile

@@ -50,6 +50,9 @@ profile:
 optprof:
 	-gcc -pg -o vplanet src/*.c -lm -O3 -DGITVERSION=\"$(GITVERSION)\"
 
+sanatize:
+	-gcc -g -fsanitize=address -o vplanet src/*.c -DGITVERSION=\"$(GITVERSION)\"
+
 test:
 	-gcc -o vplanet src/*.c -lm -DGITVERSION=\"$(GITVERSION)\"
 	py.test

Manual/README.rst

@@ -2,4 +2,6 @@ VPLanet Manual
 =============
 
 This directory contains the manual for VPLanet. It consists of a quantitative description of all modules, 
-as well as their validation through the reproduction of previous results.
+as well as their validation through the reproduction of previous results. The PDF is the accepted version
+of the model description and validation paper, to appear in the Proceedings of the Astronomical Society of
+the Pacific.

README.md

@@ -1,14 +1,22 @@
-# VPLanet
-[![Build Status](https://travis-ci.com/VirtualPlanetaryLaboratory/vplanet.svg?token=jABaFLLgJNHTWSqkT7CM&branch=master)](https://travis-ci.com/VirtualPlanetaryLaboratory/vplanet)
-[![Documentation](https://img.shields.io/badge/read-the_docs-blue.svg?style=flat)](https://VirtualPlanetaryLaboratory.github.io/vplanet)
-<a href="https://arxiv.org/abs/1905.06367"><img src="https://img.shields.io/badge/read-the_paper-7d93c7.svg?style=flat"/></a>
-<a href="http://ascl.net/1811.017"><img src="https://img.shields.io/badge/ascl-1811.017-blue.svg?colorB=262255" alt="ascl:1811.017" /></a>
+# VPLanet: The Virtual Planet Simulator
+<p align="center">
+  <a href="https://VirtualPlanetaryLaboratory.github.io/vplanet"><img src="https://img.shields.io/badge/read-the_docs-blue.svg?style=flat"></a>
+  <a href="https://ui.adsabs.harvard.edu/abs/2019arXiv190506367B/abstract"><img src="https://img.shields.io/badge/read-the_paper-7d93c7.svg?style=flat"/></a>
+  <a href="http://ascl.net/1811.017"><img src="https://img.shields.io/badge/ascl-1811.017-blue.svg?colorB=262255" alt="ascl:1811.017" /></a>
+  <a href="https://raw.github.com/VirtualPlanetaryLaboratory/vplanet/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-purple.svg"/></a>
+  <img src = "https://img.shields.io/badge/platform-Linux_|%20macOS-darkgreen.svg?style=flat"><br>
+  <a href="https://travis-ci.com/VirtualPlanetaryLaboratory/vplanet"><img src="https://travis-ci.com/VirtualPlanetaryLaboratory/vplanet.svg?token=jABaFLLgJNHTWSqkT7CM&branch=master"></a>
+  <img src = "https://img.shields.io/badge/memcheck-clean-brightgreen.svg?style=flat">
+  <img src = "https://img.shields.io/badge/coverage-71%25-red.svg?style=flat">
+</p>
 
-© 2018 The VPLanet Team.
+### Overview
+
+`VPLanet` is software to simulate planetary system evolution, with a focus on habitability. Physical models, typically consisting of ordinary differential equations, are coupled together to simulate evolution, from planetary cores to passing stars, for the age of a system. We strive for full transparency and reproducibility in our software, and this repository contains the [source code](src), [extensive documentation](https://VirtualPlanetaryLaboratory.github.io/vplanet), [the scripts and files to generate published figures](examples), and [scripts to validate the current release](tests). We can't claim we found aliens with closed source software!
 
-`VPLanet` is software to simulate planetary system evolution, with a focus on habitability. Physical models, typically consisting of ordinary differential equations, are coupled together to simulate evolution for the age of a system. We strive for full transparency and reproducibility in our software, and this repository contains the [source code](src), [extensive documentation](https://VirtualPlanetaryLaboratory.github.io/vplanet), [the scripts and files to generate published figures](examples), and [scripts to validate the current release](tests). We can't claim we found aliens with closed source software!
+To get started, ensure you have clang/gcc installed and follow the [QuickStart Guide](https://virtualplanetarylaboratory.github.io/vplanet/quickstart.html). Note that VPLanet does not currently function on Windows operating systems.
 
-To get started, ensure you have clang/gcc installed and follow the [QuickStart Guide](https://virtualplanetarylaboratory.github.io/vplanet/quickstart.html). Alternatively you can follow the instructions in [INSTALL](INSTALL).
+### Modules
 
 `VPLanet` currently consists of 11 functioning "modules," each containing a set of equations
 that models a specifc physical process:
@@ -22,17 +30,17 @@ escape, oxygen escape, and oxygen build-up.
 of resonance.
 
 **DistRot**: Evolution of a world's rotational axis due to orbital evolution and
-the stellar torque (includes shape evolution as a function of rotational frequency).
+the stellar torque (including shape evolution as a function of rotational frequency).
 
 **EqTide**: Tidal evolution in the equilibrium tide framework.
 
 **GalHabit**: Evolution of a wide orbit due to the galactic tide and impulses from
-passing stars (includes radial migration).
+passing stars (including radial migration).
 
 **POISE**: Energy balance climate model including dynamic ice sheets and lithospheric
 compression/rebound.
 
-**RadHeat**: Radiogenic heating of a world's interior.
+**RadHeat**: Radiogenic heating in a world's core, mantle, and crust.
 
 **SpiNBody**: N-body integrator for the evolution of a system of massive particles.
 
@@ -41,24 +49,37 @@ compression/rebound.
 **ThermInt**: Thermal interior evolution, including magnetic fields, for planets
 undergoing plate tectonics or stagnant lid evolution.
 
-`VPLanet` is a community project. We're happy to take pull requests; if you want to create one, please issue it to the *dev* branch. Soon we will include tutorials on adding new input options, governing variables, and modules. It's a platform for planetary science that can grow exponentially, either by adding new physics or by adding competing models for clean comparisons.
+### Resources
+
+The [examples/](examples) directory contains input files and scripts for generating the figures in [Barnes et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019arXiv190506367B/abstract) and all subsequent module descriptions. The [Manual/](Manual) directory contains the pdf of [Barnes et al. (2019)](https://ui.adsabs.harvard.edu/abs/2019arXiv190506367B/abstract), which describes the physics of each module, validates the software against observations and/or past results, and uses figures from the [examples/](examples) directory.
+
+An ecosystem of support software is also publicly available. In this repo, [vspace/](vspace) contains scripts to generate input files for a parameter space sweep. [bigplanet/](bigplanet) contains scripts to store large datasets in HDF5 format and quickly calculate summary properties from an integration, such as change in surface temperature. In a separate repository is [vplot](https://github.com/VirtualPlanetaryLaboratory/vplot), which consists of both a command line tool to quickly plot the evolution of a system, and also matplotlib functions to generate publication-worthy figures. Finally, we recommend using [approxposterior](https://github.com/dflemin3/approxposterior) to quickly obtain posterior distributions of model parameters.
+
+### Code Integrity
 
-The [examples/](examples) directory contains input files and scripts for generating the figures in [Barnes et al. (2019)](https://arxiv.org/abs/1905.06367) and all subsequent module descriptions. The [Manual/](Manual) directory contains the pdf of [Barnes et al. (2019)](https://arxiv.org/abs/1905.06367), which describes the physics of each module, validates each module against observations or past results, and uses figures from the [examples/](examples) directory.
+Behind the scenes, the VPLanet team maintains code integrity through [continuous integration](https://travis-ci.org), in which numerous scientific and numerical tests are validated at every commit. Check the "build" badge above for the current status. See the [tests/](tests) directory for the validation checks that the current build passes. The "coverage" badge shows the percentage of the code (by line number) that is currently tested. Additionally, we use [valgrind](http://valgrind.org) and [addresssanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer) to periodically search for memory issues like use of uninitialized memory, accessing memory beyond array bounds, etc. The "memcheck" badge shows the current status, either clean (no errors) or dirty. We are committed to maintaining a stable tool for scientists to analyze any planetary system.  
 
-An ecosystem of support software is also publicly available. In this repo, [vspace/](vspace) contains scripts to generate input files for a parameter space sweep. [bigplanet/](bigplanet) contains scripts to store large datasets in HDF5 format and quickly calculate summary properties from an integration, like change in surface temperature. In a separate repository is [vplot](https://github.com/VirtualPlanetaryLaboratory/vplot), which consists of both a command line tool to quickly plot the evolution of a system, and also matplotlib functions to more easily generate publication-worthy figures. Finally, we recommend using [approxposterior](https://github.com/dflemin3/approxposterior) to quickly obtain posterior distributions of model parameters.
+### Community
 
-Behind the scenes, the vplanet team maintains code integrity through continuous integration, in which numerous scientific and numerical tests are validated at every commit. Check the "build" badge above for the current status. See the [tests/](tests) directory for the validation checks that the current build passes. Additionally, we use valgrind and addresssanitizer to periodically search for memory issues like leaks, accessing memory beyond array bounds, etc. We are committed to maintaining a stable tool that planetary scientists can rely on for fast analyses of the Solar System and beyond.  
+`VPLanet` is a community project. We're happy to take pull requests; if you want to create one, please issue it to the *dev* branch. Soon we will include tutorials on adding new input options, governing variables, and modules. It's a platform for planetary science that can grow exponentially, either by adding new physics or by adding competing models for clean comparisons.
 
 Additional `VPLanet` examples can be found at the following GitHub pages:
 
 [Virtual Planetary Laboratory](https://github.com/VirtualPlanetaryLaboratory) <br />
 [Rory Barnes](https://github.com/RoryBarnes) <br />
 [David Fleming](https://github.com/dflemin3)
 
+If you believe you have encountered a bug, please raise an issue using the "Issues" tab at the top of this page. 
+
 If you'd like to stay up to date on `VPLanet` by joining the e-mail list, please send a request to Rory Barnes, [email protected]. You can also follow VPLanet on twitter: [@VPLanetCode](https://twitter.com/VPLanetCode).
 
-Finally, if you use this code to generate results used in any publication or conference contribution, please cite [Barnes, R. et al. (2019), PASP, submitted](https://arxiv.org/abs/1905.06367).
+### Acknowledgments
+
+If you use this code to generate results used in any publication or conference contribution, please cite [Barnes, R. et al. (2019), PASP, accepted](https://ui.adsabs.harvard.edu/abs/2019arXiv190506367B/abstract).
 
-`VPLanet` development has been supported by NASA grants NNA13AA93A, NNX15AN35G, and 13-13NAI7_0024. We also acknowledge support from the University of Washington and the Carnegie Institute for Science.
+`VPLanet` development has been supported by NASA grants NNA13AA93A, NNX15AN35G, 80NSSC17K048, and 13-13NAI7_0024. We also acknowledge support from the University of Washington and the Carnegie Institute for Science.
 
 Enjoy!
+
+
+© 2018 The VPLanet Team.

VERSION

@@ -1 +1 @@
-0.9.4
+1.0.0

bigplanet/README.rst

@@ -1,6 +1,6 @@
 bigplanet
 -----
-A suite of data analysis and extraction routines for ``VPLANET``.
+A suite of data analysis and extraction routines for ``VPLanet``.
 
 Installation
 ============
@@ -9,4 +9,4 @@ Clone the repository and run the ``setup`` script by entering ``python setup.py
 Examples
 ========
 
-Check out the example.ipynb for a in-depth tutorial!
+Check out the example.ipynb for a in-depth tutorial!

bugs/README.rst

@@ -0,0 +1,4 @@
+VPLanet Bugs
+------------
+
+There are no (known) significant bugs in VPLanet at this time.