TidalPy

TidalPy Documentation

Tidal Dynamics and Thermal-Orbital Evolution Toolkit

TidalPy is an open source software suite that utilizes a semi-analytic approach to estimate tidal heating, spin-orbit resonances, tidal & loading Love numbers, and thermal evolution for rocky and icy worlds. It has been used to simulate the thermal-orbital evolution of moons within our Solar System as well as exoplanets beyond. TidalPy's RadialSolver package can accurately estimate the viscoelastic Love and Shida numbers for a multi-layered, rocky or icy world, including the effects of liquid layers, compressibility, dynamic tides, and advanced rheological models. This module has been used to study the tidal response of Mercury, Venus, Earth, our Moon, Mars, and much more.

TidalPy is implemented in C++ and wrapped with Cython and Python. This enables efficient calculations while still allowing for easy integration into popular astrophysics and scientific Python packages.

Have any questions or suggestions? Feel free to leave an issue or send a message to TidalPy@gmail.com.

Overview

How to Install

Compatibility

TidalPy has been developed to work on most modern operating systems. We specifically test it on the latest versions of Ubuntu, Windows, and MacOS. We also pre-build binaries for these operating systems and provide them via PyPI or Conda-Forge. If a pre-built binary is not available for your operating system version then see details about building TidalPy from source.

Basic Installation

Installing TidalPy is as simple as ensuring 64-bit Python 3.9+ is installed on your system and running from a terminal:

pip install TidalPy

Alternatively you can use conda to install TidalPy:

conda install -c conda-forge TidalPy

or

mamba install TidalPy

We recommend using a virtual environments (via a manager like uv or miniforge) when installing TidalPy.

Accessing Jupyter Notebooks

There are several demos provided with TidalPy that make use of Jupyter notebooks found in the /Demos/ folder of TidalPy's repository. In order to access these you will need to make sure you install Jupyter and a few related packages:

pip install ipympl ipython ipywidgets jupyter

or

conda install ipympl ipython ipywidgets jupyter

You can then clone TidalPy's GitHub repository,

git clone https://github.com/jrenaud90/TidalPy

to a local directory. Navigate to this directory and the Demos sub-directory then access the notebooks by using the command, jupyter notebook.

Cartopy

TidalPy offers the ability to make 2D surface projection plots using the cartopy package. In the past, there was difficulty installing cartopy as it relied on GEOS which was not a python package and had to be installed without pip. As of 2026, this does not appear to be a problem any more and cartopy can be installed with pip or conda. Please report any issues you have with this though!

Installation Troubleshooting

If you ran into a problem that is not listed below please submit an issue and we will work on addressing it!

Known Problems:

• The setuptools package is required before TidalPy can be installed. Usually it is automatically installed, but if you are starting with a clean virtual environment it may not have been.
  • For conda: conda install setuptools
  • Or pip: pip install setuptools

Building TidalPy from Source

We automatically provide pre-built binaries for the latest version of MacOS, Ubuntu, and Windows via PyPI or Conda-Forge. If your OS version does not have pre-built binaries or if you are running into problems with the pre-builds, then you can build TidalPy from its source code.

To do so, you will need to make sure that your environment has access to a C and C++ compiler that supports C++20 standards, a recent version of Python, and has Cython 3.0+ installed. Each platform's default compiler works (MSVC on Windows, GCC on Linux, Apple's clang on MacOS via xcode-select --install).

PyPI Build from Source

Using the source code uploaded to PyPI by running,

python -m pip install TidalPy -v --no-binary TidalPy

GitHub Repo

Alternatively you can clone the latest version of the GitHub repo and build locally,

git clone --recursive https://www.GitHub.com/jrenaud90/TidalPy.git  # --recursive fetches the C++ library submodules
python -m pip install . -v --no-binary TidalPy  # The . assumes you have navigated to the directory with `pyproject.toml`

This is also the approach you would take to build TidalPy if you plan to edit its code. See more details about developing TidalPy here.

Special consideration for MacOS

TidalPy v0.7.5 and later (and CyRK v0.19.0 and later) compile with Apple's default clang. Earlier versions linked to OpenMP and needed Homebrew's llvm and libomp; those steps are no longer required. If a source build picks up an unexpected compiler, check your shell profile for leftover CC, CXX, LDFLAGS, or CPPFLAGS exports from that older recipe and remove them.

Including TidalPy C++ Files

TidalPy includes several C++ source files (header-only ".hpp" files). You may find some of the code in them useful and want to include the source files to build a separate C++ or Cython-based projects. To help with this, TidalPy offers a helper function to provide all source file directories so they can be quickly and accurately included.

