Metadata-Version: 2.4
Name: TidalPy
Version: 0.8.0
Summary: Tidal Dynamics and Thermal-Orbital Evolution Software Suite Implemented in C++, Cython, and Python
Author-email: "Joe P. Renaud" <TidalPy@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/jrenaud90/TidalPy
Project-URL: Bug Tracker, https://github.com/jrenaud90/TidalPy/issues
Project-URL: Documentation, https://tidalpy.readthedocs.io/en/latest/
Keywords: Scientific Computing,Scientific Modeling,Astrophysics,Astronomy,Planets,Moons,Exoplanets,Planetary Science,Planetary Interiors,Orbital Dynamics,Tides,Tidal Dynamics,Tidal Heating,Numerical Integration
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Cython
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Natural Language :: English
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: <3.15,>=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy<2.6,>=1.22
Requires-Dist: scipy>=1.9.3
Requires-Dist: matplotlib>=3.4.2
Requires-Dist: platformdirs>=3.11.0
Requires-Dist: toml>=0.10.2
Requires-Dist: tqdm>=4.64
Requires-Dist: cyrk<0.21.0,>=0.20.0
Provides-Extra: dev
Requires-Dist: jupyter; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: psutil>=5.8.0; extra == "dev"
Requires-Dist: pandas>=1.5; extra == "dev"
Requires-Dist: cmcrameri<2.0,>=1.4; extra == "dev"
Requires-Dist: palettable>=3.3.0; extra == "dev"
Requires-Dist: ipympl>=0.8.7; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: linkify-it-py; extra == "docs"
Requires-Dist: sphinx_rtd_theme; extra == "docs"
Requires-Dist: toml; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Requires-Dist: ipykernel; extra == "docs"
Requires-Dist: nbconvert; extra == "docs"
Requires-Dist: jupyter; extra == "docs"
Provides-Extra: graphics
Requires-Dist: jupyter; extra == "graphics"
Requires-Dist: cmcrameri<2.0,>=1.4; extra == "graphics"
Requires-Dist: palettable>=3.3.0; extra == "graphics"
Requires-Dist: ipympl>=0.8.7; extra == "graphics"
Requires-Dist: cartopy>=0.22.0; extra == "graphics"
Dynamic: license-file

# TidalPy
<p align="center">
  <img src="https://raw.githubusercontent.com/jrenaud90/TidalPy/87436336932860441e377dc24d606164e855ddf0/Documentation/_static/images/2025-11-28_Logo_2-4.svg" width="350" alt="TidalPy Logo">
</p>
<div align="center" style="text-align: center;">
    <a href="https://app.readthedocs.org/projects/tidalpy/builds/?version__slug=latest"><img src="https://app.readthedocs.org/projects/tidalpy/badge/?version=latest&style=flat" alt="TidalPy Documentation" /></a>
    <a href="https://doi.org/10.5281/zenodo.7017474"><img src="https://zenodo.org/badge/DOI/10.5281/zenodo.7017474.svg" alt="DOI: 10.5281/zenodo.7017474"></a>
    <a href="https://github.com/jrenaud90/TidalPy/releases"><img src="https://img.shields.io/badge/TidalPy-0.8.0-orange" alt="TidalPy Version 0.8.0" /></a><br />
    <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/Python-3.9|3.10|3.11|3.12|3.13|3.14-blue" alt="Python Version 3.9-3.14" /></a>
    <a href="https://github.com/jrenaud90/TidalPy/actions/workflows/tests.yml"><img src="https://github.com/jrenaud90/TidalPy/actions/workflows/tests.yml/badge.svg?branch=main" alt="Tests" /></a><br />
    <a href="https://pypi.org/project/TidalPy/"><img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dm/TidalPy?label=PyPI%20Downloads" /></a>
    <a href="https://anaconda.org/conda-forge/tidalpy"> <img alt="Conda Downloads" src="https://img.shields.io/conda/d/conda-forge/tidalpy" /></a>
    <a href="https://emac.gsfc.nasa.gov?cid=2207-034"><img src="https://img.shields.io/badge/EMAC-2207--034-blue" alt="EMAC 2207-034"></a>
</div>

---
<p align="center"><a href="https://tidalpy.readthedocs.io/en/latest/">TidalPy Documentation</a></p>

