PlanetProfile 3.1.1

Self-consistent geophysical models for large moons and ocean worlds

PlanetProfile

PlanetProfile is a software framework for constructing 1D interior structure models based on planetary properties. Self-consistent thermodynamics are used for fluid, rock, and mineral phases. Sound speeds, attenuation, and electrical conductivities are computed as outputs. The main code is called from an input file containing all the planetary data.

The following is a non-comprehensive list of capabilities offered in PlanetProfile:

• Self-consistent ocean world modeling: Coupling of geophysics with thermodynamic and transport properties dictated by input ocean geochemistry
  • Available laboratory-measured ocean compositions: Pure water and Sodium Chloride (Seafreeze), Seawater (GSW), Magnesium Sulfate (Vance)
  • Can now model arbitrary ocean compositions whose thermodynamics and transport properties are computationally simulated with the geochemical databases Frezchem and Supcrt adapted in the gibbs minimization modeling package Reaktoro
• Self-consistent interior modeling: Coupling of silicate and core geophysics with thermodynamics dictated by material equation of states (i.e. CV, CM, etc.) defined by PerpleX
• Forward model Tidal love numbers with PyALMA3
• Forward model spherical harmonic and asymmetric magnetic induction responses with MoonMag
• Large scale model explorations that forward model across 2 different properties (ExploreOgrams) or many models via Monte Carlo explorations
• Export model data via .txt files, .pkl files, and .mat files
• Built-in plots to visualize models

For the latest updates being introduced to PlanetProfile, check out the CHANGELOG.md file

USERS WHO HAVE CLONED PLANETPROFILE PRIOR TO 2025 SHOULD REINSTALL A FRESH CLONE. SEE THE UNINSTALLING SECTION FOR MORE DETAILS The code was rebased to push many changes undertaken over the past year. Due to new file size limitations, this meant excluding a large Software framework for constructing 1D interior structure models based on planetary properties. Self-consistent thermodynamics are used for fluid, rock, and mineral phases. Sound speeds, attenuation, and electrical conductivities are computed as outputs. The main code is called from an input file containing all the planetary data.

The main repository is mirrored at https://github.com/NASA-Planetary-Science/PlanetProfile; any pull requests should be submitted to https://github.com/vancesteven/PlanetProfile. Read the software documentation at https://vancesteven.github.io/PlanetProfile.

Acknowledging PlanetProfile

We want to hear about your work with PlanetProfile! Please consider sending us a message alerting us to your work ([e-mail]). Suggested acknowledgement in publications: "Data used in this work were generated using the open-source PlanetProfile software hosted on GitHub (https://github.com/vancesteven/PlanetProfile)." Please also cite: Vance et al. (2018) Geophysical investigations of habitability in ice-covered ocean worlds. Journal of Geophysical Research: Planets, 10.1002/2017JE005341. Styczinski, S. D. Vance, and M. Melwani Daswani (2023) PlanetProfile: Self-consistent interior structure modeling for ocean worlds and rocky dwarf planets in Python. Earth and Space Science, 10(8), 10.1029/2022ea002748.

Getting started

PlanetProfile is available in Python and Matlab.

For Python

The recommended way to install is with pip. Developers: see below--do not install via pip.

However you install, you can run a test suite by "python Testing.py" from the main PlanetProfile directory. Developers should add test modules for new features and ensure to run the full test suite before deploying updates.

Pip installation

1. (Recommended) Install all dependencies listed in the next section before proceeding.

2. At a terminal: python -m pip install PlanetProfile Python 3.8 or higher is required, and Python 3.11 is recommended (newer version of Python have not been tested). A later version of PlanetProfile with Python 3.14 is in the works but not currently available.. Pip will install dependencies, but a conda or mamba (better) environment with the prerequisites listed below is recommended.

3. Create a directory where you'd like to store configurations and have folders for each body.

4. Navigate into the new directory.

5. Run the installation script: python -m PlanetProfile.install This will:

   • Copy default configuration files to your working directory
   • Automatically download large Perple_X EOS data files (~164 MB) that are not shipped with PlanetProfile package

6. Run the software with, for example: python -m PlanetProfile.Main Europa or python -m PlanetProfile.Main path/to/PPBody.py or in a Python script with from PlanetProfile.Main import RunPPfile RunPPfile('Europa', 'PPEuropa.py')

Developers

1. Install all prerequisites below to a dedicated conda environment. Python 3.11 is required for developers. If you are not yet using Python 3.11, upgrade before installing prerequisites.
2. Clone this repository.
3. Navigate to the top-level directory of the repository.
4. At a terminal: python -m PlanetProfile.install PPinstall
5. Run the software with the command line interface (CLI) script, for example: python PlanetProfileCLI.py Europa or python PlanetProfileCLI.py path/to/PPBody.py

For Matlab

1. Download or clone this repository.
2. Install prerequisites below.
3. At a terminal: make install Or, add everything in the top-level directory except the PlanetProfile sub-folder to the Matlab path.
4. In Matlab, set the current directory to the top-level directory of the downloaded repository (top PlanetProfile folder).
5. Run the software with PPEuropa in the Matlab command prompt, or by opening and running one of the files located at Body/PPBody.m (e.g. Titan/PPTitan.m).

Prerequisites

A simple list with install commands for Python is in the next section.

• SeaFreeze -- see https://github.com/Bjournaux/SeaFreeze
  • Python: Installed with pip: pip install SeaFreeze
  • Matlab: Download the repository to Thermodynamics/SeaFreeze and add the contents to the Matlab path
