Tutorials (2)

Running Model

Now that you are able to validate and load data files using the Obliqua.load module, we can start using the tidal models Obliqua.Solid, Obliqua.Love and Obliqua.Fluid. In principle, this is rather simple, since you only have to call one function depending on your use case. For example, let us proceed with the data file from Loading data. In this case, following the Table of inputs, we are interested in the solid-phase tides only, so we may use the Obliqua.calc_solid_tides function.

Warning

Newer versions of the code will stop using the distinct phase calc_..._tides functions, instead all models can be accessed through run_tides.

using Obliqua

# location of data files
RES_DIR = "/path/to/Obliqua/res"

# use the relevant load function
omega, ecc, rho, radius, visc, shear, bulk, ncalc = Obliqua.load.load_interior("$RES_DIR/interior_data/test_mantle.json", false)

# call the desired model
power_prf, power_blk, imag_k2 = Obliqua.calc_solid_tides(omega, ecc, rho, radius, visc, shear, bulk; ncalc=ncalc, material="maxwell")

In general, we can use

Tides	Function
solid-phase	`Obliqua.calc_solid_tides`
solid-phase + mush interface	`Obliqua.calc_solid_tides_mush`
liquid-phase	`Obliqua.calc_fluid_tides`
mixed-phase	`Obliqua.run_tides`

Obliqua.calc_fluid_tides — Method

calc_fluid_tides(omega, axial, ecc, sma, S_mass, rho, radius, visc; 
                N_sigma=301, visc_l=5e2, visc_s=5e21, sigma_R=1e-3)

Calculate the tidal heating in the fluid layers of a planetary interior.

This function computes the tidal dissipation power profile and the total tidal heating for liquid layers using Love numbers, Hansen coefficients, and a viscoelastic approximation for the solid interior. It also returns the k2 Love number at the forcing frequency used by the calculation.

Arguments

omega::prec : Orbital frequency of the planet [rad/s].
axial::prec : Axial rotation frequency of the planet [rad/s].
ecc::prec : Orbital eccentricity.
sma::prec : Semi-major axis of the orbit [m].
S_mass::prec : Stellar mass [kg].
rho::Array{prec,1} : Layered density profile [kg/m³].
radius::Array{prec,1} : Layer boundaries [m], length = number of layers + 1.
visc::Array{prec,1} : Layer viscosities [Pa·s].

Keyword Arguments

N_sigma::Int=301 : Number of frequency bins for spectral calculations.
visc_l::Float64=5e2 : Threshold viscosity below which a layer is considered liquid [Pa·s].
visc_s::Float64=5e21 : Threshold viscosity above which a layer is considered solid [Pa·s].
sigma_R::Float64=1e-3 : Rayleigh drag coefficient for the fluid interface [1/s].

Returns

A tuple with three elements:

power_prf::Vector{Float64} : Tidal heating power profile for each layer [W].
P_tidal_total::Float64 : Total tidal dissipation power in the fluid layers [W].
k2_total::Float64 : Complex k2 Love number at the forcing frequency.

Errors

Throws an error if:

No liquid layers are found in the interior (ρ_l empty), suggesting that visc_l needs adjustment.
The interior structure is incompatible with computing mean densities.

Notes

Layers are categorized into liquid, mush, and solid based on visc_l and visc_s.
r_b denotes the bottom of the liquid region.
Hansen coefficients and Love numbers are computed over a frequency spectrum and interpolated.

source

Obliqua.calc_solid_tides — Method

calc_solid_tides(omega, ecc, rho, radius, visc, shear, bulk; ncalc=2000, material="andrade")

Calculate tidal heating in a solid planetary interior using the Love number approach (Love.jl).

Arguments

omega::prec : Forcing angular frequency (rad/s).
ecc::prec : Orbital eccentricity.
rho::Vector{prec} : Radial density profile (kg/m³), first element = core.
radius::Vector{prec} : Radial grid points corresponding to rho (m).
visc::Vector{prec} : Viscosity profile (Pa·s).
shear::Vector{prec} : Shear modulus profile (Pa).
bulk::Vector{prec} : Bulk modulus profile (Pa).

Keyword Arguments

ncalc::Int=2000 : Number of subdivisions for radial layers.
material::String="andrade" : Rheology model for complex shear modulus. Options: "maxwell", "andrade".

Returns

A tuple (power_prf, power_blk, k2_im):

power_prf::Vector{Float64} : Tidal heating profile per unit mass (W/kg).
power_blk::Float64 : Total bulk tidal heating (W).
k2_im::Float64 : Imaginary part of the complex tidal Love number k2 at the forcing frequency.

Notes

