TidalPy.tides.methods package

Submodules

TidalPy.tides.methods.base module

Base Tides Module

class TidalPy.tides.methods.base.TidesBase[source]

Bases: WorldConfigHolder

Holder for all tidal heating and tidal potential calculations

Tides class stores model parameters and methods for calculating tidal heating and tidal potential derivatives

which are general functions of (T, P, melt_frac, w, e, obliquity)

eccentricity_truncation_lvl
max_tidal_order_lvl
use_obliquity_tides
multiply_modes_by_sign
eccentricity_results
obliquity_results
tidal_susceptibility_reduced
tidal_susceptibility
unique_tidal_frequencies
tidal_terms_by_frequency
tidal_heating_global
global_negative_imk_by_orderl
global_love_by_orderl
effective_q_by_orderl
dUdM
dUdw
dUdO
fixed_q
fixed_dt
fixed_k2
thermal_set
orbit_set
static calculate_complex_love_number(shear_modulus: FloatArray, complex_compliance: ComplexArray, effective_rigidity: FloatArray, tidal_order_l: int = 2) → ComplexArray[source]

Calculate the complex Love number of a layer or planet

Wrapper for TidalPy.tides.love1d.complex_love_general

Parameters:

  • shear_modulus (FloatArray) – Shear modulus of a layer/planet [Pa]

  • complex_compliance (ComplexArray) – Complex compliance of a layer/planet [Pa -1]

  • effective_rigidity (FloatArray) – Effective rigidity of a layer/planet [Pa Pa-1] See: Tides.calculate_effective_rigidity

  • tidal_order_l (int = 2) – Tidal harmonic order integer

Returns:

complex_love_number – Complex Love number for the layer/planet

Return type:

ComplexArray

static calculate_effective_rigidity(shear_modulus: FloatArray, gravity: float, radius: float, bulk_density: float, tidal_order_l: int = 2) → FloatArray[source]

Calculate the effective rigidity of a layer or planet

Wrapper for TidalPy.tides.love1d.effective_rigidity_general

Parameters:

  • shear_modulus (FloatArray) – Shear modulus of a layer/planet [Pa]

  • gravity (float) – Acceleration of gravity at the surface of a layer/planet [m s-2]

  • radius (float) – Radius at the top of a layer/planet [m]

  • bulk_density (float) – Bulk density of a layer/planet [kg m-3]

  • tidal_order_l (int = 2) – Tidal harmonic order integer

Returns:

effective_rigidity – Effective rigidity of the layer/planet [Pa Pa-1]

Return type:

FloatArray

static calculate_tidal_susceptibility(host_mass: float, target_radius: float, semi_major_axis: FloatArray) → FloatArray[source]

Calculate the tidal susceptibility for a target object orbiting

Wrapper for TidalPy.tides.dissipation.calc_tidal_susceptibility

Parameters:

  • host_mass (float) – Tidal host’s mass [kg]

  • target_radius (float) – Target body’s mean radius [m]

  • semi_major_axis (FloatArray) – Orbital separation between the target and host [m]

Returns:

tidal_susceptibility – Tidal Susceptibility [N m]

Return type:

FloatArray

clear_state()[source]

Clear the tidal model’s state properties

collapse_modes()[source]

Calculate Global Love number based on current thermal state.

Requires a prior orbit_spin_changed() call as unique frequencies are used to calculate the complex compliances

used to calculate the Love numbers.

