TidalPy.rheology.complex_compliance package

TidalPy.rheology.complex_compliance.get_complex_comp_model_default_inputs(layer_type: str)[source]

Submodules

TidalPy.rheology.complex_compliance.complex_compliance module

class TidalPy.rheology.complex_compliance.complex_compliance.ComplexCompliance[source]

Bases: LayerModelHolder

Complex compliance provides the functionality to calculate the complex compliance once provided a viscosity, shear

modulus, and forcing frequency. Different rheological models provide different functional forms of the complex compliance function.

See also

TidalPy.utilities.methods.model.LayerModelHolder, TidalPy.rheology.Rheology

property beta

Outer-scope wrapper for rheology.beta

clear_state()[source]

Clears the current state of the class without destroying data set by initialization.

property complex_compliances: Dict[FreqSig, ComplexArray]

Complex compliances stored as a dictionary for each unique frequency signature

property compliance

Outer-scope wrapper for rheology.unique_tidal_freqs

known_model_const_args = {'andrade': ('alpha', 'zeta'), 'andrade_freq': ('alpha', 'zeta', 'critical_freq', 'critical_freq_falloff'), 'burgers': ('voigt_compliance_offset', 'voigt_viscosity_offset'), 'elastic': (), 'fixed_q': (), 'maxwell': (), 'newton': (), 'off': (), 'sundberg': ('voigt_compliance_offset', 'voigt_viscosity_offset', 'alpha', 'zeta'), 'sundberg_freq': ('voigt_compliance_offset', 'voigt_viscosity_offset', 'alpha', 'zeta', 'critical_freq', 'critical_freq_falloff'), 'voigt': ('voigt_compliance_offset', 'voigt_viscosity_offset')}
known_model_live_args = {'andrade': ('self.compliance', 'self.viscosity'), 'andrade_freq': ('self.compliance', 'self.viscosity'), 'burgers': ('self.compliance', 'self.viscosity'), 'elastic': ('self.compliance', 'self.viscosity'), 'fixed_q': ('self.compliance', 'self.viscosity', 'self.beta', 'self.quality_factor'), 'maxwell': ('self.compliance', 'self.viscosity'), 'newton': ('self.compliance', 'self.viscosity'), 'off': ('self.compliance', 'self.viscosity'), 'sundberg': ('self.compliance', 'self.viscosity'), 'sundberg_freq': ('self.compliance', 'self.viscosity'), 'voigt': ('self.compliance', 'self.viscosity')}
known_models = {'andrade': CPUDispatcher(<function andrade>), 'andrade_freq': CPUDispatcher(<function andrade_freq>), 'burgers': CPUDispatcher(<function burgers>), 'elastic': CPUDispatcher(<function elastic>), 'fixed_q': CPUDispatcher(<function fixed_q>), 'maxwell': CPUDispatcher(<function maxwell>), 'newton': CPUDispatcher(<function newton>), 'off': CPUDispatcher(<function off>), 'sundberg': CPUDispatcher(<function sundberg>), 'sundberg_freq': CPUDispatcher(<function sundberg_freq>), 'voigt': CPUDispatcher(<function voigt>)}
model_config_key = 'rheology'
property quality_factor

Outer-scope wrapper for rheology.quality_factor

reinit(initial_init: bool = False)[source]

Reinit method for the ComplexCompliance class

Model will look at the user-provided configurations and pull out model information including constants

Parameters:

initial_init (bool = False) –

Must be set to True if this is the first time this method has been called (additional steps may be

preformed during the first reinit call).

property rheology_class: Rheology

The rheology class instance where the complex compliance model is stored

property tidal_freqs

Outer-scope wrapper for rheology.unique_tidal_freqs

property viscosity

Outer-scope wrapper for rheology.viscosity

TidalPy.rheology.complex_compliance.complex_compliance.compliance_dict_helper(tidal_frequencies: Dict[FreqSig, FloatArray], compliance_func: Callable, live_inputs: Tuple[FloatArray, ...], inputs: Tuple[float, ...])[source]

