TidalPy.structures.world_types package

Submodules

TidalPy.structures.world_types.basic module

class TidalPy.structures.world_types.basic.BaseWorld(world_config: dict, name: str = None, initialize: bool = True)

Bases: PhysicalObjSpherical

WorldBase Class - Base class used to build other world methods.

See also

Parent

TidalPy.structures.PhysicalObjSpherical

Child

TidalPy.structures.world_types.TidalWorld TidalPy.structures.world_types.GasGiantWorld TidalPy.structures.world_types.StarWorld TidalPy.structures.world_types.LayeredWorld TidalPy.structures.world_types.GasGiantLayeredWorld TidalPy.structures.world_types.BurnManWorld

property albedo: float

World’s Albedo

clear_state(preserve_orbit: bool = False)

Clear the world’s current state variables back to their defaults.

The defaults may be Nones or set by the user-provided configuration.

Parameters:

preserve_orbit (bool = False) – If True, data about this planet’s orbit will be cleared from any associated Orbit methods.

property eccentricity

World’s Orbital Eccentricity (stored in the world’s Orbit class)

property eccentricity_time_derivative: NoneType | FloatArray

Derivative of eccentricity with respect to time (only effects due to tides are considered)

property emissivity: float

World’s Emissivity

property equilibrium_insolation_func: EquilibFuncType

Flag that is used to force the world’s spin rate to equal its orbital motion if changed.

property force_spin_sync: bool

Flag that is used to force the world’s spin rate to equal its orbital motion if changed.

get_internal_heating_to_surface() → NoneType | FloatArray

Get the amount of internal heating that is making it to the surface.

Returns:

internal_heating_to_surface – Amount of heating that is reaching the surface [W]

Return type:

Union[NoneType, FloatArray]

property insolation_heating: FloatArray

Surface heating received on a world from its host star [W]

property internal_to_surf_heating_frac: EquilibFuncType

Fraction of internal heating that makes its way to the surface (used for surface equilibrium temperature calculations).

kill_world()

Performs saving tasks when the world is about to be deleted due to end of run

The exit_planets variable in the main TidalPy config controls rather or not this method ever gets called automatically.

property n

Alias of BaseWorld.orbital_frequency

property name: str

Name of the world

property obliquity: FloatArray

World’s Obliquity [rad]

This obliquity must be relative to the orbital plane defined by the tidal target and tidal host [1]_.

If the star is neither the host nor target, then it should not be used as a reference object.

References

[1]

J. P. Renaud et al, “Tidal Dissipation in Dual-Body, Highly Eccentric, and Non-synchronously Rotating Systems: Applications to Pluto-Charon and the Exoplanet TRAPPIST-1e” The Planetary Science Journal, vol. 22, pp. TBA, 2020.

orbit: NoneType | Orbit

orbit_spin_changed(orbital_freq_changed: bool = False, spin_freq_changed: bool = False, eccentricity_changed: bool = False, obliquity_changed: bool = False, call_orbit_dissipation: bool = True)

The world’s orbit, spin, and/or obliquity has changed. Make any necessary updates

Parameters:

• orbital_freq_changed (bool = False) – Set to True if the orbital frequency has changed.

• spin_freq_changed (bool = False) – Set to True if the world’s rotation frequency has changed.

• eccentricity_changed (bool = False) – Set to True if the eccentricity has changed.

• obliquity_changed (bool = False) – Set to True if the world’s obliquity has changed.

• call_orbit_dissipation (bool = True) – If True, then the Orbit class’ dissipation method will be called.

property orbital_freq

Alias of BaseWorld.orbital_frequency

property orbital_frequency

World’s Orbital Frequency (inverse of orbital period; stored in the world’s Orbit class) [rad s-1]

property orbital_motion

Alias of BaseWorld.orbital_frequency

property orbital_motion_time_derivative: NoneType | FloatArray

Derivative of the orbital mean motion with respect to time (only effects due to tides are considered)

property orbital_period

World’s Orbital Period (inverse of orbital frequency; stored in the world’s Orbit class) [days]

paint(depth_plot: bool = False, auto_show: bool = True, return_fig: bool = False)

Create a geotherm or depth plot of the planet’s gravity, pressure, and density :param depth_plot: If True the plot will be versus depth rather than radius. :type depth_plot: bool = False :param auto_show: Calls plt.show() if true. :type auto_show: bool = False :param return_fig: If True, return the matplotlib fig object otherwise return True. :type return_fig: bool = False

Returns:

figure

Return type:

matplotlib.pyplot.figure

reinit(initial_init: bool = False, reinit_geometry: bool = True)