**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](https://github.com/jrenaud90/TidalPy/issues) or send a message to [TidalPy@gmail.com](mailto: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](https://pypi.org/project/TidalPy/) or [Conda-Forge](https://anaconda.org/conda-forge/tidalpy). If a pre-built binary is not available for your operating system version then see details about [building TidalPy from source](https://tidalpy.readthedocs.io/en/latest/Overview/Readme.html#building-tidalpy-from-source).

### Basic Installation

Installing TidalPy is as simple as ensuring 64-bit [Python 3.9+](https://www.python.org/) 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](https://docs.astral.sh/uv/pip/environments/) or [miniforge](https://conda-forge.org/download/)) when installing TidalPy.

### Accessing Jupyter Notebooks
There are several demos provided with TidalPy that make use of [Jupyter notebooks](https://jupyter.org/) found in the /Demos/ folder of TidalPy's [repository](https://github.com/jrenaud90/TidalPy). 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](https://scitools.org.uk/cartopy/docs/latest/index.html) package. In the past, there was difficulty installing cartopy as it relied on [GEOS](https://trac.osgeo.org/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](https://github.com/jrenaud90/TidalPy/issues) 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](https://pypi.org/project/TidalPy/) or [Conda-Forge](https://anaconda.org/conda-forge/tidalpy). 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,

```bash
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,
```bash
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](https://tidalpy.readthedocs.io/en/latest/Overview/Contributing.html).

#### 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:
```python
import TidalPy
tidalpy_includes = TidalPy.get_include()
```

The headers also need the header-only libraries TidalPy builds with ([Eigen](https://eigen.tuxfamily.org), [xsf](https://github.com/scipy/xsf), and [spdlog](https://github.com/gabime/spdlog)), which are not installed with TidalPy. The function works similarly to NumPy's `numpy.get_include`, which can be used during cythonization:
```python
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](https://github.com/jrenaud90/TidalPy/releases)). 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](https://github.com/jrenaud90/TidalPy/issues). 

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](https://tidalpy.readthedocs.io/en/latest/future_structure.html) 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](https://tidalpy.readthedocs.io/en/latest/Overview/1_Getting_Started.html) guide to learn about TidalPy's features. The `Demos` directory is another good resource to learn by looking at [Jupyter notebooks](https://jupyter.org/) 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](https://tidalpy.readthedocs.io/en/latest/Overview/Contributing.html) (`CONTRIBUTING.md` in the repository).

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

* Go to TidalPy's [Github page](https://github.com/jrenaud90/TidalPy) 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](https://github.com/jrenaud90/TidalPy/blob/main/citation.cff). Currently, that is its Zenodo
[doi: 10.5281/zenodo.7017474](https://doi.org/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](mailto: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](https://tidalpy.readthedocs.io/en/latest/Overview/License.html).

```bibtex
@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](https://zenodo.org/records/16883555).

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](https://ui.adsabs.harvard.edu/abs/2009ApJ...707.1000H/abstract)
  * [Increased Tidal Dissipation Using Advanced Rheological Models](https://ui.adsabs.harvard.edu/abs/2018ApJ...857...98R/abstract)
* Dynamics and Tides Module:
  * [Tidal Dissipation in Dual-Body, Highly Eccentric, and Non-synchronously Rotating System](https://ui.adsabs.harvard.edu/abs/2021PSJ.....2....4R/abstract)
  * [Tidal Evolution of the Keplerian Elements](https://ui.adsabs.harvard.edu/abs/2019CeMDA.131...30B/abstract)
* RadialSolver (Love Number Calculator) Module:
  * [Constraining the Venus Interior Structure](https://ui.adsabs.harvard.edu/abs/2023PSJ.....4...65C).
  * [Seismic Surface Waves](https://www.doi.org/10.1016/B978-0-12-460811-5.50010-6)
* Third Party Software:
  * *Integration Routines*: [CyRK](https://zenodo.org/records/8329446)
  * *C++ Libraries*: [Eigen](https://eigen.tuxfamily.org), [xsf](https://github.com/scipy/xsf), [spdlog](https://github.com/gabime/spdlog)
  * *Graphics*: [Scientific Color Maps](https://doi.org/10.5281/zenodo.1243862), [Cartopy](https://scitools.org.uk/cartopy/docs/latest/), [Matplotlib](https://www.doi.org/10.1109/MCSE.2007.55)
  * *Scientific Python*: [NumPy](https://doi.org/10.1038/s41586-020-2649-2), [SciPy](https://doi.org/10.1038/s41592-019-0686-2)
  * *Performance*: [Cython](https://www.doi.org/10.1109/MCSE.2010.118)
  * *Equation of State Comparison*: [BurnMan](https://github.com/geodynamics/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](https://github.com/jrenaud90/TidalPy/graphs/contributors).

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](https://github.com/jrenaud90). 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](http://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](https://github.com/jrenaud90/TidalPy).
* Any published research cites this code using the preferred citation found in the [citation.cff file](https://github.com/jrenaud90/TidalPy/blob/main/citation.cff).

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