Njit-safe Complex compliance calculator helper - Array version

Parameters:

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

  • compliance_func (Callable) – Complex compliance function.

  • live_inputs (Tuple[FloatArray, ...]) – Live inputs to the complex compliance function.

  • inputs (Tuple[float, ...]) – Static inputs to the complex compliance function.

Returns:

complex_compliance_by_tidal_freq

Return type:

Dict[FreqSig, ComplexArray]

TidalPy.rheology.complex_compliance.compliance_models module

Complex Compliance Functions

This module provides functions to calculate the complex compliance for various rheological models. The complex compliance is the inverse of the complex shear modulus and is used to estimate tidal dissipation. It depends on the static (non-complex) shear modulus, viscosity, forcing frequency, and other material properties — some of which may depend upon temperature, melt-fraction, etc. The functional form of this dependence is determined by the material’s rheology.

Notes

How To Implement a new complex compliance (rheology) model:

  • Make a new function here with a function doc-string that follows the format of the other pre-built complex compliance functions found here.

    • All complex compliance functions require at least three arguments: frequency, compliance (non-complex), viscosity. These must be the first arguments and kept in this order.

    • Additional arguments can be supplied by adding them after these required arguments but they must be included in the function’s doc-string using either (or both) the “!TPY_args live:” or “!TPY_args const:” prefix. The arguments should be listed in the doc-string in the same order they are in the argument field.

  • Any new arguments that are simple constants can then be added to the rheology section of a planet’s layer configuration. These should have a “!TPY_args const:” prefix. Non-constants require “!TPY_args live:” prefix.

  • You will also need to make a function that works with arrays. If the above function works fine with both floats and arrays then you don’t need to do anything. Otherwise you should make a float safe version called “name” and an array safe one called “name_array”

References

Rheologies and the relationship between stress and strain have had literally hundreds of years of study. However, the following references provide a good starting point for the currently implemented rheologies in TidalPy in the context of tides.

  • Henning, O’Connell, and Sasselov (2009), ApJ, DOI: 10.1088/0004-637X/707/2/1000

    • Background information on the Maxwell, Voigt-Kelvin, and Burgers rheologies.

  • Efroimsky (2012), ApJ, DOI: 10.1088/0004-637X/746/2/150

    • Details on how complex compliances are related to global Love numbers.

  • Renaud and Henning (2018), ApJ, DOI: 10.3847/1538-4357/aab784

    • Background information on the Andrade and Sundberg-Cooper rheologies.

TidalPy.rheology.complex_compliance.compliance_models.andrade(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, alpha: float = 0.3, zeta: float = 1.0) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Andrade

!TPY_args live: self.compliance, self.viscosity !TPY_args const: alpha, zeta

Notes

The Andrade rheology is partially constructed from the Maxwell rheology. This is further modified by a term that, in the time-domain, is proportional to t^{lpha}. In the Fourier domain this translates to a frequency dependence ~omega^{-lpha}. This model was originally developed for the stress-strain relationship in metals, but has been found to model planetary materials as well.

This version of the model will not transition into a Maxwell-like rheology at very low frequencies.

References

  • Gribb and Cooper (1998), JGR, DOI: 10.1029/98JB02786

  • Efroimsky (2012), ApJ, DOI: 10.1088/0004-637X/746/2/150

  • Renaud and Henning (2018), ApJ, DOI: 10.3847/1538-4357/aab784

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • alpha (float) – Andrade exponent parameter

  • zeta (float) – Andrade timescale parameter

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.andrade_freq(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, alpha: float = 0.3, zeta: float = 1.0, critical_freq: float = 7.27221e-07, critical_freq_falloff: float = 30) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Andrade with a frequency-dependent zeta

!TPY_args live: self.compliance, self.viscosity !TPY_args const: alpha, zeta, critical_freq, critical_freq_falloff

Notes

