API

Abstract type of an asteroid's thermophysical model. The AbstractAsteroidTPM type is an alias for AbstractAsteroidThermoPhysicalModel.

Type of the backward Euler method:

• Implicit in time (Unconditionally stable in the heat conduction equation)
• First order in time

The BackwardEulerSolver type has vectors for the tridiagonal matrix algorithm.

struct BinaryAsteroidThermoPhysicalModel{M1, M2} <: AbstractAsteroidThermoPhysicalModel

Fields

• pri : TPM for the primary
• sec : TPM for the secondary
• MUTUAL_SHADOWING : Flag to consider mutual shadowing
• MUTUAL_HEATING : Flag to consider mutual heating

BinaryAsteroidThermoPhysicalModel(pri, sec; MUTUAL_SHADOWING=true, MUTUAL_HEATING=true) -> btpm

Construct a thermophysical model for a binary asteroid (BinaryAsteroidThermoPhysicalModel).

struct BinaryAsteroidThermoPhysicalModelResult

Output data format for BinaryAsteroidThermoPhysicalModel

Fields

• pri : TPM result for the primary
• sec : TPM result for the secondary

Outer constructor of BinaryAsteroidThermoPhysicalModelResult

Arguments

• btpm : Thermophysical model for a binary asteroid
• ephem : Ephemerides
• times_to_save : Timesteps to save temperature (Common to both the primary and the secondary)
• face_ID_pri : Face indices to save subsurface temperature of the primary
• face_ID_sec : Face indices to save subsurface temperature of the secondary

Abstract type of a boundary condition for a heat conduction equation

Type of the Crank-Nicolson method:

• Implicit in time (Unconditionally stable in the heat conduction equation)
• Second order in time

The CrankNicolsonSolver type has vectors for the tridiagonal matrix algorithm.

References

• https://en.wikipedia.org/wiki/Crank–Nicolson_method

Type of the forward Euler method:

• Explicit in time
• First order in time

The ForwardEulerSolver type includes a vector for the temperature at the next time step.

Abstract type of a solver for a heat conduction equation

Singleton type of insulation boundary condition

Type of isothermal boundary condition

Singleton type of radiation boundary condition

ShapeModel

A polyhedral shape model of an asteroid.

Fields

• nodes : Vector of node positions
• faces : Vector of vertex indices of faces
• face_centers : Center position of each face
• face_normals : Normal vector of each face
• face_areas : Area of of each face
• visiblefacets : Vector of vector of VisibleFacet

struct SingleAsteroidThermoPhysicalModel <: AbstractAsteroidThermoPhysicalModel

Fields

• shape : Shape model

• thermo_params : Thermophysical parameters

• flux : Flux on each face. Matrix of size (Number of faces, 3). Three components are:

  • flux[:, 1] : F_sun, flux of direct sunlight
  • flux[:, 2] : F_scat, flux of scattered light
  • flux[:, 3] : F_rad, flux of thermal emission from surrounding surface

• temperature : Temperature matrix (n_depth, n_face) according to the number of depth cells n_depth and the number of faces n_face.

• face_forces : Thermal force on each face

• force : Thermal recoil force at body-fixed frame (Yarkovsky effect)

• torque : Thermal recoil torque at body-fixed frame (YORP effect)

• SELF_SHADOWING : Flag to consider self-shadowing

• SELF_HEATING : Flag to consider self-heating

• SOLVER : Solver of heat conduction equation

• BC_UPPER : Boundary condition at the upper boundary

• BC_LOWER : Boundary condition at the lower boundary

TODO:

• roughness_maps ::ShapeModel[]

SingleAsteroidThermoPhysicalModel(shape, thermo_params; SELF_SHADOWING=true, SELF_HEATING=true) -> stpm

Construct a thermophysical model for a single asteroid (SingleAsteroidThermoPhysicalModel).

Arguments

• shape : Shape model
• thermo_params : Thermophysical parameters

Keyword arguments

• SELF_SHADOWING : Flag to consider self-shadowing
• SELF_HEATING : Flag to consider self-heating
• SOLVER : Solver of heat conduction equation
• BC_UPPER : Boundary condition at the upper boundary
• BC_LOWER : Boundary condition at the lower boundary

