Planet class

Planet class#

class pykep.planet(udpla)#

Planet class.

This type-erasing class represents a generic object moving in space. Basically anything which can be defined by its position and velocity in some reference frame.

In order to define a planet in pykep, the user must first define a class whose methods describe the properties of the planet and allow to compute its ephemerides (position and velocity), possibly its osculating elements, etc.. In pykep, we refer to such a class as a user-defined planet, or UDPLA for short. Once defined and instantiated, a UDPLA can then be used to construct an instance of this class, the planet.

Every UDPLA must implement at least the following method:

def eph(self, epoch):
  ...

The eph() method is expected to return the Cartesian position and velocity at epoch in some chosen reference frame.

The eph() method of the UDPLA will then be accessible from the corresponding pykep.planet.eph() method (see its documentation for information on how the method should be implemented in the UDPLA and other details).

The mandatory method above allow to define a simple planet, which, in a minimal case, could actually be also just a fixed point in space, for example if its eph() method returns a constant position and zero velocity.

In order to consider more complex cases, the UDPLA may implement one or more of the following methods:

def eph_v(self, mjd2000s):
  ...
def get_mu_central_body(self):
  ...
def get_mu_self(self):
  ...
def get_radius(self):
  ...
def get_safe_radius(self):
  ...
def period(self, mjd2000):
  ...
def elements(self, mjd2000, elements_type):
  ...
def get_name(self):
  ...
def get_extra_info(self):
  ...

See the documentation of the corresponding methods in this class for details on how the optional methods in the UDPLA should be implemented and on how they are used by planet.

Args:: udpla: a user-defined planet, either C++ or Python
Raises:: NotImplementedError: if udpla does not implement the mandatory methods detailed above unspecified: any exception thrown by methods of the UDP invoked during construction, the deep copy of the UDP, the constructor of the underlying C++ class, failures at the intersection between C++ and Python (e.g., type conversion errors, mismatched function signatures, etc.)

elements(when=0., el_type=KEP_F)#

The elements of the planet at epoch.

If the UDPLA provides a elements(float, pk.el_type) method, then planet.elements will call it. Otherwise, if the UDPLA provides a get_mu_self() method planet.elements will return the elements as computed by the pykep.ic2par(). Otherwise, -1 will be returned.

Args:

when (float or epoch): the epoch at which compute the period. When a float is passed mjd2000 is assumed.

el_type (el_type): the elements type.

Returns:

list: the planet’s elements at epoch.

eph(when=0.)#

The planet ephemerides, i.e. its position and velocity.

In order to be able to construct a planet object, the user must provide his own UDPLA (User-Defined-Planet). This is a class that must implement the method:

def eph(self, mjd2000: float):
   ...
   return [[float, float, float], [float, float, float]]

Note

In the udpla, the signature for eph demands a float as epoch (mjd2000). The planet, instead, constructed from the same udpla, will also allow epoch.

Args:: when (float or epoch): the epoch at which compute the period. When a float is passed mjd2000 is assumed.
Returns:: list [list, list]: r and v, that is the final position and velocity after the propagation.

eph_v(mjd2000s)#

The planet ephemerides, i.e. position and velocity (vectorized version over many epochs).

This method is the vectorized version of its companion eph() and, in its default implementation, it just calls it in a loop. This behaviour can be changed by the user (for efficiency purposes) who can provide a more efficient version in his UDPLA by coding a method having the signature:

def eph_v(self, mjd2000s):
   ...
   return np.array((len(mjd2000s), 6))

see, for example, the python implementation of the UDPLAS tle and spice.

Args:: mjd2000s (numpy.ndarray or list): the Modified Julian Dates at which to compute the ephemerides.
Returns:: list [list, list]: r and v, that is the final position and velocity after the propagation.

property extra_info#

get_extra_info()

PLanet’s extra info.

If the UDPLA provides a get_extra_info() method, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

The string representation of a planet contains the output of a call to this method.

Returns:: str: extra info about the UDPLA
Raises:: unspecified: any exception thrown by the get_extra_info() method of the UDPLA

extract(t)#

Extract the user-defined planet.

This method allows to extract a reference to the user-defined planet (UDPLA) stored within the planet instance. The behaviour of this function depends on the value of t (which must be a type) and on the type of the internal UDPLA:

if the type of the UDPLA is t, then a reference to the UDP will be returned,
if t is object and the UDP is a Python object (as opposed to an exposed C++ planet), then a reference to the UDPLA will be returned (this allows to extract a Python UDPLA without knowing its type),
otherwise, None will be returned.

Args:

t (type): the type of the user-defined planet to extract

Returns:

a reference to the internal user-defined planet, or None if the extraction fails

Raises:

TypeError: if t is not a type

Examples:

>>> import pykep as pk
>>> udpla = pk.udpla.keplerian(pk.epoch(0), [1,0,0,0,0,0], 1)
>>> pla = pk.planet(udpla)
>>> type(pla.extract(pk.udpla.keplerian)) 
<class 'udpla._keplerian'>
>>> pla.extract(pk.udpla.jpl_lp) is None
True
>>> class my_udpla:
...     def eph(self, ep):
...         return [[1,0,0],[0,1,0]]
...     def get_name(self):
...         return "my_udpla"
...     def get_mu_central_body(self):
...         return 1.
>>> pla2 = pk.planet(my_udpla())
>>> p2.extract(object) 
<__main__.my_udpla at 0x7ff68b63d210>
>>> pla2.extract(my_udpla) 
<__main__.my_udpla at 0x7f8f7241c350>
>>> pla2.extract(pk.udpla.keplerian) is None
True

get_extra_info()#

PLanet’s extra info.

If the UDPLA provides a get_extra_info() method, then this method will return the output of its get_extra_info() method. Otherwise, an empty string will be returned.

The string representation of a planet contains the output of a call to this method.

Returns:: str: extra info about the UDPLA
Raises:: unspecified: any exception thrown by the get_extra_info() method of the UDPLA

get_mu_central_body()#

The gravitational parameter in SI units (m^3/sec^2) of a main body of attraction.

If the UDPLA provides a get_mu_central_body() method, then this method will return the output of its get_mu_central_body() method. Otherwise, -1 will be returned.

Returns:: float: the central body gravitational parameter.

get_mu_self()#

The gravitational parameter in SI units (m^3/sec^2) of the planet.

If the UDPLA provides a get_mu_self() method, then this method will return the output of its get_mu_self() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s gravitational parameter.

get_name()#

Planet’s name.

If the UDPLA provides a get_name() method, then this method will return the output of its get_name() method. Otherwise, an implementation-defined name based on the type of the UDPLA will be returned.

The string representation of a planet contains the output of a call to this method.

Returns:: str: the problem’s name

get_radius()#

An average radius in SI units (m^3/sec^2) of the planet.

If the UDPLA provides a get_radius() method, then this method will return the output of its get_radius() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s average radius.

get_safe_radius()#

The safe radius in SI units (m^3/sec^2) of the planet. This is mainly for use in planetary fly-manouvres as to avoid the planet atmosphere or circumvent its radiation environment.

If the UDPLA provides a get_safe_radius() method, then this method will return the output of its get_safe_radius() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s safe radius.

is_(t)#

Check the type of the user-defined planet.

This method returns False if extract() returns None, and True otherwise.

Args:: t (type): the type that will be compared to the type of the UDPLA
Returns:: bool: whether the UDPLA is of type t or not
Raises:: unspecified: any exception thrown by extract()

property mu_central_body#

get_mu_central_body()

The gravitational parameter in SI units (m^3/sec^2) of a main body of attraction.

If the UDPLA provides a get_mu_central_body() method, then this method will return the output of its get_mu_central_body() method. Otherwise, -1 will be returned.

Returns:: float: the central body gravitational parameter.

property mu_self#

get_mu_self()

The gravitational parameter in SI units (m^3/sec^2) of the planet.

If the UDPLA provides a get_mu_self() method, then this method will return the output of its get_mu_self() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s gravitational parameter.

property name#

get_name()

Planet’s name.

The string representation of a planet contains the output of a call to this method.

Returns:: str: the problem’s name

period(when=0.)#

The period of the planet in seconds.

If the UDPLA provides a period(float) method, planet.period will call it. Otherwise, if the UDPLA provides a get_mu_self() method planet.period will return the period as computed by the equation:

\[T = 2 \pi \sqrt{\frac{a^3}{\mu}}\]

Else, -1 will be returned.

Args:: when (float or epoch): the epoch at which compute the period. When a float is passed mjd2000 is assumed.
Returns:: float: the planet’s period.

property radius#

get_radius()

An average radius in SI units (m^3/sec^2) of the planet.

If the UDPLA provides a get_radius() method, then this method will return the output of its get_radius() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s average radius.

property safe_radius#

get_safe_radius()

The safe radius in SI units (m^3/sec^2) of the planet. This is mainly for use in planetary fly-manouvres as to avoid the planet atmosphere or circumvent its radiation environment.

If the UDPLA provides a get_safe_radius() method, then this method will return the output of its get_safe_radius() method. Otherwise, -1 will be returned.

Returns:: float: the planet’s safe radius.

Planet class

Contents

Planet class#