Struct TaskController

pub struct TaskController {
    task_schedule: Arc<RwLock<VecDeque<Task>>>,
}

TaskController manages and schedules tasks for MELVIN. It leverages a thread-safe task queue and powerful scheduling algorithms.

Fields

task_schedule: Arc<RwLock<VecDeque<Task>>>

Schedule for the next task, e.g. state switches, burn sequences, …

Implementations

impl TaskController

const MAX_ORBIT_PREDICTION_SECS: u32 = 80_000u32

The maximum number of seconds for orbit prediction calculations.

const BATTERY_RESOLUTION: I32F32

The resolution for battery levels used in calculations, expressed in fixed-point format.

pub const MIN_BATTERY_THRESHOLD: I32F32

The minimum batter threshold for all scheduling operations

pub const MAX_BATTERY_THRESHOLD: I32F32

The maximum battery treshold for all scheduling operations

const TIME_RESOLUTION: I32F32

The resolution for time duration calculations, expressed in fixed-point format.

const OBJECTIVE_SCHEDULE_MIN_DT: usize = 1_000usize

The minimum delta time for scheduling objectives, in seconds.

const OBJECTIVE_MIN_RETRIEVAL_TOL: usize = 100usize

The minimum tolerance for retrieving scheduled objectives.

const MANEUVER_INIT_BATT_TOL: I32F32

The initial battery threshold for performing a maneuver.

pub(crate) const MANEUVER_MIN_DETUMBLE_DT: usize = 20usize

The minimum delta time required for detumble maneuvers, in seconds.

pub const ZO_IMAGE_FIRST_DEL: TimeDelta

The Delay for imaging objectives when the first image should be shot

pub const IN_COMMS_SCHED_SECS: usize = 1_100usize

The number of seconds that are planned per acquisition cycle

const COMMS_SCHED_PERIOD: usize = 800usize

The period (number of seconds) after which another comms sequence should be scheduled.

const COMMS_SCHED_USABLE_TIME: TimeDelta

The usable TimeDelta between communication state switches

pub const COMMS_CHARGE_USAGE: I32F32

The charge usage per strictly timed communication cycle

pub const MIN_COMMS_START_CHARGE: I32F32

The minimum charge needed to enter communication state

pub fn new() -> Self

Creates a new instance of the TaskController struct.

Returns

• A new TaskController with an empty task schedule.

fn init_sched_dp( orbit: &ClosedOrbit, p_t_shift: usize, dt: Option<usize>, end_state: Option<FlightState>, end_batt: Option<I32F32>, ) -> OptimalOrbitResult

Initializes the optimal orbit schedule calculation.

This method sets up the required data structures and parameters necessary for determining the most efficient orbit path based on the given parameters.

Arguments

• orbit - Reference to the ClosedOrbit structure representing the current orbit configuration.
• p_t_shift - The starting index used to shift and reorder the bitvector of the orbit.
• dt - Optional maximum prediction duration in seconds. If None, defaults to the orbit period or the maximum prediction length.
• end_status - Optional tuple containing the end flight state (FlightState) and battery level (I32F32) constraints.

Returns

• OptimalOrbitResult - The final result containing calculated decisions and coverage slice used in the optimization.

fn calculate_optimal_orbit_schedule<'a>( pred_dt: usize, p_t_it: impl Iterator<Item = BitRef<'a>>, score_cube: LinkedBox<ScoreGrid>, score_grid_default: &ScoreGrid, dec_cube: AtomicDecisionCube, ) -> OptimalOrbitResult

Calculates the optimal orbit schedule based on predicted states and actions.

This function iterates backward over a prediction window (pred_dt) to compute the best decisions and score grid values for optimizing orbit transitions. It uses battery levels, state transitions, and the orbits done-BitBox.

Arguments

• pred_dt: The number of prediction time steps.
• p_t_it: Iterator over the orbit’s completion bitvector, providing timed scores.
• score_cube: A linked list holding previous and current score grids for dynamic programming.
• score_grid_default: A grid initialized with default scores used during calculations.
• dec_cube: A decision cube to store the selected actions at each time step.

Returns

• OptimalOrbitResult: Contains the final decision cube and the score grid linked box.

fn find_last_possible_dt( i: &IndexedOrbitPosition, vel: &Vec2D<I32F32>, targets: &[(Vec2D<I32F32>, Vec2D<I32F32>)], max_dt: usize, ) -> usize

Finds the last possible time offset (dt) at which a burn can still start to reach a target.

The method simulates forward motion and calculates how long a burn can be delayed while still ensuring that MELVIN can traverse the remaining distance in time.

Arguments

• i: The current orbit index position.
• vel: Current velocity vector.
• targets: Target positions and additional target direction vector.
• max_dt: Upper bound for time offset.

Returns

• dt: The latest viable starting offset in seconds.