struct SingleAsteroidThermoPhysicalModelResult

Output data format for SingleAsteroidThermoPhysicalModel

Fields

Saved at all time steps

• times : Timesteps, given the same vector as ephem.time [s]
• E_in : Input energy per second on the whole surface [W]
• E_out : Output enegey per second from the whole surface [W]
• E_cons : Energy conservation ratio [-], ratio of total energy going out to total energy coming in in the last rotation cycle
• force : Thermal force on the asteroid [N]
• torque : Thermal torque on the asteroid [N ⋅ m]

Saved only at the time steps desired by the user

• times_to_save : Timesteps to save temperature and thermal force on every face [s]
• depth_nodes : Depths of the calculation nodes for 1-D heat conduction [m], a vector of size n_depth
• surface_temperature : Surface temperature [K], a matrix in size of (n_face, n_time).
  • n_face : Number of faces
  • n_time : Number of time steps to save surface temperature
• subsurface_temperature : Temperature [K] as a function of depth [m] and time [s], Dict with face ID as key and a matrix (n_depth, n_time) as an entry.
  • n_depth : The number of the depth nodes
  • n_time : The number of time steps to save temperature
• face_forces : Thermal force on every face of the shape model [N], a matrix in size of (n_face, n_time).
  • n_face : Number of faces
  • n_time : Number of time steps to save surface temperature

Outer constructor of SingleAsteroidThermoPhysicalModelResult

Arguments

• stpm : Thermophysical model for a single asteroid
• ephem : Ephemerides
• times_to_save : Timesteps to save temperature
• face_ID : Face indices to save subsurface temperature

struct ThermoParams

Fields

• period : Period of thermal cycle (rotation period) [sec]

• skindepth : Vector of thermal skin depth for each facet [m]

• inertia : Vector of thermal inertia for each facet [thermal inertia unit (tiu)]

• reflectance_vis : Vector of reflectance in visible light for each facet [-]

• reflectance_ir : Vector of reflectance in thermal infrared for each facet [-]

• emissivity : Vector of emissivity for each facet [-]

• z_max : Depth of the lower boundary of a heat conduction equation [m]

• Δz : Depth step width [m]

• n_depth : Number of depth steps

ThermoParams(
    period          ::Float64,
    skindepth       ::Float64,
    inertia         ::Float64,
    reflectance_vis ::Float64,
    reflectance_ir  ::Float64,
    emissivity      ::Float64,
    z_max           ::Float64,
    Δz              ::Float64,
    n_depth         ::Int
)

Outer constructor for ThermoParams. You can give the same parameters to all facets by Float64.

Arguments

• period : Period of thermal cycle (rotation period) [sec]
• skindepth : Thermal skin depth [m]
• inertia : Thermal inertia [tiu]
• reflectance_vis : Reflectance in visible light [-]
• reflectance_ir : Reflectance in thermal infrared [-]
• emissivity : Emissivity [-]
• z_max : Depth of the lower boundary of a heat conduction equation [m]
• Δz : Depth step width [m]
• n_depth : Number of depth steps

struct VisibleFacet

Index of an interfacing facet and its view factor

Fields

• id : Index of the interfacing facet
• f : View factor from facet i to j
• d : Distance from facet i to j
• d̂ : Normal vector from facet i to j

backward_euler!(stpm::SingleAsteroidTPM, Δt)

Predict the temperature at the next time step by the backward Euler method.

• Implicit in time (Unconditionally stable in the heat conduction equation)
• First order in time
• Second order in space

In this function, the heat conduction equation is non-dimensionalized in time and length.

blackbody_radiance(λ, T) -> L_λ

Accroding to Planck's law, calculate the spectral intensity of blackbody radiation at wavelength λ and temperature T.

Arguments

• λ : Wavelength [m]
• T : Temperature [K]

Return

• L_λ : Spectral radiance [W/m²/m/steradian]

cf. https://github.com/JuliaAstro/Planck.jl/blob/main/src/Planck.jl

blackbody_radiance(T) -> L

