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 Type Description
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:

Name Type Description Default
ax Axes | None

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

 None

Returns:

Type Description
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:

Name Type Description Default
n_time_steps int

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

 5
state_names list[str] | None

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

 None
objective_state_name str | None

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

 None
charge_rates list[float] | None

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

 None
data_rates list[float] | None

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

 None
charge_initial int

Initial battery charge, by default 5.

 5
charge_min int

Minimum allowable battery charge, by default 0.

 0
charge_max int

Maximum allowable battery charge, by default 10.

 10
data_initial int

Initial data stored on board, by default 0.

 0
data_min int

Minimum allowable data on board, by default 0.

 0
data_max int

Maximum allowable data on board, by default 8.

 8
allowed_times list[list[int]] | 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]].

 None

Returns:

Type Description
SatelliteSchedulingData

A SatelliteSchedulingData instance with the given values.

Raises:

Type Description
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:

Name Type Description Default
n_time_steps int

Number of time steps, by default 5.

 5
seed int | None

Random seed for reproducibility, by default None.

 None

Returns:

Type Description
SatelliteSchedulingData

A randomly generated instance.

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:

Name Type Description Default
data SatelliteSchedulingData

The problem data.

 required

Returns:

Type Description
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:

Name Type Description Default
solution Solution

The solver solution.

 required
data SatelliteSchedulingData

The problem data.

 required

Returns:

Type Description
SatelliteSchedulingSolution

Structured solution with schedule and metrics.

Solution

Solution model for Satellite Scheduling use case.

SatelliteSchedulingSolution

Bases: UcSolution

Solution for the Satellite Scheduling use case.

Attributes:

Name Type Description
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:

Name Type Description Default
data SatelliteSchedulingData | None

Problem data for state names and allowed times.

 None
ax Axes | None

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

 None

Returns:

Type Description
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:

Name Type Description Default
min_time_steps int

Minimum number of time steps.

 required
max_time_steps int

Maximum number of time steps.

 required
num_instances int

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

 1
seed int | None

Random seed for reproducibility, by default None.

 None

Returns:

Type Description
SatelliteSchedulingCollection

Collection containing generated instances.