SystemGeometry

class VSPEC.geometry.SystemGeometry(inclination=<Quantity 0. deg>, init_stellar_lon=<Quantity 0. deg>, init_planet_phase=<Quantity 0. deg>, stellar_period=<Quantity 80. d>, orbital_period=<Quantity 11. d>, semimajor_axis=<Quantity 0.05 AU>, planetary_rot_period=<Quantity 11. d>, planetary_init_substellar_lon=<Quantity 0. deg>, stellar_offset_amp=<Quantity 0. deg>, stellar_offset_phase=<Quantity 0. deg>, eccentricity=0, phase_of_periasteron=<Quantity 0. deg>, system_distance=<Quantity 1.3 pc>, obliquity=<Quantity 0. deg>, obliquity_direction=<Quantity 0. deg>)

Bases: object

System Geometry

Class to store and calculate information on the geometry of a star-planet-observer system.

Parameters:

• inclination (astropy.units.Quantity [angle], default=0 deg) – The inclination of the system, defined the same as in PSG. Transit is i=90 deg.

• init_stellar_lon (astropy.units.Quantity [angle], default=0 deg) – The sub-observer longitude at the beginning of observation.

• init_planet_phase (astropy.units.Quantity [angle], default=0 deg) – The planet phase at beginning of observation.

• stellar_period (astropy.units.Quantity [time], default=80 day) – The rotational period of the star.

• orbital_period (astropy.units.Quantity [time], default=11 day) – The orbital period of the planet.

• semimajor_axis (astropy.units.Quantity [distance], default=0.05 AU) – The semimajor axis of the planet’s orbit.

• planetary_rot_period (astropy.units.Quantity [time], default=11 day) – The rotational period of the planet.

• planetary_init_substellar_lon (astropy.units.Quantity [angle], default=0 deg) – The sub-stellar longitude of the planet at the beginning of observation.

• stellar_offset_amp (astropy.units.Quantity [angle], default=0 deg) – The offset between stellar rotation axis and normal to orbital plane.

• stellar_offset_phase (astropy.units.Quantity [angle], default=0 deg) – The direction of the stellar offset. 0 is defined as facing the observer, and right hand direction is positive.

• eccentricity (float, default=0) – The orbital eccentricity of the planet.

• phase_of_periasteron (astropy.units.Quantity [angle], default=0 deg) – The phase at which the planet reaches periasteron.

• system_distance (astropy.units.Quantity [distance], default=1.3 pc) – The distance to the system.

• obliquity (astropy.units.Quantity [angle], default=0 deg) – The planet obliquity magnitude.

• obliquity_direction (astropy.units.Quantity [angle], default=0 deg) – The true anomaly at which the planet’s north pole faces away from the star.

inclination

Inclination of the planet’s orbit, defined as the angle between the line of sight and the orbital plane. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

init_stellar_lon

Sub-observer longitude at the beginning of observation. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

init_planet_phase

Phase of the planet at the beginning of observation. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

stellar_period

Rotational period of the star. Default is 80 day.

Type:

astropy.units.Quantity [time]

orbital_period

Orbital period of the planet. Default is 11 day.

Type:

astropy.units.Quantity [time]

semimajor_axis

Semimajor axis of the planet’s orbit. Default is 0.05 AU.

Type:

astropy.units.Quantity [length]

planetary_rot_period

Rotational period of the planet. Default is 11 day.

Type:

astropy.units.Quantity [time]

planetary_init_substellar_lon

Sub-stellar longitude of the planet at the beginning of observation. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

alpha

Offset between the stellar rotation axis and normal to orbital plane. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

beta

Direction of the stellar offset, defined as the angle between the line connecting the observer and the system barycenter and the projection of the stellar offset vector onto the plane perpendicular to the line of sight. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

eccentricity

Eccentricity of the planet’s orbit. Default is 0.

Type:

float

phase_of_periasteron

Phase at which the planet reaches periasteron. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

system_distance

Distance to the system. Default is 1.3 pc.