According to Stefan-Boltzmann law, calculate the total radiance of blackbody radiation at temperature T, integrated over all wavelength.

Arguments

• T : Temperature [K]

Return

• L : Radiance [W/m²/steradian]

broadcast_thermo_params!(thermo_params::ThermoParams, n_face::Int)

Broadcast the thermophysical parameters to all faces if the values are uniform globally.

Arguments

• thermo_params : Thermophysical parameters
• n_face : Number of faces on the shape model

broadcast_thermo_params!(thermo_params::ThermoParams, shape::ShapeModel)

Broadcast the thermophysical parameters to all faces if the values are uniform globally.

Arguments

• thermo_params : Thermophysical parameters
• shape : Shape model

concave_spherical_segment(r, h, xc, yc, x, y) -> z

Return the z-coordinate of a concave spherical segment.

Arguments

• r : Crater radius
• h : Crater depth
• xc: x-coordinate of crater center
• yc: y-coordinate of crater center
• x : x-coordinate where to calculate z
• y : y-coordinate where to calculate z

concave_spherical_segment(r, h; Nx=2^5, Ny=2^5, xc=0.5, yc=0.5) -> xs, ys, zs

Return (x, y, z) grid of a concave spherical segment.

Arguments

• r : Crater radius
• h : Crater depth
• Nx: Number of nodes in the x-direction
• Ny: Number of nodes in the y-direction
• xc: x-coordinate of crater center
• yc: y-coordinate of crater center

crank_nicolson!(stpm::SingleAsteroidTPM, Δt)

Predict the temperature at the next time step by the Crank-Nicolson method.

• Implicit in time (Unconditionally stable in the heat conduction equation)
• Second order in time
• Second order in space

In this function, the heat conduction equation is non-dimensionalized in time and length.

crater_curvature_radius(r, h) -> R

Return the curvature radius of a concave spherical segment.

Arguments

• r: Crater radius
• h: Crater depth

energy_in(stpm::SingleAsteroidTPM) -> E_in

Input energy per second on the whole surface [W]

energy_out(stpm::SingleAsteroidTPM) -> E_out

Output enegey per second from the whole surface [W]

Arguments

• stpm : Thermophysical model for a single asteroid

export_TPM_results(dirpath, result::BinaryAsteroidThermoPhysicalModelResult)

Export the result of BinaryAsteroidThermoPhysicalModel to CSV files. The output files are saved in the following directory structure:

dirpath
├── pri
│   ├── physical_quantities.csv
│   ├── subsurface_temperature.csv
│   ├── surface_temperature.csv
│   └── thermal_force.csv
└── sec
    ├── physical_quantities.csv
    ├── subsurface_temperature.csv
    ├── surface_temperature.csv
    └── thermal_force.csv

Arguments

• dirpath : Path to the directory to save CSV files.
• result : Output data format for BinaryAsteroidThermoPhysicalModel

export_TPM_results(dirpath, result::SingleAsteroidThermoPhysicalModelResult)

Export the result of SingleAsteroidThermoPhysicalModel to CSV files. The output files are saved in the following directory structure:

dirpath
├── physical_quantities.csv
├── subsurface_temperature.csv
├── surface_temperature.csv
└── thermal_force.csv

Arguments

• dirpath : Path to the directory to save CSV files.
• result : Output data format for SingleAsteroidThermoPhysicalModel

find_visiblefacets!(shape::ShapeModel; show_progress=true)

Find facets that is visible from the facet where the observer is located.

Arguments

• shape : Shape model of an asteroid

Keyword arguments

• show_progress : Switch to show a progress meter

flux_total(R_vis, R_ir, F_sun, F_scat, F_rad) -> F_total

Total energy absorbed by the surface [W/m²]

Arguments

• R_vis : Reflectance for visible light [-]
• R_ir : Reflectance for thermal infrared [-]
• F_sun : Flux of direct sunlight [W/m²]
• F_scat : Flux of scattered light [W/m²]
• F_rad : Flux of thermal radiation from surrounding surface [W/m²]

forward_euler!(stpm::SingleAsteroidTPM, Δt)

Predict the temperature at the next time step by the forward Euler method.

• Explicit in time
• First order in time