The Andrade rheology is partially constructed from the Maxwell rheology. This is further modified by a term that, in the time-domain, is proportional to t^{lpha}. In the Fourier domain this translates to a frequency dependence ~omega^{-lpha}. This model was originally developed for the stress-strain relationship in metals, but has been found to model planetary materials as well.

This version of the model will transition into a Maxwell-like rheology at very low frequencies.

References

  • Karato and Spetzler (1990), RGeo, DOI: 10.1029/RG028i004p00399

  • Gribb and Cooper (1998), JGR, DOI: 10.1029/98JB02786

  • Efroimsky (2012), ApJ, DOI: 10.1088/0004-637X/746/2/150

  • Renaud and Henning (2018), ApJ, DOI: 10.3847/1538-4357/aab784

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • alpha (float) – Andrade exponent parameter

  • zeta (float) – Andrade timescale parameter equal to the Andrade characteristic timescale / Maxwell

  • critical_freq (float = 7.27221e-7) – For forcing frequencies smaller than the critical frequency, the Andrade component converges to the Maxwell component [rads s-1]. Default is 2 * pi / 100 days.

  • critical_freq_falloff (float = 30) – Determines how quickly the Andrade rheology turns to Maxwell falls off after dropping below the critical freq.

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.burgers(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, voigt_compliance_offset: float = 0.2, voigt_viscosity_offset: float = 0.02) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Burgers

!TPY_args live: self.compliance, self.viscosity !TPY_args const: voigt_compliance_offset, voigt_viscosity_offset

Notes

The Burgers rheology exhibits a secondary peak in the dissipation vs. frequency domain. This peak describes a secondary dissipation mechanism that is dominant at this forcing frequency (grain boundary sliding, dislocation diffusion, etc.). It can be constructed by a linear summation of the Voigt-Kelvin and Maxwell rheologies.