After installing TidalPy you can access a Python list of strings for each include directory (CyRK's include directories followed by every TidalPy directory that holds a header) with:

import TidalPy
tidalpy_includes = TidalPy.get_include()

The headers also need the header-only libraries TidalPy builds with (Eigen, xsf, and spdlog), which are not installed with TidalPy. The function works similarly to NumPy's numpy.get_include, which can be used during cythonization:

include_dirs=[np.get_include()] + TidalPy.get_include()

TidalPy Versioning

TidalPy uses the major.minor.bugfix versioning scheme. In TidalPy's current state, we only promise to provide support for the latest version (as found on the GitHub release page). Therefore, older minor versions may not get critical patches (e.g., TidalPy 0.7.x will get patches where 0.6.x will not even if the patches are applicable to that earlier version). If you would like to see a bug fix back ported to an older version please open an issue.

In the future we hope to support multiple minor versions of TidalPy. At that time, all supported versions will be listed in this section.

TidalPy 0.8.0 replaced the Python, Cython, and numba backend used through 0.7.X with a C++ + Cython backend, and its API changed with it. Scripts written for 0.7.X need to be updated: the migration guide maps the old modules, functions, and settings onto the new ones. TidalPy 0.7.6 is the last release with the 0.7.X API, and 0.7.X receives no further development. If you need that API, pin the version with pip install "TidalPy<0.8".

Using TidalPy

Check out the Getting Started guide to learn about TidalPy's features. The Demos directory is another good resource to learn by looking at Jupyter notebooks that can teach you how to use TidalPy's features.

Contribute to TidalPy

TidalPy is still in active development and there are lots of areas where it can improve! If you are interested in helping out, please check out the contributing guide (CONTRIBUTING.md in the repository).

Found a bug or have an idea for a new feature?

• Go to TidalPy's Github page and click the "Issues" tab then make a new report.
  • If you ran into a bug please include a code snippet (in markdown: code is designated by Grave accents surrounding the text) that reproduces the error (please keep this snippet as concise as possible).
  • It is helpful to triage issues when they are made. If you think you know the severity of a bug or can provide any other at-a-glance context, consider adding a "label" (right-hand side of the github issue form) to the issue.

Citing TidalPy

TidalPy has been used in several studies already, and we encourage you to use it in yours. If you do, please cite the package by using the preferred citation found in the citation.cff. Currently, that is its Zenodo doi: 10.5281/zenodo.7017474.

We also would love to hear where TidalPy is being used! Please feel free to send us an email: TidalPy@gmail.com when a paper or presentation utilized TidalPy. Anyone is welcome to create forks or copies of TidalPy as long as their work references back to this page. License information can be found here.

@software{2022zndo...7017475R,
       author = {{Renaud}, Joe P.},
        title = "{TidalPy}",
         year = 2022,
        month = jan,
          eid = {10.5281/zenodo.7017474},
          doi = {10.5281/zenodo.7017474},
    publisher = {Zenodo},
       adsurl = {https://ui.adsabs.harvard.edu/abs/2022zndo...7017475R},
      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

It is good practice to cite the specific version of TidalPy you are using. Major versions have their own DOI on Zenodo.

The science used in TidalPy is described in the following papers and software (with additional references therein):

• Rheology Module:
  • Tidally Heated Terrestrial Exoplanets: Viscoelastic Response Models
  • Increased Tidal Dissipation Using Advanced Rheological Models
• Dynamics and Tides Module:
  • Tidal Dissipation in Dual-Body, Highly Eccentric, and Non-synchronously Rotating System
  • Tidal Evolution of the Keplerian Elements
• RadialSolver (Love Number Calculator) Module:
  • Constraining the Venus Interior Structure.
  • Seismic Surface Waves
• Third Party Software:
  • Integration Routines: CyRK
  • C++ Libraries: Eigen, xsf, spdlog
  • Graphics: Scientific Color Maps, Cartopy, Matplotlib
  • Scientific Python: NumPy, SciPy
  • Performance: Cython
  • Equation of State Comparison: BurnMan

Acknowledgements

TidalPy was partially developed with support from NASA Goddard Space Flight Center's Sellers Exoplanet Environments Collaboration (SEEC) and Planetary Geodesy ISFMs. TidalPy is partially based upon work supported by NASA under award number 80GSFC21M0002 and the Center for Research and Exploration in Space Science & Technology II (CRESST II) administered at the University of Maryland, College Park.

TidalPy has been improved by numerous contributors some of which you can find here.

TidalPy has benefited from work and conversations with the following:

• Wade G. Henning (U. of Maryland, College Park / NASA GSFC)
• Michael Efroimsky (U.S. Naval Observatory)
• Michaela Walterová (Charles University)
• Sander Goossens (NASA GSFC)
• Marc Neveu (U. of Maryland, College Park / NASA GSFC)
• Gael Cascioli (U. of Maryland, Baltimore County / NASA GSFC)
• Nick Wagner (Brown University)

License and Copyright

Copyright 2025 by Joe P. Renaud. TidalPy is licensed under the Apache License, Version 2.0 (the "License"); you may not use this code except in compliance with the License. You may obtain a copy of the License at www.apache.org/licenses/LICENSE-2.0 or in this repository's LICENSE.md file. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" basis, without warranties or conditions of any kind, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You are welcome to copy/fork TidalPy and make modifications assuming the following conditions are met:

• Code repositories link back to TidalPy's original repository.
• Any published research cites this code using the preferred citation found in the citation.cff file.

TidalPy's logo was originally designed by Ruhul Amin and modified by Joe P. Renaud.