In this function, the heat conduction equation is non-dimensionalized in time and length.

Arguments

• stpm : Thermophysical model for a single asteroid
• Δt : Time step [sec]

grid_to_faces(xs::AbstractVector, ys::AbstractVector, zs::AbstractMatrix) -> nodes, faces

Convert a regular grid (x, y) and corresponding z-coordinates to triangular facets

| ⧹| ⧹| ⧹|

j+1 ・–C–D–・ |⧹ |⧹ |⧹ | | ⧹| ⧹| ⧹| j ・–A–B–・ |⧹ |⧹ |⧹ | i i+1

Arguments

• xs::AbstractVector : x-coordinates of grid points (should be sorted)
• ys::AbstractVector : y-coordinates of grid points (should be sorted)
• zs::AbstractMatrix : z-coordinates of grid points

init_temperature!(btpm::BinaryTBinaryAsteroidThermoPhysicalModelPM, T₀::Real)

Initialize all temperature cells at the given temperature T₀

Arguments

• btpm : Thermophysical model for a binary asteroid
• T₀ : Initial temperature of all cells [K]

init_temperature!(stpm::SingleAsteroidThermoPhysicalModel, T₀::Real)

Initialize all temperature cells at the given temperature T₀

Arguments

• stpm : Thermophysical model for a single asteroid
• T₀ : Initial temperature of all cells [K]

isilluminated(shape::ShapeModel, r☉::StaticVector{3}, i::Integer) -> Bool

Return if the i-th face of the shape model is illuminated by the direct sunlight or not

Arguments

• shape : Shape model of an asteroid
• r☉ : Sun's position in the asteroid-fixed frame, which doesn't have to be normalized.
• i : Index of the face to be checked

load_shape_grid(xs, ys, zs; scale=1.0, find_visible_facets=false) -> shape

Convert a regular grid (x, y) to a shape model

Arguments

• xs::AbstractVector : x-coordinates of grid points
• ys::AbstractVector : y-coordinates of grid points
• zs::AbstractMatrix : z-coordinates of grid points

load_shape_obj(shapepath; scale=1.0, find_visible_facets=false; show_progress=true)

Load a shape model from a Wavefront OBJ file.

Arguments

• shapepath : Path to a Wavefront OBJ file

Keyword arguments

• scale : Scale factor of the shape model
• find_visible_facets : Switch to find visible facets
• show_progress : Switch to show a progress meter

loadobj(shapepath::String; scale=1, message=true) -> nodes, faces

mutual_heating!(btpm::BinaryAsteroidTPM, rₛ, R₂₁)

Calculate the mutual heating between the primary and secondary asteroids.

Arguments

• btpm : Thermophysical model for a binary asteroid
• rₛ : Position of the secondary relative to the primary (NOT normalized)
• R₂₁ : Rotation matrix from secondary to primary

TODO

• Need to consider local horizon?

mutual_shadowing!(btpm::BinaryAsteroidTPM, r☉, rₛ, R₂₁)

Detect eclipse events between the primary and secondary, and update the solar fluxes of the faces.

Arguments

• btpm : Thermophysical model for a binary asteroid
• r☉ : Position of the sun relative to the primary (NOT normalized)
• rₛ : Position of the secondary relative to the primary (NOT normalized)
• R₂₁ : Rotation matrix from secondary to primary

polyhedron_volume(nodes, faces)      -> vol
polyhedron_volume(shape::ShapeModel) -> vol

Calculate volume of a polyhedral

raycast(A, B, C, R) -> Bool

Intersection detection between ray R and triangle ABC. Note that the starting point of the ray is the origin (0, 0, 0).

raycast(A, B, C, R, O) -> Bool

Intersection detection between ray R and triangle ABC. Use when the starting point of the ray is an arbitrary point O.

run_TPM!(btpm::BinaryAsteroidThermoPhysicalModel, ephem, savepath)

Run TPM for a binary asteroid.

Arguments

• btpm : Thermophysical model for a binary asteroid
• ephem : Ephemerides
  • time : Ephemeris times
  • sun1 : Sun's position in the primary's frame
  • sun2 : Sun's position in the secondary's frame
  • sec : Secondary's position in the primary's frame
  • P2S : Rotation matrix from primary to secondary frames
  • S2P : Rotation matrix from secondary to primary frames