Initialize or Reinitialize the world based on changes to its config.

This must be called at least once before an instance can be used. The constructor will automatically make an

initial call to reinit unless told to not to.

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).

• reinit_geometry (bool = True) – If True, the initializer will automatically call the set_geometry() method.

save_world(save_dir: str = None, no_cwd: bool = False, save_to_world_dir: bool = False)

Save the world’s configuration file to a specified directory.

Parameters:

• save_dir (str = None) – The current working directory will be preappended unless no_cwd is set to true. If no directory is provided it will be saved os.getcwd()

• no_cwd (bool = False) – If True, the current working directory will not be prepended to the provided directory.

• save_to_world_dir (bool = False) – If True, the config will be saved to the TidalPy directory as well as the CWD.

property semi_major_axis

World’s Semi-Major Axis (stored in the world’s Orbit class) [m]

property semi_major_axis_time_derivative: NoneType | FloatArray

Derivative of the semi-major axis with respect to time (only effects due to tides are considered)

set_geometry(radius: float, mass: float, thickness: float = None, mass_below: float = 0.0, update_state_geometry: bool = True, build_slices: bool = True)

Calculates and sets the world’s physical parameters based on user provided input.

Assumptions

Spherical Geometry

param radius:

Outer radius of object [m]

type radius:

float

param mass:

Mass of object [kg]

type mass:

float

param thickness:

Thickness of the object [m]

type thickness:

float = None

param mass_below:

Mass below this object (only applicable for shell-like structures) Used in gravity and pressure calculations

type mass_below:

float = 0.

param update_state_geometry:

Update the class’ state geometry

type update_state_geometry:

bool = True

param build_slices:

If True, method will attempt to calculate gravities, densities, etc. for each slice.

type build_slices:

bool = True

set_insolation_heating(insolation_heating: FloatArray)

Set a new insolation heating received on the world’s surface from a host star.

This method will update the surface temperature which will in turn change the thermal state.

See also

TidalPy.orbit.physics.PhysicsOrbit.calculate_insolation

Parameters:

insolation_heating (FloatArray) – Heating received from a stellar host [W]

set_obliquity(obliquity: FloatArray, call_updates: bool = True)

Set the world’s obliquity.

This obliquity must be relative to the orbital plane defined by the tidal target and tidal host [1]_.

If the star is neither the host nor target, then it should not be used as a reference object.

References

[1]

J. P. Renaud et al, “Tidal Dissipation in Dual-Body, Highly Eccentric, and Non-synchronously Rotating Systems: Applications to Pluto-Charon and the Exoplanet TRAPPIST-1e” The Planetary Science Journal, vol. 22, pp. TBA, 2020.

Parameters:

• obliquity (FloatArray) – New obliquity for the world relative to its orbit around the tidal host [rad]

• call_updates (bool = True) – If True, method will not call the update tides method.

set_spin_frequency(spin_frequency: FloatArray, call_updates: bool = True)

Update the world’s spin frequency.

Parameters:

• spin_frequency (FloatArray) – New spin frequency for the world [rad s-1]

• call_updates (bool = True) – If True, method will call the update tides method.

set_spin_period(spin_period: FloatArray, call_updates: bool = True)

Update the world’s spin period in days.

Parameters:

• spin_period (FloatArray) – New spin period for the world [days]

• call_updates (bool = True) – If True, method will call the update tides method.

set_state(spin_frequency: FloatArray = None, spin_period: FloatArray = None, obliquity: FloatArray = None, time: FloatArray = None, orbital_frequency: FloatArray = None, orbital_period: FloatArray = None, semi_major_axis: FloatArray = None, eccentricity: FloatArray = None, set_by_world: bool = False)

Set multiple orbital parameters at once, this reduces the number of calls to self.orbit_change

This contains a wrapper to the orbit class method set_state. It extends that function by including the spin frequency.

This function has better performance than the individual setters for these parameters if (and only if) you are changing two or more of them at the same time.

Parameters:

• spin_frequency (FloatArray = None) – New spin frequency for the world [rad s-1].

• spin_period (FloatArray = None) – New spin period for the world [days]

• obliquity (FloatArray = None) – New obliquity for the world relative to its orbit around the tidal host [rad].

• time (FloatArray = None) – Time used in integration and radiogenic calculations [Myr].

• orbital_frequency (FloatArray = None) – New orbital frequency (orbital motion) for the world around its tidal host [rad s-1].

• orbital_period (FloatArray = None) – New orbital period for the world around its tidal host [days].

• semi_major_axis (FloatArray = None) – New orbital separation between world and its tidal host [m].