• Gibbs Seawater toolbox of TEOS-10 -- see https://www.teos-10.org/
  • Python: Installed with conda via conda-forge: conda install -c conda-forge gsw
  • Matlab: Already packaged into the PlanetProfile repository along with the original license.
• Perple_X -- see http://www.perplex.ethz.ch/
  • For both Python and Matlab, Perple_X outputs are currently hosted as part of the installation, in Thermodynamics/Perple_X for Matlab and in PlanetProfile/Thermodynamics/EOSdata/Perple_X for Python. The files we use were generated with Perple_X v6.7.9.
• TauP/ObsPy (optional) -- see https://www.seis.sc.edu/taup/
  • Python: Installed with conda via conda-forge: conda install -c conda-forge obspy
  • Matlab: Download mMatTauP contents into Utilities/ and add-with-subfolders to the Matlab path.
• A working TeX/LaTeX distribution (such as TeXlive) is recommended for optimum plot labels. TeXlive is available at: https://tug.org/texlive/acquire-netinstall.html It can also be installed using pip.
• Reaktoro -- see https://reaktoro.org
  • Python: Installed with conda: conda install reaktoro
• PyALMA3 -- see https://github.com/drsaikirant88/PyALMA3
  • Python: Installed with pip: pip install PyALMA3
• PlanetMag (optional) -- see https://github.com/coreyjcochrane/PlanetMag
  • Matlab only: Installed following detailed instructions on the repo.

Note about SeaFreeze versions prior to v1.0.0

If you had installed SeaFreeze before version v1.0.0, you will need to manually remove the prior installation because the new features are required. To do so, run the command python -m site and open the listed directory that ends in site-packages. Delete the files seafreeze.py and SeaFreeze_Gibbs.mat and any directories beginning with "SeaFreeze" (e.g. SeaFreeze.egg-info). Once these files have been removed, install the newer version of SeaFreeze with pip install SeaFreeze.

Installation of prerequisites

Python

1. Python version 3.8-3.11 must be installed, preferably via miniconda or Anaconda. Required modules can be installed in Miniconda with the following command:
2. conda install numpy=1.26.4 scipy=1.16.3 matplotlib mpmath pandas
3. Conda-forge modules can be installed in Anaconda or Miniconda with the following command:
4. conda install -c conda-forge gsw obspy spiceypy cmasher reaktoro
5. AFTER the above modules have been installed with conda, install SeaFreeze, MoonMag, and hdf5storage with the following command:
6. pip install SeaFreeze MoonMag hdf5storage PyALMA3
7. Finally, install PlanetProfile as described above.

Matlab

1. Download PlanetProfile repository.
2. Download SeaFreeze repository to PlanetProfile/Thermodynamics/SeaFreeze/ (NOT PlanetProfile/PlanetProfile/Thermodynamics).
3. Add SeaFreeze folder and sub-folders to Matlab path. Some magnetic field features require use of the SPICE toolkit through Mice. To install Mice:
4. Navigate to https://naif.jpl.nasa.gov/naif/toolkit_MATLAB.html
5. Follow the link for your operating system and download the .zip or .tar.Z file to PlanetProfile/Utilities/spice/
6. Unpack the archive (into PlanetProfile/Utilities/mice/)
7. Add PlanetProfile/Utilities/mice/src/mice/ and PlanetProfile/Utilities/mice/lib/ to your Matlab path.
8. Install necessary SPICE kernels by downloading them from https://naif.jpl.nasa.gov/pub/naif/generic_kernels/ and placing them in PlanetProfile/Utilities/spice/. The planetary constants kernel (PCK) and leap-seconds kernel (TLS) are saved in this repository, but the generic ephemeris kernels (SPK, .bsp files) are too large for us to save here. There is one for each planet's satellites, located at https://naif.jpl.nasa.gov/pub/naif/generic_kernels/spk/satellites/. Currently in use are:
9. jup365.bsp
10. sat441.bsp
11. ura111.bsp
12. nep095.bsp

Uninstalling

1. In the top-level directory, run the command python -c "from PlanetProfile.install import PPuninstall; PPuninstall()". All files named the same as the defaults will be deleted. If any non-default files have been added, you will be prompted whether you would like to delete them as well as the defaults. Empty folders will be deleted. Complete the uninstallation by deleting the entire directory and running the command pip uninstall PlanetProfile.

Contributing

PlanetProfile is open source software. Please see the LICENSE file and read the guidelines for contrbuting in CONTRIBUTING.md if you are interested in joining the project. Also see our community guidelines in CODE_OF_CONDUCT.md.

Notes

• With the PlanetProfile 3.0 release, both Python and Matlab are available. However, the MATLAB branch does not ahve the same functionality and we do not plan to keep it up to date with the Python version. For the latest features, use the Python version.
• With the PlanetProfile 2.0 release, both Python and Matlab are available. The two branches do not have the same functionality yet with this release--some features exist in the Python version that are not yet implemented in the Matlab.
• As of 2020-09-28, PlanetProfile v1.1.0 was released along with code for making calculations regarding magnetic induction. The development (main) branch of PlanetProfile is set up to generate profiles from minimal inputs. Output profiles that may be used along with the induction calculations may be found in the v1.1.0 release.
• The default settings include a recalculation of all parameters. It is recommended to recalculate all parameters whenever PlanetProfile is updated and any time a change in input parameters may affect layer thicknesses or other intermediate variables.

Some calculations in Python use parallel computing with the multiprocessing builtin module. There are sometimes cross-platform compatibility issues that crop up. By default, multiprocessing is enabled; disable it by setting Params.DO_PARALLEL = False in UserConfigs/configPP.py.