Type:

astropy.units.Quantity [length]

obliquity

Obliquity of the planet, defined as the angle between the planet’s equator and its orbital plane. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

obliquity_direction

The true anomaly at which the planet’s North pole faces away from the star. Default is 0 deg.

Type:

astropy.units.Quantity [angle]

init_time_since_periasteron

Time since periasteron at the beginning of observation. Default is the time since periasteron at init_planet_phase.

Type:

astropy.units.Quantity [angle]

init_true_anomaly

True anomaly at the beginning of observation, computed from init_time_since_periasteron.

Type:

astropy.units.Quantity [angle]

Methods Summary

eccentric_anomaly(time)	Calculate the eccentric anomaly of the system at a given time
get_observation_plan(start_times)	Calculate information describing the state of the system for a series of observations.
get_pl_sub_obs_lat(phase)	Compute the sub-observer latitude of the planet.
get_pl_sub_obs_lon(time_since_periasteron, phase)	Compute the sub-observer longitude of the planet.
get_planet_visual(phase[, ax])	Draw a visualization of the planet's geometry from the view of the observer.
get_radius_coeff(phase)	Compute the orbital radius coefficient that depends on eccentricity and phase.
get_substellar_lat(phase)	Calculate the sub-stellar latitude of the planet at a particular phase.
get_substellar_lon(time_since_periasteron)	Calculate the sub-stellar longitude at a particular time since periasteron.
get_substellar_lon_at_periasteron()	Compute the sub-stellar longitude at the previous periasteron given the rotation period, orbital period, and initial substellar longitude
get_system_visual(phase[, ax])	Create a graphical representation of the host+planet geometry.
get_time_since_periasteron(phase)	Calculate the time since the last periasteron for a given phase.
mean_anomaly(time)	Get the mean anomaly of the orbit at a given time.
mean_motion()	Get the mean motion of the planet's orbit.
phase(time)	Calculate the phase at a given time.
plot(phase)	Create a plot of the geometry at a particular phase.
sub_obs(time)	Calculate the point on the stellar surface that is facing the observer.
sub_planet(time[, phase])	Get the coordinates of the sub-planet point on the star.
true_anomaly(time)	Calculate the true anomaly.

Methods Documentation

eccentric_anomaly(time)

Calculate the eccentric anomaly of the system at a given time

Parameters:

time (astropy.units.Quantity [time]) – The time elapsed since periasteron.

Returns:

The eccentric anomaly.

Return type:

astropy.units.Quantity [angle]

get_observation_plan(start_times: astropy.units.Quantity) → astropy.table.QTable

Calculate information describing the state of the system for a series of observations.

Parameters:

start_times (astropy.units.Quantity [time]) – The time of each observation.

Returns:

The geometry of each observation.

Return type:

QTable

get_pl_sub_obs_lat(phase: astropy.units.Quantity) → astropy.units.Quantity

Compute the sub-observer latitude of the planet.

Parameters:

phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

The current sub-observer latitude of the planet.

Return type:

astropy.units.Quantity [angle]

Raises:

NotImplementedError – If self.obliquity is not 0 deg.

get_pl_sub_obs_lon(time_since_periasteron: astropy.units.Quantity, phase: astropy.units.Quantity) → astropy.units.Quantity

Compute the sub-observer longitude of the planet.

Parameters:

• time_since_periasteron (astropy.units.Quantity [time]) – The time elapsed since periasteron.

• phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

The current sub-observer longitude of the planet.

Return type:

astropy.units.Quantity [angle]

get_planet_visual(phase: astropy.units.Quantity, ax=None)

Draw a visualization of the planet’s geometry from the view of the observer.

Parameters:

• phase (astropy.units.Quantity) – The current phase.

• ax (matplotlib.axes.Axes, optional) – The Axes to draw on, by default None

Returns:

The drawn figure.

Return type:

matplotlib.axes.Axes

get_radius_coeff(phase: astropy.units.Quantity) → float