Implements Efroimsky (2012) equations for viscoelastic response.
Shear and bulk heating contributions are computed separately and summed.

source

Obliqua.calc_solid_tides_mush — Method

calc_solid_tides_mush(omega, ecc, rho, radius, visc, shear, bulk, phi;
                        ncalc=2000, material="andrade", visc_l=1e2,
                        bulk_l=1e9, permea=1e-7)

Calculate tidal heating in a partially molten planetary interior with a mush region.

Arguments

omega::prec : Forcing angular frequency (rad/s).
ecc::prec : Orbital eccentricity.
rho::Vector{prec} : Radial density profile (kg/m³), first element = core.
radius::Vector{prec} : Radial grid points corresponding to rho (m).
visc::Vector{prec} : Viscosity profile (Pa·s).
shear::Vector{prec} : Shear modulus profile (Pa).
bulk::Vector{prec} : Bulk modulus profile (Pa).
phi::Vector{prec} : Melt fraction profile (0–1) for each layer.

Keyword Arguments

ncalc::Int=2000 : Number of subdivisions for radial layers.
material::String="andrade" : Rheology model for complex shear modulus. Options: "maxwell", "andrade".
visc_l::Float64=1e2 : Liquid viscosity in mush region (Pa·s).
bulk_l::Float64=1e9 : Bulk modulus of liquid in mush region (Pa).
permea::Float64=1e-7 : Permeability of mush region (m²).

Returns

A tuple (power_prf, power_blk, k2_im):

power_prf::Vector{Float64} : Tidal heating profile per unit mass (W/kg).
power_blk::Float64 : Total bulk tidal heating (W).
k2_im::Float64 : Imaginary part of the complex tidal Love number k2 at the forcing frequency.

Notes

Accounts for porosity and partial melt (mush) effects on tidal dissipation.
Uses drained and Biot moduli to handle fluid–solid coupling.
Throws an error if no mush region is identified (phi insufficient).

source

Obliqua.complex_mu — Method

complex_mu(σ_range, μ_profile, η_profile; material="andrade", α=0.3)

Return the complex shear modulus μ̃(σ) for Maxwell or Andrade rheology.

Arguments

σ_range::AbstractVector : Forcing frequency range.
μ_profile::Array{precc,1} : Shear profile of the planet (aka unrelaxed rigidity).
η_profile::Array{prec,1} : Viscosity profile of the planet.

Keyword Arguments

material::String="andrade" : Material for which to find complex shear modulus.
α::Float64=0.3" : Power-law exponent (free parameter).

Returns

μc::Matrix{precc} : Complex shear modulus profile at all forcing frequencies.

source

Obliqua.get_layers — Method

get_layers(r, η, η_l, η_s; min_frac=0.02)

Determine the phase profile of a planetary interior considering solid, fluid, and mush layers.

Arguments

r::Array{prec,1} : Radial positions of layers, from core to surface.
η::Array{prec,1} : Viscosity profile of the planet.
η_l::Float64 : Liquidus viscosity.
η_s::Float64 : Solidus viscosity.

Keyword Arguments

min_frac::Float64=0.02 : Minimal segment radius fraction before smoothing.

Returns

mask_s::Vector{Bool} : Solid region mask.
mask_l::Vector{Bool} : Fluid region mask.
mask_c::Vector{Bool} : Mush region mask.
is_seg::Vector{Tuple{Int,Int}} : Segment [start, stop] index array.
segments::Vector{String} : Segment phase array.

source

Obliqua.open_config — Method

Open and validate config file.

Arguments:

cfg_path::String : Path to configuration file

Returns:

cfg_dict::Dict : Dictionary containing the configuration

source

Obliqua.radial_heating_profile — Method

radial_heating_profile(r, mu, Ptot)

Compute a spherically symmetric volumetric heating profile H(r) [W/m^3]

Arguments

k2_L::precc : Complex Load k2 Lovenumber.
r::Vector : Radial positions of layers, from core to surface.
mu::Vector : Complex shear modulus profile of the planet.
Ptot::Real : Totally dissipated power (W)

Returns

H::Vector : Heating profile.

Heating is assumed proportional to Im(μ(r)) and normalized so the integral of H over the volume equals Ptot.

source

Obliqua.run_fluid — Method

run_fluid(omega, rho, radius, ρ_ratio; n=2, sigma_R=1e-3)

Calculate k2 Lovenumbers in the fluid.

Arguments

omega::Float64 : Forcing frequency range.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
ρ_ratio::prec : Density contrast between current (fluid) and lower (non-fluid) layer.

Keyword Arguments

n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
sigma_R::Float64=1e-3 : Rayleigh drag coefficient.

