Module kiam
This Python module is a part of the KIAM Astrodynamics Toolbox developed in Keldysh Institute of Applied Mathematics (KIAM), Moscow, Russia.
The module serves as a safe and convenient interface to Fortran-compiled astrodynamical routines and provides instruments for performing translations between variables, coordinate systems, and time descriptions, propagating the trajectories in various models, and getting fast answers on typical questions about the two and n-body problems. It also contains some plotting routins and useful matrix linear algebra operations.
The toolbox is licensed under the MIT License.
The GitHub page of the project: https://github.com/shmaxg/KIAMToolbox.
Functions
def astro_const() ‑> tuple
-
Get astronomical constants.
Returns:
uni_const
: dictUniversal constants containing the speed of light (SoL) in km/s, astronomical unit (AU) in km, constant of gravitation (G) in km^3/kg/s^2, standard acceleration due to gravity (g0) in m/s^2, degrees in 1 radian (RAD).
star
: dictContains a dictionary that constants of the Sun: the gravitational parameter (GM) in km^3/s^2, the mean radius (MeanRadius) in km.
planet
: dictContains constants of the planets (Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune). The keys of the dictionary are the names of the planets. Eack planet[planet_name] is also a dictionary that contains the gravitational parameter of the planet (GM) in km^3/s^2, the mean raidus (MeanRadius) in km, the equator radius (EquatorRadius) in km, the semi-major axis of the orbit around the Sun (SemimajorAxis) in km. For the Earth there are additionaly the obliquity of the ecliptic (Obliquity) in degrees and its time derivative (dObliquitydt) in arcsec/cy (cy = century years).
moon
: dictContains constants of the moons (currently only of the Moon). The dictionary has a single key named Moon and moon['Moon'] is also a dictionary. That dictionary contains the gravitational parameter of the Moon (GM) in km^3/s^2, the mean raidus (MeanRadius) in km, the semi-major axis of the orbit around the Sun (SemimajorAxis) in km.
small_body
: dictContains constants of the small celestial bodies (currently only of the Pluto). The dictionary has a single key named Pluto and small_body['Pluto'] is also a dictionary. That dictionary contains the gravitational parameter of the Pluto (GM) in km^3/s^2, the mean raidus (MeanRadius) in km, the equator radius (EquatorRadius) in km, the semi-major axis of the orbit around the Sun (SemimajorAxis) in km.
Examples:
uni_const, star, planet, moon, small_body = kiam.astro_const() # If you need all the dicts _, star, planet, _, _ = kiam.astro_const() # If you need only star and planet dicts print(star['Sun']['MeanRadius']) # Mean radius of the Sun print(planet['Earth']['GM']) # Gravitational parameter of the Earth print(planet['Mars']['SemimajorAxis']) # Semi-major axis of the Mars's orbit.
def b1crs2b2crs(body1: str, body2: str, xb1crs: numpy.ndarray, jd: Union[float, numpy.ndarray], dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from one CRS c/s to another CRS c/s.
Parameters:
body1
: strThe name of the first body.
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'.
body2
: strThe name of the second (target) body.
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'.
xb1crs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the CRS coordinate system of body1.
Vector structure: [x, y, z, vx, vy, vz]
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xb1crs
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xb2crs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the CRS coordinate system of body2.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
# Example 1 (6D -> 6D): ku = kiam.units('sun', 'mars') xb1crs = numpy.array([1, 0, 0, 0, 1, 0]) # wrt the Sun jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xb2crs = kiam.b1crs2b2crs('sun', 'mars', xb1crs, jd, ku['DistUnit'], ku['VelUnit']) # wrt Mars print(xb2crs) # Example 2 (6x1 -> 6x1) ku = kiam.units('sun', 'mars') xb1crs = numpy.array([[1, 0, 0, 0, 1, 0]]).T # wrt the Sun jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xb2crs = kiam.b1crs2b2crs('sun', 'mars', xb1crs, jd, ku['DistUnit'], ku['VelUnit']) # wrt Mars print(xb2crs)
def body_surface(body: str, radius: float = 1.0, quality: str = 'medium')
-
Return figure object for showing the surface of a celestial body (Earth, Moon).
Parameters:
body
: strThe name of the celestial body.
Options: 'earth', 'moon'.
radius
: floatThe radius of the body.
Default: 1.0.
quality
: strThe quality of the image.
Options: 'high', 'medium' (default), 'low'.
Returns:
fig
: plotly.graph_objects.FigureThe Plotly figure object..
Examples:
fig = kiam.body_surface('earth') fig.show() fig = kiam.body_surface('moon') fig.show()
def box_plot(*args)
-
Creates summary statistics with boxplots.
Parameters:
*args
: Tuple[numpy.ndarray]The 1D arrays. For each of them a boxplot is created.
Returns:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Examples:
y0 = numpy.random.randn(50) - 1 y1 = numpy.random.randn(50) + 1 fig = kiam.box_plot(y0, y1) fig.show()
def cart2latlon(cart: numpy.ndarray) ‑> numpy.ndarray
-
Cartesian coordinates to latitude and longitude.
Parameters:
cart
: numpy.ndarray, shape (3,), (3, n)3D vector or array of column 3D vectors of Cartesian coordinates.
Vector structure: [x, y, z]
Returns:
latlon
: numpy.ndarray, shape (2,), (2, n)2D Vector or array of column 2D vectors of latitude and longitude pairs.
Vector structure: [lat, lon], where
lat in [-pi/2, pi/2],
lon in [-pi, pi].
Examples:
cart = numpy.array([1, 0, 0]) latlon = kiam.cart2latlon(cart) print(latlon) # [0. 0.]
def cart2sphere(cart: numpy.ndarray) ‑> numpy.ndarray
-
Cartesian coordinates to spherical coordinates.
Parameters:
cart
: numpy.ndarray, shape (3,), (3, n)3D vector or 3xn array of column 3D vectors of Cartesian coordinates
Vector structure: [x, y, z]
Returns:
sphere
: numpy.ndarray, shape (3,), (3, n)3D vector or 3xn array of column 3D vectors of spherical coordinates
Vector structure: [r, phi, theta], where
phi in [-pi, pi], theta in [0, pi], x = r*cos(theta)*cos(phi), y = r*cos(theta)*sin(phi), z = r*sin(theta).
Examples:
cart = numpy.array([1, 0, 0]) sphere = kiam.cart2sphere(cart) print(sphere) # [1. 0. 1.57079633]
def cosd(x: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Cosine of a degree argument.
Parameters:
x
: float, numpy.ndarrayAngle or an array of angles in degrees.
Returns:
s
: float, numpy.ndarrayA cosine or array of cosines of angles in degrees.
Examples:
print(kiam.cosd(60)) # 0.5000000000000001
def cotand(x: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Coangent of a degree argument.
Parameters:
x
: float, numpy.ndarrayAngle or an array of angles in degrees.
Returns:
s
: float, numpy.ndarrayA cotangent or array of cotangents of angles in degrees.
Examples:
print(kiam.cotand(45)) # 1.0000000000000002
def cr3bp_fb(t: float, s: numpy.ndarray, mu: float, stm_req: bool) ‑> numpy.ndarray
-
Right-hand side of the circular restricted three-body problem equations of motion wrt the first primary body.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing position and velocity and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[x, y, z, vx, vy, vz] if stm_req = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm_req = True
mu
: floatMass parameter of the three-body system
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
Returns:
f
: numpy.ndarray, shape (6,), (42,)Gravitational acceleration according to the circular restricted three-body model of motion wrt the first primary body extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fx, fy, fz, fvx, fvy, fvz] if stm_req = False
[fx, fy, fz, fvx, fvy, fvz, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t0 = 0.0 s0 = numpy.array([0.5, 0, 0, 0, 1, 0]) mu = 1.2e-02 dsdt = kiam.cr3bp_fb(t0, s0, mu, False) print(dsdt) # [ 0. 1. 0. -1.416 -0. -0. ]
def cr3bp_sb(t: float, s: numpy.ndarray, mu: float, stm_req: bool) ‑> numpy.ndarray
-
Right-hand side of the circular restricted three-body problem equations of motion wrt the secondary primary body.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing position and velocity and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[x, y, z, vx, vy, vz] if stm_req = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm_req = True
mu
: floatMass parameter of the three-body system
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
Returns:
f
: numpy.ndarray, shape (6,), (42,)Gravitational acceleration according to the circular restricted three-body model of motion wrt the secondary primary body extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fx, fy, fz, fvx, fvy, fvz] if stm_req = False
[fx, fy, fz, fvx, fvy, fvz, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t0 = 0.0 s0 = numpy.array([0.5, 0, 0, 0, 1, 0]) mu = 1.2e-02 dsdt = kiam.cr3bp_sb(t0, s0, mu, False) print(dsdt) # [ 0. 1. 0. 3.00088889 -0. -0. ]
def deg2rad(deg: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Degrees to radians conversion.
Parameters:
deg
: float, numpy.ndarrayAngle or array of angles in degrees.
Returns:
rad
: float, numpy.ndarrayAngle or array of angles in radians.
Examples:
print(kiam.deg2rad(180)) # 3.141592653589793
def dotainvb(a: numpy.ndarray, b: numpy.ndarray) ‑> numpy.ndarray
-
Calculate
a*b^(-1)
for matricesa
andb
.Parameters:
a
: numpy.ndarray, shape (n, n)A square matrix.
b
: numpe.ndarray, shape (n, n)A square matrix.
Returns:
c
: numpy.ndarray, shape (n, n)The matrix that equals
a*b^(-1)
Examples:
a = numpy.array([[1, 2], [3, 4]]) b = numpy.array([[1, 2], [3, 4]]) c = kiam.dotainvb(a, b) print(c) # [[1. 0.] # [0. 1.]]
def ea2ta(ea: Union[float, numpy.ndarray], ecc: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Eccentric anomaly to true anomaly.
Parameters:
ea
: float, numpy.ndarray, shape (n,)Scalar or array of eccentric anomalies.
ecc
: float, numpy.ndarray, shape (n,)Scalar or array of eccentricities. In case of array, the dimension should match the one of
ea
.Returns:
ta
: float, numpy.ndarray, shape (n,)Scalar or array of true anomalies. Domain: (-pi, pi).
If
ea
andecc
are scalars, thenta
is a scalar.If
ea
is a scalar,ecc
is a vector, thenta
is a vector of the same size asecc
.If
ea
is a vector,ecc
is a scalar, thenta
is a vector of the same size asea
.If
ea
andecc
are vectors with the same size, thenta
is a vector of the same size.Examples:
ea = numpy.array([0.0, numpy.pi]) ecc = 0.1 ta = kiam.ea2ta(ea, ecc)
def ee2rv(ee: numpy.ndarray, mu: float, grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Equinoctial orbital elements to position and velocity.
Parameters:
ee
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column vectors of equinoctial orbital elements:
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination.
mu
: floatGravitational parameter.
grad_req
: boolFlag to calculate the derivatives of position and velocity wrt elemets.
Returns:
rv
: numpy.ndarray, shape (6,), (6,n)6D phase vector or array of 6D column vectors containing position and velocity.
Vector structure: [x, y, z, vx, dy, dz].
drv
: numpy.ndarray, shape (6,6), (6,6,n)6x6 matrix or 6x6xn array of partial derivatives of rv wrt ee (drv/dee).
Returns only if
grad_req = True
.Examples:
ee = numpy.array([1, 0, 0, 0, 0, 0]) rv = kiam.ee2rv(ee, 1.0, False) rv, drv = kiam.ee2rv(ee, 1.0, True) print(rv)
def eye2vec(n: int) ‑> numpy.ndarray
-
Vector form of an identity matrix.
Parameters:
n
: intThe number of rows and columns in the identity matrix.
Returns:
a
: numpy.ndarray, shape (n**2,)Vector form of the identity matrix.
Examples:
a = kiam.eye2vec(3) print(a) # [1. 0. 0. 0. 1. 0. 0. 0. 1.]
def gcrs2hcrs(xgcrs: numpy.ndarray, jd: Union[float, numpy.ndarray], dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from GCRS c/s to HCRS c/s.
Parameters:
xgcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the GCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xgcrs
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xhcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the HCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
# Example 1 (6D -> 6D): ku = kiam.units('sun', 'earth') xgcrs = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xhcrs = kiam.gcrs2hcrs(xgcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xhcrs) # Example 2 (6x1 -> 6x1): ku = kiam.units('sun', 'earth') xgcrs = numpy.array([[1, 0, 0, 0, 1, 0]]).T jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xhcrs = kiam.gcrs2hcrs(xgcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xhcrs)
def gcrs2itrs(xgcrs: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vector from GCRS c/s to ITRS c/s.
Parameters:
xgcrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the GCRS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to column(s) in xgcrs
grad_req
: boolFlag to calculate the derivatives of the ITRS vector wrt the GCRS vector
Returns:
xitrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the ITRS coordinate system
dxitrs
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)3x3 or 6x6 matrix or 3x3xn or 6x6xn array of partial derivatives of xitrs wrt xgcrs (dxitrs/dxgcrs).
Returns only if
grad_req = True
.Examples:
jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) xgcrs = numpy.array([1, 0, 0]) xitrs = kiam.gcrs2itrs(xgcrs, jd, False) xitrs, dxitrs = kiam.gcrs2itrs(xgcrs, jd, True) print(xitrs)
def gcrs2scrs(xgcrs: numpy.ndarray, jd: Union[float, numpy.ndarray], dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from GCRS c/s to SCRS c/s.
Parameters:
xgcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the GCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz]
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xgcrs
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xscrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the SCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
# Example 1 (6D -> 6D): ku = kiam.units('earth', 'moon') xgcrs = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xscrs = kiam.gcrs2scrs(xgcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xscrs) # Example 2 (6x1 -> 6x1) ku = kiam.units('earth', 'moon') xgcrs = numpy.array([[1, 0, 0, 0, 1, 0]]).T jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xscrs = kiam.gcrs2scrs(xgcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xscrs)
def get_altitude_km(period_hours: float, body: str) ‑> float
-
Calculate the altitude of a circular orbit with a given period around a specified celestial body.
Parameters:
period
: floatThe circular orbit period in hours.
body
: strThe name of the celesial body.
Returns:
altitude_km
: floatThe altitude above the surface of the body in km.
Examples:
altitude_km = kiam.get_altitude_km(1.5, 'earth') print(altitude_km) # 281.5472668353086
def get_circular_velocity_km_s(altitude_km: float, body: str) ‑> float
-
Calculate the circular velocity at a given altitude around a specified celestial body.
Parameters:
altitude_km
: floatThe altitude above the surface of the body in km.
body
: strThe name of the celesial body.
Returns:
velocity
: floatThe circular velocity at the given altitude.
Examples:
velocity_km_s = kiam.get_circular_velocity_km_s(200.0, 'earth') print(velocity_km_s) # 7.7884829462208724
def get_dv_hohmann(r1_nondim: float, r2_nondim: float) ‑> float
-
Calculate delta-v in a Hohmann transfer.
Parameters:
r1_nondim
: floatNondimensional distance to the center of mass of the central body at the start.
r2_nondim
: floatNondimensional distance to the center of mass of the central body at the end.
Returns:
dv
: floatNondimensional delta-v in the Hohmann transfer connecting r1_nondim and r2_nondim. It is assumed that the gravitational parameter equals 1.0.
Examples:
dv = kiam.get_dv_hohmann(1.0, 2.0) print(dv) # 0.024944026382329704
def get_order(altitude_thousands_km: float, approx_level: str = 'soft') ‑> int
-
The minimum order and degree of the complex lunar gravitational field at a given altitude according to the Trofimov–Shirobokov model.
Parameters:
altitude_thousands_km
: floatThe altitude above the lunar surface in km.
approx_level
: strThe level of approximation, can be 'soft' or 'hard'.
Returns:
order
: intThe order and degree of the complex lunar gravitational field.
Examples:
order = kiam.get_order(2.0, approx_level='soft') print(order) # 8.0
def get_period_hours(altitude_km: float, body: str) ‑> float
-
Calculate the circular orbit period with a given altitude around a specified celestial body.
Parameters:
altitude_km
: floatThe altitude above the surface of the body in km.
body
: strThe name of the celesial body.
Returns:
period
: floatThe circular orbit period in hours.
Examples:
period_hours = kiam.get_period_hours(200.0, 'earth') print(period_hours) # 1.4725041134211172
def get_tof_hohmann(r1_nondim: float, r2_nondim: float) ‑> float
-
Calculate the time of flight in a Hohmann transfer.
Parameters:
r1_nondim
: floatNondimensional distance to the center of mass of the central body at the start.
r2_nondim
: floatNondimensional distance to the center of mass of the central body at the end.
Returns:
tof
: floatNondimensional time of flight in the Hohmann transfer connecting r1_nondim and r2_nondim. It is assumed that the gravitational parameter equals 1.0.
Examples:
tof = kiam.get_tof_hohmann(1.0, 2.0) print(tof) # 5.771474235728388
def grid_off(fig: plotly.graph_objs._figure.Figure)
-
Removes the grid.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.grid_off(fig) fig.show() fig = kiam.grid_on(fig) fig.show()
def grid_on(fig: plotly.graph_objs._figure.Figure)
-
Shows the grid.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.grid_off(fig) fig.show() fig = kiam.grid_on(fig) fig.show()
def hcrs2gcrs(xhcrs: numpy.ndarray, jd: Union[float, numpy.ndarray], dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from HCRS c/s to GCRS c/s.
Parameters:
xhcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the HCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xhcrs
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xgcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the GCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
# Example 1 (6D -> 6D) ku = kiam.units('sun', 'earth') xhcrs = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xgcrs = kiam.hcrs2gcrs(xhcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xgcrs) # Example 2 (6x1 -> 6x1) ku = kiam.units('sun', 'earth') xhcrs = numpy.array([[1, 0, 0, 0, 1, 0]]).T jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xgcrs = kiam.hcrs2gcrs(xhcrs, jd, ku['DistUnit'], ku['VelUnit']) print(xgcrs)
def ine2rot(xine: numpy.ndarray, t: Union[float, numpy.ndarray], t0: Union[float, numpy.ndarray]) ‑> numpy.ndarray
-
Translate phase vectors from INE c/s to ROT c/s.
Parameters:
xine
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the INE coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
t
: float, numpy.ndarray, shape (1,), (n,)Time(s) corresponding to column(s) of xine
t0
: float, numpy.ndarray, shape (1,), (n,)Time(s) of INE and ROT c/s coincidence for each column of xine.
Returns:
xrot
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the ROT coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
xine = numpy.array([1, 0, 0, 0, 1, 0]) t = 1.0 t0 = 0.0 xrot = kiam.ine2rot(xine, t, t0) print(xrot)
def ine2rot_eph(xine: numpy.ndarray, jd: Union[float, numpy.ndarray], first_body: str, secondary_body: str, dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from INEEPH c/s to ROTEPH c/s.
Parameters:
xine
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the INEEPH coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to column(s) in xine
first_body
: strName of the first primary body
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'
secondary_body
: strName of the secondary primary body
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xrot
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the ROTEPH coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
xine = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) ku = kiam.units('earth', 'moon') xrot = kiam.ine2rot_eph(xine, jd, 'earth', 'moon', ku['DistUnit'], ku['VelUnit']) print(xrot)
def invadotb(a: numpy.ndarray, b: numpy.ndarray) ‑> numpy.ndarray
-
Calculate
a^(-1)*b
for matricesa
andb
.Parameters:
a
: numpy.ndarray, shape (n, n)A square matrix.
b
: numpe.ndarray, shape (n, n)A square matrix.
Returns:
c
: numpy.ndarray, shape (n, n)The matrix that equals
a^(-1)*b
.Examples:
a = numpy.array([[1, 2], [3, 4]]) b = numpy.array([[1, 2], [3, 4]]) c = kiam.invadotb(a, b) print(c) # [[1.00000000e+00 0.00000000e+00] # [8.32667268e-17 1.00000000e+00]]
def is_visible(r_sat: numpy.ndarray, lat_deg: Union[int, float, numpy.ndarray], long_deg: Union[int, float, numpy.ndarray], body_radius: float, threshold_deg: Union[int, float, numpy.ndarray]) ‑> tuple
-
Get visibility statuses (0 or 1) of a vector from a point on a sphere surface.
Parameters:
r_sat
: numpy.ndarray, shape (3,), (3,n)Radius-vector(s) around a sphere surface
lat_deg
: int, float, numpy.ndarray, shape (m,)Latitude of a point(s) on a surface in degrees
long_deg
: int, float, numpy.ndarray, shape (m,)Longitude of a point(s) on a surface in degrees
body_radius
: floatBody radius
threshold_deg
: int, float, numpy.ndarray, shape (n,)Minimum angle below which the vector is not visible.
Returns:
status
: numpy.ndarray, shape (n,m)Visibility statuses of the r_sat vectors from lat_deg/long_deg points.
n - number of vectors in r_sat
m - number of points on the surface
elev_deg
: numpy.ndarray, shape (n,m)Elevation angles in degrees
n - number of vectors in r_sat
m - number of points on the surface
azim_deg
: numpy.ndarray, shape (n,m)Azimuth angles in degrees
n - number of vectors in r_sat
m - number of points on the surface
Examples:
r_sat = numpy.array([2, 0, 0]) lat_deg = 0.0 long_deg = 0.0 body_radius = 1.0 threshold_deg = 5.0 status, elev_deg, azim_deg = kiam.is_visible(r_sat, lat_deg, long_deg, body_radius, threshold_deg) print(status, elev_deg, azim_deg)
def itrs2gcrs(xitrs: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vector from ITRS c/s to GCRS c/s.
Parameters:
xitrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the ITRS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to column(s) of xitrs
grad_req
: boolFlag to calculate the derivatives of the GCRS vector wrt the ITRS vector
Returns:
xgcrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the GCRS coordinate system
dxgcrs
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)3x3 or 6x6 matrix or 3x3xn or 6x6xn array of partial derivatives of xgcrs wrt xitrs (dxgcrs/dxitrs).
Returns only if
grad_req = True
.Examples:
jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) xitrs = numpy.array([1, 0, 0]) xgcrs = kiam.itrs2gcrs(xitrs, jd, False) xgcrs, dxgcrs = kiam.itrs2gcrs(xitrs, jd, True) print(xgcrs)
def jd2time(jd: float) ‑> datetime.datetime
-
Julian date to usual date and time.
Parameters:
jd
: floatJulian date
Returns:
time
: datetime.datetimeDate and time object of type datetime.datetime
Examples:
print(kiam.jd2time(2459905.5)) # 2022-11-22 00:00:00
def juliandate(year: int, month: int, day: int, hour: int, minute: int, second: int) ‑> float
-
Usual date to Julian date.
Parameters:
year
: intYear
month
: intMonth
day
: intDay
hour
: intHour
minute
: intMinute
second
: intSecond
Returns:
jd
: floatJulian date
Examples:
jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) print(jd) # 2459905.5
def kepler(mean_anomaly: float, ecc: float, atol: float = 1e-10, maxiter: int = 1000) ‑> float
-
Solve the Kepler equation.
Parameters:
mean_anomaly
: floatThe mean anomaly.
ecc
: floatThe eccentricity in range [0, 1).
atol
: floatThe absolute tolerance. Newton iterations will finish when absolute difference between two successive approximations to the solution of the Kepler equation will be lower than
atol
. Default if 1E-10.maxiter
: intThe maximum number of Newton iterations. Default is 1000.
Returns:
ea
: floatEccentric anolmaly, solution to the Kepler equation E - e*sin(E) = M.
Examples:
ea = kiam.kepler(2*numpy.pi, 0.1)
def latlon2cart(latlon: numpy.ndarray) ‑> numpy.ndarray
-
Latitude and longitude to Cartesian coordinates.
Parameters:
latlon
: numpy.ndarray, shape (2,), (2, n)2D Vector or array of column 2D vectors of latitude and longitude pairs.
Vector structure: [lat, lon], where
lat in [-pi/2, pi/2],
lon in [-pi, pi]
Returns:
cart
: numpy.ndarray, shape (3,), (3, n)3D vector or array of column 3D vectors of Cartesian coordinates.
Vector structure: [x, y, z].
Examples:
latlon = numpy.array([0, 0]) cart = kiam.latlon2cart(latlon) print(cart) # [1. 0. 0.]
def leap_second_count() ‑> int
-
Returns current leap seconds count.
Returns:
leap_second_count()
: intThe current leap seconds count.
Examples:
lsc = kiam.leap_second_count() # 37 print(lsc)
def legend_off(fig: plotly.graph_objs._figure.Figure)
-
Removes the legend.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.legend_off(fig) fig.show() fig = kiam.legend_on(fig) fig.show()
def legend_on(fig: plotly.graph_objs._figure.Figure)
-
Shows the legend.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.legend_off(fig) fig.show() fig = kiam.legend_on(fig) fig.show()
def load(filename: str) ‑> Any
-
Loads a variable from a specified file.
Parameters:
filename
: strA path to the file.
Returns:
var
: AnyA variable contained in the file.
Examples:
a = kiam.load('variable_a') print(a)
def lvlh2mer(xlvlh: numpy.ndarray, lat: float, lon: float) ‑> numpy.ndarray
-
Translate phase vector(s) from LVLH c/s to MER c/s.
Parameters:
xlvlh
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the LVLH coordinate system
lat
: floatLatitude that specifies the LVLH c/s in radians
lon
: floatLongitude that specifies the LVLH c/s in radians
Returns:
xmer
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the MER coordinate system
Examples:
xlvlh = numpy.array([1, 2, 3]) lat = 0.0 lon = 1.0 xmer = kiam.lvlh2mer(xlvlh, lat, lon) print(xmer)
def mat2vec(a: numpy.ndarray) ‑> numpy.ndarray
-
Square matrix to vector form translation.
Parameters:
a
: numpy.ndarray, shape (n, n)A square matrix.
Returns:
v
: numpy.ndarray, shape (n**2,)Vector form of the matrix.
Vector structure (Fortran/MATLAB order):
[a11, a21, a31, … ]
Examples:
a = numpy.array([[1, 2], [3, 4]]) v = kiam.mat2vec(a) print(v) # [1 3 2 4]
def mer2lvlh(xmer: numpy.ndarray, lat: float, lon: float) ‑> numpy.ndarray
-
Translate phase vector(s) from MER c/s to LVLH c/s.
Parameters:
xmer
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the MER coordinate system
lat
: floatLatitude that specifies the LVLH c/s in radians
lon
: floatLongitude that specifies the LVLH c/s in radians
Returns:
xlvlh
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the LVLH coordinate system
Examples:
xmer = numpy.array([1, 2, 3]) lat = 0.0 lon = 1.0 xlvlh = kiam.mer2lvlh(xmer, lat, lon) print(xlvlh)
def mer2scrs(xmer: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vectors from MER c/s to SCRS c/s.
Parameters:
xmer
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the MER coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to vector or columns in xmer
grad_req
: boolFlag to calculate the derivatives of the SCRS vector wrt the MER vector
Returns:
xscrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SCRS coordinate system
dxscrs
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)Array of matrices of partial derivatives of xscrs wrt xmer (dxscrs/dxmer).
Returns only if
grad_req = True
.Examples:
xmer = numpy.array([1, 0, 0]) jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) xscrs = kiam.mer2scrs(xmer, jd, False) dxscrs = kiam.mer2scrs(xmer, jd, True) print(xscrs)
def nbp_ee_earth(t: float, s: numpy.ndarray, stm_req: bool, sources: dict, data: dict, units_data: dict) ‑> numpy.ndarray
-
Right-hand side of the n-body problem equations of motion wrt the Earth in terms of the equinoctial orbital elements.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing equinoctial elements and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[h, ex, ey, ix, iy, L] if stm_req = False,
[h, ex, ey, ix, iy, L, m11, m21, m31, …] if stm_req = True,
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
sources
: dictDictionary that contains the perturbations that should be accounted.
The dictionary keys:
'atm' (Earth's atmosphere)
'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 sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
For Earth's atmosphere, several levels are implemented.
If sources['atm'] == False, the atmosphere is not accounted.
If sources['atm'] == 'low', the low long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'mean', the mean long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'high', the high long term solar and geomagnetic activities are accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
data
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
units_data
: dictA dictionary that contains the units.
The dictionary keys:
'DistUnit' (The unit of distance in km)
'VelUnit' (The unit of velocity in km/s)
'TimeUnit' (The unit of time in days)
'AccUnit' (The unit of acceleration in m/s^2)
'RSun' (The radius of the Sun in the units of distance)
'REarth' (The radius of the Earth in the units of distance)
'RMoon' (The radius of the Moon in the units of distance)
'SunGM' (The nondimensional gravitational parameter of the Sun)
'MercuryGM' (The nondimensional gravitational parameter of Mercury)
'VenusGM' (The nondimensional gravitational parameter of Venus)
'EarthGM' (The nondimensional gravitational parameter of the Earth)
'MoonGM' (The nondimensional gravitational parameter of the Moon)
'MarsGM' (The nondimensional gravitational parameter of Mars)
'JupiterGM' (The nondimensional gravitational parameter of Jupiter)
'SaturnGM' (The nondimensional gravitational parameter of Saturn)
'UranusGM' (The nondimensional gravitational parameter of Uranus)
'NeptuneGM' (The nondimensional gravitational parameter of Neptune)
The units dictionary can be created by the kiam.prepare_units_dict() function.
The gravitational parameter in the specified units should be 1.0.
Returns:
f
: numpy.ndarray, shape (6,), (42,)Phase state time dericatives according to the specified n-body problem equations of motion extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fh, fex, fey, fix, fiy, fL] if stm_req = False
[fh, fex, fey, fix, fiy, fL, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t = 0.0 s = numpy.array([1, 0, 0, 0, 0, 0]) stm_req = False sources = kiam.prepare_sources_dict() data = kiam.prepare_data_dict() data['jd_zero'] = kiam.juliandate(2022, 11, 1, 0, 0, 0) data['area'] = 1.0 data['mass'] = 100.0 units_data = kiam.prepare_units_dict('earth') dsdt = kiam.nbp_ee_earth(t, s, stm_req, sources, data, units_data) print(dsdt) # [0. 0. 0. 0. 0. 1.]
def nbp_ee_moon(t: float, s: numpy.ndarray, stm_req: bool, sources: dict, data: dict, units_data: dict) ‑> numpy.ndarray
-
Right-hand side of the n-body problem equations of motion wrt the Moon in terms of the equinoctial orbital elements.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing equinoctial elements and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[h, ex, ey, ix, iy, L] if stm_req = False,
[h, ex, ey, ix, iy, L, m11, m21, m31, …] if stm_req = True,
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
sources
: dictDictionary that contains the perturbations that should be accounted. The dictionary keys:
'atm' (Earth's atmosphere)
'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 sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
For Earth's atmosphere, several levels are implemented.
If sources['atm'] == False, the atmosphere is not accounted.
If sources['atm'] == 'low', the low long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'mean', the mean long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'high', the high long term solar and geomagnetic activities are accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
data
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
units_data
: dictA dictionary that contains the units.
The dictionary keys:
'DistUnit' (The unit of distance in km)
'VelUnit' (The unit of velocity in km/s)
'TimeUnit' (The unit of time in days)
'AccUnit' (The unit of acceleration in m/s^2)
'RSun' (The radius of the Sun in the units of distance)
'REarth' (The radius of the Earth in the units of distance)
'RMoon' (The radius of the Moon in the units of distance)
'SunGM' (The nondimensional gravitational parameter of the Sun)
'MercuryGM' (The nondimensional gravitational parameter of Mercury)
'VenusGM' (The nondimensional gravitational parameter of Venus)
'EarthGM' (The nondimensional gravitational parameter of the Earth)
'MoonGM' (The nondimensional gravitational parameter of the Moon)
'MarsGM' (The nondimensional gravitational parameter of Mars)
'JupiterGM' (The nondimensional gravitational parameter of Jupiter)
'SaturnGM' (The nondimensional gravitational parameter of Saturn)
'UranusGM' (The nondimensional gravitational parameter of Uranus)
'NeptuneGM' (The nondimensional gravitational parameter of Neptune)
The units dictionary can be created by the kiam.prepare_units_dict() function.
The gravitational parameter in the specified units should be 1.0.
Returns:
f
: numpy.ndarray, shape (6,), (42,)Phase state time dericatives according to the specified n-body problem equations of motion extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fh, fex, fey, fix, fiy, fL] if stm_req = False
[fh, fex, fey, fix, fiy, fL, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t = 0.0 s = numpy.array([1, 0, 0, 0, 0, 0]) stm_req = False sources = kiam.prepare_sources_dict() data = kiam.prepare_data_dict() data['jd_zero'] = kiam.juliandate(2022, 11, 1, 0, 0, 0) data['area'] = 1.0 data['mass'] = 100.0 units_data = kiam.prepare_units_dict('moon') dsdt = kiam.nbp_ee_moon(t, s, stm_req, sources, data, units_data) print(dsdt) # [0. 0. 0. 0. 0. 1.]
def nbp_rv_body(body: str, t: float, s: numpy.ndarray, stm_req: bool, sources: dict, data: dict, units_data: dict) ‑> numpy.ndarray
-
Right-hand side of the n-body problem equations of motion wrt the specified body in terms of the position and velocity variables.
Parameters:
body
: strThe body wrt that the right-hand side of the equations of motion is calculated.
Options:
Sun
,Mercury
,Venus
,Mars
,Jupiter
,Saturn
,Uranus
,Neptune
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing position and velocity and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[x, y, z, vx, vy, vz] if stm_req = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm_req = True
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
sources
: dictDictionary that contains the perturbations that should be accounted.
The dictionary keys:
'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)
If sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
data
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
units_data
: dictA dictionary that contains the units.
The dictionary keys:
'DistUnit' (The unit of distance in km)
'VelUnit' (The unit of velocity in km/s)
'TimeUnit' (The unit of time in days)
'AccUnit' (The unit of acceleration in m/s^2)
'RSun' (The radius of the Sun in the units of distance)
'REarth' (The radius of the Earth in the units of distance)
'RMoon' (The radius of the Moon in the units of distance)
'SunGM' (The nondimensional gravitational parameter of the Sun)
'MercuryGM' (The nondimensional gravitational parameter of Mercury)
'VenusGM' (The nondimensional gravitational parameter of Venus)
'EarthGM' (The nondimensional gravitational parameter of the Earth)
'MoonGM' (The nondimensional gravitational parameter of the Moon)
'MarsGM' (The nondimensional gravitational parameter of Mars)
'JupiterGM' (The nondimensional gravitational parameter of Jupiter)
'SaturnGM' (The nondimensional gravitational parameter of Saturn)
'UranusGM' (The nondimensional gravitational parameter of Uranus)
'NeptuneGM' (The nondimensional gravitational parameter of Neptune)
The units dictionary can be created by the kiam.prepare_units_dict() function.
The gravitational parameter in the specified units should be 1.0.
Returns:
f
: numpy.ndarray, shape (6,), (42,)Gravitational acceleration according to the specified n-body problem equations of motion extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fx, fy, fz, fvx, fvy, fvz] if stm_req = False
[fx, fy, fz, fvx, fvy, fvz, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t = 0.0 s = numpy.array([1, 0, 0, 0, 1, 0]) stm_req = False sources = kiam.prepare_sources_dict() sources['jupiter'] = True data = kiam.prepare_data_dict() data['jd_zero'] = kiam.juliandate(2022, 11, 1, 0, 0, 0) data['area'] = 1.0 data['mass'] = 100.0 units_data = kiam.prepare_units_dict('sun') dsdt = kiam.nbp_rv_body('sun', t, s, stm_req, sources, data, units_data) print(dsdt)
def nbp_rv_earth(t: float, s: numpy.ndarray, stm_req: bool, sources: dict, data: dict, units_data: dict) ‑> numpy.ndarray
-
Right-hand side of the n-body problem equations of motion wrt the Earth in terms of the position and velocity variables.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing position and velocity and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[x, y, z, vx, vy, vz] if stm_req = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm_req = True
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
sources
: dictDictionary that contains the perturbations that should be accounted.
The dictionary keys:
'atm' (Earth's atmosphere)
'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 sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
For Earth's atmosphere, several levels are implemented.
If sources['atm'] == False, the atmosphere is not accounted.
If sources['atm'] == 'low', the low long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'mean', the mean long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'high', the high long term solar and geomagnetic activities are accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
data
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
units_data
: dictA dictionary that contains the units.
The dictionary keys:
'DistUnit' (The unit of distance in km)
'VelUnit' (The unit of velocity in km/s)
'TimeUnit' (The unit of time in days)
'AccUnit' (The unit of acceleration in m/s^2)
'RSun' (The radius of the Sun in the units of distance)
'REarth' (The radius of the Earth in the units of distance)
'RMoon' (The radius of the Moon in the units of distance)
'SunGM' (The nondimensional gravitational parameter of the Sun)
'MercuryGM' (The nondimensional gravitational parameter of Mercury)
'VenusGM' (The nondimensional gravitational parameter of Venus)
'EarthGM' (The nondimensional gravitational parameter of the Earth)
'MoonGM' (The nondimensional gravitational parameter of the Moon)
'MarsGM' (The nondimensional gravitational parameter of Mars)
'JupiterGM' (The nondimensional gravitational parameter of Jupiter)
'SaturnGM' (The nondimensional gravitational parameter of Saturn)
'UranusGM' (The nondimensional gravitational parameter of Uranus)
'NeptuneGM' (The nondimensional gravitational parameter of Neptune)
The units dictionary can be created by the kiam.prepare_units_dict() function.
The gravitational parameter in the specified units should be 1.0.
Returns:
f
: numpy.ndarray, shape (6,), (42,)Gravitational acceleration according to the specified n-body problem equations of motion extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fx, fy, fz, fvx, fvy, fvz] if stm_req = False
[fx, fy, fz, fvx, fvy, fvz, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t = 0.0 s = numpy.array([1, 0, 0, 0, 1, 0]) stm_req = False sources = kiam.prepare_sources_dict() data = kiam.prepare_data_dict() data['jd_zero'] = kiam.juliandate(2022, 11, 1, 0, 0, 0) data['area'] = 1.0 data['mass'] = 100.0 units_data = kiam.prepare_units_dict('earth') dsdt = kiam.nbp_rv_earth(t, s, stm_req, sources, data, units_data) print(dsdt) # [ 0. 1. 0. -1. -0. -0.]
def nbp_rv_moon(t: float, s: numpy.ndarray, stm_req: bool, sources: dict, data: dict, units_data: dict) ‑> numpy.ndarray
-
Right-hand side of the n-body problem equations of motion wrt the Moon in terms of the position and velocity variables.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,), (42,)Phase state vector containing position and velocity and (if stm_req = True) vectorized state-transition matrix.
Vector structure:
[x, y, z, vx, vy, vz] if stm_req = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm_req = True
stm_req
: boolFlag to calculate the derivative of the state-transition matrix
sources
: dictDictionary that contains the perturbations that should be accounted.
The dictionary keys:
'atm' (Earth's atmosphere)
'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 sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
For Earth's atmosphere, several levels are implemented.
If sources['atm'] == False, the atmosphere is not accounted.
If sources['atm'] == 'low', the low long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'mean', the mean long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'high', the high long term solar and geomagnetic activities are accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
data
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
units_data
: dictA dictionary that contains the units.
The dictionary keys:
'DistUnit' (The unit of distance in km)
'VelUnit' (The unit of velocity in km/s)
'TimeUnit' (The unit of time in days)
'AccUnit' (The unit of acceleration in m/s^2)
'RSun' (The radius of the Sun in the units of distance)
'REarth' (The radius of the Earth in the units of distance)
'RMoon' (The radius of the Moon in the units of distance)
'SunGM' (The nondimensional gravitational parameter of the Sun)
'MercuryGM' (The nondimensional gravitational parameter of Mercury)
'VenusGM' (The nondimensional gravitational parameter of Venus)
'EarthGM' (The nondimensional gravitational parameter of the Earth)
'MoonGM' (The nondimensional gravitational parameter of the Moon)
'MarsGM' (The nondimensional gravitational parameter of Mars)
'JupiterGM' (The nondimensional gravitational parameter of Jupiter)
'SaturnGM' (The nondimensional gravitational parameter of Saturn)
'UranusGM' (The nondimensional gravitational parameter of Uranus)
'NeptuneGM' (The nondimensional gravitational parameter of Neptune)
The units dictionary can be created by the kiam.prepare_units_dict() function.
The gravitational parameter in the specified units should be 1.0.
Returns:
f
: numpy.ndarray, shape (6,), (42,)Gravitational acceleration according to the specified n-body problem equations of motion extended (if stm_req = True) by the derivative of the state-transition matrix.
Vector structure:
[fx, fy, fz, fvx, fvy, fvz] if stm_req = False
[fx, fy, fz, fvx, fvy, fvz, fm11, fm21, fm31, … ] if stm_req = True
Examples:
t = 0.0 s = numpy.array([1, 0, 0, 0, 1, 0]) stm_req = False sources = kiam.prepare_sources_dict() data = kiam.prepare_data_dict() data['jd_zero'] = kiam.juliandate(2022, 11, 1, 0, 0, 0) data['area'] = 1.0 data['mass'] = 100.0 units_data = kiam.prepare_units_dict('moon') dsdt = kiam.nbp_rv_moon(t, s, stm_req, sources, data, units_data) print(dsdt) # [ 0. 1. 0. -1. -0. -0.]
def oe2rv(oe: numpy.ndarray, mu: float, grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Classical orbital elements to position and velocity.
Parameters:
oe
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column vectors of 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).
mu
: floatGravitational parameter.
grad_req
: boolFlag to calculate the derivatives of position and velocity wrt elements.
Returns:
rv
: numpy.ndarray, shape (6,), (6,n)6D phase vector or array of 6D column vectors containing position and velocity.
Vector structure: [x, y, z, vx, dy, dz].
drv
: numpy.ndarray, shape (6,6), (6,6,n)6x6 matrix or 6x6xn array of partial derivatives of rv wrt oe (drv/doe).
Returns only if
grad_req = True
.Examples:
oe = numpy.array([1, 0.1, 1.0, 0.0, 0.0, 0.0]) rv = kiam.oe2rv(oe, 1.0, False) rv, drv = kiam.oe2rv(oe, 1.0, True) print(rv)
def planet_state(jd: float, center: str, target: str) ‑> numpy.ndarray
-
Gives position and velocity of the planet at specified julian date wrt to the specified center (planet).
Parameters:
jd
: floatJulian date
center
: strName of the center planet
target
: strName of the target planet
Returns:
state
: numpy.ndarray, shape(6,)State of the target planet wrt the center planet.
Position in km, velocity in km/s.
Examples:
s = kiam.planet_state(kiam.juliandate(2022, 12, 3, 0, 0, 0), 'Earth', 'Moon') print(s) # [ 3.76623766e+05 7.07472988e+04 1.01213236e+04 # -1.36269070e-01 8.97864551e-01 4.72492325e-01 ]
def plot(x: numpy.ndarray, y: numpy.ndarray, fig: plotly.graph_objs._figure.Figure = None, xlabel: str = 'x', ylabel: str = 'y', name: str = '', axis_equal: bool = False, grid: str = 'on')
-
Creates a 2D line plot.
Parameters:
x
: numpy.ndarray, shape (n,)The x-axis nodes.
y
: numpt.ndarray, shape (n,)The y-axis data.
fig
: plotly.graph_objects.FigureThe Plotly figure object. If provided (not None), then the line plot will be added to the existing figure in
fig
.xlabel
: strThe x-axis label.
ylabel
: strThe y-axis label
name
: strThe name of the plot to be indicated in the legend.
'axis_equal' : bool
Sets axis to be equal. False by default.
'grid' : str
Grid option setting.
Options:
None, 'plotly' – grid used by default by plotly (not used in papers normally)
'on' – white background, black dashed grid
'off' – disables the grid
Returns:
fig
: plotly.graph_objects.FigureThe (updated) Plotly figure object.
Examples:
# Example 1 (minimal): x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig.show() # Example 2: x = numpy.array([1, 2, 3, 4, 5]) y1 = numpy.array([2, 3, 0, 1, 2]) y2 = numpy.array([3, 4, 1, 2, 3]) fig = kiam.plot(x, y1, name='blue') fig = kiam.plot(x, y2, fig, name='red') # add to the existing figure fig.show()
def plot3(x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, fig: plotly.graph_objs._figure.Figure = None, xlabel: str = 'x', ylabel: str = 'y', zlabel: str = 'z', name: str = '', axis_equal: bool = False, grid: str = 'on')
-
Creates a 3D line plot.
Parameters:
x
: numpy.ndarray, shape (n,)The x-axis data.
y
: numpt.ndarray, shape (n,)The y-axis data.
z
: numpt.ndarray, shape (n,)The z-axis data.
fig
: plotly.graph_objects.FigureThe Plotly figure object. If provided (not None), then the line plot will be added to the existing figure in
fig
.xlabel
: strThe x-axis label.
ylabel
: strThe y-axis label
zlabel
: strThe z-axis label
name
: strThe name of the plot to be indicated in the legend.
'axis_equal' : bool
Sets axis to be equal. False by default.
'grid' : str
Grid option setting.
Options:
None, 'plotly' – grid used by default by plotly (not used in papers normally)
'on' – white background, black dashed grid
'off' – disables the grid
Returns:
fig
: plotly.graph_objects.FigureThe (updated) Plotly figure object.
Examples:
# Example 1 (minimal): x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) z = numpy.array([3, 4, 1, 2, 3]) fig = kiam.plot3(x, y, z) fig.show() # Example 2: x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) z1 = numpy.array([3, 4, 1, 2, 3]) z2 = numpy.array([4, 5, 2, 3, 4]) fig = kiam.plot3(x, y, z1, name='blue') fig = kiam.plot3(x, y, z2, fig, name='red') fig.show()
def polar_plot(r: numpy.ndarray, theta_deg: numpy.ndarray, mode: str = 'lines')
-
Plots a line in polar coordinates.
Parameters:
r
: numpy.ndarray, shape (n,)The radiuses.
theta_deg
: numpy.ndarray, shape (n,)The angles in degrees.
mode
: strThe line display mode.
Options: 'lines' (default), 'markers', 'lines+markers'
Returns:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Examples:
r = numpy.array([0.5, 1, 2, 2.5, 3, 4]) theta = numpy.array([35, 70, 120, 155, 205, 240]) fig = kiam.polar_plot(r, theta) fig.show()
def prepare_data_dict() ‑> dict
-
Auxilary function that returns a dictionary of data.
Returns:
data : dict
The data structure used in right-hand side of the equations of motion.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
All the values are assigned to zero.
Examples:
print(kiam.prepare_data_dict()) # {'jd_zero': 0.0, 'order': 0, 'area': 0.0, 'mass': 0.0}
def prepare_sources_dict() ‑> dict
-
Auxilary function that returns a dictionary of perturbations.
Returns:
sources
: dictThe dictionary keys:
'atm' (Earth's atmosphere)
'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)
Examples:
print(kiam.prepare_sources_dict()) # {'sun': False, 'mercury': False, 'venus': False, 'earth': False, 'moon': False, 'mars': False, 'jupiter': False, 'saturn': False, 'uranus': False, 'neptune': False, 'srp': False, 'cmplxmoon': False, 'atm': False, 'j2': False}
def prepare_units_dict(units_name: str) ‑> dict
-
Auxilary function that returns a dictionary of units.
Parameters:
units_name
: strA name of the units that should be used.
Options:
'dim': a dictionary with unity values will be returned
'earth': a dictionary of the earth units will be returned
'moon': a dictionary of the moon units will be returned
Returns:
units_dict
: dictA dictionary that containes the following keys:
'DistUnit': the unit of distance, km
'VelUnit': the unit of velocity, km/s
'TimeUnit': the unit of time, days
'AccUnit': the units of acceleration, m/s^2
'RSun': the mean radius of the Sun in DistUnit units
'REarth': the mean radius of the Earth in DistUnit units
'RMoon': the mean radius of the Moon in DistUnit units
Examples:
print(kiam.prepare_units_dict('earth')) # {'DistUnit': 6371.0084, 'VelUnit': 7.909787126714006, 'TimeUnit': 0.009322440916154166, 'AccUnit': 9.820224438870717, 'RSun': 109.19778413728038, 'REarth': 1.0, 'RMoon': 0.27270408244949107}
def propagate_br4bp(central_body: str, tspan: numpy.ndarray, x0: numpy.ndarray, mu: float, gm4b, a4b: float, theta0: float, stm: bool, atol: float = 1e-10, rtol: float = 1e-10) ‑> tuple
-
Propagate trajectory in the bi-circular restricted four-body model of motion.
Parameters:
central_body
: strFirst or secondary primary body or baricenter as the origin of the coordinate system
Options: 'first', 'secondary', 'center'
tspan
: numpy.ndarray, shape (n,)Time nodes at which the solution is required
x0
: numpy.ndarray, shape (6,), (42,)Initial state containing:
position and velocity (if stm = False),
position and velocoty extended by vectorized state-transition matrix (if stm = True),
Vectory structure:
[x, y, z, vx, vy, vz] if stm = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm = True
mu
: floatMass parameter of the three-body system
gm4b
: floatScaled gravitational parameter of the fourth (perturbing) body
a4b
: floatDistance from the center of mass of the primary bodies to the fourth body in units where the distance between the primaries equals 1.
theta0
: floatInitial value of the synodic phase - the angle between the direction to the fourth body from the center of mass of the primaries and the line connecting the primaties.
stm
: boolFlag to calculate the derivative of the state-transition matrix.
atol
: floatAbsolute tolerance when integrating the equations. Default is 1e-10.
rtol
: floatRelative tolerance when integrating the equations. Default is 1e-10.
Returns:
t
: numpy.ndarray, shape(n,)Times (nodes) in tspan at which the solution is obtained.
y
: numpy.ndarray, shape(6, n)Array of column trajectory phase states.
Vector structure:
[x, y, z, vx, vy, vz] if stm = False.
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm = True.
Examples:
central_body = 'first' tspan = numpy.linspace(0, 10, 1000) x0 = numpy.array([0.5, 0, 0, 0, 0.5, 0]) mu = 1.215e-02 stm = False gm4b = 3.289005596e+05 a4b = 389.170375544352 theta0 = 0.0 t, y = kiam.propagate_br4bp(central_body, tspan, x0, mu, gm4b, a4b, theta0, stm) print(t[-1], y[:, -1])
def propagate_cr3bp(central_body: str, tspan: numpy.ndarray, x0: numpy.ndarray, mu: float, stm: bool, atol: float = 1e-10, rtol: float = 1e-10) ‑> tuple
-
Propagate trajectory in the circular restricted three-body model of motion.
Parameters:
central_body
: strFirst or secondary primary body or barycenter as the origin of the coordinate system
Options: 'first', 'secondary', 'center'
tspan
: numpy.ndarray, shape (n,)Time nodes at which the solution is required
x0
: numpy.ndarray, shape (6,), (42,)Initial state containing:
position and velocity (if stm = False),
position and velocoty extended by vectorized state-transition matrix (if stm = True),
Vectory structure:
[x, y, z, vx, vy, vz] if stm = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm = True
mu
: floatMass parameter of the three-body system
stm
: boolFlag to calculate the derivative of the state-transition matrix
atol
: floatAbsolute tolerance when integrating the equations. Default is 1e-10.
rtol
: floatRelative tolerance when integrating the equations. Default is 1e-10.
Returns:
t
: numpy.ndarray, shape(n,)Times (nodes) in tspan at which the solution is obtained
y
: numpy.ndarray, shape(6, n)Array of column trajectory phase states.
Vector structure:
[x, y, z, vx, vy, vz] if stm = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if stm = True
Examples:
central_body = 'first' tspan = numpy.linspace(0, 10, 1000) x0 = numpy.array([0.5, 0, 0, 0, 0.5, 0]) mu = 1e-02 stm = False t, y = kiam.propagate_cr3bp(central_body, tspan, x0, mu, stm) print(t[-1], y[:, -1])
def propagate_hill(tspan: numpy.ndarray, x0: numpy.ndarray, atol: float = 1e-10, rtol: float = 1e-10) ‑> tuple
-
Propagate trajectory in Hill's model of motion.
Parameters:
tspan
: numpy.ndarray, shape (n,)Time nodes at which the solution is required
x0
: numpy.ndarray, shape (6,)Initial state containing position and velocity.
Vector structure: [x, y, z, vx, vy, vz]
Returns:
t
: numpy.ndarray, shape(n,)Times (nodes) in tspan at which the solution is obtained
y
: numpy.ndarray, shape(6, n)Array of column trajectory phase states.
Vector structure: [x, y, z, vx, vy, vz].
atol
: floatAbsolute tolerance when integrating the equations. Default is 1e-10.
rtol
: floatRelative tolerance when integrating the equations. Default is 1e-10.
Examples:
tspan = numpy.linspace(0, 2*numpy.pi, 1000) x0 = numpy.array([-0.5, 0, 0, 0, 2.0, 0]) t, y = kiam.propagate_hill(tspan, x0) print(t[-1], y[:, -1])
def propagate_nbp(central_body: str, tspan: numpy.ndarray, x0: numpy.ndarray, sources_dict: dict, dat_dict: dict, units_dict: dict, stm: bool, variables: str, atol: float = 1e-10, rtol: float = 1e-10, control_function: Callable = None) ‑> tuple
-
Propagate trajectory in the n-body model of motion.
Parameters:
central_body
: strName of the central body
tspan
: numpy.ndarray, shape (n,)Time nodes at which the solution is required
x0
: numpy.ndarray, shape (6,), (42,)Initial state containing:
position and velocity (if variables = 'rv', stm = False),
position and velocoty extended by vectorized state-transition matrix (if variables = 'rv_stm', stm = True),
equinoctial orbital elements (if variables = 'ee', stm = False),
equinoctial orbital elements extended by vectorized state-transition matrix (if variables = 'ee_stm', stm = True),
Vector structure:
[x, y, z, vx, vy, vz] if variables = 'rv' and stm = False
[x, y, z, vx, vy, vz, m11, m21, m31, …] if variables = 'rv_stm' and stm = True
[h, ex, ey, ix, iy, L] if variables = 'ee' and stm = False
[h, ex, ey, ix, iy, L, m11, m21, m31, …] if variables = 'ee_stm' and stm = True
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination
sources_dict
: dictDictionary that contains the perturbations that should be accounted.
The dictionary keys:
'atm' (Earth's atmosphere)
'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 sources[key] = True, the corresponding perturbation will be accounted.
If sources[key] = False, the corresponding perturbation will not be accounted.
For Earth's atmosphere, several levels are implemented.
If sources['atm'] == False, the atmosphere is not accounted.
If sources['atm'] == 'low', the low long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'mean', the mean long term solar and geomagnetic activities are accounted.
If sources['atm'] == 'high', the high long term solar and geomagnetic activities are accounted.
The sources dictionary with all False values can be created by the kiam.prepare_sources_dict() function.
dat_dict
: dictA dictionary that contains auxilary data.
The dictionary keys:
'jd_zero' (Julian date that corresponds to t = 0)
'order' (Order of the lunar complex gravitational field)
'area' (Area of the spacecraft to account in atmospheric drag and SRP, m^2)
'mass' (Mass of the spacecraft to account in atmospheric drag and SRP, kg)
The data should be submitted even if the corresponding perturbations are not accounted.
'units_dict' : dict
A dictionary that contains the units of distance, velocity, time, acceleration, and the gravitational parameters of the bodies.
This variable can be generated by kiam.prepare_units_dict function.
stm
: boolFlag to calculate the derivative of the state-transition matrix
variables
: strType of variables used to propagate the trajectory.
If stm = False, then variables should be 'rv' or 'ee'.
If stm = True, then variables should be 'rv_stm' or 'ee_stm'.
control_function
: CallableThe control function that returns force vector, specific impulse and (if stm is True) force vector time derivative,
force vector state derivative, specific impulce time derivative, specific impulse state derivative. The control function
should take two arguments: the time and the phase state that corresponds to
variables
.None by default.
atol
: floatAbsolute tolerance when integrating the equations. Default is 1e-10.
rtol
: floatRelative tolerance when integrating the equations. Default is 1e-10.
Returns:
t
: numpy.ndarray, shape(n,)Times (nodes) in tspan at which the solution is obtained
y
: numpy.ndarray, shape(6, n), shape(42, n)Array of column trajectory phase states extended (if stm = True) by vectorized state-transition matrices.
Vector structure:
[x, y, z, vx, vy, vz] if stm = False and variables = 'rv'
[x, y, z, vx, vy, vz, m11, m21, m31, … ] if stm = True and variables = 'rv_stm'
[h, ex, ey, ix, iy, L] if stm = False and variables = 'ee'
[h, ex, ey, ix, iy, L, m11, m21, m31, … ] if stm = True and variables = 'ee_stm'
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination
Examples:
central_body = 'earth' tspan = numpy.linspace(0, 100, 10000) x0 = numpy.array([1, 0, 0, 0, 1, 0]) sources_dict = kiam.prepare_sources_dict() dat_dict = kiam.prepare_data_dict() units_dict = kiam.prepare_units_dict('earth') stm = False variables = 'rv' t, y = kiam.propagate_nbp(central_body, tspan, x0, sources_dict, dat_dict, units_dict, stm, variables) print(t[-1], y[:, -1])
Examples with using the control function can be found on GitHub: https://github.com/shmaxg/KIAMToolbox/tree/master/examples
def propagate_r2bp(tspan: numpy.ndarray, x0: numpy.ndarray, atol: float = 1e-10, rtol: float = 1e-10) ‑> tuple
-
Propagate trajectory in the two-body model of motion.
Parameters:
tspan
: numpy.ndarray, shape (n,)Time nodes at which the solution is required
x0
: numpy.ndarray, shape (6,)Initial state containing position and velocity.
Vector structure: [x, y, z, vx, vy, vz]
Returns:
t
: numpy.ndarray, shape(n,)Times (nodes) in tspan at which the solution is obtained
y
: numpy.ndarray, shape(6, n)Array of column trajectory phase states.
Vector structure: [x, y, z, vx, vy, vz].
atol
: floatAbsolute tolerance when integrating the equations. Default is 1e-10.
rtol
: floatRelative tolerance when integrating the equations. Default is 1e-10.
Examples:
tspan = numpy.linspace(0, 100, 10000) x0 = numpy.array([1, 0, 0, 0, 1, 0]) t, y = kiam.propagate_r2bp(tspan, x0) print(t[-1], y[:, -1])
def r2bp(t: float, s: numpy.ndarray) ‑> numpy.ndarray
-
Right-hand side of the restricted two-body problem equations of motion.
Parameters:
t
: floatTime
s
: numpy.ndarray, shape (6,)Phase state vector containing position and velocity.
Vector structure [x, y, z, vx, vy, vz].
Returns:
f
: numpy.ndarray, shape (6,)Gravity acceleration according to the two-body model.
Vector structure [fx, fy, fz, fvx, fvy, fvz].
Examples:
t0 = 0.0 s0 = numpy.array([1, 0, 0, 0, 1, 0]) print(kiam.r2bp(t0, s0)) # [ 0. 1. 0. -1. -0. -0.]
def rad2deg(rad: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Radians to degrees conversion.
Parameters:
rad
: float, numpy.ndarrayAngle or array of angles in radians.
Returns:
deg
: float, numpy.ndarrayAngle or array of angles in degrees.
Examples:
print(kiam.rad2deg(3.141592)) # 179.99996255206332
def rot2ine(xrot: numpy.ndarray, t: Union[float, numpy.ndarray], t0: Union[float, numpy.ndarray]) ‑> numpy.ndarray
-
Translate phase vectors from ROT c/s to INE c/s.
Parameters:
xrot
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the ROT coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
t
: float, numpy.ndarray, shape (n,)Time(s) corresponding to column(s) of xrot
t0
: float, numpy.ndarray, shape (1,), (n,)Time(s) of of INE and ROT c/s coincidence for each column of xrot.
Returns:
xine
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the INE coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
xrot = numpy.array([1, 0, 0, 0, 0, 0]) t = 1.0 t0 = 0.0 xine = kiam.rot2ine(xrot, t, t0) print(xine)
def rot2ine_eph(xrot: numpy.ndarray, jd: Union[float, numpy.ndarray], first_body: str, secondary_body: str, dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from ROTEPH c/s to INEEPH c/s.
Parameters:
xrot
: numpy.ndarray, shape (6,), (6,n)6D vector array or 6D column phase vectors in the ROTEPH coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to column(s) in xrot
first_body
: strName of the first primary body
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'
secondary_body
: strName of the secondary primary body
Options: 'sun', 'mercury', 'venus', 'earth', 'moon', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune'
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xine
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the INEEPH coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
xrot = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) ku = kiam.units('earth', 'moon') xine = kiam.ine2rot_eph(xrot, jd, 'earth', 'moon', ku['DistUnit'], ku['VelUnit']) print(xine)
def rv2ee(rv: numpy.ndarray, mu: float, grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Position and velocity to equinoctial orbital elements.
Parameters:
rv
: numpy.ndarray, shape (6,), (6,)6D phase vector or array of 6D column vectors containing position and velocity.
Vector structure: [x, y, z, vx, dy, dz]
mu
: floatGravitational parameter
grad_req
: boolFlag to calculate the derivatives of elements wrt position and velocity
Returns:
ee
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column vectors of equinoctial orbital elements:
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),
e - eccentricity,
Omega - right ascension of the ascending node,
omega - argument of pericenter,
i - inclination.
dee
: numpy.ndarray, shape (6,6), (6,6,n)6x6 matrix or 6x6xn array of partial derivatives of ee wrt rv (dee/drv).
Returns only if
grad_req = True
.Examples:
rv = numpy.array([1, 0, 0, 0, 1, 0]) ee = kiam.rv2ee(rv, 1.0, False) ee, dee = kiam.rv2ee(rv, 1.0, True) print(ee)
def rv2oe(rv: numpy.ndarray, mu: float, grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Position and velocity to classical orbital elements.
Parameters:
rv
: numpy.ndarray, shape (6,), (6,n)6D phase vector or array of column 6D phase vectors containing position and velocity.
Vector structure:
[x, y, z, vx, dy, dz]
.mu
: floatGravitational parameter.
grad_req
: boolFlag to calculate the derivatives of elements wrt position and velocity.
Returns:
oe
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column vectors of 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)
doe
: numpy.ndarray, shape (6,6), (6,6,n)6x6 matrix or 6x6xn array of partial derivatives of oe wrt rv (doe/drv).
Returns only if
grad_req = True
.Examples:
rv = numpy.array([1, 0, 0, 0.1, 1, 0.1]) oe = kiam.rv2oe(rv, 1.0, False) oe, doe = kiam.rv2oe(rv, 1.0, True) print(oe)
def save(variable: Any, filename: str) ‑> None
-
Saves a variable into a specified file.
Parameters:
variable
: AnyVariable to be saved.
For limitations on variables see the pickle package https://docs.python.org/3/library/pickle.html
filename
: strA path to the file.
Examples:
a = numpy.random.rand(10, 10) kiam.save(a, 'variable_a')
def save_figure(fig: plotly.graph_objs._figure.Figure, filename: str)
-
Saves the figure as an interactive html file.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
filename
: strThe file name (or file path) with extension to which the figure should be saved.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) kiam.save_figure(fig, 'myfig.html')
def save_image(fig: plotly.graph_objs._figure.Figure, filename: str, scale: int = 2)
-
Saves the figure as a static image (PNG, PDF, etc).
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
filename
: strThe file name (or file path) with extension to which the figure should be saved.
scale
: intThe scale parameter controls dpi. Default is 2.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) kiam.save_image(fig, 'myfig.png')
def scrs2gcrs(xscrs: numpy.ndarray, jd: Union[float, numpy.ndarray], dist_unit: float, vel_unit: float) ‑> numpy.ndarray
-
Translate phase vectors from SCRS c/s to GCRS c/s.
Parameters:
xscrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the SCRS coordinate system
Vector structure: [x, y, z, vx, vy, vz]
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xscrs
dist_unit
: floatThe unit of distance in km
vel_unit
: floatThe unit of velocity in km/s
Returns:
xgcrs
: numpy.ndarray, shape (6,), (6,n)6D vector or array of 6D column phase vectors in the GCRS coordinate system.
Vector structure: [x, y, z, vx, vy, vz].
Examples:
# Example 1 (6D -> 6D): ku = kiam.units('earth', 'moon') xscrs = numpy.array([1, 0, 0, 0, 1, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xgcrs = kiam.scrs2gcrs(xscrs, jd, ku['DistUnit'], ku['VelUnit']) print(xgcrs) # Example 2 (6x1 -> 6x1): ku = kiam.units('earth', 'moon') xscrs = numpy.array([[1, 0, 0, 0, 1, 0]]).T jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xgcrs = kiam.scrs2gcrs(xscrs, jd, ku['DistUnit'], ku['VelUnit']) print(xgcrs)
def scrs2mer(xscrs: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vectors from SCRS c/s to MER c/s.
Parameters:
xscrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SCRS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to vector or columns in xscrs
grad_req
: boolFlag to calculate the derivatives of the MER vector wrt the SCRS vector
Returns:
xmer
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the MER coordinate system.
dxmer
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)Matrix or array of matrices of partial derivatives of xmer wrt xscrs (dxmer/dxscrs).
Returns only if
grad_req = True
.Examples:
xscrs = numpy.array([1, 0, 0]) jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) xmer = kiam.scrs2mer(xscrs, jd, False) dxmer = kiam.scrs2mer(xscrs, jd, True) print(xmer)
def scrs2pa(xscrs: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vector from SCRS c/s to PA c/s.
Parameters:
xscrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SCRS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian date(s) corresponding to column(s) in xscrs
grad_req
: boolFlag to calculate the derivatives of the PA vector wrt the SCRS vector
Returns:
xpa
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the PA coordinate system
dxpa
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)3x3 or 6x6 matrix or 3x3xn or 6x6xn array of partial derivatives of xpa wrt xscrs (dxpa/dxscrs).
Returns only if
grad_req = True
.Examples:
jd = kiam.juliandate(2022, 11, 22, 0, 0, 0) xscrs = numpy.array([1, 0, 0]) xpa = kiam.scrs2pa(xscrs, jd, False) xpa, dxpa = kiam.scrs2pa(xscrs, jd, True) print(xpa)
def scrs2sors(xscrs: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vectors from SCRS c/s to SORS c/s.
Parameters:
xscrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SCRS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xscrs
grad_req
: boolFlag to calculate the derivatives of the SORS vector wrt the SCRS vector
Returns:
xsors
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SORS coordinate system
dxsors
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)Matrix or array of matrices of partial derivatives of xsors wrt xscrs (dxsors/dxscrs).
Returns only if
grad_req = True
.Examples:
xscrs = numpy.array([1, 0, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xsors = kiam.scrs2sors(xscrs, jd, False) xsors, dxsors = kiam.scrs2sors(xscrs, jd, True) print(xsors)
def set_axis_equal(fig: plotly.graph_objs._figure.Figure)
-
Sets axis to be equal.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.set_axis_equal(fig) fig.show()
def set_default_grid(fig: plotly.graph_objs._figure.Figure)
-
Sets the default grid.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.grid_off(fig) fig.show() fig = kiam.set_default_grid(fig) fig.show()
def set_xlabel(fig: plotly.graph_objs._figure.Figure, xlabel: str)
-
Set a custom x-axis label.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
xlabel
: strThe new x-axis label.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Only Scatter and Scatter3d figure datatypes supported.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.set_xlabel(fig, 'x variable') fig.show()
def set_ylabel(fig: plotly.graph_objs._figure.Figure, ylabel: str)
-
Set a custom y-axis label.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter and Scatter3d figure types are supported.
ylabel
: strThe new y-axis label.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot(x, y) fig = kiam.set_ylabel(fig, 'y variable') fig.show()
def set_zlabel(fig: plotly.graph_objs._figure.Figure, zlabel: str)
-
Set a custom y-axis label.
Parameters:
fig
: plotly.graph_objects.FigureThe Plotly figure object.
Only Scatter3d figure types are supported.
zlabel
: strThe new z-axis label.
Returns:
fig
: plotly.graph_objects.FigureThe updated Plotly figure object.
Examples:
x = numpy.array([1, 2, 3, 4, 5]) y = numpy.array([2, 3, 0, 1, 2]) z = numpy.array([2, 3, 0, 1, 2]) fig = kiam.plot3(x, y, z) fig = kiam.set_zlabel(fig, 'z variable') fig.show()
def sind(x: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Sine of a degree argument.
Parameters:
x
: float, numpy.ndarrayAngle or an array of angles in degrees.
Returns:
s
: float, numpy.ndarrayA sine or array of sines of angles in degrees.
Examples:
print(kiam.sind(30)) # 0.49999999999999994
def sors2scrs(xsors: numpy.ndarray, jd: Union[float, numpy.ndarray], grad_req: bool = False) ‑> Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]
-
Translate vectors from SORS c/s to SCRS c/s.
Parameters:
xsors
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SORS coordinate system
jd
: float, numpy.ndarray, shape (n,)Julian dates corresponding to columns in xsors
grad_req
: boolFlag to calculate the derivatives of the SCRS vector wrt the SORS vector
Returns:
xscrs
: numpy.ndarray, shape (3,), (6,), (3,n), (6,n)3D vector, 6D vector or array of 3D or 6D column vectors in the SCRS coordinate system
dxscrs
: numpy.ndarray, shape (3,3), (6,6), (3,3,n), (6,6,n)Matrix or array of matrices of partial derivatives of xscrs wrt xsors (dxscrs/dxsors).
Returns only if
grad_req = True
.Examples:
xsors = numpy.array([1, 0, 0]) jd = kiam.juliandate(2022, 12, 6, 0, 0, 0) xscrs = kiam.sors2scrs(xsors, jd, False) xscrs, dxscrs = kiam.sors2scrs(xsors, jd, True) print(xscrs)
def sphere2cart(sphere: numpy.ndarray) ‑> numpy.ndarray
-
Spherical coordinates to Cartesian coordinates.
Parameters:
sphere
: numpy.ndarray, shape (3,), (3, n)3D vector or 3xn array of column 3D vectors of spherical coordinates
Vector structure: [r, phi, theta], where
phi in [-pi, pi], theta in [0, pi], x = r*cos(theta)*cos(phi), y = r*cos(theta)*sin(phi), z = r*sin(theta)
Returns:
cart
: numpy.ndarray, shape (3,), (3, n)3D vector or 3xn array of column 3D vectors of Cartesian coordinates.
Vector structure: [x, y, z].
Examples:
sphere = numpy.array([1, 0, 0]) cart = kiam.sphere2cart(sphere) print(cart) # [0. 0. 1.]
def sphere_coordinates(radius: float, nlat: int, nlon: int)
-
Get x, y, z coordinates on a sphere.
Parameters:
radius
: floatThe radius of the sphere.
nlat
: intThe number of latitude angles in a grid.
nlon
: intThe number of longitude angles in a grid.
Returns:
x
: numpy.ndarray, shape(nlat, nlon)The x-coordinates.
y
: numpy.ndarray, shape(nlat, nlon)The y-coordinates.
z
: numpy.ndarray, shape(nlat, nlon)The z-coordinates.
Examples:
x, y, z = kiam.sphere_coordinates(1.0, 100, 100)
def ta2ea(ta: Union[float, numpy.ndarray], ecc: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
True anomaly to eccentric anomaly.
Parameters:
ta
: float, numpy.ndarray, shape (n,)Scalar or array of true anomalies.
ecc
: float, numpy.ndarray, shape (n,)Scalar or array of eccentricities. In case of array, the dimension should match the one of
ta
.Returns:
ea
: float, numpy.ndarray, shape (n,)Scalar or array of eccentric anomalies. Domain: (-pi, pi).
If
ta
andecc
are scalars, thenea
is a scalar.If
ta
is a scalar,ecc
is a vector, thenea
is a vector of the same size asecc
.If
ta
is a vector,ecc
is a scalar, thenea
is a vector of the same size asta
.If
ta
andecc
are vectors with the same size, thenea
is a vector of the same size.Examples:
ta = numpy.array([0.0, numpy.pi]) ecc = 0.1 ea = kiam.ta2ea(ta, ecc)
def tai2utc(tai: datetime.datetime) ‑> datetime.datetime
-
TAI to UTC conversion.
Parameters:
tai
: datetime.datetimeThe International Atomic Time (TAI).
Returns:
utc
: datetime.datetimeThe Coordinated Universal Time (UTC).
Examples:
tai = datetime.datetime(2023, 3, 8, 12, 0, 0) # 2023-03-18 12:00:00 utc = kiam.tai2utc(tai) # 2023-03-08 11:59:27.816000 print(utc)
def tand(x: Union[float, numpy.ndarray]) ‑> Union[float, numpy.ndarray]
-
Tangent of a degree argument.
Parameters:
x
: float, numpy.ndarrayAngle or an array of angles in degrees.
Returns:
s
: float, numpy.ndarrayA tangent or array of tangents of angles in degrees.
Examples:
print(kiam.tand(45)) 0.9999999999999999
def time2jd(time: datetime.datetime) ‑> float
-
Usual date and time to Julian date.
Parameters:
time
: datetime.datetimeDate and time object of type datetime.datetime
Returns:
jd
: floatJulian date
Examples:
jd = kiam.time2jd(datetime.datetime(2022, 11, 22, 0, 0, 0, 0)) print(jd) # 2459905.5
def to_float(*args: Any) ‑> tuple
-
Convert all arguments to the float64 type.
Parameters:
*args
Arguments separated by comma to convert to float64.
Returns:
float_args
: tupleTuple of numpy arrays with components converted to
float64
arguments.Examples:
f = kiam.to_float([1, 2], 3, [4, 5, 6]) print(f) # (array([1., 2.]), array(3.), array([4., 5., 6.]))
def tt2utc(tt: datetime.datetime) ‑> datetime.datetime
-
TT to UTC conversion.
Parameters:
tt
: datetime.datetimeThe Terrestrial Time (TT).
Returns:
utc
: datetime.datetimeThe Coordinated Universal Time (UTC).
Examples:
tt = datetime.datetime(2023, 3, 8, 12, 0, 0) # 2023-03-18 12:00:00 utc = kiam.tt2utc(tt) # 2023-03-08 11:58:50.816000 print(utc)
def units(*args: str) ‑> dict
-
Get units of distance, velocity, time, and gravitational parameters.
Parameters:
*args
Name or a pair of names of a celestial bodies
Options for a single argument: 'earth', 'moon', 'sun', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', 'pluto'
Options for two arguments: ('earth', 'moon'), ('sun', 'earth')
Returns:
units_dict
: dictA dictionary containing the units of distance, velocity, and time.
'DistUnit'
– the unit of distance, km'VelUnit'
– the unit of velocity, km/s'TimeUnit'
– the unit of time, days'AccUnit'
– the unit of acceleration, m/s^2'SunGM'
– the nondimensional gravitational parameter of the Sun'MercuryGM'
– the nondimensional gravitational parameter of Mercury'VenusGM'
– the nondimensional gravitational parameter of Venus'EarthGM'
– the nondimensional gravitational parameter of the Earth'MoonGM'
– the nondimensional gravitational parameter of the Moon'EarthMoonGM'
– the nondimensional gravitational parameter of the Earth+Moon system'MarsGM'
– the nondimensional gravitational parameter of Mars'JupiterGM'
– the nondimensional gravitational parameter of Jupiter'SaturnGM'
– the nondimensional gravitational parameter of Saturn'UranusGM'
– the nondimensional gravitational parameter of Uranus'NeptuneGM'
– the nondimensional gravitational parameter of NeptuneExamples:
un = kiam.units('earth') DU = un['DistUnit'] # Unit of distance for the earth system of units print(DU) un = kiam.units('earth', 'moon') VU = un['VelUnit'] # Unit of velocity for the Earth-Moon system of units print(VU)
def utc2tai(utc: datetime.datetime) ‑> datetime.datetime
-
UTC to TAI conversion.
Parameters:
utc
: datetime.datetimeThe Coordinated Universal Time (UTC).
Returns:
tai
: datetime.datetimeThe International Atomic Time (TAI).
Examples:
utc = datetime.datetime(2023, 3, 8, 12, 0, 0) # 2023-03-18 12:00:00 tai = kiam.utc2tai(utc) # 2023-03-08 12:00:32.184000 print(tai)
def utc2tt(utc: datetime.datetime) ‑> datetime.datetime
-
UTC to TT conversion.
Parameters:
utc
: datetime.datetimeThe Coordinated Universal Time (UTC).
Returns:
tt
: datetime.datetimeThe Terrestrial Time (TT).
Examples:
utc = datetime.datetime(2023, 3, 8, 12, 0, 0) # 2023-03-18 12:00:00 tt = kiam.utc2tt(utc) # 2023-03-08 12:01:09.184000 print(tt)
def vec2mat(v: numpy.ndarray) ‑> numpy.ndarray
-
Vector to square matrix translation.
Parameters:
v
: numpy.ndarray, shape (n**2,)A vector.
Returns:
a
: numpy.ndarray, shape (n, n)A square matrix.
Matrix structure (Fortran/MATLAB order):
[[v1, v2, ..., vn], [v_(n+1), ...]].T
Examples:
v = numpy.array([1, 2, 3, 4]) m = kiam.vec2mat(v) print(m) # [[1 3] # [2 4]]