Skip to content

Commit

Permalink
Showing 13 changed files with 115 additions and 96 deletions.
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -90,3 +90,5 @@ sandbox
todo
misc
vplot/
build/
dist/
6 changes: 2 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
2.0.6
2.1.0
Binary file modified docs/VPLanetLogo.png
100644 → 100755
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions docs/authors.rst
Original file line number Diff line number Diff line change
@@ -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.

160 changes: 89 additions & 71 deletions docs/parametersweep.rst
Original file line number Diff line number Diff line change
@@ -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!
1 change: 1 addition & 0 deletions docs/repos.rst
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit 8401af1

Please sign in to comment.