• times_to_save : Timesteps to save temperature
• face_ID_pri : Face indices where to save subsurface termperature for the primary
• face_ID_sec : Face indices where to save subsurface termperature for the secondary

Keyword arguments

• show_progress : Flag to show the progress meter

run_TPM!(stpm::SingleAsteroidThermoPhysicalModel, ephem, savepath)

Run TPM for a single asteroid.

Arguments

• stpm : Thermophysical model for a single asteroid
• ephem : Ephemerides
  • ephem.time : Ephemeris times
  • ephem.sun : Sun's position in the asteroid-fixed frame (Not normalized)
• times_to_save : Timesteps to save temperature
• face_ID : Face indices where to save subsurface termperature

Keyword arguments

• show_progress : Flag to show the progress meter

subsolar_temperature(r☉) -> Tₛₛ

Subsolar temperature [K] on an asteroid at a heliocentric distance r☉ [m], assuming radiative equilibrium with zero conductivity.

Return surface temperature of a single asteroid corrsponding to each face.

thermal_inertia(k, ρ, Cp) -> Γ

Arguments

• k : Thermal conductivity [W/m/K]
• ρ : Material density [kg/m³]
• Cₚ : Heat capacity [J/kg/K]

Return

• Γ : Thermal inertia [tiu (thermal intertia unit)]

thermal_radiance(shape, emissivities, temperatures, obs) -> L

Calculate the radiance from the temperature distribution based on a shape model.

Arguments

• shape : Shape model of an asteroid
• emissivities : Emissivity of each facet of the shape model [-]
• temperatures : Temperature of each facet of the shape model [K]
• obs : Position vector of the observer in the same coordinate system as shape [m]

Return

• L : Radiance [W/m²]

thermal_skin_depth(P, k, ρ, Cp) -> l_2π

Arguments

• P : Cycle of thermal cycle [sec]
• k : Thermal conductivity [W/m/K]
• ρ : Material density [kg/m³]
• Cₚ : Heat capacity [J/kg/K]

Return

• l_2π : Thermal skin depth [m], as defined in Rozitis & Green (2011).

tridiagonal_matrix_algorithm!(a, b, c, d, x)
tridiagonal_matrix_algorithm!(stpm::SingleAsteroidThermoPhysicalModel)

Tridiagonal matrix algorithm to solve the heat conduction equation by the backward Euler and Crank-Nicolson methods.

| b₁ c₁ 0  ⋯  0   | | x₁ |   | d₁ |
| a₂ b₂ c₂ ⋯  0   | | x₂ |   | d₂ |
| 0  a₃ b₃ ⋯  0   | | x₃ | = | d₃ |
| ⋮  ⋮  ⋮  ⋱  cₙ₋₁| | ⋮  |   | ⋮  |
| 0  0  0  aₙ bₙ  | | xₙ |   | dₙ |

References

• https://en.wikipedia.org/wiki/Tridiagonalmatrixalgorithm

update_TPM_result!(result::BinaryAsteroidThermoPhysicalModelResult, btpm::BinaryAsteroidThermoPhysicalModel, ephem, i_time::Integer)

Save the results of TPM at the time step i_time to result.

Arguments

• result : Output data format for BinaryAsteroidThermoPhysicalModel
• btpm : Thermophysical model for a binary asteroid
• ephem : Ephemerides
• i_time : Time step

update_TPM_result!(result::SingleAsteroidThermoPhysicalModelResult, stpm::SingleAsteroidThermoPhysicalModel, i_time::Integer)

Save the results of TPM at the time step i_time to result.

Arguments

• result : Output data format for SingleAsteroidThermoPhysicalModel
• stpm : Thermophysical model for a single asteroid
• i_time : Time step to save data

update_flux_rad_single!(btpm::BinaryAsteroidTPM)

Update flux of absorption of thermal radiation from surrounding surface. Single radiation-absorption is only considered, assuming albedo is close to zero at thermal infrared wavelength.

Arguments