• eccentricity (FloatArray = None) – New orbital eccentricity relative to the tidal host.

• set_by_world (bool = False) – If True, then world_types update methods will not be called.

set_time(time: FloatArray, call_updates: bool = True)

Set the time of the world.

Parameters:

• time (FloatArray) – Time used in integration and radiogenic calculations [Myr]

• call_updates (bool = True) – If True, method will call the update time method.

property spin_freq

Alias of BaseWorld.spin_frequency

property spin_frequency: FloatArray

Spin (Sidereal Rotation) Frequency of the World [rad s-1]

property spin_period: FloatArray

Spin (Sidereal Rotation) Period of the World [days]

property stellar_distance

World’s Orbital Distance relative to its host star (stored in the world’s Orbit class) [m]

property stellar_eccentricity

World’s Orbital Eccentricity relative to its host star (stored in the world’s Orbit class)

property surface_temperature: FloatArray

World’s Surface Temperature [K]

surface_temperature_changed(called_from_cooling: bool = False)

Surface temperature has changed - Perform any calculations that may have also changed.

Parameters:

called_from_cooling (bool = False) – Flag to avoid recursive loops between surface temperature and cooling.

property tidal_host: NoneType | 'AllWorldType'

Wrapper for the orbit class’s get_tidal_host method

property time: FloatArray

The time of either the Orbit or the object (used for radiogenic calculations) [Myr]

time_changed()

The world’s time has been changed. Make any necessary updates.

update_surface_temperature(called_from_cooling: bool = False)

Surface temperature has changed - Perform any calculations that may have also changed.

Parameters:

called_from_cooling (bool = False) – Flag to avoid recursive loops between surface temperature and cooling.

world_class = 'base'

TidalPy.structures.world_types.gas module

class TidalPy.structures.world_types.gas.GasGiantLayeredWorld

Bases: LayeredWorld

Worlds that are gas or ice giants and dissipate tidal energy through either the CPL/CTL method or a more complex

rheology.

These world types are not implemented as of at lease v0.2.1

See also

Parent

TidalPy.structures.world_types.LayeredWorld

world_class = 'gas_giant_layered'

class TidalPy.structures.world_types.gas.GasGiantWorld

Bases: TidalWorld

Worlds that are simple gas giants and dissipate tidal energy through the CPL/CTL method (or not at all).

See also

Parent

TidalPy.structures.world_types.TidalWorld

world_class = 'gas_giant'

TidalPy.structures.world_types.layered module

class TidalPy.structures.world_types.layered.LayeredWorld(world_config: dict, name: str = None, initialize: bool = True)

Bases: TidalWorld

LayeredWorld - Construct tidal world_types that have layers.

See also

Parent

TidalPy.structures.world_types.TidalWorld

Child

TidalPy.structures.world.GasGiantLayeredWorld TidalPy.structures.world.BurnManWorld

complex_compliances_changed(collapse_tidal_modes: bool = True)

The complex compliances have changed. Make any necessary updates.

Parameters:

collapse_tidal_modes (bool = True) – If True, then the world will tell its tides model to collapse tidal modes.

dissipation_changed()

Tidal dissipation has changed. Make any necessary updates.

find_layer(layer_name: str) → PhysicsLayer | LayerBase | GasLayer

Returns a reference to a layer with the provided name

Layers are also stored in the planet’s __dict__ and can be accessed via <world>.”layer_name” as well as:

<world>.layers_by_name (dict) <world>.layers (list)

Parameters:

layer_name (str) – Name assigned to layer in the planet’s original configuration

Returns:

layer – Reference to the layer class

Return type:

PhysicsLayer

find_layer_by_radius(radius: float) → PhysicsLayer | LayerBase | GasLayer

Returns a reference to a layer that the provided radius resides in If the provided radius is at the interface of two layers this method will choose the lower layer.

Parameters:

radius (float) – Radius [m] where the desired layer is located.

Returns:

layer – Reference to the layer class at that radius.

Return type:

PhysicsLayer

get_internal_heating_to_surface() → None | float | float64 | ndarray

Get the amount of internal heating that is making it to the surface.

Returns:

internal_heating_to_surface – Amount of heating that is reaching the surface [W]

Return type:

Union[NoneType, FloatArray]

property layer_types: Tuple[str, ...]

Tuple of layer types within world, ordered from bottom-most to top-most

property layers: Tuple[PhysicsLayer | LayerBase | GasLayer, ...]

Tuple of layers within world, ordered from bottom-most to top-most

property layers_by_name: Dict[str, PhysicsLayer | LayerBase | GasLayer]