References

  • Henning, O’Connell, and Sasselov (2009), ApJ, DOI: 10.1088/0004-637X/707/2/1000

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • voigt_compliance_offset (float) – Voigt component’s compliance offset eta_voigt = voigt_compliance_offset * compliance

  • voigt_viscosity_offset (float) – Voigt component’s viscosity offset eta_voigt = voigt_viscosity_offset * viscosity

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.elastic(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Elastic

!TPY_args live: self.compliance, self.viscosity

Notes

References

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.fixed_q(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, planet_beta: float = 344300000000.0, quality_factor: float = 10.0) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Fixed-Q

!TPY_args live: self.compliance, self.viscosity, self.beta, self.quality_factor

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • planet_beta (FloatArray) – Planet or Layer: Radius * Density * Gravity Accl. [kg m-1 s-2]

  • quality_factor (FloatArray) – Planet or Layer’s Quality factor (k_2 / Q)

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.maxwell(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Maxwell

!TPY_args live: self.compliance, self.viscosity

Notes

The Maxwell rheology has been the traditional model used to estimate tidal dissipation in planets and moons. It has a characteristic peak in dissipation vs. forcing frequency. However, it has been shown that it underestimates dissipation at high frequencies.

References

  • Henning, O’Connell, and Sasselov (2009), ApJ, DOI: 10.1088/0004-637X/707/2/1000

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.newton(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Newton

!TPY_args live: self.compliance, self.viscosity

Notes

References

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.off(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Off

!TPY_args live: self.compliance, self.viscosity

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.sundberg(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, voigt_compliance_offset: float = 0.2, voigt_viscosity_offset: float = 0.02, alpha: float = 0.3, zeta: float = 1.0) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Sundberg-Cooper

!TPY_args live: self.compliance, self.viscosity !TPY_args const: voigt_compliance_offset, voigt_viscosity_offset, alpha, zeta

Notes

The Sundberg-Cooper rheology is a linear sum of the Andrade and Burgers rheologies. However, even though its Parameters share the same symbol and names, they may differ from those used for either of its composite model.

This version of the model will not transition into a Burgers-like rheology at very low frequencies.

References

  • Sundberg and Cooper (2010), Philo. Mag., DOI: 10.1080/14786431003746656

  • Renaud and Henning (2018), ApJ, DOI: 10.3847/1538-4357/aab784

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • voigt_compliance_offset (float) – Voigt component’s compliance offset eta_voigt = voigt_compliance_offset * compliance

  • voigt_viscosity_offset (float) – Voigt component’s viscosity offset eta_voigt = voigt_viscosity_offset * viscosity

  • alpha (float) – Andrade exponent parameter

  • zeta (float) – Andrade timescale parameter

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.sundberg_freq(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, voigt_compliance_offset: float = 0.2, voigt_viscosity_offset: float = 0.02, alpha: float = 0.3, zeta: float = 1.0, critical_freq: float = 7.27221e-07, critical_freq_falloff: float = 30) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Sundberg-Cooper with a frequency-dependent zeta

!TPY_args live: self.compliance, self.viscosity !TPY_args const: voigt_compliance_offset, voigt_viscosity_offset, alpha, zeta, critical_freq, critical_freq_falloff

Notes

The Sundberg-Cooper rheology is a linear sum of the Andrade and Burgers rheologies. However, even though its Parameters share the same symbol and names, they may differ from those used for either of its composite model.

This version of the model will transition into a Burgers-like rheology at very low frequencies.

References

  • Karato and Spetzler (1990), RGeo, DOI: 10.1029/RG028i004p00399

  • Sundberg and Cooper (2010), Philo. Mag., DOI: 10.1080/14786431003746656

  • Renaud and Henning (2018), ApJ, DOI: 10.3847/1538-4357/aab784

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • voigt_compliance_offset (float) – Voigt component’s compliance offset eta_voigt = voigt_compliance_offset * compliance

  • voigt_viscosity_offset (float) – Voigt component’s viscosity offset eta_voigt = voigt_viscosity_offset * viscosity

  • alpha (float) – Andrade exponent parameter

  • zeta (float) – Andrade timescale parameter equal to the Andrade characteristic timescale / Maxwell

  • critical_freq (float = 7.27221e-7) – For forcing frequencies smaller than the critical frequency, the Andrade component converges to the Maxwell component [rads s-1]. Default is 2 * pi / 100 days.

  • critical_freq_falloff (float = 30) – Determines how quickly the Andrade rheology turns to Maxwell falls off after dropping below the critical freq.

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray

TidalPy.rheology.complex_compliance.compliance_models.voigt(frequency: float | float64 | ndarray, compliance: float | float64 | ndarray, viscosity: float | float64 | ndarray, voigt_compliance_offset: float = 0.2, voigt_viscosity_offset: float = 0.02) → complex | complex128 | ndarray[source]

Calculates the complex compliance utilizing the model: Voigt-Kelvin

!TPY_args live: self.compliance, self.viscosity !TPY_args const: voigt_compliance_offset, voigt_viscosity_offset

Notes

The Voigt-Kelvin rheology is a non-realistic (except for very specific circumstances) that is generally more useful when comparing or building other models. It is characterized by an ‘island’ of dissipation in the shear modulus vs. viscosity phase space.

References

  • Henning, O’Connell, and Sasselov (2009), ApJ, DOI: 10.1088/0004-637X/707/2/1000

Parameters:

  • frequency (FloatArray) – Tidal forcing frequency [rads s-1] Note that a world may experience multiple tidal frequencies for NSR tides, if the eccentricity or obliquity is large, or for a tidal harmonic integer l > 2.

  • compliance (FloatArray) – Layer or Planet’s compliance (inverse of shear modulus) [Pa-1]

  • viscosity (FloatArray) – Layer or Planet’s effective viscosity [Pa s]

  • voigt_compliance_offset (float) – Voigt component’s compliance offset eta_voigt = voigt_compliance_offset * compliance

  • voigt_viscosity_offset (float) – Voigt component’s viscosity offset eta_voigt = voigt_viscosity_offset * viscosity

Returns:

complex_compliance – Complex compliance (complex number) [Pa-1]

Return type:

ComplexArray