• btpm : Thermophysical model for a binary asteroid

update_flux_rad_single!(stpm::SingleAsteroidTPM)

Update flux of absorption of thermal radiation from surrounding surface. Single radiation-absorption is only considered, assuming albedo is close to zero at thermal infrared wavelength.

Arguments

• stpm : Thermophysical model for a single asteroid

update_flux_scat_single!(btpm::BinaryAsteroidTPM)

Update flux of scattered sunlight, only considering single scattering.

Arguments

• btpm : Thermophysical model for a binary asteroid

update_flux_scat_single!(stpm::SingleAsteroidTPM)

Update flux of scattered sunlight, only considering single scattering.

Arguments

• stpm : Thermophysical model for a single asteroid

update_flux_sun!(btpm::BinaryAsteroidTPM, r☉₁::StaticVector{3}, r☉₂::StaticVector{3})

Arguments

• btpm : Thermophysical model for a binary asteroid
• r☉₁ : Sun's position in the body-fixed frame of the primary, which is not normalized.
• r☉₂ : Sun's position in the body-fixed frame of the secondary, which is not normalized.

update_flux_sun!(stpm::SingleAsteroidTPM, r̂☉::StaticVector{3}, F☉::Real)

Update solar irradiation flux on every face of a shape model.

• shape : Shape model
• r̂☉ : Normalized vector indicating the direction of the sun in the body-fixed frame
• F☉ : Solar radiation flux [W/m²]

update_flux_sun!(stpm::SingleAsteroidTPM, r☉::StaticVector{3})

Update solar irradiation flux on every face of a shape model.

Arguments

• stpm : Thermophysical model for a single asteroid
• r☉ : Position of the sun in the body-fixed frame (NOT normalized)

update_bottom_temperature!(shape::ShapeModel)

Update the temperature of the bottom surface based on the boundary condition stpm.BC_LOWER.

Arguments

• stpm : Thermophysical model for a single asteroid

update_surface_temperature!(T::AbstractVector, F_total::Real, k::Real, l::Real, Δz::Real, ε::Real)

Newton's method to update the surface temperature under radiation boundary condition.

Arguments

• T : 1-D array of temperatures
• F_total : Total energy absorbed by the facet
• Γ : Thermal inertia [tiu]
• P : Period of thermal cycle [sec]
• Δz̄ : Non-dimensional step in depth, normalized by thermal skin depth l
• ε : Emissivity [-]

update_temperature!(btpm::BinaryAsteroidTPM, Δt)

Calculate the temperature for the next time step based on 1D heat conductivity equation.

Arguments

• btpm : Thermophysical model for a binary asteroid
• Δt : Time step [sec]

update_temperature!(stpm::SingleAsteroidTPM, Δt)

Calculate the temperature for the next time step based on 1D heat conduction equation. If the thermal inertia (conductivity) is zero, omit to solve the heat conduction equation. The surface termperature is determined only by radiative equilibrium.

Arguments

• stpm : Thermophysical model for a single asteroid
• Δt : Time step [sec]

update_thermal_force!(btpm::BinaryAsteroidTPM)

Calculate the thermal force and torque on every face and integrate them over all faces.

Arguments

• btpm : Thermophysical model for a binary asteroid

update_thermal_force!(stpm::SingleAsteroidTPM)

Calculate the thermal force and torque on every face and integrate them over all faces.

Arguments

• stpm : Thermophysical model for a single asteroid

update_upper_temperature!(stpm::SingleAsteroidTPM, i::Integer)

Update the temperature of the upper surface based on the boundary condition stpm.BC_UPPER.

Arguments

• stpm : Thermophysical model for a single asteroid
• i : Index of the face of the shape model

view_factor(cᵢ, cⱼ, n̂ᵢ, n̂ⱼ, aⱼ) -> fᵢⱼ, dᵢⱼ, d̂ᵢⱼ

View factor from facet i to j, assuming Lambertian emission.

• ---

• (i) fᵢⱼ (j)
• △ –> △

• ---

• cᵢ cⱼ : Center of each face
• n̂ᵢ n̂ⱼ : Normal vector of each face

• •       aⱼ  : Area of j-th face

• ---