Module trajectory
This Python module is a part of the KIAM Astrodynamics Toolbox developed in Keldysh Institute of Applied Mathematics (KIAM), Moscow, Russia.
The module provides a useful and convenient a class Trajectory for the design of space trajectories. With this class, the users can propagate trajectories within the selected model of motion, perform change of variables, coordinate systems, and units systems, and visualize the trajectories and their characteristics.
The toolbox is licensed under the MIT License.
For more information see GitHub page of the project: https://github.com/shmaxg/KIAMToolbox
Functions
def dict2traj(d: dict) ‑> Trajectory
-
Converts dictionary to trajectory object.
Parameters:
d
: dictThe dictionary containing the attributes of some Trajectory object.
Returns:
tr
: TrajectoryThe Trajectory object converted from the dictionary.
def traj2dict(tr: Trajectory) ‑> dict
-
Converts trajectory object to dictionary.
Parameters:
tr
: TrajectoryThe Trajectory object needed to convert into dictionary.
Returns:
d
: dictThe dictionary containing the attributes of the given Trajectory object.
Classes
class Trajectory (initial_state: numpy.ndarray, initial_time: float, initial_jd: float, variables: str, system: str, units_name: str)
-
Initialize the Trajectory object with given initial conditions and properties.
Parameters:
initial_state
: numpy.ndarray, shape (6,), (7,), (42,)Initial state of the spacecraft.
It can be a
-
position-velocity vector ('rv'), shape (6,)
-
position-velocity-mass vector ('rvm'), shape (7,)
-
position-velocity-stm vector('rv_stm'), shape (42,)
-
equinoctial orbital elements vector ('ee'), shape (6,)
-
equinoctial orbital elements extended by mass vector ('eem'), shape (7,)
-
equinoctial orbital elements extended by stm vector ('ee_stm'), shape (42,)
-
classical orbital elements vector ('oe'), shape (6,)
-
classical orbital elements extended by mass vector ('oem'), shape (7,)
-
classical orbital elements extended by stm vector ('oe_stm'), shape (42,)
stm means state-transition matrix
The classical orbital elements:
a (semi-major axis),
e (eccentricity),
i (inclination),
Omega (right ascension of the ascending node),
omega (argument of pericenter),
theta (true anomaly)
The equinoctial orbital elements:
h, ex, ey, ix, iy, L
h = sqrt(p/mu),
ex = e*cos(Omega+omega),
ey = e*sin(Omega+omega),
ix = tan(i/2)*cos(Omega),
iy = tan(i/2)*sin(Omega),
L = theta + omega + Omega,
where
mu - gravitational parameter,
p - semi-latus rectum (focal parameter)
initial_time
: floatInitial time.
initial_jd
: floatJulian date corresponding to initial_time.
variables
: strVariables in terms of which initial_state is given.
It can be 'rv', 'rvm', 'rv_stm', 'ee', 'eem', 'ee_stm', 'oe', 'oem', 'oe_stm'.
system
: strThe coordinate system in which initial_state is given.
It can be
'scrs', 'mer', 'sors', 'ssrm_em' (the Moon-centered systems)
'gcrs', 'itrs', 'gsrf_em', 'gsrf_se' (the Earth-centered systems)
'hcrs', 'hsrf_se' (the Sun-centered systems)
'ine_fb', 'rot_fb' (first primary-centered systems in CR3BP)
'ine_sb', 'rot_sb' (second primary-centered systems in CR3BP)
'ine_cm', 'rot_cm' (baricenter-centered systems in CR3BP)
units_name
: strThe name of the units in which initial_state is given.
It can be 'earth', 'moon', 'dim', 'earth_moon', 'sun_earth'.
Properties:
control_history
: numpy.ndarray(3,n)The control history, contains 3D thrust force vectors for a controlled trajectory.
finalDate
: datetime.datetimeThe date and time of the last phase state in trajectory.
initialDate
: datetime.datetimeThe date and time of the first phase state in trajectory.
jds
: numpy.ndarray, shape(n,)Julian dates corresponding to phase vectors in states property.
model
: dictThe model used for trajectory propagation.
parts
: list[int]The nodes between which the trajectory was sequentially propagated:
tr.states[:, tr.parts[0]:tr.parts[1]+1]
– first parttr.states[:, tr.parts[1]:tr.parts[2]+1]
– second parttr.states[:, tr.parts[2]:tr.parts[3]+1]
– third partetc.
specific_impulse_history
: numpy.ndarray(n)The history of specific impulse for a controlled trajectory.
states
: numpy.array, shape(m,n)Phase vectors along the trajectory.
system
: strThe current coordinate system.
system_graph
: networkx.classes.graph.GraphThe graph of transormations between coordinate systems.
times
: numpy.array(n,)Times along the trajectory.
units
: dictThe dictionary of the current units.
units_graph
: networkx.classes.graph.GraphThe graph of transormations between units.
units_name
: strThe name of the current units.
vars
: strThe current variables.
vars_graph
: networkx.classes.digraph.DiGraphThe graph of transormations between variables.
Examples:
Examples can be found in all_examples.py.
Methods
def change_system(self, new_system: str) ‑> None
-
Change coordinate system to the specified one.
Parameters:
new_system
: strThe name of the new coordinate system.
Options:
'scrs', 'mer', 'sors', 'ssrm_em' (the Moon-centered systems)
'gcrs', 'itrs', 'gsrf_em', 'gsrf_se' (the Earth-centered systems)
'hcrs', 'hsrf_se' (the Sun-centered systems)
'mercrs', 'mersrf_smer' (the Mercury-centered systems)
'vcrs', 'vsrf_sv' (the Venus-centered systems)
'mcrs', 'msrf_sm' (the Mars-centered systems)
'jcrs', 'jsrf_sj' (the Jupiter-centered systems)
'satcrs', 'satsrf_ssat' (the Saturn-centered systems)
'ucrs', 'usrf_su' (the Uranus-centered systems)
'ncrs', 'nsrf_sn' (the Neptune-centered systems)
'ine_fb' (non-rotating frame in CR3BP, BR4BP at first primary)
'ine_cm' (non-rotating frame in CR3BP, BR4BP at barycenter)
'ine_sb' (non-rotating frame in CR3BP, BR4BP, Hill at secondary primary)
'rot_fb' (rotating frame in CR3BP, BR4BP at first primary)
'rot_cm' (rotating frame in CR3BP, BR4BP at barycenter)
'rot_sb' (rotating frame in CR3BP, BR4BP, Hill at secondary primary)
All transformations are possible within given rules:
-
The variables are 'rv', 'rvm', or 'rv_stm'.
-
Changes with variables 'rv_stm' are possible only in scrs <-> sors and scrs <-> mer translations.
Implemented transformations:
Model nbp, both systems should be from: systems_ephemeris.
Model CR3BP, both systems should be from: systems_cr3bp.
Model BR4BP, both systems should be from: systems_br4bp.
Model Hill, both systems should be from: systems_hill.
The routine automatically find the chain of transformations from the current coordinate system to the specified coordinate system.
-
def change_units(self, new_units: str) ‑> None
-
Change units to the specified ones.
Parameters:
new_units
: strThe name of the new units.
Options:
'earth', 'moon', 'dim', 'earth_moon', 'sun_earth'.
All transformations are possible.
The routine automatically find the chain of transformations from the current units to the specified units.
def change_vars(self, new_vars: str) ‑> None
-
Change variables to the specified ones.
Parameters:
new_vars
: strThe name of the new variables.
It can be 'rv', 'rvm', 'rv_stm', 'ee', 'eem', 'ee_stm', 'oe', 'oem', 'oe_stm'.
All transformations are possible with given rules:
-
units_name are 'earth' or 'moon'
-
transformations that increases the number of variables are impossible.
E.g. rv -> rvm or rv -> rv_stm transformations are impossible.
The routine automatically find the chain of transformations from the current variables to the specified variables.
-
def clear(self) ‑> None
-
Clears states, times, julian dates, parts, and resets the final date.
def copy(self, forced: bool = False)
-
Returns independent copy of the trajectory object.
Parameters:
forced : bool
If False (default), raise exception if model['control'] is not None. Do not make copy.
If True (default), erase funtion handle in model['control'] and make copy.
Returns:
If successfull, the deep copy of the Trajectory object is returned.
def propagate(self, tof: float, npoints: int = 2, atol: float = 1e-10, rtol: float = 1e-10) ‑> None
-
Propagate the trajectory.
Parameters:
tof
: floatThe time of flight in units specified by the chosen by set_model model.
The time interval will be [t0, t0 + tof].
npoints
: intThe number of nodes in the propagation time interval.
def repropagate(self, tof: float, npoints: int = 2, start_index: int = 0) ‑> None
-
Clears the calculated data in trajectory and propagate the trajectory from the beginning.
Parameters:
tof
: floatThe time of flight in units specified by the chosen by set_model model.
The time interval will be [t0, t0 + tof].
npoints
: intThe number of nodes in the propagation time interval.
start_index
: intThe number of a time node from which the trajectory should be repropagated.
At the moment, in can be only 0.
def set_model(self, variables: str, model_type, primary: str, sources_list: list) ‑> None
-
Set the model used for propagating the trajectory. It also initializes tr.model['data'] property.
Parameters:
variables
: strVariables in terms of which the equations will be chosen.
model_type
: strThe model type of the dynamics.
Options:
-
r2bp (restricted two-body problem)
-
cr3bp_fb (circular restricted three-body problem with center at the first primary body)
-
cr3bp_sb (circular restricted three-body problem with center at the secondary primary body)
-
nbp (generic n-body problem)
primary
: strThe center body or the primaries wrt which the equations will be chosen.
Options:
-
'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune' if model_type = 'r2bp'
-
'sun_[planet]' or 'earth_moon if model_type = 'cr3bp_fb' or 'cr3bp_sb'
-
'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune' if model_type = 'nbp'
sources_lits
: list of strListed sources of perturbations to be taken into account if model_type = 'nbp'.
The full list of sources:
'atm' (Earth's atmosphere, mean long term solar and geomagnetic activities)
'atm_low' (Earth's atmosphere, low long term solar and geomagnetic activities)
'atm_mean' (Earth's atmosphere, mean long term solar and geomagnetic activities)
'atm_high' (Earth's atmosphere, high long term solar and geomagnetic activities)
'j2' (Earth's J2)
'srp' (Solar radiation pressure)
'sun' (Gravitational acceleration of the Sun)
'mercury' (Gravitational acceleration of Mercury)
'venus' (Gravitational acceleration of Venus)
'earth' (Gravitational acceleration of the Earth)
'mars' (Gravitational acceleration of Mars)
'jupiter' (Gravitational acceleration of Jupiter)
'saturn' (Gravitational acceleration of Saturn)
'uranus' (Gravitational acceleration of Uranus)
'neptune' (Gravitational acceleration of Neptune)
'moon' (Gravitational acceleration of the Moon)
'cmplxmoon' (Complex gravitational acceleration of the Moon)
If
model_type
is 'cr3bp', thenmodel_specifics
is a dictionary.The dictionary contains t0 - the time at which the rotating and non-rotating coordinate systems coincide.
Returns:
A 'model' dictionary is created in a Trajectory object.
The dictionary contains the following keys.
vars
: strEquals to lowerized
variables
. It is better not to change this variable by hand.type
: strEquals to lowerized
model_type
. It is better not to change this variable by hand.primary
: strEquals to lowerized
primary
. It is better not to change this variable by hand.sources_list
: list[str]Equals to list of lowerized elements of
sources_list
. It is better not to change this variable by hand.data
: dictA dictionary that containes the following keys:
jd_zero
: floatJulian date that correscponds to t = 0. Defaulf is 0.0. Should be set by hand by the user.
area
: floatThe area of the spacecraft. Default is 0.0. Should be set by hand by the user. Used for calculation of the are-to-mass value.
mass
: floatThe mass of the spacecraft. Default is 0.0. Should be set by hand by the user. Used for calculation of the are-to-mass value.
order
: intThe order and degree of the lunar complex gravity field. Should be set by hand by the user.
Other two keys in
model
dictionary:units
: strContains the units of the model. Calculated automatically. It is better not to change this variable by hand.
control
: CallableFunction handle to the control function. The function handle should take two positional variables: time and phase state. By default is None. Can be set by the user.
-
def show(self, variables: str, draw=True, language='eng')
-
Plots the specified characteristics of the trajectory.
Parameters:
variables
: strVariables that will be plotted.
Options:
-
'xy', '3d', 'r' if self.vars in ['rv', 'rvm', 'rv_stm']
'xy' plots the trajectory in x-y axes.
'3d' plots the trajectory in 3d.
'r' plots the distance to the origin of the coordinate system.
'm' plots the mass of the spacecraft (if self.vars == 'rvm').
-
'a', 'e', 'inc', 'Om', 'w', 'th' if self.vars in ['oe', 'oem', 'oe_stm']
'a' plots the semi-major axis wrt time
'e' plots the eccentricity wrt time
'inc' plots the inclination wrt time
'Om' plots the right ascension of the ascending node wrt time
'w' plots the argument of pericenter wrt time
'th' plots the true anomaly wrt time
'm' plots the mass of the spacecraft (if self.vars == 'oem').
-
'h', 'ex', 'ey', 'ix', 'iy', 'L' if self.vars in ['ee', 'eem', 'ee_stm']
'h' plots h = sqrt(p/mu) wrt time
'ex' plots ex = e*cos(Omega+omega) wrt time
'ey' plots ey = e*sin(Omega+omega) wrt time
'ix' plots ix = tan(i/2)*cos(Omega) wrt time
'iy' plots iy = tan(i/2)*sin(Omega) wrt time
'L' plots L = theta + omega + Omega wrt time
'm' plots the mass of the spacecraft (if self.vars == 'eem').
draw
: boolIf True (by default), the fig plotly object will be returned and figure will be showed.
If False, the fig plot object will be returned and the figure will not be showed.
language
: strLanguage used for the titles.
Options: 'eng' (default), 'rus'.
Returns:
ax
: matplotlib axis objectThe matplotlib axis object for further work.
-
-