Merge pull request #195 from VirtualPlanetaryLaboratory/dev

Dev

Author: RoryBarnes

.gitignore

@@ -90,3 +90,5 @@ sandbox
 todo
 misc
 vplot/
+build/
+dist/

README.md

@@ -69,14 +69,13 @@ Many of these modules can be combined together to simulate numerous phenomena an
 ### Resources
 
 The [examples/](examples) directory contains input files and scripts for generating the figures in [Barnes et al. (2020)](https://ui.adsabs.harvard.edu/abs/2020PASP..132b4502B/abstract) and subsequent publications. The [Manual/](Manual) directory contains the pdf of [Barnes et al. (2020)](https://ui.adsabs.harvard.edu/abs/2020PASP..132b4502B/abstract), which describes the physics of the first 11 modules, 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, and then use [multi-planet/](multiplanet) to perform the simulations on an arbitrary number of cores. [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. These three scripts can be run from the command line to seamlessly [perform parameter sweeps](https://virtualplanetarylaboratory.github.io/vplanet/parametersweep.html). 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. These python scripts are optimized for [anaconda](https://www.anaconda.com/) distributions versions 3.5-3.7.
 
 ### Code Integrity
 
 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 by <a href="https://codecov.io/gh/VirtualPlanetaryLaboratory/vplanet">Codecov</a> at every commit. 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 of the main branch, either clean (no errors) or dirty. If dirty, check the [Issues](https://github.com/VirtualPlanetaryLaboratory/vplanet/issues) for more information about the current status. Note that all releases are clean. We are committed to maintaining a stable tool for scientists to analyze any planetary system.  
 
-
 ### Community
 
 `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. The documentation includes [tutorials on adding new features and modules](https://VirtualPlanetaryLaboratory.github.io/vplanet/tutorials.html). It's a platform for planetary science that can grow exponentially, either by adding new physics or by adding competing models for clean comparisons.
@@ -95,5 +94,4 @@ If you use this code to generate results used in any publication or conference c
 
 Enjoy!
 
-
-© 2018-2020 The VPLanet Team.
+© 2018-2021 The VPLanet Team.

VERSION

@@ -1 +1 @@
-2.0.6
+2.1.0

docs/VPLanetLogo.png

@@ -35,8 +35,8 @@ development.
 He also found many bugs with valgrind and address-sanitizer.
 
 **Caitlyn Wilhelm** added forced eccentricity and obliquity oscillations to
-POISE, and assisted in debugging it. She also built the bigplanet and
-multi-planet script.
+POISE, and assisted in debugging it. She also built the BigPlanet and
+MultiPlanet scripts.
 
 **Rodolfo Garcia** assisted in AtmEsc and ThermInt development.
 

docs/authors.rst

@@ -1,10 +1,10 @@
 Parameter Sweep Guide
 ===================
 
-Parameter sweeps are a very common use of VPLanet, and the team has
-developed a set of python and command line tools to facilitate their completion
-and analysis. In brief, :code:`vspace` builds a set of initial conditions,
-:code:`multi-planet` performs the simulations, and :code:`bigplanet` compresses the data
+Parameter sweeps are a very common use of ``VPLanet``, and the team has
+developed a set of Python and command line tools to facilitate their completion
+and analysis. In brief, :code:`VSPACE` builds a set of initial conditions,
+:code:`multi-planet` performs the simulations, and :code:`BigPlanet` compresses the data
 and streamlines analysis. The following guide explains how to use these
 tools with an example based on Earth's internal thermal evolution. Files for the example
 presented here can be found in `examples/ParameterSweep
@@ -15,93 +15,92 @@ core temperature and the current amount of radiogenic heating from potassium-40.
 
 .. note::
 
-    You need to install :code:`vplot`, :code:`vspace`, :code:`multi-planet`, and :code:`bigplanet` to
+    You need to install :code:`vplot`, :code:`VSPACE`, :code:`MultiPlanet`, and :code:`BigPlanet` to
     reproduce this example.
 
 
-Initializing Parameter Sweeps with :code:`vspace`
+Initializing Parameter Sweeps with :code:`VSPACE`
 ------------------------
 
-The first step is to create an input file for :code:`vspace`, which is typically called `vspace.in`.
-As described in more detail in :code:`vspace`'s `documentation
-<https://github.com/VirtualPlanetaryLaboratory/vplanet/tree/master/vspace>`_, this file
-modifies template files (here we use the .in files from `examples/EarthInterior
+The first step is to create an input file for :code:`VSPACE`, which is typically called `VSPACE.in`.
+As described in more detail in :code:`VSPACE`'s `documentation
+<https://virtualplanetarylaboratory.github.io/VSPACE/>`_, this file
+modifies template files (here we use the ``VPLanet`` input files from `examples/EarthInterior
 <https://github.com/VirtualPlanetaryLaboratory/vplanet/tree/master/examples/EarthInterior>`_)
 and then builds a directory structure with each
-folder containing the .in files for a specific simulation. In this guide we vary
+folder containing the input files for a specific simulation. In this guide we vary
 dTCore (initial core temperature) and d40KPowerCore (initial radiogenic power from potassium-40).
 
-Here’s the input file for :code:`vspace`:
+Here’s the input file for :code:`VSPACE`:
 
 .. code-block:: bash
 
-    srcfolder ~/vplanet/examples/EarthInterior
-    destfolder ParameterSweep
-    trialname test_
+    sSrcFolder ~/vplanet/examples/EarthInterior
+    sDestFolder ParameterSweep
+    sTrialName test_
 
-    file   sun.in
+    sBodyFile   sun.in
 
-    file   earth.in
+    sBodyFile   earth.in
 
     dTCore [5500, 6500, n10] tcore
     d40KPowerCore [-1.5, -0.5, n10] K
 
-    file   vpl.in
+    sPrimaryFile   vpl.in
 
-This file directs :code:`vspace` to vary initial core temperature from 5500 to 6500 in 10 steps and
-initial potassium-40 power from 50 - 150% of Earth's nominal initial amount (see the VPLanet paper
-for more details). The directories will be built in a folder called
+This file directs :code:`VSPACE` to vary initial core temperature from 5500 to 6500 in 10 steps and
+initial potassium-40 power from 50 - 150% of Earth's nominal initial amount. The directories will be built in a folder called
 ParameterSweep and the individual folders will be called test_tcore?K?, where the
-"n" tells :code:`vspace` to create 10 evenly spaced values for each (other distributions are available), so the total number of
+"n" tells :code:`VSPACE` to create 10 evenly spaced values for each (other distributions are available), so the total number of
 simulations will be 100.
 
-To build the files, run the following command in the command line:
+To build the files, run the following command:
 
 .. code-block:: bash
 
-    vspace [-q, -f] vspace.in
+    vspace [-q -f] vspace.in
 
 This command will create the folder ParameterSweep, with 100 folders
 inside of it, each with their own sun.in, earth.in and vpl.in with the
 parameters from the EarthInteror example, but with dTCore and d40KPowerCore changed
-based on the vspace file. Use -q to suppress output and -f to force :code:`vspace` to overwrite previous
-data (including any :code:`multi-planet` and :code:`bigplanet` files!). Now we are ready to run the parameter sweep.
+based on the instructions in the VSPACE.in file. Use ``-q`` to suppress output and ``-f`` to force :code:`VSPACE` to overwrite previous
+data (including any :code:`MultiPlanet` and :code:`BigPlanet` files!). Now we are ready to run the parameter sweep.
 
 .. note::
 
-    If you randomly generate initial conditions, i.e. Monte Carlo, then :code:`vspace` automatically creates histograms of the
-    options you varied so you can confirm the initial conditions. These png files are located in destfolder.
+    If you randomly generate initial conditions, i.e. Monte Carlo, then :code:`VSPACE` automatically creates histograms of the
+    options you varied so you can confirm the initial conditions. These png files are located in *destfolder*.
 
-Running Simulations with :code:`multi-planet`
+Running Simulations with :code:`MultiPlanet`
 -------------------------
 
-:code:`multi-planet` is the command line tool to run the simulations created with :code:`vspace`
+:code:`MultiPlanet` is the command line tool to run the simulations created with :code:`VSPACE`
 across the processors on your computer. To run, type the following in the
 command line:
 
 .. code-block:: bash
 
-    multi-planet -c <num_cores> [-q] vspace.in
+    multiplanet -c <num_cores> [-q -bp] vspace.in
 
-The optional argument -c (or --cores) tells :code:`multi-planet` the number of cores to run.
-There is another optional argument that creates the HDF5 Files for :code:`bigplanet`
+The optional argument ``-c`` (or ``--cores``) tells :code:`MultiPlanet` the number of cores to run.
+The ``-bp`` flag creates `"BigPlanet archive <https://virtualplanetarylaboratory.github.io/bigplanet/filetypes.html>`_
 directly after the simulation completes, but we are going to leave it at the default
-setting, which is false. See the :code:`multi-planet` `documentation
-<https://github.com/VirtualPlanetaryLaboratory/vplanet/tree/master/multi-planet>`_ for
+setting, which is false. See the :code:`MultiPlanet` `documentation
+<https://virtualplanetarylaboratory.github.io/multi-planet>`_ for
 more information. Use the -q option to suppress output to the terminal.
 
 .. note::
 
-    The default number of cores :code:`multi-planet` will use is the maximum number of
+    The default number of cores :code:`MultiPlanet` will use is the maximum number of
     cores on the machine.
 
-Checking :code:`multi-planet` Progress with :code:`mpstatus`
+Checking :code:`MultiPlanet` Progress with :code:`mpstatus`
 -------------------------
 
 This example is quick to run (~1 minute, depending on the number of cores), but for
 longer simulations it is often
 helpful to know how far along the parameter sweep is. The command :code:`mpstatus` returns the
-current state of the :code:`multi-planet` process. To check the current status, type the
+current state of the :code:`MultiPlanet` process. To check the current status, type the
 following command:
 
 .. code-block:: bash
@@ -112,56 +111,75 @@ This command returns output like the following to the terminal:
 
 .. code-block:: bash
 
-      --Multi-Planet Status--
+      --MultiPlanet Status--
     Number of Simulations completed: 35
     Number of Simulations in progress: 6
     Number of Simulations remaining: 59
 
 But with the proper numbers shown.
 
-After :code:`multi-planet` completes, you may have a large number of directories with gigabytes
+After :code:`MultiPlanet` completes, you may have a large number of directories with gigabytes
 of data. Storing, analyzing, and plotting these data can be tedious as each output file
 from each directory must be opened and read in sequentially. To streamline this process,
-use :code:`bigplanet`.
+use :code:`BigPlanet`.
 
-Compressing Data with :code:`bigplanet`
+Compressing Data with :code:`BigPlanet`
 -------------------------------
 
-The :code:`bigplanet` command compresses your parameter sweep data into an HDF5 file in which
+The :code:`BigPlanet` command compresses your parameter sweep data into an HDF5 file in which
 specific data can be efficiently extracted. **Although compression can take some time,
-plotting with a** :code:`bigplanet` **file can be orders of magnitude faster because the script will
-not need to open files and each directory!**
-To compress the data, type the following command in the terminal (after multi-planet
+plotting with a** :code:`BigPlanet` ** file can be orders of magnitude faster because the script will
+not need to open files and each directory!** Here we demonstrate the typical workflow of building a biplanet file.
+To compress the data, type the following command in the terminal (after MultiPlanet
 finishes):
 
 
 .. code-block:: bash
 
-    bigplanet -c <num_cores> [-q] vspace.in
+    bigplanet -c <num_cores> [-a] bpl.in
 
-The bigplanet arguments work identically to :code:`multi-planet`’s with the user able to
-specify the number of processors :code:`bigplanet` can use. This will create an `HDF5
+The BigPlanet arguments work similarly to :code:`multiplanet`’s with the user able to
+specify the number of processors :code:`BigPlanet` can use. The only difference is that
+BigPlanet uses a bpl.in file, which is *very* similar to a vspace input file. 
+
+Here’s the input file for :code:`BigPlanet`:
+
+.. code-block:: bash
+
+    sSrcFolder ~/vplanet/examples/EarthInterior
+    sDestFolder ParameterSweep
+    sArchiveFile ParameterSweep.bpa
+
+    saBodyFiles   sun.in earth.in
+
+    sPrimaryFile   vpl.in
+
+    saKeyInclude earth:TCore:initial earth:40KPowerCore:final earth:RIC:final
+
+
+This will create an `HDF5
 <https://en.wikipedia.org/wiki/Hierarchical_Data_Format>`_ file
-that shares the same name as the destfolder from the :code:`vspace` file, but with ".hdf5"
-appended, e.g. ParameterSweep.hdf5. This file will now replace the directory structure
-created by :code:`vspace`. Use the -q option to suppress output to the terminal.
+that shares the same name as the destfolder from the :code:`VSPACE` file, but with ".bpf" or ".bpa"
+appended, e.g. ParameterSweep.bpa. This file will now replace the directory structure
+created by :code:`VSPACE`. The -a option is for creation of an achvie file, which has **everything from
+the destfolder created with :code:`VSPACE` and the data generated from :code:`MultiPlanet`. Here is a 
 
 .. note::
 
-    The default number of cores :code:`bigplanet` will use is the maximum number of
+    The default number of cores :code:`BigPlanet` will use is the maximum number of
     cores on the machine.
 
-Checking :code:`bigplanet` Progress with :code:`bpstatus`
+Checking :code:`BigPlanet` Progress with :code:`bpstatus`
 -------------------------
 
-For large data sets, :code:`bigplanet` may take several hours or more to complete. To check the
+For large data sets, :code:`BigPlanet` may take several hours or more to complete. To check the
 status, use :code:`bpstatus`, which employs the same syntax as :code:`mpstatus` above.
 
-Extracting and Plotting with :code:`bigplanet`
+Extracting and Plotting with :code:`BigPlanet`
 ------------------------------
 
 After you have compressed your data, you need to access it. To accomplish this goal,
-:code:`bigplanet` is also a python module that can be imported into python scripts for the
+:code:`BigPlanet` is also a python module that can be imported into python scripts for the
 extraction of data from the HDF5 file. For our example, final inner core radius as a function of
 current potassium-40 abundance in the core and the initial core temerature, the script looks like
 this:
@@ -172,7 +190,7 @@ this:
   import matplotlib.pyplot as plt
   import vplot as vpl
 
-  data = bp.HDF5File(‘ParameterSweep.hdf5’)
+  data = bp.HDF5File(‘ParameterSweep.bpf’)
 
 This loads in the necessary modules and reads in the HDF5 file as data. Now we are
 ready to extract the data we want to graph, which are the initial values of TCore,
@@ -181,13 +199,13 @@ start with inner core radius, grabbing its final values and its units:
 
 .. code-block:: python
 
-    RIC = bp.ExtractColumn(data,'earth_RIC_final')
-    RIC_units = bp.ExtractUnits(data,'earth_RIC_final')
+    RIC = bp.ExtractColumn(data,'earth:RIC:final')
+    RIC_units = bp.ExtractUnits(data,'earth:RIC:final')
 
 ExtractColumn returns an array in which each element corresponds to the final
 value of the inner core radius for each simulation. The first argument is the HDF5
 file, the second argument is called a "key" and describes a parameter of
-interest. To learn more about keys, consult the `bigplanet documentation
+interest. To learn more about keys, consult the `BigPlanet documentation
 <https://github.com/VirtualPlanetaryLaboratory/vplanet/tree/master/multi-planet>`_.
 In brief, the key syntax is "body_variable_aggregation", in
 which aggregation is some property of a body's variable, e.g. the final value. The
@@ -201,14 +219,14 @@ needed for the plot, use the ``ExtractUniqueValues`` function, like so:
 
 .. code-block:: python
 
-    TCore_uniq = bp.ExtractUniqueValues(data,'earth_TCore_initial')
-    TCore_units = bp.ExtractUnits(data,'earth_TCore_initial')
+    TCore_uniq = bp.ExtractUniqueValues(data,'earth:TCore:initial')
+    TCore_units = bp.ExtractUnits(data,'earth:TCore:initial')
 
-    K40_uniq = bp.ExtractUniqueValues(data,'earth_40KPowerCore_final')
-    K40_units = bp.ExtractUnits(data,'earth_40KPowerCore_final')
+    K40_uniq = bp.ExtractUniqueValues(data,'earth:40KPowerCore:final')
+    K40_units = bp.ExtractUnits(data,'earth:40KPowerCore:final')
 
 Now we have the values we need for our plot, but the inner core radius is currently
-stored as an array, not a matrix, so we're still not ready to plot. With :code:`bigplanet` you
+stored as an array, not a matrix, so we're still not ready to plot. With :code:`BigPlanet` you
 can easily transform an array into the appropriately shaped matrix with the ``CreateMatrix``
 function:
 
@@ -227,30 +245,30 @@ of Earth's inner core radius.
 
 .. figure:: BigPlanetExample.png
 
-Creating Meta-Data Files with :code:`bigplanet`
+Creating Meta-Data Files with :code:`BigPlanet`
 ----------------------------
 
 Finally, it's often convenient to write out ASCII files in which each line contains the meta-data
 for your parameter sweep, e.g. the initial eccentricity, the final semi-major axis, and the maximum
-inclination. :code:`bigplanet` facilitates the creation of these files with the ``WriteOutput`` method:
+inclination. :code:`BigPlanet` facilitates the creation of these files with the ``ArchiveToCSV`` method:
 
 .. code-block:: python
 
-    WriteOutput(inputfile, columns, file="bigplanet.out", delim=" ", header=False, ulysses=False)
+    ArchiveToCSV(inputfile, columns, exportfile, delim=" ", header=False, ulysses=0)
 
 where:
 
 *inputfile* is the name of the HDF5 file
 
 *columns* is the list of keys you are extracting, i.e. the output from calls to ExtractColumn
 
-*File* is the name of the output file
+*exportfile* is the name of the output file
 
 *delim* is the delimiter for the output file (the default is spaces)
 
 *header* adds the names and units for each column (default is False)
 
-*ulysses* makes the file compatable with `VR Ulysses <https://www.vrulysses.com/>`_ (default is False)
+*ulysses* makes the file compatable with `VR Ulysses <https://www.vrulysses.com/>`_ (default is 0)
 
 
 You are now ready to efficiently explore your parameter space!

docs/parametersweep.rst

@@ -13,3 +13,4 @@ can be found at the GitHub sites:
    David Graham <https://github.com/dglezg7>
    David Fleming <https://github.com/dflemin3>
    Héctor Martínez-Rodríguez <https://github.com/hector-mr>
+   Caitlyn Wilhelm <https://github.com/caitlyn-wilhelm>