Tutorials (3)

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.solid0d, Obliqua.solid1d, Obliqua.solid1d_mush, Obliqua.solid1d_relax, Obliqua.solid1d_mush_relax, Obliqua.fluid0d and Obliqua.fluid1d. In principle, this is rather simple, since you only have to call one function. For example, let us proceed with the data file from Loading data.

using Obliqua

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

# Load configuration
cfg = Obliqua.open_config("$RES_DIR/config/all_options.toml")

# use the relevant load function
omega, axial, ecc, sma, S_mass, rho, radius, visc, shear, bulk, phi, ncalc =
    Obliqua.load.load_interior_mush_full("$RES_DIR/interior_data/test_mantle_mush_full_test.json", false)

# Extract mush zone properties
perm      = Obliqua.interior.get_permeability(phi, cfg)
perm, phi = Obliqua.interior.limit_porosity(perm, phi, cfg)
bulkd     = Obliqua.interior.get_drained_bulk(bulk, phi, cfg)

# call the desired model
power_prf, power_blk, nmk, σ_range, LNk = Obliqua.run_tides(
    omega, axial, ecc, sma, S_mass, rho, radius, visc, shear, bulk, bulkd, phi, perm, cfg
)

Obliqua.complex_modulus — Method

complex_modulus(σ_range, x_profile, η_profile; material="andrade", α=0.3)

Return the complex shear modulus μ̃(σ) and complex bulk modulus κ̃(σ) for Elastic, Maxwell, or Andrade rheology.

Arguments

σ_range::AbstractVector : Forcing frequency range.
x_profile::Array{precc,1} : Shear or Bulk profile of the planet (aka unrelaxed rigidity, unrelaxed bulk).
η_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

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

Obliqua.data_to_nc — Method

data_to_nc(nmk, is_seg, segments, knms_T, knms_L, σ_range, P_T_s_prf, P_T_prf, P_T_blk, P_T_prf_blk, radius, P_T_s_glb_μ, P_T_s_glb_κ, P_T_s_glb_l, datafile_path)

Write model results to a NetCDF file.

Arguments

nmk::Vector{Tuple{Int,Int,Int}} : Array of (n,m,k) tuples for each segment.
is_seg::Array{Tuple{Int,Int},1} : Array of (il,it) tuples indicating segment indices.
segments::Array{String,1} : Array of segment labels.
knms_total::Array{ComplexF64,1} : Total k2 Lovenumbers for each (n,m,k).
knms_T::Matrix{ComplexF64} : Tidal k2 Lovenumbers for each (n,m,k) and segment.
knms_L::Matrix{ComplexF64} : Load k2 Lovenumbers for each (n,m,k) and segment.
σ_range::Array{Float64,1} : Array of forcing frequencies.
P_T_blk::Float64 : Tidal heating (bulk).
P_T_prf_blk::Float64 : Tidal heating (bulk from profile).
P_T_s_prf::Matrix{Float64} : Tidal heating profile for each (n,m,k) and spatial location.
radius::Vector{Float64} : Radial grid points.
P_T_s_glb_μ::Array{Float64,4} : Tidal heating map for each (n,m,k) and spatial location.
P_T_s_glb_κ::Array{Float64,4} : Tidal heating map for each (n,m,k) and spatial location.
P_T_s_glb_l::Array{Float64,4} : Tidal heating map for each (n,m,k) and spatial location.
datafile_path::String : Path to the output NetCDF file.

Obliqua.enforce_energy_conservation! — Method

enforce_energy_conservation!(prf_slice, knms_T_slice, ω, R, dv_slice, nmk, map_μ_slice, map_κ_slice, map_l_slice)

Enforce energy conservation by scaling the heating profile and global maps to match the expected bulk heating from the k Lovenumber.

Arguments