pub fn calculate_single_target_burn_sequence( curr_i: IndexedOrbitPosition, curr_vel: Vec2D<I32F32>, target_pos: Vec2D<I32F32>, target_start_time: DateTime<Utc>, target_end_time: DateTime<Utc>, fuel_left: I32F32, target_id: usize, ) -> Option<ExitBurnResult>

Calculates the optimal burn sequence to reach a single target position within a specified end time.

This function determines the most efficient sequence of orbital maneuvers (acceleration vectors) to steer the spacecraft from its current position towards a given target position, considering time and energy constraints. The resulting burn sequence minimizes fuel consumption, angle deviation, and off-orbit time while ensuring sufficient battery charge.

Arguments

• curr_i - The current indexed orbit position of the spacecraft.
• f_cont_lock - A shared lock on the FlightComputer for velocity and control access.
• target_pos - The target position as a Vec2D<I32F32>.
• target_end_time - The deadline by which the target must be reached.

Returns

• (BurnSequence, I32F32) - A tuple containing:
  • The optimized BurnSequence object representing the maneuver sequence.
  • The minimum battery charge needed for the burn sequence.

Panics

Panics if no valid burn sequence is found or the target is unreachable.

pub fn calculate_multi_target_burn_sequence( curr_i: IndexedOrbitPosition, curr_vel: Vec2D<I32F32>, entries: [(Vec2D<I32F32>, Vec2D<I32F32>); 4], target_start_time: DateTime<Utc>, target_end_time: DateTime<Utc>, fuel_left: I32F32, target_id: usize, ) -> Option<ExitBurnResult>

Calculates an optimal burn sequence targeting multiple positions within a time window.

Arguments

• curr_i: Current indexed orbit position.
• curr_vel: Current velocity vector.
• entries: Array of target positions with uncertainties.
• target_start_time: When acquisition window starts.
• target_end_time: Deadline to acquire.
• fuel_left: Remaining propellant budget.
• target_id: ID of the image objective.

Returns

Some(ExitBurnResult) on success, or None if no valid burn sequence was found.

fn get_min_max_dt( start_time: DateTime<Utc>, end_time: DateTime<Utc>, curr: DateTime<Utc>, ) -> (usize, usize)

Determines the earliest and latest time offsets (in seconds) for a given target interval.

Arguments

• start_time: UTC time when the target becomes valid.
• end_time: UTC time by which the target must be acquired.
• curr: The current UTC time.

Returns

A tuple of (min_dt, max_dt):

• min_dt: The earliest time offset from curr to consider.
• max_dt: The latest time offset from curr before the target deadline.

async fn sched_single_comms_cycle( &self, c_end: (DateTime<Utc>, I32F32), sched_start: (DateTime<Utc>, usize), orbit: &ClosedOrbit, strict_end: (DateTime<Utc>, usize), ) -> Option<(DateTime<Utc>, I32F32)>

Schedules a single communication cycle within an orbit plan.

This function is responsible for planning a charge-acquire-comm cycle based on the given start time and constraints. It ensures sufficient battery and time are available to enter communication mode, and either schedules the cycle or short-circuits if the window is too small.

Arguments

• c_end: A tuple of the form (DateTime<Utc>, I32F32) representing the end time of the previous communication cycle and the remaining battery charge.
• sched_start: A tuple (DateTime<Utc>, usize) indicating the start time and the orbit index for scheduling.
• orbit: A reference to the ClosedOrbit used for orbit-based scheduling decisions.
• strict_end: A tuple (DateTime<Utc>, usize) specifying the hard cutoff for scheduling.

Returns

• Some((DateTime<Utc>, I32F32)) with the projected end time and battery after the next comms cycle, if another cycle can be scheduled.
• None if the scheduling window is too short and no comms cycle can be inserted.

Notes

• This method ensures each comms cycle starts with sufficient charge.
• Uses COMMS_SCHED_USABLE_TIME and COMMS_CHARGE_USAGE constants to define time and battery requirements.

pub async fn sched_opt_orbit_w_comms( self: Arc<TaskController>, orbit_lock: Arc<RwLock<ClosedOrbit>>, f_cont_lock: Arc<RwLock<FlightComputer>>, scheduling_start_i: IndexedOrbitPosition, last_bo_end_t: DateTime<Utc>, first_comms_end: DateTime<Utc>, end_cond: Option<EndCondition>, )

Computes and schedules tasks that balance imaging and communication passes.

This scheduling method handles alternating communication slots interleaved with optimized orbit operation schedules. It tries to maximize productivity while periodically entering comms mode.

Arguments

• self: Shared reference to this TaskController.
• orbit_lock: Reference to the current orbital model.
• f_cont_lock: Reference to the flight controller state.
• scheduling_start_i: Position to start scheduling from.
• last_bo_end_t: Deadline after which comms mode must stop.
• first_comms_end: Initial estimate of when the first comms cycle ends.
• end_cond: Optional condition that defines the final desired state and battery level.

