API

API#

class pyqlaw.QLaw(mu=1.0, rpmin=0.1, k_petro=1.0, m_petro=3.0, n_petro=4.0, r_petro=2.0, b_petro=0.01, wp=1.0, elements_type='mee_with_a', integrator='rk4', verbosity=1, anomaly_grid_size=5, tol_oe=None, oe_min=None, oe_max=None, nan_angles_threshold=10, print_frequency=200, use_sundman=False, perturbations=None)#

Object for Q-law based transfer problem.

The overall procedure for using this class is:

  1. Create object via prob = QLaw()

  2. Set problem parameters via prob.set_problem()

  3. solve problem via prob.solve()

Exitcodes:

  • 0 : initial value (problem not yet attempted)

  • 1 : solved within tolerance

  • 2 : solved within relaxed tolerance

  • -1 : mass is below threshold

  • -2 : target elements could not be reached within allocated time

  • -3 : thrust angles from feedback control law is nan

Parameters:

  • mu (float) – gravitational parameter, default is 1.0

  • rpmin (float) – minimum periapsis

  • k_petro (float) – scalar factor k on minimum periapsis

  • m_petro (float) – scalar factor m to prevent non-convergence, default is 3.0

  • n_petro (float) – scalar factor n to prevent non-convergence, default is 4.0

  • r_petro (float) – scalar factor r to prevent non-convergence, default is 2.0

  • b_petro (float) – scalar factor b for dot(omega)_xx, default is 0.01

  • wp (float) – penalty scalar on minimum periapsis, default is 1.0

  • elements_type (str) – type of elements to define Q-law

  • integrator (str) – “rk4” or “rkf45”

  • verbosity (int) – verbosity level for Q-law

  • anomaly_grid_size (int) – number of evaluation point along orbit for Q-law effectivity

  • disable_tqdm (bool) – whether to disable progress bar

  • tol_oe (np.array or None) – tolerance on 5 elements targeted

  • oe_min (np.array) – minimum values of elements for safe-guarding

  • oe_max (np.array) – minimum values of elements for safe-guarding

  • nan_angles_threshold (int) – number of times to ignore nan thrust angles

  • print_frequency (int) – if verbosity >= 2, prints at this frequency

  • use_sundman (bool) – whether to use Sundman transformation for propagation

  • perturbations (SpicePerturbations) – object containing perturbation computation scheme

evaluate_osculating_qdot(oe, accel_thrust)#

Evaluate Qdot over the entire orbit

Parameters:

  • oe (np.array) – current osculating elements

  • accel_thrust (float) – acceleration magnitude, tmax/mass

Returns:

min and max Qdot

Return type:

(tuple)

get_cartesian_history(interpolate=False, steps=None, kind='quadratic', get_t_evals=False)#

Get Cartesian history of states

interpolate_states(kind='quadratic')#

Create interpolation states

pretty()#

Pretty print

pretty_results()#

Pretty print results of the problem

pretty_settings()#

Pretty print settings about the problem instance

save_to_dict(filepath, canonical_units=None, save_control_angles=False)#

Export result into a dictionary, saved as json if filepath is provided

Parameters:

filepath (str) – filepath to json filename to save the dictionary

set_problem(oe0, oeT, mass0, tmax, mdot, tf_max=100000.0, t_step=0.1, mass_min=0.1, woe=None, duty_cycle=(1e+16, 0.0), battery_initial=1.0, battery_capacity=(0.2, 1.0), battery_charge_discharge_rate=(0.0, 0.0), require_full_recharge=False)#

Set transfer problem

Parameters:

  • oe0 (np.array) – initial state, in Keplerian elements (6 components)

  • oeT (np.array) – final target Keplerian elements (5 components)

  • mass0 (float) – initial mass

  • tmax (float) – max thrust

  • mdot (float) – mass-flow rate

  • tf_max (float) – max time allocated to transfer

  • t_step (float) – initial time-step size to be used for integration

  • mass_min (float) – minimum mass

  • woe (np.array) – weight on each osculating element

  • duty_cycle (tuple) – ON and OFF times for duty cycle, default is (1e16, 0.0)

  • use_sundman (bool) – whether to use Sundman transformation for propagation

  • battery_capacity (tuple) – min and max battery capacity (min should be DOD)

  • battery_charge_discharge_rate (tuple) – charge and discharge rate (both positive values)

  • require_full_recharge (bool) – whether full recharge is required once DOD is reached

solve(eta_a=0.0, eta_r=0.0)#

Propagate and solve control problem

Efficiency thresholds eta_a and eta_r may be given either as constant floats or as callables. If providing callables, the required signatures are:

  • eta_a(t, oe, mass, battery) -> eta_a_value::float

  • eta_r(t, oe, mass, battery) -> eta_r_value::float

Parameters:

  • eta_a (float or callable) – min absolute effectivity to thrust

  • eta_r (float or callable) – relative effectivity, 0.0 <= eta_r <= 1.0

pyqlaw.SpicePerturbations(et_ref, LU, TU, obs_id='399', frame_qlaw='J2000', frame_PA='ITRF93', third_bodies_names=['301', '10'], third_bodies_gms=None, J2=0.00108263, Re_km=6378.0, P_SRP_SI=4.56e-06, Cr_SRP=1.2, Am_SI=0.01, use_J2=True, use_SRP=True)#

Class contains parameters for computing perturbations in RTN frame. SPICE is used to query positions of third bodies and transformation matrices. Default inputs are for an Earth-centered orbit.

Parameters:

  • et_ref (float) – reference time in ET, i.e. ephemeris time corresponding to t = 0

  • LU (float) – length unit in km

  • TU (float) – time unit in seconds

  • obs_id (str) – SPICE ID of observer body, i.e. central body

  • frame_qlaw (str) – SPICE frame in which Q-law is defined

  • frame_PA (str) – SPICE frame corresponding to principal axes frame of central body

  • third_bodies_names (list) – list of SPICE IDs of third bodies

  • third_bodies_gms (list) – list of GM’s of third bodies

  • J2 (float) – J2 coefficient of central body

  • Re_km (float) – equatorial radius of central body in km

  • use_J2 (bool) – flag to use J2 perturbation

pyqlaw.mee_with_a2kep(oe_mee_with_a)#
pyqlaw.kep2mee_with_a(oe_kep)#

Get targeting element set used by Q-law when using MEE

Contents