fds.utils package

Submodules

fds.utils.dates module

class fds.utils.dates.DateRange(start: str | datetime, end: str | datetime)

Bases: object

contains(date: datetime, include_start=True, include_end=True) → bool

property duration: timedelta

property duration_seconds: float

property end: datetime

property end_string: str

classmethod from_dict(data: dict[str, str | datetime]) → Self

Create a DateRange object from a dictionary with ‘start’ and ‘end’ keys.

classmethod from_end_and_duration(end: datetime, duration: float) → Self

Create a DateRange object from an end date and a duration in seconds.

classmethod from_input(data: Self | dict[str, str | datetime] | list[str | datetime]) → Self

Create a DateRange object from a variety of input formats (DateRange, dict, list).

classmethod from_list(data: list[str | datetime]) → Self

Create a DateRange object from a list of two strings or datetime objects.

classmethod from_midpoint_and_duration(midpoint: datetime, duration: float) → Self

Create a DateRange object from a midpoint date and a duration in seconds.

classmethod from_now_to_end(end: datetime) → Self

Create a DateRange object from the current date and time to an end date.

classmethod from_start_and_duration(start: datetime, duration: float) → Self

Create a DateRange object from a start date and a duration in seconds.

classmethod from_start_to_now(start: datetime) → Self

Create a DateRange object from a start date to the current date and time.

get_intersection(other) → Self | None

get_overlap(other) → Self | None

get_union(other) → Self | None

is_adjacent(other) → bool

is_adjacent_or_overlapping(other) → bool

is_before(other) → bool

is_containing(other) → bool

is_inside(other) → bool

is_overlapping(other) → bool

property mid_date: datetime

property start: datetime

property start_string: str

to_dict()

fds.utils.dates.convert_date_to_utc(date: datetime)

fds.utils.dates.datetime_to_iso_string(date: datetime | None)

fds.utils.dates.filter_sequence_with_minimum_time_step(initial_sequence: Sequence, dates: list[datetime], minimum_step_in_seconds: float) → Sequence

fds.utils.dates.get_datetime(date_utc: str | datetime | None) → datetime | None

This function always returns a datetime object with UTC timezone (if the input is not None). In both cases, the timezone is checked. If it is not UTC, an exception is raised.

fds.utils.dict module

fds.utils.dict.compare_two_dicts(test_dict: dict, blueprint: dict)

The two dictionaries have a set of keys, the test_dict one must be a subset of the blueprint one. Moreover, each key corresponds to a dictionary, and keys of this dictionary must be the same as the blueprint one.

fds.utils.enum module

