renaming to get consistent terminology with report

itchono · itchono · commit 79eec3d136e0 · 2024-04-13T21:56:25.000-04:00
diff --git a/postprocessing/plotting/plot_quivers.m b/postprocessing/plotting/plot_quivers.m
@@ -8,12 +8,12 @@ function plot_quivers(t, y, y_target)
 sun_dir_o = COI * sun_dir_i;
 
 % GNC
-[alpha, beta] = lyapunov_steering(t, y, y_target);
+[alpha, beta] = q_law(t, y, y_target);
 
 n_lyapunov_o = steering2lvlh(alpha, beta);
 
 % Adjust targeted steering angle if needed
-[alpha, beta] = ndf_heuristic(t, y, alpha, beta);
+[alpha, beta] = cone_adaptation(t, y, alpha, beta);
 
 n_ndf_o = steering2lvlh(alpha, beta);
 
diff --git a/postprocessing/plotting/plot_steering_history.m b/postprocessing/plotting/plot_steering_history.m
@@ -12,8 +12,8 @@ function plot_steering_history(y, t, cfg)
 for j = 1:length(t)
     % yup this is slow, but that's the price to pay for getting rid of
     % explicit-ness in lyapunov steering
-    [alpha(j), beta(j)] = lyapunov_steering(t(j), y(:, j), cfg);
-    [alpha_f(j), beta_f(j)] = ndf_heuristic(t(j), y(:, j), alpha(j), beta(j), cfg);
+    [alpha(j), beta(j)] = q_law(t(j), y(:, j), cfg);
+    [alpha_f(j), beta_f(j)] = cone_adaptation(t(j), y(:, j), alpha(j), beta(j), cfg);
 end
 
 %% Rates
diff --git a/scripts/benchmark_transfer.m b/scripts/benchmark_transfer.m
@@ -10,7 +10,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/benchmark_transfer_cart.m b/scripts/benchmark_transfer_cart.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-6, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/benchmark_transfer_cone_limits.m b/scripts/benchmark_transfer_cone_limits.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/benchmark_transfer_no_feather.m b/scripts/benchmark_transfer_no_feather.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 2e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/benchmark_transfer_optim.m b/scripts/benchmark_transfer_optim.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/geo_disposal.m b/scripts/geo_disposal.m
@@ -7,7 +7,7 @@
 cfg.y0 = [42164e3; 1e-6; 0; 0; 0; 0];
 cfg.y_target = [42464e3; 1e-6; 0; 0; 0];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e7];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/geo_stiff.m b/scripts/geo_stiff.m
@@ -6,7 +6,7 @@
 cfg.y0 = [42164e3; 1e-6; 0; 0; 0; 0];
 cfg.y_target = [42464e3; 1e-6; 0; 0; 0];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e7];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/leo_operations.m b/scripts/leo_operations.m
@@ -6,7 +6,7 @@
 cfg.y0 = [6878e3; 0.1; -0.1; 0.5; 0; 0];
 cfg.y_target = [7500e3; 0; 0; 0; 0.2];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/oguri_case_G.m b/scripts/oguri_case_G.m
@@ -18,7 +18,7 @@
 cfg.y0 = [sma_i * (1 - e_i^2); e_i; 0; 0; 0; 0];
 cfg.y_target = [sma_f * (1 - e_f^2); 0; e_f; 0; -1];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/oguri_case_G_limit_50.m b/scripts/oguri_case_G_limit_50.m
@@ -18,7 +18,7 @@
 cfg.y0 = [sma_i * (1 - e_i^2); e_i; 0; 0; 0; 0];
 cfg.y_target = [sma_f * (1 - e_f^2); 0; e_f; 0; -1];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/oguri_case_G_limit_90.m b/scripts/oguri_case_G_limit_90.m
@@ -18,7 +18,7 @@
 cfg.y0 = [sma_i * (1 - e_i^2); e_i; 0; 0; 0; 0];
 cfg.y_target = [sma_f * (1 - e_f^2); 0; e_f; 0; -1];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/oguri_case_G_optim.m b/scripts/oguri_case_G_optim.m
@@ -18,7 +18,7 @@
 cfg.y0 = [sma_i * (1 - e_i^2); e_i; 0; 0; 0; 0];
 cfg.y_target = [sma_f * (1 - e_f^2); 0; e_f; 0; -1];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/plane_change.m b/scripts/plane_change.m
@@ -10,7 +10,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/smoother_ndf.m b/scripts/smoother_ndf.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/two_leg.m b/scripts/two_leg.m
@@ -6,7 +6,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/twoleg_cart.m b/scripts/twoleg_cart.m
@@ -7,7 +7,7 @@
 cfg.y0 = [20000e3; 0.5; -0.2; 0.5; 0; 0];
 cfg.y_target = [25000e3; 0.2; 0.5; 0; 0.3];
 cfg.propulsion_model = @sail_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @quail;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e8];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/video_nodal_precession.m b/scripts/video_nodal_precession.m
@@ -6,7 +6,7 @@
 cfg.y0 = [10000e3; 0.2; -0.5; 0; 0; 0];
 cfg.y_target = [10000e3; 0.5; 0.2; 0; 0];
 cfg.propulsion_model = @constant_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @q_law;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e7];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/video_orbit_raising.m b/scripts/video_orbit_raising.m
@@ -6,7 +6,7 @@
 cfg.y0 = [10000e3; 0; -0.1; 0; 0; 0];
 cfg.y_target = [20000e3; 0; -0.7; 0; 0];
 cfg.propulsion_model = @constant_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @q_law;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e7];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/scripts/video_plane_change.m b/scripts/video_plane_change.m
@@ -6,7 +6,7 @@
 cfg.y0 = [10000e3; 0.2; 0.2; 0; 0; 0];
 cfg.y_target = [10000e3; 0.2; 0.2; 0.8; 0];
 cfg.propulsion_model = @constant_thrust;
-cfg.steering_law = @lyapunov_steering;
+cfg.steering_law = @q_law;
 cfg.solver = @ode89;
 cfg.t_span = [0, 1e7];
 cfg.options = odeset('RelTol', 1e-4, "Stats", "on", "MaxStep", 1e4);
diff --git a/sim/dynamics/dyn_cartesian.m b/sim/dynamics/dyn_cartesian.m
@@ -13,11 +13,6 @@
 % GNC
 [alpha, beta] = cfg.steering_law(t, y_mee, cfg);
 
-% Adjust targeted steering angle if needed
-if func2str(cfg.propulsion_model) == "sail_thrust"
-    [alpha, beta] = ndf_heuristic(t, y_mee, alpha, beta, cfg);
-end
-
 % Propulsion
 acceleration = cfg.propulsion_model(t, y, alpha, beta);
 if cfg.j2
diff --git a/sim/dynamics/dyn_mee.m b/sim/dynamics/dyn_mee.m
@@ -13,11 +13,6 @@
 % GNC
 [alpha, beta] = cfg.steering_law(t, y, cfg);
 
-% Adjust targeted steering angle if needed
-if func2str(cfg.propulsion_model) == "sail_thrust"
-    [alpha, beta] = ndf_heuristic(t, y, alpha, beta, cfg);
-end
-
 % Propulsion
 acceleration = cfg.propulsion_model(t, y, alpha, beta);
 if cfg.j2
diff --git a/sim/propulsion/thrust_magnitude.m b/sim/propulsion/thrust_magnitude.m
@@ -1,5 +1,7 @@
 function T = thrust_magnitude
+% THRUST_MAGNITUDE  Returns the thrust magnitude for the propulsion system
 % convenience function for defining thrust magnitude used across the board
+% i.e. so that constant_thrust and sail_thrust can use the same value
 
 % Sail/Sun parameters
 P = 9.12e-6; % N/m^2
diff --git a/steering/basic_steering_laws/on_off_steering.m b/steering/basic_steering_laws/on_off_steering.m
@@ -1,5 +1,6 @@
 function [alpha, beta] = on_off_steering(t, y, ~)
 % Reference steering law from McInnes 4.4.2.1; to debug simulator
+% Untested in 3D sims; used only early on in development
 
 [~, ~, ~, ~, ~, L] = unpack_mee(y);
 phi_sun = sun_angle(t);
diff --git a/steering/q_law/approxmaxroc.m b/steering/q_law/approxmaxroc.m
@@ -1,6 +1,15 @@
 function maxroc = approxmaxroc(y)
-% Approximate maximum rates of change of each element across all steering
-% angles and true longitudes, based on Petropoulos' 2004 paper.
+% APPROXMAXROC  Approximate maximum rates of change of each element across
+% all steering angles and true longitudes
+%   maxroc = approxmaxroc(y) calculates the approximate maximum rates of
+%   change of each element across all steering angles and true longitudes
+%   based on Petropoulos' 2004 paper.
+%
+% Inputs:
+%   y = state vector
+%
+% Outputs:
+%   maxroc = approximate maximum rates of change (d_p, d_f, d_g, d_h, d_k)
 
 [p, f, g, h, k, L] = unpack_mee(y);
 
diff --git a/steering/q_law/penalty.m b/steering/q_law/penalty.m
@@ -1,5 +1,16 @@
 function [P, dPdy] = penalty(y, pen_param, rpmin)
-% k is a penalty scaling parameter, not to be confused with the MEE value k
+% PENALTY  Calculate the penalty function and its partials
+%  [P, dPdy] = penalty(y, pen_param, rpmin) calculates the penalty function
+%  and its partials with respect to the state vector y
+%
+% Inputs:
+%  y - state vector
+%  pen_param - penalty scaling parameter
+%  rpmin - minimum periapsis radius
+%
+% Outputs:
+%  P - penalty function
+%  dPdy - partials of the penalty function with respect to the state vector y
 
 [p, f, g, ~, ~, ~] = unpack_mee(y);
 
