Skip to content

Satellite Scheduling API Reference

Data

Data model for Satellite Scheduling use case.

SatelliteSchedulingData

Bases: UcData

Data for the Satellite Scheduling use case.

The satellite must choose one of several operational states at each time step (e.g. charge, downlink, experiment) subject to cumulative charge and data-storage constraints.

Attributes:

  • name (Literal['satellite_scheduling']) –

    Identifier for this data type.

  • n_time_steps (int) –

    Number of discrete time steps in the planning horizon.

  • n_states (int) –

    Number of possible operational states (typically 3).

  • state_names (list[str]) –

    Human-readable names for each state, e.g. ["charge", "downlink", "experiment"].

  • charge_rates (NumPyArray) –

    Change in battery charge per time step for each state.

  • data_rates (NumPyArray) –

    Change in on-board data storage per time step for each state.

  • charge_initial (int) –

    Initial battery charge.

  • charge_min (int) –

    Minimum allowable battery charge.

  • charge_max (int) –

    Maximum allowable battery charge.

  • data_initial (int) –

    Initial data stored on board.

  • data_min (int) –

    Minimum allowable data on board.

  • data_max (int) –

    Maximum allowable data on board.

  • allowed_times (list[list[int]]) –

    allowed_times[s] is a list of time steps at which state s may be selected. Must not be empty for any state.

  • objective_state (int) –

    Index of the state to maximize in the objective function.

plot(*, ax: Axes | None = None) -> Axes

Plot the allowed times and state rates as a matrix.

Parameters:

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the data.

from_values(n_time_steps: int = 5, state_names: list[str] | None = None, objective_state_name: str | None = None, charge_rates: list[float] | None = None, data_rates: list[float] | None = None, charge_initial: int = 5, charge_min: int = 0, charge_max: int = 10, data_initial: int = 0, data_min: int = 0, data_max: int = 8, allowed_times: list[list[int]] | None = None) -> SatelliteSchedulingData staticmethod

Create a SatelliteSchedulingData instance from explicit values.

Parameters:

  • n_time_steps (int, default: 5 ) –

    Number of discrete time steps in the planning horizon, by default 5.

  • state_names (list[str] | None, default: None ) –

    Human-readable names for each state, by default ["Charging", "Experiment", "Downlink"].

  • objective_state_name (str | None, default: None ) –

    Name of the state to maximize in the objective function, by default the last state in state_names.

  • charge_rates (list[float] | None, default: None ) –

    Change in battery charge per time step for each state, by default [2.0, -1.0, -1.0].

  • data_rates (list[float] | None, default: None ) –

    Change in on-board data storage per time step for each state, by default [0.0, -2.0, 1.0].

  • charge_initial (int, default: 5 ) –

    Initial battery charge, by default 5.

  • charge_min (int, default: 0 ) –

    Minimum allowable battery charge, by default 0.

  • charge_max (int, default: 10 ) –

    Maximum allowable battery charge, by default 10.

  • data_initial (int, default: 0 ) –

    Initial data stored on board, by default 0.

  • data_min (int, default: 0 ) –

    Minimum allowable data on board, by default 0.

  • data_max (int, default: 8 ) –

    Maximum allowable data on board, by default 8.

  • allowed_times (list[list[int]] | None, default: None ) –

    allowed_times[s] is a list of time steps at which state s may be selected. By default [[0, 1, 2, 3, 4], [0, 1, 3], [1, 2, 4]].

Returns:

Raises:

  • ValueError –

    If allowed_times[s] is empty for any state s, or if objective_state_name is not found in state_names.

Notes

Charge and data rates are discrete — no partial charging, discharging, storing, or sending is possible. Ensure that rates and bounds are chosen such that transitions always result in valid states. For example, a data_rates[s] = -2 for a downlink state requires at least 2 units of data to be stored before downlinking is feasible. If rates and bounds are mismatched, the solver may find no improvement possible even though the schedule appears suboptimal.

Examples:

>>> data = SatelliteSchedulingData.from_values(
...     n_time_steps=5,
...     allowed_times=[[0, 1, 2, 3, 4], [0, 1, 3], [1, 2, 4]],
...     objective_state_name="Experiment",
... )

generate_random(n_time_steps: int = 5, seed: int | None = None) -> SatelliteSchedulingData staticmethod

Generate a random Satellite Scheduling instance.

Creates a 3-state satellite (charge, downlink, experiment) with feasible charge/data parameters. The experiment state is used as the objective state.

Parameters:

  • n_time_steps (int, default: 5 ) –

    Number of time steps, by default 5.

  • seed (int | None, default: None ) –

    Random seed for reproducibility, by default None.

Returns:

Formulation

Formulation for Satellite Scheduling use case.

SatelliteSchedulingFormulation

Bases: UcFormulation[SatelliteSchedulingData, SatelliteSchedulingSolution]

Constraint-based formulation for Satellite Scheduling.

Mathematical Formulation

Decision Variables: x[s,t] binary -- state s active at time t

Objective: maximize sum_t data_rates[objective_state] * x[objective_state, t]

Constraints: 1. One state per time: sum_s x[s,t] == 1 2. Allowed times: x[s,t] == 0 if t not in allowed_times[s] 3. Charge bounds at each time step 4. Data bounds at each time step

to_string(data: SatelliteSchedulingData) -> str staticmethod

Return a string describing the formulation.

formulate(data: SatelliteSchedulingData) -> Model staticmethod

Formulate the Satellite Scheduling problem.

Parameters:

Returns:

  • Model –

    A Luna Model ready to be solved.

Notes

Decision variables: x[s, t] : binary variable, 1 if state s is active at time step t, where s indexes data.state_names and t indexes the planning horizon 0, ..., n_time_steps - 1.

interpret(solution: Solution, data: SatelliteSchedulingData) -> SatelliteSchedulingSolution staticmethod

Extract solution from solver result.

Parameters:

Returns:

Solution

Solution model for Satellite Scheduling use case.

SatelliteSchedulingSolution

Bases: UcSolution

Solution for the Satellite Scheduling use case.

Attributes:

  • name (Literal['satellite_scheduling']) –

    Identifier for this solution type.

  • state_schedule (NumPyArray) –

    The state index chosen at each time step.

  • total_data_collected (float) –

    Total data collected (objective value).

  • is_valid (bool) –

    Whether the solution satisfies all constraints.

plot(data: SatelliteSchedulingData | None = None, *, ax: Axes | None = None) -> Axes

Plot the satellite schedule as a matrix.

Parameters:

  • data (SatelliteSchedulingData | None, default: None ) –

    Problem data for state names and allowed times.

  • ax (Axes | None, default: None ) –

    Matplotlib axes to draw on. Creates a new figure if None.

Returns:

  • Axes –

    The axes with the plot.

to_string() -> str

Return a string describing the solution.

Instance

Instance model for SatelliteScheduling use case.

SatelliteSchedulingInstance

Bases: UcInstance[SatelliteSchedulingData, SatelliteSchedulingFormulation, SatelliteSchedulingSolution]

Instance combining data and formulation for SatelliteScheduling.

Collection

Collection of Satellite Scheduling instances.

SatelliteSchedulingCollection

Bases: UcInstanceCollection[SatelliteSchedulingInstance]

Collection of Satellite Scheduling instances.

from_random(min_time_steps: int, max_time_steps: int, num_instances: int = 1, *, seed: int | None = None) -> SatelliteSchedulingCollection classmethod

Generate random Satellite Scheduling instances.

Parameters:

  • min_time_steps (int) –

    Minimum number of time steps.

  • max_time_steps (int) –

    Maximum number of time steps.

  • num_instances (int, default: 1 ) –

    Number of instances per time step count, by default 1.

  • seed (int | None, default: None ) –

    Random seed for reproducibility, by default None.

Returns: