TidalPy.toolbox package

Submodules

TidalPy.toolbox.quick_tides module

quick_tides.py module.

Purpose

The primary purpose of this module is to quickly and easily provide the user with tidal dissipation calculation

functions (heating and orbit-spin derivatives) for homogeneous worlds without requiring the user to manually pull together several different TidalPy functions.

Limitations

These functions may have an impact to performance and certainly to flexibility. For example, there are various

checks performed in each that a user may want to skip. It is recommended to only use this function as a starting point and then develop a custom function or script to suite your specific needs.

These are intended to be used for homogeneous worlds with one layer. Dissipation for multi-layer worlds can be done

with TidalPy’s OOP approach or a custom script.

TidalPy.toolbox.quick_tides.dual_dissipation_from_dict_or_world_instance(host: dict | all_tidal_world_types, secondary: dict | all_tidal_world_types, viscosities: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, shear_moduli: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, rheologies: str | Tuple[str, str] = 'Maxwell', complex_compliance_inputs: NoneType | Tuple[Tuple[float, ...], Tuple[float, ...]] = None, obliquities: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, spin_frequencies: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, spin_periods: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, tidal_scales: Tuple[float, float] = (1.0, 1.0), fixed_k2s: Tuple[float, float] = (0.3, 0.3), fixed_qs: Tuple[float, float] = (100.0, 100.0), fixed_dts: Tuple[NoneType | float, NoneType | float] = (None, None), eccentricity: NoneType | FloatArray = None, orbital_frequency: NoneType | FloatArray = None, orbital_period: NoneType | FloatArray = None, max_tidal_order_l: NoneType | int = 2, eccentricity_truncation_lvl: NoneType | int = 2, use_obliquity: bool | NoneType = True, da_dt_scale: float = 1.0, de_dt_scale: float = 1.0, dspin_dt_scale: float = 1.0) → Dict[str, FloatArray | Dict[str, FloatArray | Dict[int, ComplexArray | FloatArray]]]

By providing a dictionaries or TidalPy world objects, this function will pull out the necessary

planetary parameters and calculate the single body tidal dissipation. It is assumed that both the host and the secondary participate in tidal dissipation.

Parameters:

• host (Union[dict, 'all_tidal_world_types'])

• secondary (Union[dict, 'all_tidal_world_types'])

