TidalPy.RadialSolver package

Subpackages

Submodules

TidalPy.RadialSolver.constants module

TidalPy.RadialSolver.helpers module

TidalPy.RadialSolver.helpers.build_rs_input_from_data(forcing_frequency, radius_array, density_array, static_bulk_modulus_array, static_shear_modulus_array, bulk_viscosity_array, shear_viscosity_array, layer_upper_radius_tuple, layer_type_tuple, layer_is_static_tuple, layer_is_incompressible_tuple, shear_rheology_model_tuple, bulk_rheology_model_tuple, perform_checks=True, warnings=True)
TidalPy.RadialSolver.helpers.build_rs_input_homogeneous_layers(planet_radius, forcing_frequency, density_tuple, static_bulk_modulus_tuple, static_shear_modulus_tuple, bulk_viscosity_tuple, shear_viscosity_tuple, layer_type_tuple, layer_is_static_tuple, layer_is_incompressible_tuple, shear_rheology_model_tuple, bulk_rheology_model_tuple, radius_fraction_tuple=None, thickness_fraction_tuple=None, volume_fraction_tuple=None, slices_tuple=None, slice_per_layer=10, perform_checks=True)

TidalPy.RadialSolver.love module

TidalPy.RadialSolver.love.find_love(complex_love_numbers_view, surface_solutions_view, surface_gravity)

Find the complex Love and Shida numbers given the surface radial solutions for a planet.

Parameters:

  • complex_love_numbers_view (double complex[::1], array, output) – Array to store complex Love numbers. There must be space for 3 double complex numbers.

  • surface_solutions_view (double complex[::1], array, input) – Array of radial solutions (y_i) values at the surface of a planet.

  • surface_gravity (double, input) – Acceleration due to gravity at the planet’s surface [m s-2].

TidalPy.RadialSolver.matrix module

Propagation of tidal solution using the fundamental matrix

References