class fds.utils.enum.EnumFromInput(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

classmethod from_input(value: str | Self)

fds.utils.frames module

class fds.utils.frames.Frame(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: EnumFromInput

CIRF = 'CIRF'

ECF = 'ECF'

ECI = 'ECI'

EME2000 = 'EME2000'

GCRF = 'GCRF'

GTOD = 'GTOD'

ITRF = 'ITRF'

J2000 = 'J2000'

QSW = 'QSW'

TEME = 'TEME'

TNW = 'TNW'

property value_or_alias: str

fds.utils.frames.get_rot_order_axes(r: str) → ndarray

Get the rotation order axes.

Parameters:

r (str) – rotation order

Returns:

rotation order axes

Return type:

np.ndarray

fds.utils.frames.transformation_matrix_in_to_lvlh(state_cart: ndarray | Sequence[float]) → ndarray[float]

Compute the transformation matrix from inertial to LVLH frame.

Parameters:

state_cart (np.ndarray) – state in cartesian coordinates (X, Y, Z, Vx, Vy, Vz) [km, km, km, km/s, km/s, km/s]

Returns:

transformation matrix from inertial to LVLH frame

Return type:

np.ndarray

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_fr_lvlhMat

fds.utils.frames.transformation_matrix_in_to_tnw(state_cart: ndarray | Sequence[float]) → ndarray[float]

Compute the transformation matrix from inertial to TNW frame.

Parameters:

state_cart (np.ndarray) – state in cartesian coordinates (X, Y, Z, Vx, Vy, Vz) [km, km, km, km/s, km/s, km/s]

Returns:

transformation matrix from inertial to TNW frame

Return type:

np.ndarray

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_fr_tnwMat

fds.utils.geometry module

fds.utils.geometry.angle_between(v1: ndarray, v2: ndarray) → float

Computes the angle in radians between two vectors v1 and v2.

Parameters:

• v1 (np.ndarray) – A NumPy array representing the first vector.

• v2 (np.ndarray) – A NumPy array representing the second vector.

Returns:

The angle in radians between the two vectors.

Return type:

float

Raises:

ValueError – If v1 or v2 are zero vectors or if their dimensions don’t match.

fds.utils.geometry.check_vector_shape(v: ndarray, shape: tuple)

Check if the input vector has the correct shape.

Parameters:

• v (np.ndarray) – input vector

• shape (tuple) – expected shape

Raises:

ValueError – if the input vector has a different length than expected

fds.utils.geometry.convert_to_numpy_array_and_check_shape(v: Sequence, shape: tuple) → ndarray

Convert a list to a numpy array and check if the length is correct.

Parameters:

• v (list) – input list

• shape (tuple) – expected shape

Returns:

input list as numpy array

Return type:

np.ndarray

Raises:

ValueError – if the input vector has a different length than expected

fds.utils.geometry.unit_vector(v: ndarray) → ndarray

Return the unit vector of the input vector.

Parameters:

v (np.ndarray) – input vector

Returns:

unit vector

Return type:

np.ndarray

fds.utils.log module

fds.utils.log.log_and_raise(exception_type: Type[BaseException], message: str = '') → NoReturn

Raise an exception with a message and log it.

Parameters:

• exception_type (Exception) – The exception to be raised.

• message (str) – The message to be logged and raised. Defaults to “”.

Raises:

exception_type – The exception to be raised.

fds.utils.math module

fds.utils.math.modulo_with_range(x: float, x_min: float, x_max: float, x_min_atol: float = 1e-10, x_max_atol: float = 1e-10) → float

Modulo with result in range [x_min, x_max)

Parameters:

• x – The value to be modulated

• x_min – The minimum value of the range

• x_max – The maximum value of the range

• x_min_atol – The tolerance for the minimum value (to avoid floating point errors)

• x_max_atol – The tolerance for the maximum value (to avoid floating point errors)

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_rMod

fds.utils.math.pmodulo(x: float, modulo: float) → float

Modulo with positive result

Source:

SciLab (v 2023.1.0), https://atoms.scilab.org pmodulo

fds.utils.nmea module

class fds.utils.nmea.GgaSentence(message_id: str, utc_time: str, latitude: float, longitude: float, quality_indicator: int, satellites_used: int, hdop: float, msl_altitude: float, geoid_separation: float, age_of_diff_corr: str, differential_base_station_id: str, sentence: str)

Bases: NmeaSentence

age_of_diff_corr: str

differential_base_station_id: str

geoid_separation: float

hdop: float

classmethod is_valid(sentence: str, raise_if_false: bool = True) → bool

latitude: float

longitude: float

message_id: str

msl_altitude: float

classmethod parse(sentence: str)

classmethod parse_altitude(split_sentence: list[str]) → float

classmethod parse_geoid_separation(split_sentence: list[str]) → float | None

quality_indicator: int

satellites_used: int

sentence: str

utc_time: str

exception fds.utils.nmea.NmeaFileError

Bases: ValueError

class fds.utils.nmea.NmeaMeasurement(longitude: float, latitude: float, ground_speed: float, date: datetime.datetime, altitude: float | None = None, geoid_height: float | None = None)

Bases: object

altitude: float | None = None

date: datetime

geoid_height: float | None = None

ground_speed: float

latitude: float

longitude: float

class fds.utils.nmea.NmeaSentence

Bases: ABC

static get_coordinate_from_string_and_direction(coordinate: str, direction: str) → float

static get_measure_in_meters(measure: float, unit: str) → float

abstract classmethod parse(sentence: str)

classmethod parse_latitude(split_sentence: list[str]) → float

classmethod parse_longitude(split_sentence: list[str]) → float

class fds.utils.nmea.RmcSentence(message_id: str, utc_time: str, latitude: float, longitude: float, ground_speed: float, course_over_ground: float, date: datetime.datetime, magnetic_variation: float | None, positioning_system_mode: str | None, status: str, sentence: str)

Bases: NmeaSentence

course_over_ground: float

date: datetime

ground_speed: float

classmethod is_valid(sentence: str, raise_if_false: bool = True) → bool

latitude: float

longitude: float

magnetic_variation: float | None

message_id: str

classmethod parse(sentence: str)

classmethod parse_datetime(split_sentence: list[str]) → datetime

classmethod parse_magnetic_variation(split_sentence: list[str]) → float | None

positioning_system_mode: str | None

sentence: str

status: str

utc_time: str

class fds.utils.nmea.SentenceBundle(rmc: fds.utils.nmea.RmcSentence, gga: fds.utils.nmea.GgaSentence = None)

Bases: object

property date: datetime

classmethod from_strings(rmc: str, gga: str = None)

gga: GgaSentence = None

rmc: RmcSentence

fds.utils.nmea.export_list_of_sentences(sentences: list[SentenceBundle], use_gga: bool = True) → list[str]

fds.utils.nmea.filter_sentences(sentences: list[SentenceBundle], measurement_start_date_limit: datetime = None, measurement_end_date_limit: datetime = None, measurement_min_step: float = None) → list[SentenceBundle]

fds.utils.nmea.filter_sentences_by_date(sentences: list[SentenceBundle], measurement_start_date_limit: datetime, measurement_end_date_limit: datetime) → list[SentenceBundle]

fds.utils.nmea.filter_sentences_by_step(sentences: list[SentenceBundle], measurement_min_step: float) → list[SentenceBundle]

fds.utils.nmea.get_list_of_measurements_from_raw_and_dates(raw_measurements: list[list[float]], dates: list[datetime]) → list[NmeaMeasurement]

fds.utils.nmea.get_list_of_measurements_from_sentences(sentences: list[SentenceBundle]) → list[NmeaMeasurement]

fds.utils.nmea.get_raw_sentences_from_folder(folder_path: str | Path) → list[str]

fds.utils.nmea.get_raw_sentences_from_single_file(file_path: str | Path) → list[str]

fds.utils.nmea.parse_raw_sentences(raw_sentences: list[str], return_statistics: bool = False) → list[SentenceBundle] | tuple[list[SentenceBundle], dict]

fds.utils.nmea.parse_raw_sentences_from_file(file_path: str | Path, return_statistics: bool = False) → list[SentenceBundle] | tuple[list[SentenceBundle], dict]

fds.utils.nmea.parse_raw_sentences_from_folder(folder_path: str | Path, return_statistics: bool = False) → list[SentenceBundle] | tuple[list[SentenceBundle], dict]

fds.utils.orbital_mechanics module

class fds.utils.orbital_mechanics.OrbitalElements(SMA: float, ECC: float, INC: float, AOP: float, RAAN: float, TA: float)

Bases: object

property AOP: float

Argument of Perigee [deg]

property ECC: float

Eccentricity [-]

property INC: float

Inclination [deg]

property MA: float

Mean Anomaly [deg]

property RAAN: float

Right Ascension of the Ascending Node [deg]

property SMA: float

Semi-major axis [km]

property TA: float

True Anomaly [deg]

as_array(with_mean_anomaly: bool = True, radians: bool = False) → ndarray

Returns the orbital elements as a numpy array.

Parameters:

• with_mean_anomaly – If true, returns orbital elements with mean anomaly. If false, with true anomaly.

• radians – If true, all angles are expressed in radians; if false, in degrees.

Returns:

an array with the orbital elements

classmethod with_mean_anomaly(SMA: float, ECC: float, INC: float, AOP: float, RAAN: float, MA: float) → OrbitalElements

Create an instance with mean anomaly.

Args:

SMA (float): semi-major axis [km] ECC (float): eccentricity [-] INC (float): inclination [deg] AOP (float): argument of periapsis [deg] RAAN (float): right ascension of the ascending node [deg] MA (float): mean anomaly [deg]

fds.utils.orbital_mechanics.check_kep_validity(sma: float, ecc: float)

Check the validity of some keplerian elements. Raises an exception if not.

Parameters:

• sma – semi-major axis [km]

• ecc – eccentricity [-]

fds.utils.orbital_mechanics.compute_delta_v_with_rocket_equation(specific_impulse: float, initial_mass: float, final_mass: float) → float

Compute the delta-v required to perform a maneuver with the rocket equation.

Parameters:

• specific_impulse (float) – specific impulse [s]

• initial_mass (float) – initial mass [kg]

• final_mass (float) – final mass [kg]

Returns:

delta-v [m/s]

Return type:

float

Source:

Curtis, Orbital Mechanics for Engineering Students, eq 6.21

fds.utils.orbital_mechanics.eccentric_anomaly_from_mean_anomaly(eccentricity: float, mean_anomaly: float) → float

Compute the eccentric anomaly from the mean anomaly using one Halley step and one Newton-Raphson step.

Parameters:

• eccentricity – eccentricity [-]

• mean_anomaly – mean anomaly [rad]

Returns:

eccentric anomaly [rad]

Return type:

float

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL__kp_M2Eell

fds.utils.orbital_mechanics.eccentric_anomaly_from_mean_anomaly_newton_rhapson(eccentricity: float, mean_anomaly: float, step_tol: float = 1e-15) → float

Compute the eccentric anomaly from the mean anomaly using the Newton-Raphson method.

Parameters:

• eccentricity – eccentricity [-]

• mean_anomaly – mean anomaly [rad]

• step_tol – tolerance for the Newton-Raphson method

Returns:

eccentric anomaly [rad]

Return type:

float

Source:

Curtis, Orbital Mechanics for Engineering Students, eq 3.14

fds.utils.orbital_mechanics.eccentric_anomaly_from_true_anomaly(eccentricity: float, true_anomaly: float) → float

Compute the eccentric anomaly from the true anomaly.

Parameters:

• eccentricity – eccentricity [-]

• true_anomaly – true anomaly [rad] in the range [-pi, pi]

Returns:

eccentric anomaly [rad]

Return type:

float

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_kp_v2E

fds.utils.orbital_mechanics.get_delta_cartesian_tnw_between_two_keplerian_states(sma_ref: float, ecc_ref: float, inc_ref: float, aop_ref: float, raan_ref: float, ma_ref: float, sma_target: float, ecc_target: float, inc_target: float, aop_target: float, raan_target: float, ma_target: float) → ndarray

Get the cartesian delta between two keplerian states in the TNW frame.

Parameters:

• sma_ref (float) – semi-major axis of the first orbit [km]

• ecc_ref (float) – eccentricity of the first orbit

• inc_ref (float) – inclination of the first orbit [rad]

• aop_ref (float) – argument of perigee of the first orbit [rad]

• raan_ref (float) – right ascension of the ascending node of the first orbit [rad]

• ma_ref (float) – mean anomaly of the first orbit [rad]

• sma_target (float) – semi-major axis of the second orbit [km]

• ecc_target (float) – eccentricity of the second orbit

• inc_target (float) – inclination of the second orbit [rad]

• aop_target (float) – argument of perigee of the second orbit [rad]

• raan_target (float) – right ascension of the ascending node of the second orbit [rad]

• ma_target (float) – mean anomaly of the second orbit [rad]

Returns:

cartesian delta between two keplerian states in the TNW frame [km, km, km, km/s, km/s, km/s]

Return type:

np.ndarray

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_op_orbGapLof

fds.utils.orbital_mechanics.kep_to_car(sma: float, ecc: float, inc: float, aop: float, raan: float, ma: float) → ndarray

Convert Keplerian to Cartesian elements.

Parameters:

• sma (float) – semi-major axis [km]

• ecc (float) – eccentricity [-]

• inc (float) – inclination [rad]

• aop (float) – argument of perigee [rad]

• raan (float) – right ascension of the ascending node [rad]

• ma (float) – mean anomaly [rad]

Returns:

cartesian elements (X, Y, Z, Vx, Vy, Vz) [km, km, km, km/s, km/s, km/s]

Return type:

np.ndarray

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_oe_kep2car

fds.utils.orbital_mechanics.keplerian_period(semi_major_axis: float, mu: float = 398600.4418) → float

Compute the keplerian period of an orbit.

fds.utils.orbital_mechanics.mean_anomaly_from_eccentric_anomaly(eccentricity: float, eccentric_anomaly: float) → float

Compute the mean anomaly from the eccentric anomaly.

Parameters:

• eccentricity – eccentricity [-]

• eccentric_anomaly – eccentric anomaly [rad]

Returns:

mean anomaly [rad]

Return type:

float

Source:

Curtis, Orbital Mechanics for Engineering Students, eq 3.11

fds.utils.orbital_mechanics.mean_anomaly_from_true_anomaly(eccentricity: float, true_anomaly: float) → float

Compute the mean anomaly from the true anomaly.

Parameters:

• eccentricity – eccentricity [-]

• true_anomaly – true anomaly [rad]

Returns:

mean anomaly [rad]

Return type:

float

fds.utils.orbital_mechanics.true_anomaly_from_eccentric_anomaly(eccentricity: float, eccentric_anomaly: float) → float

Compute the true anomaly from the eccentric anomaly.

Parameters:

• eccentricity – eccentricity [-]

• eccentric_anomaly – eccentric anomaly [rad]

Returns:

true anomaly [rad]

Return type:

float

Source:

Celestlab (v 3.4.2), https://atoms.scilab.org/toolboxes/celestlab, CL_kp_E2v

fds.utils.orbital_mechanics.true_anomaly_from_mean_anomaly(eccentricity: float, mean_anomaly: float) → float

Compute the true anomaly from the mean anomaly.

Parameters:

• eccentricity – eccentricity [-]

• mean_anomaly – mean anomaly [rad]

Returns:

true anomaly [rad]

Return type:

float

Source:

Curtis, Orbital Mechanics for Engineering Students

Module contents