Returns:

  • tidal_heating (np.ndarray) – Tidal heating [W] This could potentially restricted to a layer or for an entire planet.

  • dUdM (np.ndarray) – Tidal potential derivative with respect to the mean anomaly [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

  • dUdw (np.ndarray) – Tidal potential derivative with respect to the pericentre [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

  • dUdO (np.ndarray) – Tidal potential derivative with respect to the planet’s node [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

See also

TidalPy.tides.Tides.orbit_spin_changed

property dUdM: FloatArray

Global partial derivative of the tidal potential with respect to the mean anomaly

property dUdO: FloatArray

Global partial derivative of the tidal potential with respect to the argument of node

property dUdw: FloatArray

Global partial derivative of the tidal potential with respect to the argument of pericentre

property eccentricity

Outer-scope wrapper for world.eccentricity

property eccentricity_results: Dict[int, EccenOutput]

Eccentricity function results (squared) stored by order_l

property eccentricity_truncation_lvl: int

Maximum eccentricity truncation level to include in tidal calculations

property effective_q_by_orderl: Dict[int, FloatArray]

World’s effective tidal dissipation factor (for each tidal order level)

property fixed_dt: float

Fixed tidal dissipation frequency dependency (used in CTL tidal calculation method)

property fixed_k2: float

Fixed static k2 for the world

property fixed_q: float

Fixed tidal dissipation factor (used in CPL tidal calculation method)

fixed_q_dt_changed()[source]

The fixed tidal dissipation parameters (fixed-q or fixed-dt) have changed. Make any necessary updates.

property global_love_by_orderl: Dict[int, FloatArray]

Global complex Love number, k_l

property global_negative_imk_by_orderl: Dict[int, FloatArray]

Global negative of the imaginary portion of the Love number, -Im[k_l]

property max_tidal_order_lvl: int

Maximum tidal order to include in tidal calculations

model = 'base'
property moi

Outer-scope wrapper for world.moi

property multiply_modes_by_sign

Flag for if the tidal dissipation results should be multiplied by the mode’s sign.

This should always be True unless doing specific tests.

property obliquity

Outer-scope wrapper for world.obliquity

property obliquity_results: Dict[Tuple[int, int], InclinOutput]

Obliquity/Inclination function results (squared) stored by integers (m, p)

property orbit_set: bool

Flag to check if an Orbit Class has been initialized in the tide class host world.

orbit_spin_changed(eccentricity_change: bool = True, obliquity_change: bool = True, orbital_freq_changed: bool = True, spin_freq_changed: bool = True, force_obliquity_update: bool = False, call_world_frequency_changed: bool = True, call_collapse_modes: bool = True) → Tuple[UniqueFreqType, ResultsByFreqType][source]

Calculate tidal heating and potential derivative terms based on the current orbital state.

This will also calculate new unique tidal frequencies which must then be digested by the rheological model

at each planetary layer.

Parameters:

  • eccentricity_change (bool = True) – If there was no change in eccentricity (or if the orbit set the eccentricity) set this to False for a performance boost. If False, eccentricity functions won’t be called.

  • obliquity_change (bool = True) – If there was no change in obliquity set this to False for a performance boost. If False, obliquity functions won’t be called.

  • orbital_freq_changed (bool = True) – If there was no change in the orbital frequency set this to False for a performance boost.

  • spin_freq_changed (bool = True) – If there was no change in the spin frequency set this to False.

  • force_obliquity_update (bool = False) – If True, then this method will call the obliquity update function even if it would otherwise skip it due to obliquity dependence being turned off.

  • call_world_frequency_changed (bool = True) – If True, then the method will call the world’s complex compliance calculator. This flag is set to False for the CPL method.

  • call_collapse_modes (bool = True) – If True, then this method will call collapse modes (if needed).

Returns:

  • unique_tidal_frequencies (UniqueFreqType) – Each unique frequency stored as a signature (orbital motion and spin-rate coeffs), and the calculated frequency (combo of orbital motion and spin-rate) [rad s-1]

  • tidal_terms_by_frequency (ResultsByFreqType) – Results for tidal heating, dU/dM, dU/dw, dU/dO are stored in a tuple for each tidal harmonic l and unique frequency.

See also

TidalPy.tides.dissipation.mode_collapse

property orbital_frequency

Outer-scope wrapper for world.orbital_frequency

post_orbit_initialize()[source]

Initialize various tidal parameters once a tidal host is connected to the world (via an orbit class).

Raises:

AttributeNotSetError –

property radius

Outer-scope wrapper for world.radius

reinit(initial_init: bool = False)[source]

Load configurations into the Tides class and import any config-dependent functions.

This reinit process is separate from the __init__ method because the Orbit class may need to overload some

configurations after class initialization.

Parameters:

initial_init (bool = False) – This should be set to True the first time reinit is called.

Raises:
property semi_major_axis

Outer-scope wrapper for world.semi_major_axis

set_fixed_dt(fixed_dt: float, run_updates: bool = True)[source]

Set a new global tidal dissipation efficiency frequency scale ‘dt’ for the world

This is used in calculating tidal dissipation assuming a CTL model.

Parameters:

  • fixed_dt (float) – New dissipation efficiency frequency scale [s].

  • run_updates (bool = True) – If True, this method will call the update tides method.

set_fixed_q(fixed_q: float, run_updates: bool = True)[source]

Set a new global tidal dissipation efficiency or ‘fixed-Q’ for the world

This is used in calculating tidal dissipation assuming a CPL model.

Notes

Parameters:

  • fixed_q (float) – New dissipation efficiency.

  • run_updates (bool = True) – If True, this method will call the update tides method.

set_state(fixed_q: float = None, fixed_dt: float = None, run_updates: bool = True)[source]

Change the state of the Tides class

This is more efficient than calling the individual setters.

Parameters:

  • fixed_q (float (optional)) – New dissipation efficiency.

  • fixed_dt (float (optional)) – New dissipation efficiency frequency scale [s].

  • run_updates (bool = True) – If True, this method will call the update tides method.

property spin_frequency

Outer-scope wrapper for world.spin_frequency

property thermal_set: bool

Flag to check if a Thermal Class has been initialized in the tide class host world.

property tidal_heating_global: FloatArray

Global tidal heating rate [W]

property tidal_host

Outer-scope wrapper for world.orbit.tidal_host

property tidal_susceptibility: FloatArray

Tidal susceptibility [N m]

property tidal_susceptibility_reduced: FloatArray

Tidal susceptibility (reduced, no semi-major axis dependence) [N m7]

property tidal_terms_by_frequency: Dict[FreqSig, Dict[int, DissipTermsArray]]

Tidal terms stored by frequency signature

property unique_tidal_frequencies: Dict[FreqSig, FloatArray]

Unique tidal frequencies (abs(tidal modes)) stored by frequency signature

property use_obliquity_tides: bool

Flag for if obliquity tides should be calculated

Notes

  • Setting this to False leads to more efficient calculations than if the obliquity of a world is simply set to

zero.

world_config_key = 'tides'

TidalPy.tides.methods.global_approx module

Simple Global Approximation Tides Module

class TidalPy.tides.methods.global_approx.GlobalApproxTides[source]

Bases: TidesBase

Class used for non-layered planets (Gas Giants, Stars, Very simple homogeneous planets)

Tides class stores model parameters and methods for heating and torque which are functions of

(T, P, melt_frac, w, e, theata)

use_ctl
tidal_inputs
complex_love_by_unique_freq
ctl_calc_method()
ctl_calc_input_getter()

See also

TidalPy.tides.methods.TidesBase

clear_state()[source]

Clear the state for the global tides model

collapse_modes() → DissipTermsArray[source]

Calculate Global Love number based on current thermal state.

Requires a prior orbit_spin_changed() call as unique frequencies are used to calculate the complex compliances

used to calculate the Love numbers.

Returns:

  • tidal_heating (np.ndarray) – Tidal heating [W] This could potentially restricted to a layer or for an entire planet.

  • dUdM (np.ndarray) – Tidal potential derivative with respect to the mean anomaly [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

  • dUdw (np.ndarray) – Tidal potential derivative with respect to the pericentre [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

  • dUdO (np.ndarray) – Tidal potential derivative with respect to the planet’s node [J kg-1 radians-1] This could potentially restricted to a layer or for an entire planet.

See also

TidalPy.tides.Tides.orbit_spin_changed

property complex_love_by_unique_freq

-Im[k2] stored by unique frequency signature. Chooses between CPL and CTL

property ctl_calc_input_getter: Callable

Functions used to find the inputs for the ctl_calc_method

property ctl_calc_method: Callable

The method used to calculate the CTL method’s frequency dependence

fixed_q_dt_changed()[source]

The fixed tidal dissipation parameters (fixed-q or fixed-dt) have changed. Make any necessary updates.

model = 'global_approx'
orbit_spin_changed(eccentricity_change: bool = True, obliquity_change: bool = True, orbital_freq_changed: bool = True, spin_freq_changed: bool = True, force_obliquity_update: bool = False, call_world_frequency_changed: bool = True, call_collapse_modes: bool = True) → Tuple[UniqueFreqType, ResultsByFreqType][source]

Calculate tidal heating and potential derivative terms based on the current orbital state.

This will also calculate new unique tidal frequencies which must then be digested by the rheological model

at each planetary layer.

Parameters:

  • eccentricity_change (bool = True) – If there was no change in eccentricity (or if the orbit set the eccentricity) set this to False for a performance boost. If False, eccentricity functions won’t be called.

  • obliquity_change (bool = True) – If there was no change in obliquity set this to False for a performance boost. If False, obliquity functions won’t be called.

  • orbital_freq_changed (bool = True) – If there was no change in the orbital frequency set this to False for a performance boost.

  • spin_freq_changed (bool = True) – If there was no change in the spin frequency set this to False.

  • force_obliquity_update (bool = False) – If True, then this method will call the obliquity update function even if it would otherwise skip it due to obliquity dependence being turned off.

  • call_world_frequency_changed (bool = True) – If True, then the method will call the world’s complex compliance calculator. This flag is set to False for the CPL method.

  • call_collapse_modes (bool = True) – If True, then this method will call collapse modes (if needed).

Returns:

  • unique_tidal_frequencies (UniqueFreqType) – Each unique frequency stored as a signature (orbital motion and spin-rate coeffs), and the calculated frequency (combo of orbital motion and spin-rate) [rad s-1]

  • tidal_terms_by_frequency (ResultsByFreqType) – Results for tidal heating, dU/dM, dU/dw, dU/dO are stored in a tuple for each tidal harmonic l and unique frequency.

See also

TidalPy.tides.dissipation.mode_collapse

reinit(initial_init: bool = False)[source]

Load configurations into the Tides class and import any config-dependent functions.

This reinit process is separate from the __init__ method because the Orbit class may need to overload some

configurations after class initialization.

Parameters:

initial_init (bool = False) – This should be set to True the first time reinit is called.

Raises:
property tidal_inputs: Tuple[float, float, float, float]

The inputs required to calculate tides - these could change dynamically so they need to be pulled live

property use_ctl: bool

Flag set to True if the CTL method is being used (over the CPL method)

TidalPy.tides.methods.global_approx.cpl_neg_imk_helper_func(tidal_frequencies: Dict[FreqSig, FloatArray], fixed_k2: float, fixed_q: float) → Dict[FreqSig, ComplexArray][source]

Njit-safe helper function for calculating -Imk2 for CPL method.

Parameters:

  • tidal_frequencies (Dict[FreqSig, FloatArray]) – Njit-safe TypedDict of tidal frequencies.

  • fixed_k2 (float) – World’s static k2

  • fixed_q (float) – Fixed dissipation Q factor.

Returns:

neg_imk_by_unique_freq

Return type:

Dict[FreqSig, ComplexArray]

TidalPy.tides.methods.global_approx.ctl_neg_imk_helper_func(tidal_frequencies: Dict[FreqSig, FloatArray], fixed_k2: float, ctl_method: Callable, ctl_inputs: Tuple[float, ...]) → Dict[FreqSig, ComplexArray][source]

Njit-safe helper function for calculating -Imk2 for CTL method.

Parameters:

  • tidal_frequencies (Dict[FreqSig, FloatArray]) – Njit-safe TypedDict of tidal frequencies.

  • fixed_k2 (float) – World’s static k2

  • ctl_method (Callable) – Njit-safe CTL function

  • ctl_inputs (Tuple[float, ...]) – CTL inputs

Returns:

neg_imk_by_unique_freq

Return type:

Dict[FreqSig, ComplexArray]

TidalPy.tides.methods.layered module

Layered Tides Module

class TidalPy.tides.methods.layered.LayeredTides[source]

Bases: TidesBase

Class used for layered planets (icy or rocky world_types)

Tides class stores model parameters and methods for heating and torque which are functions of

(T, P, melt_frac, w, e, theata)

tidal_heating_by_layer
negative_imk_by_layer_by_orderl

See also

TidalPy.tides.methods.TidesBase

clear_state()[source]

Clear the state properties for the layered tides model

collapse_modes() → DissipTermsArray[source]

Calculate Global Love number based on current thermal state.

Requires a prior orbit_spin_changed() call as unique frequencies are used to calculate the complex compliances

used to calculate the Love numbers.

Returns:

  • tidal_heating (np.ndarray) – Tidal heating [W] This may be restricted to a specific layer or for an entire planet.

  • dUdM (np.ndarray) – Tidal potential derivative with respect to the mean anomaly [J kg-1 radians-1] This may be restricted to a specific layer or for an entire planet.

  • dUdw (np.ndarray) – Tidal potential derivative with respect to the pericentre [J kg-1 radians-1] This may be restricted to a specific layer or for an entire planet.

  • dUdO (np.ndarray) – Tidal potential derivative with respect to the planet’s node [J kg-1 radians-1] This may be restricted to a specific layer or for an entire planet.

Raises:

MissingAttributeError –

See also

TidalPy.tides.Tides.orbit_spin_changed

complex_compliances_changed(collapse_tidal_modes: bool = True)[source]

The complex compliances have changed. Make any necessary updates.

Parameters:

collapse_tidal_modes (bool = True) – If True, then the world will tell its tides model to collapse tidal modes.

model = 'layered'
property negative_imk_by_layer_by_orderl: Dict[PhysicalLayerType, List[FloatArray]]

-Im[k2] stored by layer instance and by order l

reinit(initial_init: bool = False)[source]

Load configurations into the Tides class and import any config-dependent functions.

This reinit process is separate from the __init__ method because the Orbit class may need to overload some

configurations after class initialization.

Parameters:

initial_init (bool = False) – This should be set to True the first time reinit is called.

Raises:

BadAttributeValueError –

property tidal_heating_by_layer: Dict[PhysicalLayerType, FloatArray]

Tidal heating stored by layer instance [W]