diff --git a/steering/q_law/q_law.m b/steering/q_law/q_law.m
@@ -1,7 +1,7 @@
-function [alpha, beta] = lyapunov_steering(t, y, cfg)
-% LYAPUNOV_STEERING  Steering law for Lyapunov control WITH PENALTY
+function [alpha, beta] = q_law(t, y, cfg)
+% Q_LAW  Steering law for Lyapunov control WITH PENALTY
 %
-%   [alpha, beta] = lyapunov_steering(t, y, y_tgt)
+%   [alpha, beta] = q_law(t, y, y_tgt)
 %
 % Inputs:
 %   t = current time
diff --git a/steering/quail/cone_adaptation.m b/steering/quail/cone_adaptation.m
@@ -1,7 +1,7 @@
-function [alpha, beta] = ndf_heuristic(t, y, alpha_star, beta_star, cfg)
-% NDF_HEURISTIC  generate new steering angles if the original target
+function [alpha, beta] = cone_adaptation(t, y, alpha_star, beta_star, cfg)
+% CONE_ADAPTATION  generate new steering angles if the original target
 % angles are not possible with a solar sail
-%  [alpha, beta] = ndf_heuristic(t, y, alpha_star, beta_star)
+%  [alpha, beta] = cone_adaptation(t, y, alpha_star, beta_star)
 %
 % Inputs:
 %  t - current time
@@ -29,12 +29,12 @@
     % Feather the sail if we're below kappa_f
     b_i = cross(u_i, cross(n_star_i, u_i));
     [alpha, beta] = lvlh2steering(COI*b_i);
-
+    
     % EXPERIMENT: apply a smoothing to "interpolate" between kappa_d and f
     % b_i = cross(u_i, cross(n_star_i, u_i));
     % n_prime_i = cos(kappa_d) * u_i + sin(kappa_d) * b_i;
     % [alpha, beta] = lvlh2steering(COI*n_prime_i);
-
+    
 elseif c_cone_ang < cos(kappa_d)
     % Degraded guidance, if we're between kappa_d and kappa_f
     % vector in plane of u_i and n_star, but orthogonal to u_i
diff --git a/steering/quail/quail.m b/steering/quail/quail.m
@@ -0,0 +1,20 @@
+function [alpha, beta] = quail(t, y, cfg)
+% QUAIL  Combined steering law
+% [alpha, beta] = quail(t, y, cfg) calculates the steering angles for the
+% current state and time using a combined Q-Law with cone angle adaptation
+%
+% Inputs:
+%   t = current time
+%   y = current state
+%   y_tgt = target state
+%
+% Outputs:
+%   [alpha, beta] = steering angles
+
+% First Stage
+[alpha_s, beta_s] = q_law(t, y, cfg);
+
+% Second Stage
+[alpha, beta] = cone_adaptation(t, y, alpha_s, beta_s, cfg);
+
+end
diff --git a/tests/test_mee_cartesian_converstions.m b/tests/test_mee_cartesian_converstions.m
@@ -1,3 +1,4 @@
+% Testing script during development of carteisan dynamics to ensure that the MEE to cartesian conversion is working correctly
 s_cart = [1e6 2e6; 2e6 3e6; 3e6 4e6; 4e3 5e3; 5e3 6e3; 6e3 7e3];
 m = cartesian2mee(s_cart);
 cart2 = mee2cartesian(m);
diff --git a/utils/converters/cartesian2mee.m b/utils/converters/cartesian2mee.m
@@ -2,6 +2,10 @@
 % CARTESIAN2MEE converts cartesian coordinates to modified equinoctial
 % elements. The inputs should be h-stacked vectors, and all be
 % the same size. The outputs will be the same size as the inputs.
+% Inputs:
+%   cart = [6 x n] array of cartesian coordinates
+% Outputs:
+%   m = [6 x n] array of modified equinoctial elements
 
 mu = 3.986e14;
 pos = cart(1:3, :);
diff --git a/utils/diagnostics/eval_last_step.m b/utils/diagnostics/eval_last_step.m
@@ -1,4 +1,16 @@
 function eval_last_step(y, t, cfg, n_eval)
+% EVAL_LAST_STEP  Evaluate the last n_eval steps of a simulation
+%   eval_last_step(y, t, cfg, n_eval) evaluates the last n_eval steps of a
+%   simulation and plots the trends of the MEE derivatives. It also plots
+%   the eclipse data.
+%
+% Inputs:
+%   y = state vector
+%   t = time vector
+%   cfg = configuration struct
+%   n_eval = number of steps to evaluate (default: all)
+
+% Used only as a diagnostic tool, not for publication-grade figures
 
 if nargin < 4
     n_eval = length(t);
diff --git a/utils/metrics/func_Q.m b/utils/metrics/func_Q.m
@@ -1,6 +1,13 @@
 function Q = func_Q(y, cfg)
 % FUNC_Q compute the Q potential function for a given state
-% y is state in MEE
+%  Q = FUNC_Q(y, cfg) computes the Q potential function for a given state
+%
+% Inputs:
+%  y - state vector (MEE)
+%  cfg - configuration struct
+%
+% Outputs:
+%  Q - Q potential function value
 
 [P, ~] = penalty(y, cfg.penalty_param, cfg.min_pe);
 