pub async fn sched_opt_orbit( self: Arc<TaskController>, orbit_lock: Arc<RwLock<ClosedOrbit>>, f_cont_lock: Arc<RwLock<FlightComputer>>, scheduling_start_i: IndexedOrbitPosition, end: Option<EndCondition>, )

Calculates and schedules the optimal orbit trajectory based on the current position and state.

Arguments

• self: A reference-counted TaskController used for task scheduling.
• orbit_lock: An Arc<RwLock<ClosedOrbit>> containing the shared closed orbit data.
• f_cont_lock: An Arc<RwLock<FlightComputer>> containing the flight control state.
• scheduling_start_i: The starting orbital position as an IndexedOrbitPosition.
• end: An optional EndCondition indicating the desired final status of MELVIN

async fn get_batt_and_state( f_cont_lock: &Arc<RwLock<FlightComputer>>, ) -> (I32F32, usize)

Retrieves the current battery level and flight state index from the FlightComputer.

Arguments

• f_cont_lock: A shared reference to the flight computer’s RwLock wrapper.

Returns

• A tuple containing:
  • I32F32: The current battery level.
  • usize: The current flight state encoded as a decision-programming (DP) index.

fn map_e_to_dp(e: I32F32) -> usize

Maps a battery level (I32F32) to a discrete DP index for scheduling purposes.

Arguments

• e: The current battery level to convert.

Returns

• usize: The index used in dynamic programming grids to represent energy.

fn map_dp_to_e(dp: usize) -> I32F32

Maps a DP battery index (usize) back to a continuous I32F32 battery level.

Arguments

• dp: The index representing the discrete battery level.

Returns

• I32F32: The real-valued battery charge corresponding to the DP index.

async fn sched_opt_orbit_res( &self, base_t: DateTime<Utc>, res: OptimalOrbitResult, dt_sh: usize, trunc: bool, __arg5: (I32F32, usize), ) -> (usize, I32F32)

Schedules the result of an optimal orbit calculation as tasks.

Arguments

• f_cont_lock: A reference-counted and thread-safe lock for accessing the flight computer state.
• base_t: The base timestamp used for scheduling adjustments.
• res: The result of the optimal orbit calculation, including decisions about state transitions.
• dt_sh: The initial shift in time steps to apply during scheduling.
• trunc: A flag indicating whether to clear the current schedule before scheduling new tasks.

Returns

• The total number of tasks added to the task schedule.

pub fn sched_arc(&self) -> Arc<RwLock<VecDeque<Task>>>

Provides a reference to the image task schedule.

Returns

• An Arc pointing to the LockedTaskQueue.

async fn schedule_switch(&self, target: FlightState, sched_t: DateTime<Utc>)

Schedules a task to switch the flight state at a specific time.

Arguments

• target: The target flight state to switch to.
• sched_t: The scheduled time for the state change as a DateTime.

async fn schedule_zo_image( &self, t: DateTime<Utc>, pos: Vec2D<I32F32>, lens: CameraAngle, )

Schedules a task to capture an image at a specific time and position using the given camera lens.

This method creates and enqueues a Task::TakeImage operation, wrapping the target position to u32 dimensions and assigning the provided lens type.

Arguments

• t: The scheduled time to capture the image.
• pos: The unwrapped 2D map position of the target.
• lens: The CameraAngle specifying which lens to use.

pub async fn schedule_retrieval_phase( &self, t: DateTime<Utc>, pos: Vec2D<I32F32>, lens: CameraAngle, )

Prepares and schedules the full sequence for capturing a Zoned Objective (ZO) image.

This includes scheduling a transition from the current flight state to FlightState::Charge, then back to FlightState::Acquisition if feasible just before the first image capture, and finally scheduling the actual image task.

Arguments

• t: The nominal time at which the image should be taken.
• pos: The target position on the map for the ZO image.
• lens: The lens configuration to use for capturing the image.

pub async fn schedule_vel_change( self: Arc<TaskController>, burn: BurnSequence, ) -> usize

Schedules a velocity change task for a given burn sequence.

Arguments

• burn: The BurnSequence containing the velocity change details.

Returns

• The total number of tasks in the schedule after adding the velocity change task.

pub async fn clear_after_dt(&self, dt: DateTime<Utc>)

Clears tasks scheduled after a specified delay.

Arguments

• dt: The DateTime<Utc> representing the cutoff time for retaining tasks.

async fn enqueue_task(&self, task: Task)

Adds a task to the task schedule.

Arguments

• task: The Task to be added to the task schedule.

pub async fn clear_schedule(&self)

Clears all pending tasks in the schedule.

Trait Implementations

impl Debug for TaskController

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.