Dictionary of layers with the keys equaling the layer names

property layers_class: str

Name of the python class used to construct this world’s layers

property num_layers: int

Number of layers within world

reinit(initial_init: bool = False, reinit_geometry: bool = True, setup_simple_tides: bool = False, reinit_layers: bool = True, pull_geo_from_config: bool = True)

Initialize or Reinitialize the world based on changes to its configurations.

This must be called at least once before an instance can be used. The constructor will automatically make an

initial call to reinit unless told to not to.

Parameters:

• initial_init (bool = False) – Must be set to True if this is the first time this function has been called.

• reinit_geometry (bool = True) – If True, the initializer will automatically call the set_geometry() method.

• setup_simple_tides (bool = True) – Set to True if a global CPL/CTL tidal calculation is desired.

• reinit_layers (bool = True) – If True, calls to the world’s layers’ reinit() method.

• pull_geo_from_config (bool = True) – If True, pulls mass and radius from world config. If False, pulls these from state attributes.

set_geometry(radius: float, mass: float, thickness: float = None, mass_below: float = 0.0, update_state_geometry: bool = True, build_slices: bool = False)

Calculates and sets world’s physical parameters based on user provided input.

Assumptions

Spherical Geometry

param radius:

Outer radius of object [m]

type radius:

float

param mass:

Mass of object [kg]

type mass:

float

param thickness:

Thickness of the object [m]

type thickness:

float = None

param mass_below:

Mass below this object (only applicable for shell-like structures) Used in gravity and pressure calculations

type mass_below:

float = 0.

param update_state_geometry:

Update the class’ state geometry

type update_state_geometry:

bool = True

param build_slices:

If True, method will attempt to calculate gravities, densities, etc. for each slice.

type build_slices:

bool = False

set_static_pressure(pressure_above: float = None, build_slices: bool = True)

Sets the static pressure for the physical structure.

Static here indicates that this is not a dynamic pressure used in many calculations. The static pressure can

be used in place of the dynamic pressure, but that is not always the case.

Parameters:

• pressure_above (float = None) –

  Pressure above this structure. If this is a layer, then it is the pressure at the base of the overlying

  layer. If it is the upper-most layer or a world, then it may be the surface pressure.

• build_slices (bool = True) – If True, method will find the pressure at each slice of the physical object.

surface_temperature_changed(called_from_cooling: bool = False)

Surface temperature has changed - Perform any calculations that may have also changed.

Parameters:

called_from_cooling (bool = False) – Flag to avoid recursive loops between surface temperature and cooling.

tidal_frequencies_changed(collapse_tidal_modes: bool = True)

The tidal frequencies have changed. Make any necessary updates.

Parameters:

collapse_tidal_modes (bool = True) – If True, then the world will tell its tides model to collapse tidal modes.

time_changed()

The world’s time has been changed. Make any necessary updates.

world_class = 'layered'

TidalPy.structures.world_types.stellar module

class TidalPy.structures.world_types.stellar.StarWorld

Bases: TidalWorld

Stars can dissipate tidal energy through the CPL/CTL method (or not at all) and have methods to calculate

insolation heating.

See also

Parent

TidalPy.structures.world_types.TidalWorld

property effective_temperature: float

Star’s effective surface temperature [K]

property luminosity: float

Stars luminosity [W]

reinit(initial_init: bool = False, reinit_geometry: bool = True, setup_simple_tides: bool = True)

Initialize or Reinitialize the star based on changes to its configurations.

This must be called at least once before an instance can be used. The constructor will automatically make an

initial call to reinit unless told to not to.

Parameters:

• initial_init (bool = False) – Must be set to True if this is the first time this function has been called.

• reinit_geometry (bool = True) – If True, the initializer will automatically call the set_geometry() method.

• setup_simple_tides (bool = True) – Set to True if a global CPL/CTL tidal calculation is desired.

world_class = 'star'

TidalPy.structures.world_types.tidal module

class TidalPy.structures.world_types.tidal.TidalWorld(world_config: dict, name: str = None, initialize: bool = True)

Bases: BaseWorld

TidalWorld - Provides a simple base to build tidally dissipative world_types off of.

Adds basic functionality for CPL or CTL world_types.

See also

Parent

TidalPy.structures.world_types.BaseWorld

Child

TidalPy.structures.world.GasGiantWorld TidalPy.structures.world.StarWorld TidalPy.structures.world.LayeredWorld TidalPy.structures.world.GasGiantLayeredWorld TidalPy.structures.world.BurnManWorld

calc_spin_derivative() → FloatArray

Calculate spin-rate time derivative based on the world’s current state.