Compute the orbital radius coefficient that depends on eccentricity and phase.

Parameters:

phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

The orbital radius coefficient.

Return type:

float

get_substellar_lat(phase: astropy.units.Quantity) → astropy.units.Quantity

Calculate the sub-stellar latitude of the planet at a particular phase.

Parameters:

phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

The current sub-stellar longitude of the planet.

Return type:

astropy.units.Quantity [angle]

Raises:

NotImplementedError – If self.obliquity is not 0 deg.

get_substellar_lon(time_since_periasteron) → astropy.units.Quantity

Calculate the sub-stellar longitude at a particular time since periasteron.

Parameters:

time_since_periasteron (astropy.units.Quantity [time]) – The time elapsed since periasteron.

Returns:

The current sub-stellar longitude of the planet.

Return type:

astropy.units.Quantity [angle]

Raises:

NotImplementedError – If self.obliquity is not 0 deg.

get_substellar_lon_at_periasteron() → astropy.units.Quantity

Compute the sub-stellar longitude at the previous periasteron given the rotation period, orbital period, and initial substellar longitude

Returns:

The sub-stellar longitude at periasteron.

Return type:

astropy.units.Quantity [angle]

get_system_visual(phase: astropy.units.Quantity, ax=None) → matplotlib.axes.Axes

Create a graphical representation of the host+planet geometry.

Parameters:

• phase (astropy.units.Quantity) – The current phase of the planet.

• ax (matplotlib.axes.Axes, optional) – The axis to draw the figure to, by default None.

Returns:

The axis with the graphics drawn.

Return type:

matplotlib.axes.Axes

get_time_since_periasteron(phase)

Calculate the time since the last periasteron for a given phase.

This calculation is costly, so it is prefered that the user avoid calling this function more than necessary. The output is stored as self.time_since_periasteron upon initialization, so it can be accessed easily without recalculating (so long as no attributes change).

Parameters:

phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

The time elapsed since periasteron.

Return type:

astropy.units.Quantity [time]

mean_anomaly(time)

Get the mean anomaly of the orbit at a given time.

Parameters:

time (astropy.units.Quantity [time]) – The time elapsed since periasteron.

Returns:

The mean anomaly.

Return type:

astropy.units.Quantity [angle]

mean_motion()

Get the mean motion of the planet’s orbit.

Returns:

The mean motion of the orbit.

Return type:

astropy.units.Quantity [angular frequency]

phase(time)

Calculate the phase at a given time.

Phase is defined using the PSG convention. Transit occurs at phase=180 degrees.

Parameters:

time (astropy.units.Quantity [time]) – The time elapsed since periasteron.

Returns:

The phase.

Return type:

astropy.units.Quantity [angle]

plot(phase: astropy.units.Quantity)

Create a plot of the geometry at a particular phase.

Parameters:

phase (astropy.units.Quantity [angle]) – The current phase of the planet.

Returns:

A figure containing the plot.

Return type:

matplotlib.figure.Figure

sub_obs(time)

Calculate the point on the stellar surface that is facing the observer.

Parameters:

[time] (time astropy.units.Quantity) – The time elapsed since the observation began.

Returns:

Coordinates of the sub-observer point in the form {‘lat’:lat,’lon’:lon}

Return type:

dict

sub_planet(time, phase=None)

Get the coordinates of the sub-planet point on the star.

Parameters:

• time (astropy.units.Quantity [time]) – The time elapsed since periasteron.

• phase (astropy.units.Quantity [angle], default=None) – The current phase, if known. Otherwise phase is calculated based on time. It is best practice to specify phase when possible to avoid using the Newtonian solver to calculate it.

Returns:

Coordinates of the sub-planet point in the form {‘lat’:lat,’lon’:lon}

Return type:

dict

true_anomaly(time)

Calculate the true anomaly.

Parameters:

time (astropy.units.Quantity [time]) – The time elapsed since periasteron.

Returns:

The true anomaly.

Return type:

astropy.units.Quantity [angle]