TidalPy.tides.modes package

Subpackages

TidalPy.tides.modes.mode_calc_helper package

Submodules

TidalPy.tides.modes.collapse_modes module

Function to collapse tidal mode frequency dictionary

TidalPy.tides.modes.collapse_modes.collapse_modes(tidal_modes: Dict[str, float], unique_frequencies: bool = False) → Dict[str, Tuple[float, int, str]][source]

Takes a (numba) dictionary of tidal modes and returns a dictionary of unique modes or frequencies

Parameters:

tidal_modes (Dict[str, float]) –
Dictionary of tidal modes stored like {‘n-o’: 0.005} where the number is in rad s-1. If numba is being used then this must be passed as a numba TypedDict of the form:

Dict.empty(
key_type=types.unicode_type, value_type=types.float64,

)
unique_frequencies (bool = False) – If True, then the absolute value of the mode will be used instead of the mode itself for comparison.

Returns:

collapsed_modes –

Dictionary of collapsed modes (or frequencies). Along with the value, the number of instances it appeared,: and a string of which modes were not unique is also provided.
Example:: { ‘2n’ : (0.005, 1, ‘’), # Mode was unique. ‘n-o’: (0.110, 3, ‘2n-2o, 3n-3o’) # Two other modes were found to have a similar value. }

Return type:

Dict[str, Tuple[float, int, str]]

TidalPy.tides.modes.mode_manipulation module

TidalPy.tides.modes.mode_manipulation.calculate_terms(spin_frequency: FloatArray, orbital_frequency: FloatArray, semi_major_axis: FloatArray, radius: float, eccentricity_results_byorderl: Dict[int, EccenOutput], obliquity_results_byorderl: Dict[int, InclinOutput], multiply_modes_by_sign: bool = True) → Tuple[Dict[Tuple[int, int], FloatArray], Dict[Tuple[int, int], Dict[int, Tuple[FloatArray, FloatArray, FloatArray, FloatArray]]]][source]

Calculate tidal dissipation terms and frequencies based on the current orbital and spin state.

Requires the user to provide the correct eccentricity and inclination functions. This is generally done by the tides.calculate_terms wrapper.

Parameters:

orbital_frequency (FloatArray) – Orbit’s orbital frequency around tidal host [rad s-1]
spin_frequency (FloatArray) – World’s rotation frequency [rad s-1]
semi_major_axis (FloatArray) – Orbital separation [m]
radius (float) – Planet’s radius (used to calculate R/a) [m]
eccentricity_results_byorderl (Dict[int, EccenOutput]) – Pre-calculated eccentricity results using the .mode_calc_helper functions Stored as a numba-safe dict of order-l: eccen_result.
obliquity_results_byorderl (Dict[int, EccenOutput]) – Pre-calculated obliquity results using the .mode_calc_helper functions Stored as a numba-safe dict of order-l: obliquity_result.
multiply_modes_by_sign (bool = True) –

If True, then the tidal coefficients will be multiplied by the mode’s sign. This should be true for a
regular rheology, but the fixed-Q model sometimes may have some modes carry their sign and others not.

This flag is for testing purposes.

Returns:

unique_frequencies (UniqueFreqType) – Unique frequency signature and calculate frequency [rad s-1] Frequencies are integer combinations of orbital motion and spin-rate.
results_by_frequency (ResultsByFreqType) – Tidal dissipation terms stored for each unique frequency and tidal harmonic order-l. At each frequency dissipation terms are stored as:

heating_term, dUdM_term, dUdw_term, dUdO_term These still need to be multiplied by the -Im[k_l] and tidal susceptibility.

See also

TidalPy.tides.dissipation.collapse_modes

TidalPy.tides.modes.mode_manipulation.collapse_modes(gravity: float, radius: float, density: float, shear_modulus: NoneType | FloatArray, tidal_scale: float, tidal_host_mass: float, tidal_susceptibility: FloatArray, complex_compliance_by_frequency: Dict[Tuple[int, int], ComplexArray], tidal_terms_by_frequency: Dict[Tuple[int, int], Dict[int, Tuple[FloatArray, FloatArray, FloatArray, FloatArray]]], max_order_l: int, cpl_ctl_method: bool = False) → Tuple[FloatArray, FloatArray, FloatArray, FloatArray, Dict[int, ComplexArray], Dict[int, FloatArray], Dict[int, FloatArray]][source]

Collapses the tidal terms calculated by calculate_terms() combined with rheological information from the layer.

Parameters:

gravity (float) – Acceleration due to gravity at the surface of the layer or planet [m s-2]
radius (float) – Surface radius of the layer or planet [m]
density (float) – Bulk density of the layer or planet [kg m-3]
shear_modulus (FloatArray) – Effective shear modulus of the layer or planet [Pa]
tidal_scale (float) –

Multiplier that ranges from 0 to 1 that scales the imaginary portion of the complex love number to simulate
only a portion of a planet’s volume is contributing to the tidal dissipation.
tidal_host_mass (float) – Mass of the tidal host [kg] Needed to offset the tidal susceptibility for the potential derivatives.
tidal_susceptibility (FloatArray) – Tidal susceptibility, defined as (3/2) G M_host^2 R_target^5 / a^6 [N m]
complex_compliance_by_frequency (Dict[FreqSig, ComplexArray]) – The complex compliance for the layer or planet calculated at each unique tidal frequency [Pa-1]
tidal_terms_by_frequency (Dict[FreqSig, Dict[int, DissipTerms]]) – Each dissipation term: E^dot, dUdM, dUdw, dUdO; calculated for each unique tidal frequency and order-l
max_order_l (int) – Max tidal order level.
cpl_ctl_method (bool = False) – Changes functionality based on if the method is ctl cpl or neither See tides.GlobalApproxTides.mode_collapse

Returns:

tidal_heating (FloatArray) – Tidal heating [W] This could potentially restricted to a layer or for an entire planet.
dUdM (FloatArray) – 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 (FloatArray) – 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 (FloatArray) – 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.
love_number_by_orderl (Dict[int, ComplexArray]) – The complex Love number [unitless] stored by tidal order l (minus 2). This could potentially restricted to a layer or for an entire planet.
negative_imk_by_orderl (Dict[int, FloatArray]) –

The negative of the imaginary part of the complex Love number, scaled by the planet’s tidal scale.
Stored by tidal order l (minus 2).

This could potentially restricted to a layer or for an entire planet.
effective_q_by_orderl (Dict[int, FloatArray]) – The effective dissipation factor for the world, stored by tidal order l.

TidalPy.tides.modes.modes module

TidalPy.tides.modes.modes.find_unique_frequency_dict(tidal_modes: Dict[str, float]) → Dict[str, float][source]

Returns a list of unique frequencies based on a dictionary of modes.

Frequencies are found by taking the absolute value of tidal modes. Modes that are zero are not stored in the final unique frequency list.

Parameters:

tidal_modes (Dict[str, float]) – Dictionary of modes stored as mode signature (str): mode (float) [rad s-1]

Returns:

unique_frequency_dict (Dict[str, float]) – Dictionary of unique frequencies stored as mode signature (str): mode (float) [rad s-1] There could be multiple mode signatures (stored as a single, space-delineated string) for one unique frequency.
unique_frequency_list (Dict[str, float]) – List of unique frequencies stored as mode signature (str): mode (float) [rad s-1]

TidalPy.tides.modes.modes.find_unique_frequency_list(tidal_modes: Dict[str, float]) → Tuple[List[float], List[int]][source]

Returns a list of unique frequencies based on a dictionary of modes.

Frequencies are found by taking the absolute value of tidal modes. Modes that are zero are not stored in the final unique frequency list.

Parameters:

tidal_modes (Dict[str, float]) – Dictionary of modes stored as mode signature (str): mode (float) [rad s-1]

Returns:

unique_frequency_list (List[float]) – List of unique frequencies stored as mode signature (str): mode (float) [rad s-1]
unique_frequency_count_list (List[int]) – List of counts for each frequency. If a frequency is fully unique it will have a count of 1. If there are multiple modes with the same frequency then the count will indicate how many.

TidalPy.tides.modes.multilayer_modes module

Multilayer calculator for multiple tidal modes.

Each tidal mode imparts a potentially different frequency which needs to be propagated throughout the planet’s interior.

This module contains functions to assist with calculating the response at each of these frequencies and then collapse: the findings into a final value.

TidalPy.tides.modes.multilayer_modes.calculate_mode_response_coupled(mode_frequency: float, radius_array: ndarray, density_array: ndarray, shear_array: ndarray, bulk_array: ndarray, shear_viscosity_array: ndarray, bulk_viscosity_array: ndarray, upper_radius_bylayer_array: ndarray, longitude_domain: ndarray, colatitude_domain: ndarray, time_domain: ndarray, tidal_potential_tuple: TidalPotentialOutput, shear_rheology_inst_bylayer: Tuple[RheologyModelBase], bulk_rheology_inst_bylayer: Tuple[RheologyModelBase], layer_indices: Tuple[float], layer_types: Tuple[str], is_static_bylayer: Tuple[bool], is_incompressible_bylayer: Tuple[bool], solve_load_numbers: bool = False, force_mode_calculation: bool = False, degree_l: int = 2, use_kamata: bool = False, integration_method: str = 'DOP853', integration_rtol: float = 1e-06, integration_atol: float = 1e-10, verbose: bool = False, nondimensionalize: bool = True, planet_bulk_density: float = None)[source]

Given a tidal frequency, this function will call on the interior integration routine with the proper inputs and: collect the results as well as calculate tidal stress, strain, and heating as a function of radius, longitude, latitude, and time.

TODO: update input param docs

Returns:

mode_skipped (bool) – If True, then the mode’s frequency was close to zero so no propagation was calculated.
strains_at_mode (np.ndarray) – Tidal strains as a function of radius, longitude, colatitude, and time. [m m-1]
stresses_at_mode (np.ndarray) – Tidal stresses as a function of radius, longitude, colatitude, and time. [Pa]
complex_shears_at_mode (np.ndarray) – Complex shear modulus as a function of radius. [Pa]
tidal_y_at_mode (np.ndarray) – Viscoelastic-gravitational radial solutions as a function of radius.

TidalPy.tides.modes.multilayer_modes.collapse_multilayer_modes(orbital_frequency: float, spin_frequency: float, semi_major_axis: float, eccentricity: float, host_mass: float, planet_bulk_density: float, radius_array: ndarray, density_array: ndarray, bulk_array: ndarray, shear_array: ndarray, bulk_viscosity_array: ndarray, shear_viscosity_array: ndarray, shear_rheology_inst_bylayer: Tuple[RheologyModelBase], bulk_rheology_inst_bylayer: Tuple[RheologyModelBase], upper_radius_bylayer_array: ndarray, longitude_matrix: ndarray, colatitude_matrix: ndarray, time_matrix: ndarray, voxel_volume: ndarray, layer_types: tuple[str], is_static_bylayer: tuple[bool], is_incompressible_bylayer: tuple[bool], obliquity: float = None, use_general_obliquity: bool = False, solve_load_numbers: bool = False, force_mode_calculation: bool = False, degree_l: int = 2, use_modes: bool = True, use_static_potential: bool = False, use_simple_potential: bool = False, orbit_average_results: bool = True, use_kamata: bool = False, integration_method: str = 'DOP853', integration_rtol: float = 1e-06, integration_atol: float = 1e-08, verbose: bool = False, nondimensionalize: bool = True)[source]

Calculate the multilayer tidal response of a planet over a range of applicable tidal modes. Collapse individual modal results into final heating distribution.

Some of these variables are ndarrays the shape of the planet’s radius array, N_r Others are multidimensional arrays the shape of (N_long, N_colat, N_time). These multidim arrays MUST be in this order [longitude_domain, colatitude_domain, time_domain]

Parameters:

TODO (Update input parameter docs)

Returns:

heating (np.ndarray) – Heating within each voxel [W]. Shape: (N_r, N_long, N_colat) If orbit_average_results is false then the results will be given at each time with a new shape of:

(N_r, N_long, N_colat, N_time)
volumetric_heating (np.ndarray) – Volumetric Heating within each voxel [W]. Shape: (N_r, N_long, N_colat) If orbit_average_results is false then the results will be given at each time with a new shape of:

(N_r, N_long, N_colat, N_time)
volumetric_heating_by_mode (Dict[str, np.ndarray]) – Volumetric heating within each voxel broken up by each tidal mode [W]. Shape of each stored array: (N_r, N_long, N_colat) If orbit_average_results is false then the results will be given at each time with a new shape of:

(N_r, N_long, N_colat, N_time)
strains (np.ndarray) – Tidal strains within each voxel [m m-1]. Shape: (N_r, N_long, N_colat) If orbit_average_results is false then the results will be given at each time with a new shape of:

(N_r, N_long, N_colat, N_time)
stresses (np.ndarray) – Tidal stresses within each voxel [m m-1]. Shape: (N_r, N_long, N_colat) If orbit_average_results is false then the results will be given at each time with a new shape of:

(N_r, N_long, N_colat, N_time)