• viscosities (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• shear_moduli (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• rheologies (Union[str, Tuple[str, str]] = 'Maxwell')

• complex_compliance_inputs (Union[NoneType, Tuple[Tuple[float, ...], Tuple[float, ...]]] = None)

• obliquities (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• spin_frequencies (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• spin_periods (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• tidal_scales (Tuple[float, float] = (1., 1.))

• fixed_k2s (Tuple[float, float] = (0.3, 0.3))

• fixed_qs (Tuple[float, float] = (100., 100.))

• fixed_dts (Tuple[NoneFloat, NoneFloat] = (None, None))

• eccentricity (NoneFloatArray = None)

• orbital_frequency (NoneFloatArray = None)

• orbital_period (NoneFloatArray = None)

• max_tidal_order_l (NoneInt = 2)

• eccentricity_truncation_lvl (NoneInt = 2)

• use_obliquity (Union[bool, NoneType] = True)

• da_dt_scale (float = 1.)

• de_dt_scale (float = 1.)

• dspin_dt_scale (float = 1.)

Returns:

dissipation_results – A dictionary of the dissipation results for both the host and secondary tidal world.

Return type:

Dict[str, Union[FloatArray, SingleBodyResultType]]

TidalPy.toolbox.quick_tides.quick_dual_body_tidal_dissipation(radii: Tuple[float, float], masses: Tuple[float, float], gravities: Tuple[float, float], densities: Tuple[float, float], mois: Tuple[float, float], viscosities: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, shear_moduli: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, rheologies: str | Tuple[str, str] = 'Maxwell', complex_compliance_inputs: NoneType | Tuple[Tuple[float, ...], Tuple[float, ...]] = None, obliquities: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, spin_frequencies: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, spin_periods: NoneType | Tuple[NoneType | FloatArray, NoneType | FloatArray] = None, tidal_scales: Tuple[float, float] = (1.0, 1.0), fixed_k2s: Tuple[float, float] = (0.3, 0.3), fixed_qs: Tuple[float, float] = (100.0, 100.0), fixed_dts: Tuple[NoneType | float, NoneType | float] = (None, None), eccentricity: NoneType | FloatArray = None, orbital_frequency: NoneType | FloatArray = None, orbital_period: NoneType | FloatArray = None, max_tidal_order_l: NoneType | int = 2, eccentricity_truncation_lvl: NoneType | int = 2, use_obliquity: bool | NoneType = True, da_dt_scale: float = 1.0, de_dt_scale: float = 1.0, dspin_dt_scale: float = 1.0) → Dict[str, FloatArray | Dict[str, FloatArray | Dict[int, ComplexArray | FloatArray]]]

Calculate the dual-body tidal dissipation for a target world orbiting its tidal host.

This function pulls together several TidalPy packages to offer an easy to use interface to calculate tidal

dissipation. However it may come with an impact to performance and flexibility. For example, there are various checks performed that may want to skip. It is recommended to only use this function as a starting point and then develop a custom function or script to suite your specific needs.

Parameters:

• radii (Tuple[float, float])

• masses (Tuple[float, float])

• gravities (Tuple[float, float])

• densities (Tuple[float, float])

• mois (Tuple[float, float])

• viscosities (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• shear_moduli (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• rheologies (Union[str, Tuple[str, str]] = 'Maxwell')

• complex_compliance_inputs (Union[NoneType, Tuple[Tuple[float, ...], Tuple[float, ...]]] = None)

• obliquities (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• spin_frequencies (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• spin_periods (Union[NoneType, Tuple[NoneFloatArray, NoneFloatArray]] = None)

• tidal_scales (Tuple[float, float] = (1., 1.))

• fixed_k2s (Tuple[float, float] = (.3, .3))

• fixed_qs (Tuple[float, float] = (100., 100.))

• fixed_dts (Tuple[NoneFloat, NoneFloat] = (None, None)) – If any are None, a fixed_dt will be calculated as 1 / (Q * n)

• eccentricity (NoneFloatArray = None)

• orbital_frequency (NoneFloatArray = None)

• orbital_period (NoneFloatArray = None)

• max_tidal_order_l (NoneInt = 2)

• eccentricity_truncation_lvl (NoneInt = 2)

• use_obliquity (Union[bool, NoneType] = True)

• da_dt_scale (float = 1.)

• de_dt_scale (float = 1.)

• dspin_dt_scale (float = 1.)

Returns:

dissipation_results – Tidal dissipation results stored for both the host and secondary.

Return type:

Dict[str, Union[FloatArray, SingleBodyResultType]]

TidalPy.toolbox.quick_tides.quick_tidal_dissipation(host_mass: float, target_radius: float, target_mass: float, target_gravity: float, target_density: float, target_moi: float, viscosity: FloatArray = None, shear_modulus: FloatArray = None, rheology: str = 'Maxwell', complex_compliance_inputs: Tuple[float, ...] = None, eccentricity: FloatArray = None, obliquity: FloatArray = None, orbital_frequency: FloatArray = None, orbital_period: FloatArray = None, spin_frequency: FloatArray = None, spin_period: FloatArray = None, max_tidal_order_l: int | NoneType = 2, eccentricity_truncation_lvl: int | NoneType = 2, use_obliquity: bool | NoneType = True, tidal_scale: float = 1.0, fixed_k2: float = 0.3, fixed_q: float = 100.0, fixed_dt: float = None, dspin_dt_scale: float = 1.0, de_dt_scale: float = 1.0, da_dt_scale: float = 1.0, precalculated_mode_results: dict = None, calculate_orbit_spin_derivatives: bool = False) → Dict[str, FloatArray | Dict[int, ComplexArray | FloatArray]]

Calculate the single body tidal dissipation for a target world orbiting its tidal host.

Assumes the host’s dissipation is zero (no contribution to the orbital evolution derivatives).

This function pulls together several TidalPy packages to offer an easy to use interface to calculate tidal

dissipation. However it may come with an impact to performance and flexibility. For example, there are various checks performed that may want to skip. It is recommended to only use this function as a starting point and then develop a custom function or script to suite your specific needs.

Parameters:

• host_mass (float)

• target_radius (float)

• target_mass (float)

• target_gravity (float)

• target_density (float)

• target_moi (float)

• viscosity (FloatArray)

• shear_modulus (FloatArray)

• rheology (str)

• complex_compliance_inputs (Tuple[float, ...])

• eccentricity (FloatArray)

• obliquity (FloatArray)

• orbital_frequency (FloatArray)

• orbital_period (FloatArray)

• spin_frequency (FloatArray)

• spin_period (FloatArray)

• max_tidal_order_l (int = 2)

• eccentricity_truncation_lvl (int = 2,)

• use_obliquity (bool = True)

• tidal_scale (float = 1.)

• fixed_k2 (float = 0.3)

• fixed_q (float = 100.)

• fixed_dt (float = None) – If None, a fixed_dt will be calculated as 1 / (Q * n)

• dspin_dt_scale (float = 1.)

• de_dt_scale (float = 1.)

• da_dt_scale (float = 1.)

• precalculated_mode_results (dict = None) – Several things can be pre-calculated to save on performance if doing, for example, dual body analysis

• calculate_orbit_spin_derivatives (bool = False) –

  If True, then the function will calculate the spin and orbital derivatives assuming the

  host is non-dissipative.

Returns:

dissipation_results – Dissipation results for the target world ‘tidal_heating’: FloatArray, ‘dUdM’: FloatArray, ‘dUdw’: FloatArray, ‘dUdO’: FloatArray, ‘love_number_by_orderl’: List[ComplexArray], ‘negative_imk_by_orderl’: List[FloatArray], ‘effective_q_by_orderl’: List[FloatArray]

Return type:

dict

TidalPy.toolbox.quick_tides.single_dissipation_from_dict_or_world_instance(host: dict | all_tidal_world_types, secondary: dict | all_tidal_world_types, viscosity: NoneType | FloatArray = None, shear_modulus: NoneType | FloatArray = None, rheology: str = 'Maxwell', complex_compliance_inputs: NoneType | Tuple[float, ...] = None, eccentricity: NoneType | FloatArray = None, obliquity: NoneType | FloatArray = None, orbital_frequency: NoneType | FloatArray = None, orbital_period: NoneType | FloatArray = None, spin_frequency: NoneType | FloatArray = None, spin_period: NoneType | FloatArray = None, max_tidal_order_l: NoneType | int = 2, eccentricity_truncation_lvl: NoneType | int = 2, use_obliquity: bool | NoneType = True, tidal_scale: float = 1.0, fixed_k2: float = 0.3, fixed_q: float = 100.0, fixed_dt: float = None, da_dt_scale: float = 1.0, de_dt_scale: float = 1.0, dspin_dt_scale: float = 1.0) → Dict[str, FloatArray | Dict[int, ComplexArray | FloatArray]]

By providing a dictionaries or TidalPy world objects, this function will pull out the necessary

planetary parameters and calculate the single body tidal dissipation. It is assumed that the host world does not participate in the tidal dissipation.

Parameters:

• host (Union[dict, 'all_tidal_world_types'])

• secondary (Union[dict, 'all_tidal_world_types'])

• viscosity (NoneFloatArray = None)

• shear_modulus (NoneFloatArray = None)

• rheology (str = 'Maxwell')

• complex_compliance_inputs (Union[NoneType, Tuple[float, ...]] = None)

• eccentricity (NoneFloatArray = None)

• obliquity (NoneFloatArray = None)

• orbital_frequency (NoneFloatArray = None)

• orbital_period (NoneFloatArray = None)

• spin_frequency (NoneFloatArray = None)

• spin_period (NoneFloatArray = None)

• max_tidal_order_l (NoneInt = 2)

• eccentricity_truncation_lvl (NoneInt = 2)

• use_obliquity (Union[bool, NoneType] = True)

• tidal_scale (float = 1.)

• fixed_k2 (float = 0.3)

• fixed_q (float = 100.)

• fixed_dt (float = None)

• da_dt_scale (float = 1.)

• de_dt_scale (float = 1.)

• dspin_dt_scale (float = 1.)

Returns:

dissipation_results – Tidal dissipation results for single body dissipation.

Return type:

SingleBodyResultType