SVC16 : Sabadini, Vermeerson, & Cambiotti (2016, DOI: 10.1007/978-94-017-7552-6) HH14 : Henning & Hurford (2014, DOI: 10.1088/0004-637X/789/1/30) ID : IcyDwarf Code by Marc Neveu (https://github.com/MarcNeveu/IcyDwarf/blob/master/IcyDwarf/Thermal.h) B13 : Beuthe (2013, DOI: 10.1016/j.icarus.2012.11.020)

TidalPy.RadialSolver.rs_solution module

class TidalPy.RadialSolver.rs_solution.RadialSolverSolution

Bases: object

Q

Return quality factors.

bulk_modulus_array
central_pressure

Return’s the pressure at the planet’s center, found by the EOS solver

degree_l

Return the harmonic degree used to perform the calculation.

density_array
density_bulk

Return’s the planet’s bulk density

eos_call(radius)
eos_error_code

Return solver’s equation of state message

eos_iterations

Return the number of iterations performed by the EOS sub-solver to find convergence on surface pressure

eos_message

Return solver’s equation of state message

eos_pressure_error

Return the surface pressure error found by the equation of state sub-solver

eos_steps_taken

Return the number of integration steps required by the last iteration of the EOS solver

eos_success

Return if the solver’s equation of state sub-solver was successful

error_code

Return solution storage’s error code

get_result_by_ytype_name(ytype_name)

Get a specific solution type array.

gravity_array
h

Tidal Love number h.

k

Tidal Love number k.

l

Tidal Shida number l.

lag

Return the dissapative lag angle (in radians).

layer_upper_radius_array

Return’s the upper radius at each layer in the planet.

love

Return all complex love numbers.

mass

Return’s the total planet mass, found by the EOS solver

mass_array
message

Return solver’s message

moi

Return’s the planet’s real moment of inertia, found by the EOS solver

moi_array
moi_factor

Return’s the planet’s moment of inertia factor, found by the EOS solver

num_layers
num_ytypes
plot_interior()
plot_ys()
pressure_array
print_diagnostics(print_diagnostics=True, log_diagnostics=False)
radius

Return’s the planet’s radius, set by user

radius_array
result

Return result array.

shear_modulus_array
steps_taken

Number of integration steps by layer and solution.

success

Return rather if the solver was successful

surface_gravity

Return’s the acceleration due to gravity at the planet’s surface, found by the EOS solver

surface_pressure

Return’s the pressure at the planet’s surface, found by the EOS solver

volume

Return’s the planet’s volume, calculated by its radius

TidalPy.RadialSolver.shooting module

TidalPy.RadialSolver.shooting.find_num_shooting_solutions(layer_type, is_static, is_incompressible)

TidalPy.RadialSolver.solver module

TidalPy.RadialSolver.solver.radial_solver(radius_array, density_array, complex_bulk_modulus_array, complex_shear_modulus_array, frequency, planet_bulk_density, layer_types, is_static_bylayer, is_incompressible_bylayer, upper_radius_bylayer_array, degree_l=2, solve_for=None, starting_radius=0.0, start_radius_tolerance=1e-05, nondimensionalize=True, use_kamata=False, integration_method='DOP853', integration_rtol=1e-05, integration_atol=1e-08, scale_rtols_bylayer_type=False, max_num_steps=500000, expected_size=1000, max_ram_MB=500, max_step=0.0, use_prop_matrix=False, core_model=0, eos_method_bylayer=None, surface_pressure=0.0, eos_integration_method='DOP853', eos_rtol=0.001, eos_atol=1e-05, eos_pressure_tol=0.001, eos_max_iters=40, verbose=False, warnings=True, raise_on_fail=False, perform_checks=True, log_info=False)

Solves the viscoelastic-gravitational problem for a planet comprised of solid and liquid layers.

See Takeuchi and Saito (1972) for more details on this method.

Parameters:

  • radius_array (np.ndarray[dtype=np.float64]) – Radius values defined at slices throughout the planet [m]. It must start at zero and end at the planet’s surface.

  • density_array (np.ndarray[dtype=np.float64]) – Density at each radius [kg m-3].

  • complex_bulk_modulus_array (np.ndarray[dtype=np.complex128]) – Bulk modulus at each radius [Pa].

  • complex_shear_modulus_array (np.ndarray[dtype=np.complex128]) – Complex shear modulus at each radius [Pa]. This should be the result of applying a rheological model to the static shear modulus, viscosity, and forcing frequency.

  • frequency (float64) – Forcing frequency [rad s-1]

  • planet_bulk_density (float64) – Bulk density of the planet [kg m-3].

  • layer_types (tuple[string, ...] (Size = number of layers)) –

    Indicator of layer type. Current options are:

    • ”solid”

    • ”liquid”

  • is_static_bylayer (tuple[bool, ...] (Size = number of layers)) – Flag declaring if each layer uses the static (True) or dynamic (False) assumption.

  • is_incompressible_bylayer (tuple[bool, ...] (Size = number of layers)) – Flag declaring if each layer is incompressible (True) or compressible (False).

  • upper_radius_by_layer (tuple[float64, ...] (Size = number of layers)) – Tuple of the upper radius of each layer. Used to determine physical structure of planet.

  • degree_l (uint32, default=2) – Harmonic degree.

  • solve_for (tuple[str, ...] (Size = number of requested solutions), default=None) –

    RadialSolver allows multiple solutions to be solved simultaneously, avoiding repeated integration. This parameter is a tuple of requested solutions. If None, then only “tidal” will be solved for. Options that are currently supported (note these are case sensitive):

    • ”tidal”: Tidal forcing boundary conditions.

    • ”loading”: Surface loading boundary conditions.

    • ”free”: Free surface boundary conditions.

    For example, if you want the tidal and loading solutions then you can set “solve_for=(‘tidal’, ‘loading’)”.

  • starting_radius (float64, default=0.0) – The initial radius at which to start solving the viscoelastic-gravitational equations. For stability purposes, the higher your degree l, the higher you want your starting r. If set to 0.0, the default, TidalPy will determine a good starting l based on the planet radius and degree l. If you provide a non-zero value then it must be in [m]

  • start_radius_tolerance (float64, default=1.0e-5) –

    If starting_radius is not provided then TidalPy will use the formula:

    r = planet_radius * start_radius_tolerance^(1.0 / degree_l)

    Depending on your layer size and the degree_l, this may be in a layer above the innermost core. TidalPy will perform a full planet equation of state calculation, but will skip the viscoelastic calculations for layers and radii below the starting value.

  • nondimensionalize (bool, default=True) – If True, then inputs will be non-dimensionalized before integration (either shooting method or prop matrix) is performed. Results will be redimensionalized before being returned.

  • use_kamata (bool, default=False) – If True, then the starting solution at the core will be based on equations from Kamata et al (2015; JGR:P) Otherwise, starting solution will be based on Takeuchi and Saito (1972)

  • integration_method (int32, default="DOP853") –

    Which CyRK integration protocol should be used. Options that are currently available are:

    • 0: Runge-Kutta 2(3)

    • 1: Runge-Kutta 4(5)

    • 2: Runge-Kutta / DOP 8(5/3)

  • integration_rtol (float64, default=1.0e-5) – Relative integration tolerance. Lower tolerance will lead to more precise results at increased computation.

  • integration_atol (float64, default=1.0e-8) – Absolute integration tolerance (when solution is near 0).

  • scale_rtols_bylayer_type (bool, default=True) – If True, then each layer will be imparted with a different relative tolerance. Liquid layers will have a lower rtol which has been found to improve stability.

  • max_num_steps (uint32, default=500,000) – Maximum number of integration steps allowed before solver forces a failed result. Useful to set to a lower number if running many calls that may be exploring an unstable parameter space for example, during a MCMC run.

  • expected_size (uint32, default=1000) – Anticipated number of integration steps that will be required per solution. Tweaking this may have a minor impact on performance. It is advised to leave it between 200–1000. Setting it too low can lead to bad performance.

  • max_ram_MB (uint32, default=500) – Maximum amount of RAM in MB the integrator is allowed (ignoring some housekeeping usage). The integrator will use this value and the “max_num_steps” to determine a true limit on the maximum number steps allowed (picking the lower value.). If system RAM is limited (or if multiple RadialSolvers will run in parallel) it maybe worth setting this lower than the default. The default of 500MB is equivalent to a max_num_steps ~ 5 Million.

  • max_step (float64, default=0) – Maximum step size the adaptive step size integrator is allowed to take. Setting to 0 (default) will tell the integrator to determine an ideal max step size.

  • use_prop_matrix (bool, default=False) – If True, RadialSolver will use a propagation matrix method rather than the default shooting method. Note that many of the parameters set by this function are only applicable to the shooting method and may not be passed to the propagation matrix solver. See more about the prop-matrix method in TidalPy.RadialSolver.PropMatrix.

  • core_model (uint32, default=0) –

    Only used with use_prop_matrix=True. Defines the starting conditions at the inner boundary of the planet.
    • 0: Henning & Hurford (2014): “At the core, a special seed matrix Bcore is created with only three columns,

      equal to the first, second, and third columns of Y for the properties at the base layer.”

    • 1: Roberts & Nimmo (2008): liquid innermost zone.

    • 2: Solid innermost zone.

    • 3: Different solid innermost zone.

    • 4: Sabadini & Veermeerson (2004), More complex interface matrix

  • eos_method_by_layer (tuple, default = None) –

    Tuple of EOS methods for each layer. This is a tuple of strings. If None then will use default for each layer (interpolation) Currently supported methods:

    • ”interpolation”

  • surface_pressure (float64, default=0) – The pressure at the surface of the planet (defined as radius_array[-1]). [Pa] Used for EOS calculations.

  • eos_integration_method (unsigned int, default = "DOP853") – Integration method used to solve for the planet’s equation of state.

  • eos_rtol (double, default = 1.0e-3) – Integration relative tolerance for equation of state solver.

  • eos_atol (double, default = 1.0e-5) – Integration absolute tolerance for equation of state solver.

  • eos_pressure_tol (double, default = 0.1) – Tolerance used when fitting to the surface pressure in the equation of state solver.

  • eos_max_iters (int, default = 40) – Maximum number of iterations used to converge surface pressure in equation of state solver.

  • verbose (bool, default=False) – If True, then additional information will be printed to the terminal during the solution.

  • warnings (bool, default=True) – If True, then warnings will be printed to the terminal during the solution.

  • raise_on_fail (bool, default=False) – If True, then the solver will raise an exception if integration was not successful. By default RadialSolver fails silently.

  • perform_checks (bool, default=True) – Performs sanity checks that raise python exceptions. If turned off then these checks will be skipped providing some boost to performance but at the risk of uncaught exceptions (crashes).

  • log_info (bool, default=False) – Flag to turn on logging of key information (diagnostic and physical) from the RadialSolverSolution. Note there is a performance hit if this is true, particularly if file logging is enabled.

Returns:

solution – Solution to the viscoelastic-gravitational problem inside a planet. Also contains the EOS solver solution for the entire planet.

Return type:

RadialSolverSolution