Requires the tides model to have already calculated dU / dO

(tidal potential derivative with respect to the node)

Returns:

spin_rate_derivative – Spin-rate derivative for the planet [rads s-2]

Return type:

FloatArray

clear_state(preserve_orbit: bool = False)

Clear the world’s current state variables back to their defaults.

The defaults may be Nones or set by the user-provided configuration.

Parameters:

preserve_orbit (bool = False) – If True, data about this planet’s orbit will be cleared from any associated Orbit methods.

property dUdM

Inner-scope wrapper for tides.dUdM

property dUdO

Inner-scope wrapper for tides.dUdO

property dUdw

Inner-scope wrapper for tides.dUdw

dissipation_changed()

Tidal dissipation has changed. Make any necessary updates.

property eccentricity_truncation_lvl

Inner-scope wrapper for tides.eccentricity_truncation_lvl

property effective_q_by_orderl

World’s effective tidal dissipation factor (for each tidal order level)

property fixed_dt: NoneType | float

World’s global tidal dissipation efficiency frequency scale

property fixed_q: NoneType | float

World’s global effective tidal dissipation efficiency ‘fixed-Q’

property fixed_time_lag

Alias for self.fixed_dt

get_internal_heating_to_surface() → NoneType | FloatArray

Get the amount of internal heating that is making it to the surface.

Returns:

internal_heating_to_surface – Amount of heating that is reaching the surface [W]

Return type:

Union[NoneType, FloatArray]

property global_love_by_orderl

Global complex Love number, k_l

property global_negative_imk_by_orderl

Global negative of the imaginary portion of the Love number, -Im[k_l]

internal_heating_changed()

The internal heating of this world has changed. Make any necessary updates.

property is_spin_sync: bool

If True, then the world will be forced in to synchronous rotation

property max_tidal_order_lvl

Inner-scope wrapper for tides.max_tidal_order_lvl

orbit_spin_changed(orbital_freq_changed: bool = False, spin_freq_changed: bool = False, eccentricity_changed: bool = False, obliquity_changed: bool = False, call_orbit_dissipation: bool = True)

The world’s orbit, spin, and/or obliquity has changed. Make any necessary updates

reinit(initial_init: bool = False, reinit_geometry: bool = True, setup_simple_tides: bool = True)

Initialize or Reinitialize the world based on changes to its configurations.

This must be called at least once before an instance can be used. The constructor will automatically make an

initial call to reinit unless told to not to.

Parameters:

• initial_init (bool = False) – Must be set to True if this is the first time this function has been called.

• reinit_geometry (bool = True) – If True, the initializer will automatically call the set_geometry() method.

• setup_simple_tides (bool = True) – Set to True if a global CPL/CTL tidal calculation is desired.

set_fixed_dt(fixed_dt: float, run_updates: bool = True)

Set a new global tidal dissipation efficiency frequency scale ‘dt’ for the world

This is used in calculating tidal dissipation assuming a CTL model.

Parameters:

• fixed_dt (float) – New dissipation efficiency frequency scale [s].

• run_updates (bool = True) – If True, this method will call the update tides method.

set_fixed_q(fixed_q: float, run_updates: bool = True)

Set a new global tidal dissipation efficiency or ‘fixed-Q’ for the world

This is used in calculating tidal dissipation assuming a CPL model.

Notes

Parameters:

• fixed_q (float) – New dissipation efficiency.

• run_updates (bool = True) – If True, this method will call the update tides method.

property spin_time_derivative: FloatArray

The time derivative of the spin rate [rad s-2]

tidal_frequencies_changed(collapse_tidal_modes: bool = True)

The tidal frequencies have changed. Make any necessary updates.

Parameters:

collapse_tidal_modes (bool = True) – If True, then the world will tell its tides model to collapse tidal modes.

property tidal_heating

Alias for self.tidal_heating_global

property tidal_heating_global

Inner-scope wrapper for tides.tidal_heating_global

property tidal_polar_torque: FloatArray

The tidal polar torque [N m]

property tidal_susceptibility

Inner-scope wrapper for tides.tidal_susceptibility

property tidal_susceptibility_reduced

Inner-scope wrapper for tides.tidal_susceptibility_reduced

property tidal_terms_by_frequency

Inner-scope wrapper for tides.tidal_terms_by_frequency

property tides

World’s Tides class instance - used to calculate all tidal parameters.

property tides_on: bool

If False, then tides will not be calculated for this world

property unique_tidal_frequencies

Inner-scope wrapper for tides.unique_tidal_frequencies

property use_nsr

Alias for self.is_spin_sync

world_class = 'simple_tidal'