prf_slice::Array{Float64,2} : Heating profile slice for the current segment.
knms_T_slice::Array{ComplexF64,1} : Complex Tidal k2 Lovenumber slice for the current segment.
ω::Array{Float64,1} : Forcing frequency range.
R::Float64 : Planet radius.
dv_slice::Array{Float64,1} : Volume elements for the current segment.
nmk::Vector{Tuple{Int, Int, Int}} : Vector of (n, m, k) tuples for each harmonnic mode.
map_μ_slice::Array{Float64,4} : Global map slice for shear heating.
map_κ_slice::Array{Float64,4} : Global map slice for bulk heating.
map_l_slice::Array{Float64,4} : Global map slice for darcy heating.

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.

Obliqua.make_logger — Method

Create a logger object and return it.

Arguments:

outpath::String : Output file (empty to disable file logging).

Optional arguments:

to_term::Bool : Log to terminal?

Returns:

logger_both : Logger object.

Obliqua.nothing_if_none — Method

Convert 'none' string into nothing literal.

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

Obliqua.run_fluid0d — Method

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

Calculate k2 Lovenumbers in the 0D fluid.

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.
ρ_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::ComplexF64 : Complex Tidal k2 Lovenumber.
k2_L::ComplexF64 : Complex Load k2 Lovenumber.

Obliqua.run_fluid1d — Method

run_fluid1d(omega, rho, radius, visc, ρ_ratio, P_b, R; n=2, sigma_R=1e-3, sigma_inf=1e-7, sigma_R_prf="uniform", H_R=1e3, efficiency=0.3, visc_l=1e2)

Compute tidal heating profile and Love numbers for a 1D fluid model.

Arguments

omega::Float64 : Forcing frequency
rho::Vector{prec} : Density profile
radius::Vector{prec} : Radial grid (core → surface)
visc::Vector{prec} : Viscosity profile
ρ_ratio::prec : Density ratio of lower layer
P_b::Float64 : Heating at lower interface
R::prec : Planet radius

Keyword Arguments

n::Int=2 : Radial power (dominant term n=2)
sigma_R::Float64=1e-3 : Rayleigh drag at interface
sigma_inf::Float64=1e-7 : Drag in fluid interior
sigma_R_prf::String="uniform" : Drag profile type
H_R::Float64=1e3 : Drag scale height
efficiency::Float64=0.3 : Interface efficiency factor
visc_l::Float64=1e2 : Liquid viscosity

Returns

power_prf::Vector{Float64} : Heating profile
k2_T::ComplexF64 : Tidal Love number
k2_L::ComplexF64 : Load Love number

Obliqua.run_interp — Method

run_interp(omega, radius, P_t, P_b; t_width=0.1, b_width=0.1)

Interpolate dissipation and k2 Lovenumbers in a 1D region without active tides.

Arguments

omega::Float64 : Forcing frequency.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
R::prec : Planet Radius.
P_t::prec : Heating at upper interface.
P_b::prec : Heating at lower interface.

Keyword Arguments

t_width::Float64=0.1 : Fraction of segment height as standard deviation for upper dissipation peak.
b_width::Float64=0.1 : Fraction of segment height as standard deviation for lower dissipation peak.

Returns

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

Obliqua.run_solid0d — Method

run_solid0d(μ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::ComplexF64 : Complex Tidal k2 Lovenumber.
k2_L::ComplexF64 : Complex Load k2 Lovenumber.

Obliqua.run_solid1d — Method

run_solid1d(omega, rho, radius, visc, shear, bulk, R, m_core, ρ_core, μ_core, κ_core; ncalc=2000, n=2, m=2, core="liquid")

Use 1D solid tides model to calculate k2 Lovenumbers, and compute 1D heating profile from strain tensor. This method ignores inertia effects, since they break the numerical stability.

Arguments

omega::prec : Forcing frequency range.
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{precc,1} : Complex bulk modulus profile of the planet.
R::prec : Planet radius.
m_core::prec : Core mass.
ρ_core::prec : Core density.
μ_core::prec : Core shear modulus.
κ_core::prec : Core bulk modulus.

Keyword Arguments

ncalc::Int=2000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
m::Int=2 : Harmonic of the true anomaly. m=2 corresponds to the semidiurnal tide, m=1 diurnal tide.
core::String="liquid" : Core state, either "liquid" or "solid".

Returns

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

Obliqua.run_solid1d_mush — Method

run_solid1d_mush(omega, rho, radius, visc, shear, bulk, bulkd, phi, alpha, perm, R, ρ_core, μ_core, κ_core; ncalc=2000, n=2, m=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.
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{precc,1} : Complex bulk modulus profile of the planet.
bulkd::Array{precc,1} : Complex drained bulk modulus profile of the planet.
phi::Array{prec,1} : Melt fraction (porosity) profile of the planet.
alpha::Array{precc,1} : Biot's modulus profile of the planet.
perm::Array{prec,1} : Permeability profile of the planet.
R::prec : Planet radius.
m_core::prec : Core mass.
ρ_core::prec : Core density.
μ_core::prec : Core shear modulus.
κ_core::prec : Core bulk modulus.

Keyword Arguments

ncalc::Int=2000 : Number of sublayers.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
m::Int=2 : Harmonic of the true anomaly. m=2 corresponds to the semidiurnal tide, m=1 diurnal tide.
core::String="liquid" : Core state, either "liquid" or "solid".
visc_l::Float64=1e2 : Liquid viscosity.
bulk_l::Float64=1e9 : Liquid bulk modulus.
porosity_thresh::Float64=1e-5 : Porosity threshold, below this value no mush.

Returns

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

Obliqua.run_solid1d_mush_relax — Method

run_solid1d_mush_relax(omega, rho, radius, visc, shear, bulk, bulkd, phi, alpha, perm, R, m_core, ρ_core, μ_core, κ_core; dr_min=300, dr_max=3000, n=2, m=2, core="liquid", visc_l=1e2, bulk_l=1e9, porosity_thresh=1e-5, optimize_scales=false, patch=false)

Use 1D solid tides model with relaxation method to calculate k2 Lovenumbers, and compute 1D heating profile from strain tensor. This method includes inertia effects, but is more computationally expensive.

Arguments

omega::prec : Forcing frequency range.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
gravity::Array{prec,1} : Gravity profile of the planet.
visc::Array{prec,1} : Viscosity profile of the planet.
shear::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{precc,1} : Complex bulk modulus profile of the planet.
bulkd::Array{precc,1} : Complex drained bulk modulus profile of the planet.
phi::Array{prec,1} : Melt fraction (porosity) profile of the planet.
alpha::Array{precc,1} : Biot's modulus profile of the planet.
perm::Array{prec,1} : Permeability profile of the planet.
R::prec : Planet radius.
m_core::prec : Core mass.
ρ_core::prec : Core density.
μ_core::prec : Core shear modulus.
κ_core::prec : Core bulk modulus.

Keyword Arguments

dr_min::Int=300 : Minimum layer thickness in m.
dr_max::Int=3000 : Maximum layer thickness in m.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
m::Int=2 : Harmonic of the true anomaly. m=2 corresponds to the semidiurnal tide, m=1 diurnal tide.
core::String="liquid" : Core state, either "liquid", "solid", or "inertial".
visc_l::Float64=1e2 : Liquid viscosity.
bulk_l::Float64=1e9 : Liquid bulk modulus.
porosity_thresh::Float64=1e-5 : Porosity threshold, below this value no mush.
optimize_scales::Bool=false : Whether to optimize non-dimensionalization scales for the relaxation method.
patch::Bool=false : Whether to insert an infinitesimal solid shell around the core. This patches an issue where y2 and y4 become decoupled and cause the solution to diverge in fluid layers.

Returns

power_prf::Array{prec,1} : Heating profile.
Eμ_glb_itp::Array{prec,4} : Heating map (colatitude, longitude, radius).
Eκ_glb_itp::Array{prec,4} : Heating map (colatitude, longitude, radius).
El_glb_itp::Array{prec,4} : Heating map (colatitude, longitude, radius).
k2_T::precc : Complex Tidal k2 Lovenumber.
k2_L::precc : Complex Load k2 Lovenumber.

Obliqua.run_solid1d_relax — Method

run_solid1d_relax(omega, rho, radius, gravity, visc, shear, bulk, R, m_core, ρ_core, μ_core, κ_core; dr_min=300, dr_max=3000, n=2, m=2, core="liquid", optimize_scales=false, patch=false)

Use 1D solid tides model with relaxation method to calculate k2 Lovenumbers, and compute 1D heating profile from strain tensor. This method includes inertia effects, but is more computationally expensive.

Arguments

omega::prec : Forcing frequency range.
rho::Array{prec,1} : Density profile of the planet.
radius::Array{prec,1} : Radial positions of layers, from core to surface.
gravity::Array{prec,1} : Gravity profile of the planet.
visc::Array{prec,1} : Viscosity profile of the planet.
shear::Array{precc,1} : Complex shear modulus profile of the planet.
bulk::Array{precc,1} : Complex bulk modulus profile of the planet.
R::prec : Planet radius.
m_core::prec : Core mass.
ρ_core::prec : Core density.
μ_core::prec : Core shear modulus.
κ_core::prec : Core bulk modulus.

Keyword Arguments

dr_min::Int=300 : Minimum layer thickness in m.
dr_max::Int=3000 : Maximum layer thickness in m.
n::Int=2 : Power of the radial factor (goes with (r/a)^{n}, since r<<a only n=2 contributes significantly).
m::Int=2 : Harmonic of the true anomaly. m=2 corresponds to the semidiurnal tide, m=1 diurnal tide.
core::String="liquid" : Core state, either "liquid", "solid", or "inertial".
optimize_scales::Bool=false : Whether to optimize non-dimensionalization scales for the relaxation method.
patch::Bool=false : Whether to insert an infinitesimal solid shell around the core. This patches an issue where y2 and y4 become decoupled and cause the solution to diverge in fluid layers.

Returns

power_prf::Array{Float64,1} : Heating profile.
Eμ_glb_itp::Array{prec,4} : Heating map (colatitude, longitude, radius).
Eκ_glb_itp::Array{prec,4} : Heating map (colatitude, longitude, radius).
k2_T::ComplexF64 : Complex Tidal k2 Lovenumber.
k2_L::ComplexF64 : Complex Load k2 Lovenumber.

Obliqua.run_tides — Method

run_tides(omega, axial, ecc, sma, S_mass, rho, radius, visc, shear, bulk, bulkd, phi, perm, 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::Float64 : Orbital eccentricity.
sma::Float64 : Semi-major axis of the orbit.
S_mass::Float64 : 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.
bulkd::Array{prec,1} : Drained bulk modulus profile of the fluid layers.
phi::Array{prec,1} : Porosity profile of the fluid layers.
perm::Array{prec,1} : Permeability profile of the fluid 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).
nmk::Array{Tuple{Int,Int,Int},1} : List of tidal modes (n, m, k) considered in the calculation.
σ_range::Array{Float64,1} : Frequencies at which the Love number k_n was evaluated.
Hansen::Array{Float64,1} : Hansen coefficients corresponding to the tidal modes.
knms_total::Array{ComplexF64,1} : Complex Love number k_n for the planet.

Obliqua.setup_logging — Method

Setup terminal logging and file logging.

Arguments:

outpath::String : Output file (empty to disable file logging)
verbosity::Int : Verbosity (0: silent, 1: normal, 2: debug)

Obliqua.smooth_complex_modulus! — Method

smooth_complex_modulus!(μc, κc, r, η)

Return the smoothed complex shear modulus μ̃(σ) and complex bulk modulus κ̃(σ).

Arguments

μc::Matrix{precc} : Complex shear modulus profile at all forcing frequencies.
κc::Matrix{precc} : Complex bulk modulus profile at all forcing frequencies.
r::Array{prec,1} : Radial positions of layers, from core to surface.
η_profile::Array{prec,1} : Viscosity profile of the planet.

Returns

μc::Matrix{precc} : Smoothed complex shear modulus profile at all forcing frequencies.
κc::Matrix{precc} : Smoothed complex bulk modulus profile at all forcing frequencies.

Obliqua.true_if_true — Method

Convert 'true'/'false' string into boolean literal.