Returns

k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_solid_0d — Method

run_solid_0d(μc, radius, mass_tot; n=2)

Calculate k2 Lovenumbers in the 0d solid.

Arguments

μc::Array{precc,1} : Forcing frequency range.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
mass_tot::Float64 : Total mass of planet.

Keyword Arguments

n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).

Returns

k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_solid_1d — Method

run_solid_1d(rho, radius, visc, shear, bulk; ncalc=2000, n=2)

Use 1D solid tides model to calculate k2 Lovenumbers.

Arguments

rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
visc::Array{prec,1} : Viscosity profile of the planet.
μ_profile::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{prec,1} : Bulk modulus profile of the planet.

Keyword Arguments

ncalc::Int=1000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).

Returns

k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_solid_1d_strain — Method

run_solid_1d_strain(omega, ecc, rho, radius, visc, shear, bulk; ncalc=2000, n=2)

Use 1D solid tides model to calculate k2 Lovenumbers, and compute 1D heating profile from strain tensor.

Arguments

omega::Float64 : Forcing frequency range.
ecc::prec : Eccentricity of the orbit.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
visc::Array{prec,1} : Viscosity profile of the planet.
μ_profile::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{prec,1} : Bulk modulus profile of the planet.

Keyword Arguments

ncalc::Int=1000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).

Returns

power_prf::Array{prec,1} : Heating profile.
k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_solid_mush_1d — Method

run_solid_mush_1d(omega, rho, radius, visc, shear, bulk, phi; ncalc=2000, n=2, visc_l=1e2, bulk_l=1e9, permea=1e-7, porosity_thresh=1e-5)

Use 1D solid tides model with mush interface to calculate k2 Lovenumbers.

Arguments

omega::Float64 : Forcing frequency.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
visc::Array{prec,1} : Viscosity profile of the planet.
shear::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{prec,1} : Bulk modulus profile of the planet.
phi::Array{prec,1} : Melt fraction (porosity) profile of the planet.

Keyword Arguments

ncalc::Int=1000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
visc_l::Float64=1e2 : Liquid viscosity.
bulk_l::Float64=1e9 : Liquid bulk modulus.
permea::Float64=1e-7 : Permeability of mush layer.
porosity_thresh::Float64=1e-5 : Porosity threshold, below this value no mush.

Returns

k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_solid_mush_1d_strain — Method

run_solid_mush_1d_strain(omega, ecc, rho, radius, visc, shear, bulk, phi; ncalc=2000, n=2, visc_l=1e2, bulk_l=1e9, permea=1e-7, porosity_thresh=1e-5)

Use 1D solid tides model with mush interface to calculate k2 Lovenumbers, and compute 1D heating profile from strain tensor.

Arguments

omega::Float64 : Forcing frequency range.
ecc::prec : Eccentricity of the orbit.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
visc::Array{prec,1} : Viscosity profile of the planet.
shear::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{prec,1} : Bulk modulus profile of the planet.
phi::Array{prec,1} : Melt fraction (porosity) profile of the planet.

Keyword Arguments

ncalc::Int=1000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
visc_l::Float64=1e2 : Liquid viscosity.
bulk_l::Float64=1e9 : Liquid bulk modulus.
permea::Float64=1e-7 : Permeability of mush layer.
porosity_thresh::Float64=1e-5 : Porosity threshold, below this value no mush.

Returns

power_prf::Array{prec,1} : Heating profile.
k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

source

Obliqua.run_tides — Method

run_tides(omega, axial, ecc, sma, S_mass, rho, radius, visc, shear, bulk, cfg)

Compute the tidal heating profile of a planetary interior considering solid and fluid layers.

Arguments

omega::prec : Orbital frequency of the body.
axial::prec : Axial (spin) frequency of the body.
ecc::prec : Orbital eccentricity.
sma::prec : Semi-major axis of the orbit.
S_mass::prec : Mass of the central body (e.g., star) inducing tides.
rho::Array{prec,1} : Radial density profile of the planet, from core to surface.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
visc::Array{prec,1} : Viscosity profile of the planet.
shear::Array{prec,1} : Shear modulus profile of the solid layers.
bulk::Array{prec,1} : Bulk modulus profile of the solid layers.
cfg::Dict : Configuration parameters from dictionary.

Returns

power_prf::Array{Float64,1} : Radial profile of tidal heating (W/m³).
power_blk::Float64 : Total tidal power integrated over the interior (W).
σ_range::Array{Float64,1} : Frequencies at which the Love number k2 was evaluated.
imag_k2::Array{Float64,1} : Imaginary part of the Love number k2 for the planet.

source