Satellite Configuration
Satellites are the basic unit of agent in the environment. Four things must be specified in subclasses of Satellite
:
The
observation_spec
, which defines the satellite’s observation.The
action_spec
, which defines the satellite’s actions.The
dyn_type
, which selects the underlying dynamics model used in simulation.The
fsw_type
, which selects the underlying flight software model.
A very simple satellite is defined below:
[1]:
from bsk_rl import sats, act, obs, scene, data, SatelliteTasking
from bsk_rl.sim import dyn, fsw
import numpy as np
from Basilisk.architecture import bskLogging
bskLogging.setDefaultLogLevel(bskLogging.BSK_WARNING)
class SimpleSatellite(sats.Satellite):
observation_spec = [obs.Time()] # Passed as list of instantiated classes
action_spec = [act.Drift()]
dyn_type = dyn.BasicDynamicsModel # Passed as a type
fsw_type = fsw.BasicFSWModel
Setting Satellite Parameters
Without instantiating the satellite, parameters that can be set in the various models can be inspected.
[2]:
SimpleSatellite.default_sat_args()
[2]:
{'hs_min': 0.0,
'maxCounterValue': 4,
'thrMinFireTime': 0.02,
'desatAttitude': 'sun',
'controlAxes_B': [1, 0, 0, 0, 1, 0, 0, 0, 1],
'thrForceSign': 1,
'K': 7.0,
'Ki': -1,
'P': 35.0,
'utc_init': 'this value will be set by the world model',
'batteryStorageCapacity': 288000.0,
'storedCharge_Init': <function bsk_rl.sim.dyn.base.BasicDynamicsModel.<lambda>()>,
'disturbance_vector': None,
'dragCoeff': 2.2,
'basePowerDraw': 0.0,
'wheelSpeeds': <function bsk_rl.sim.dyn.base.BasicDynamicsModel.<lambda>()>,
'maxWheelSpeed': inf,
'u_max': 0.2,
'rwBasePower': 0.4,
'rwMechToElecEfficiency': 0.0,
'rwElecToMechEfficiency': 0.5,
'panelArea': 1.0,
'panelEfficiency': 0.2,
'nHat_B': array([ 0, 0, -1]),
'mass': 330,
'width': 1.38,
'depth': 1.04,
'height': 1.58,
'sigma_init': <function bsk_rl.sim.dyn.base.BasicDynamicsModel.<lambda>()>,
'omega_init': <function bsk_rl.sim.dyn.base.BasicDynamicsModel.<lambda>()>,
'rN': None,
'vN': None,
'oe': <function bsk_rl.utils.orbital.random_orbit(i: Optional[float] = None, a: Optional[float] = 6871, e: float = 0, Omega: Optional[float] = None, omega: Optional[float] = None, f: Optional[float] = None, alt: float = None, r_body: float = 6371) -> Basilisk.utilities.orbitalMotion.ClassicElements>,
'mu': 398600436000000.0,
'thrusterPowerDraw': 0.0}
These parameters can be overriden when instantiating the satellite through the sat_args
argument.
[3]:
sat = SimpleSatellite(
name="SimpleSat-1",
sat_args=dict(
mass=300, # Setting a constant value
dragCoeff=lambda: np.random.uniform(2.0, 2.4), # Setting a randomized value
),
)
Each time the simulation is reset, all of the function-based randomizers are called.
[4]:
sat.generate_sat_args() # Called by the environment on reset()
sat.sat_args
[4]:
{'hs_min': 0.0,
'maxCounterValue': 4,
'thrMinFireTime': 0.02,
'desatAttitude': 'sun',
'controlAxes_B': [1, 0, 0, 0, 1, 0, 0, 0, 1],
'thrForceSign': 1,
'K': 7.0,
'Ki': -1,
'P': 35.0,
'utc_init': 'this value will be set by the world model',
'batteryStorageCapacity': 288000.0,
'storedCharge_Init': 163143.33183958015,
'disturbance_vector': None,
'dragCoeff': 2.3538247309548956,
'basePowerDraw': 0.0,
'wheelSpeeds': array([ -473.17579263, 808.95683539, -1198.9659229 ]),
'maxWheelSpeed': inf,
'u_max': 0.2,
'rwBasePower': 0.4,
'rwMechToElecEfficiency': 0.0,
'rwElecToMechEfficiency': 0.5,
'panelArea': 1.0,
'panelEfficiency': 0.2,
'nHat_B': array([ 0, 0, -1]),
'mass': 300,
'width': 1.38,
'depth': 1.04,
'height': 1.58,
'sigma_init': array([0.22038354, 0.87014395, 0.31116082]),
'omega_init': array([ 8.34516648e-05, 4.00495587e-05, -5.79661993e-05]),
'rN': None,
'vN': None,
'oe': <Basilisk.utilities.orbitalMotion.ClassicElements at 0x7fe5d3175e50>,
'mu': 398600436000000.0,
'thrusterPowerDraw': 0.0}
As a result, each episode will have different randomized parameters:
[5]:
for _ in range(3):
sat.generate_sat_args() # Called by the environment on reset()
print("New value of dragCoeff:", sat.sat_args["dragCoeff"])
New value of dragCoeff: 2.372603023150659
New value of dragCoeff: 2.0273358785169853
New value of dragCoeff: 2.106391069342978
The Observation Specification
A variety of observation elements are available for satellites. Full documentation can be found here, but some commonly used elements are explored below.
Info: In these examples, obs_type=dict
is passed to the Satellite
constructor so that the observation is human readable. While some RL libraries support dictionary-based observations, the default return type - the numpy array format - is more typically used.
Satellite Properties
The most common type of observations is introspective; i.e. what is my current state? Any @property
in the dyn_type
or fsw_type
of the satellite can be accessed using SatProperties.
[6]:
class SatPropsSatellite(sats.Satellite):
observation_spec = [
obs.SatProperties(
# At a minimum, specify the property to observe
dict(prop="wheel_speeds"),
# You can specify the module to use for the observation, but it is not necessary
# if only one module has for the property
dict(prop="battery_charge_fraction", module="dynamics"),
# Properties can be normalized by some constant. This is generally desirable
# for RL algorithms to keep values around [-1, 1].
dict(prop="r_BN_P", norm=7e6),
)
]
action_spec = [act.Drift()]
dyn_type = dyn.BasicDynamicsModel
fsw_type = fsw.BasicFSWModel
env = SatelliteTasking(
satellite=SatPropsSatellite("PropSat-1", {}, obs_type=dict),
log_level="CRITICAL",
)
observation, _ = env.reset()
observation
[6]:
{'sat_props': {'wheel_speeds': array([126.48306929, 44.98973063, 109.53523606]),
'battery_charge_fraction': 0.41234591614388755,
'r_BN_P_normd': array([-0.35512527, 0.43688692, -0.8040512 ])}}
In some cases, you may want to access a bespoke property that is not natively implemented in a model. To do that, simply extend the model with your desired property.
[7]:
class BespokeFSWModel(fsw.BasicFSWModel):
@property
def meaning_of_life(self):
return 42
class BespokeSatPropsSatellite(sats.Satellite):
observation_spec = [
obs.SatProperties(dict(prop="meaning_of_life"))
]
action_spec = [act.Drift()]
dyn_type = dyn.BasicDynamicsModel
fsw_type = BespokeFSWModel
env = SatelliteTasking(
satellite=BespokeSatPropsSatellite("BespokeSat-1", {}, obs_type=dict),
log_level="CRITICAL",
)
observation, _ = env.reset()
observation
[7]:
{'sat_props': {'meaning_of_life': 42.0}}
Alternatively, define the property with a function that takes the satellite object as an argument.
[8]:
class CustomSatPropsSatellite(sats.Satellite):
observation_spec = [
obs.SatProperties(dict(prop="meaning_of_life", fn=lambda sat: 42))
]
action_spec = [act.Drift()]
dyn_type = dyn.BasicDynamicsModel
fsw_type = fsw.BasicFSWModel
env = SatelliteTasking(
satellite=CustomSatPropsSatellite("BespokeSat-1", {}, obs_type=dict),
log_level="CRITICAL",
)
observation, _ = env.reset()
observation
[8]:
{'sat_props': {'meaning_of_life': 42.0}}
Opportunity Properties
Another common input to the observation is information about upcoming locations that are being accessed by the satellite. Currently, these include ground stations for downlink and targets for imaging, but OpportunityProperties
will work with any location added by add_location_for_access_checking
. In these examples,
[9]:
class OppPropsSatellite(sats.ImagingSatellite):
observation_spec = [
obs.OpportunityProperties(
# Properties can be added by some default names
dict(prop="priority"),
# They can also be normalized
dict(prop="opportunity_open", norm=5700.0),
# Or they can be specified by an arbitrary function
dict(fn=lambda sat, opp: opp["r_LP_P"] + 42),
n_ahead_observe=3,
)
]
action_spec = [act.Drift()]
dyn_type = dyn.ImagingDynModel
fsw_type = fsw.ImagingFSWModel
env = SatelliteTasking(
satellite=OppPropsSatellite("OppSat-1", {}, obs_type=dict),
scenario=scene.UniformTargets(1000),
rewarder=data.UniqueImageReward(),
log_level="CRITICAL",
)
observation, _ = env.reset()
observation
[9]:
{'target': {'target_0': {'priority': 0.819144367651575,
'opportunity_open_normd': 0.021598580040357227,
'prop_2': array([ 115323.64040117, 2923815.33143642, 5667394.65693138])},
'target_1': {'priority': 0.6320574465135106,
'opportunity_open_normd': 0.028104719621529252,
'prop_2': array([ 46261.20914523, 3078805.50912813, 5585711.65795746])},
'target_2': {'priority': 0.6886746498597007,
'opportunity_open_normd': 0.02783806823690282,
'prop_2': array([-301588.13484356, 2799865.48314278, 5722858.982331 ])}}}
The Action Specification
The action specification works similarly to observation specification. A list of actions is set in the class definition of the satellite.
[14]:
class ActionSatellite(sats.Satellite):
observation_spec = [obs.Time()]
action_spec = [
# If action duration is not set, the environment max_step_duration will be used;
# however, being explicit is always preferable
act.Charge(duration=120.0),
act.Desat(duration=60.0),
# One action can be included multiple time, if different settings are desired
act.Charge(duration=600.0,),
]
dyn_type = dyn.BasicDynamicsModel
fsw_type = fsw.BasicFSWModel
env = SatelliteTasking(
satellite=ActionSatellite("ActSat-1", {}, obs_type=dict),
log_level="INFO",
)
env.reset()
# Try each action; index corresponds to the order of addition
_ =env.step(0)
_ =env.step(1)
_ =env.step(2)
2025-06-20 19:57:39,227 WARNING Creating logger for new env on PID=5472. Old environments in process may now log times incorrectly.
2025-06-20 19:57:39,320 gym INFO Resetting environment with seed=1276189173
2025-06-20 19:57:39,384 gym INFO <0.00> Environment reset
2025-06-20 19:57:39,385 gym INFO <0.00> === STARTING STEP ===
2025-06-20 19:57:39,385 sats.satellite.ActSat-1 INFO <0.00> ActSat-1: action_charge tasked for 120.0 seconds
2025-06-20 19:57:39,386 sats.satellite.ActSat-1 INFO <0.00> ActSat-1: setting timed terminal event at 120.0
2025-06-20 19:57:39,401 sats.satellite.ActSat-1 INFO <120.00> ActSat-1: timed termination at 120.0 for action_charge
2025-06-20 19:57:39,401 data.base INFO <120.00> Total reward: {}
2025-06-20 19:57:39,402 comm.communication INFO <120.00> Optimizing data communication between all pairs of satellites
2025-06-20 19:57:39,402 sats.satellite.ActSat-1 INFO <120.00> ActSat-1: Satellite ActSat-1 requires retasking
2025-06-20 19:57:39,403 gym INFO <120.00> Step reward: 0.0
2025-06-20 19:57:39,404 gym INFO <120.00> === STARTING STEP ===
2025-06-20 19:57:39,404 sats.satellite.ActSat-1 INFO <120.00> ActSat-1: action_desat tasked for 60.0 seconds
2025-06-20 19:57:39,405 sats.satellite.ActSat-1 INFO <120.00> ActSat-1: setting timed terminal event at 180.0
2025-06-20 19:57:39,414 sats.satellite.ActSat-1 INFO <180.00> ActSat-1: timed termination at 180.0 for action_desat
2025-06-20 19:57:39,414 data.base INFO <180.00> Total reward: {}
2025-06-20 19:57:39,415 comm.communication INFO <180.00> Optimizing data communication between all pairs of satellites
2025-06-20 19:57:39,415 sats.satellite.ActSat-1 INFO <180.00> ActSat-1: Satellite ActSat-1 requires retasking
2025-06-20 19:57:39,416 gym INFO <180.00> Step reward: 0.0
2025-06-20 19:57:39,417 gym INFO <180.00> === STARTING STEP ===
2025-06-20 19:57:39,417 sats.satellite.ActSat-1 INFO <180.00> ActSat-1: action_charge tasked for 600.0 seconds
2025-06-20 19:57:39,418 sats.satellite.ActSat-1 INFO <180.00> ActSat-1: setting timed terminal event at 780.0
2025-06-20 19:57:39,479 sats.satellite.ActSat-1 INFO <780.00> ActSat-1: timed termination at 780.0 for action_charge
2025-06-20 19:57:39,479 data.base INFO <780.00> Total reward: {}
2025-06-20 19:57:39,480 comm.communication INFO <780.00> Optimizing data communication between all pairs of satellites
2025-06-20 19:57:39,480 sats.satellite.ActSat-1 INFO <780.00> ActSat-1: Satellite ActSat-1 requires retasking
2025-06-20 19:57:39,481 gym INFO <780.00> Step reward: 0.0
As with the observations, properties exist to help understand the actions available.
[15]:
env.action_space
[15]:
Discrete(3)
[16]:
env.unwrapped.satellite.action_description
[16]:
['action_charge', 'action_desat', 'action_charge']
Some actions take additional configurations, add multiple actions to the satellite, and/or have “special” features that are useful for manually interacting with the environment. For example, the imaging action can add an arbitrary number of actions corresponding to upcoming targets and process the name of a target directly instead of operating by action index.
[17]:
class ImageActSatellite(sats.ImagingSatellite):
observation_spec = [obs.Time()]
action_spec = [
# Set the number of upcoming targets to consider
act.Image(n_ahead_image=3)
]
dyn_type = dyn.ImagingDynModel
fsw_type = fsw.ImagingFSWModel
env = SatelliteTasking(
satellite=ImageActSatellite("ActSat-2", {}),
scenario=scene.UniformTargets(1000),
rewarder=data.UniqueImageReward(),
log_level="INFO",
)
env.reset()
env.unwrapped.satellite.action_description
2025-06-20 19:57:39,497 WARNING Creating logger for new env on PID=5472. Old environments in process may now log times incorrectly.
2025-06-20 19:57:39,499 gym INFO Resetting environment with seed=1455343752
2025-06-20 19:57:39,500 scene.targets INFO Generating 1000 targets
2025-06-20 19:57:39,576 gym INFO <0.00> Environment reset
[17]:
['action_image_0', 'action_image_1', 'action_image_2']
Demonstrating the action overload feature, we task the satellite based on target name. While this is not part of the official Gym API, we find it useful in certain cases.
[18]:
target = env.unwrapped.satellite.find_next_opportunities(n=10)[9]["object"]
_ = env.step(target)
2025-06-20 19:57:39,582 sats.satellite.ActSat-2 INFO <0.00> ActSat-2: Finding opportunity windows from 0.00 to 600.00 seconds
2025-06-20 19:57:39,630 sats.satellite.ActSat-2 INFO <0.00> ActSat-2: Finding opportunity windows from 600.00 to 1200.00 seconds
2025-06-20 19:57:39,662 gym INFO <0.00> === STARTING STEP ===
2025-06-20 19:57:39,662 act.discrete_actions WARNING <0.00> Action 'Target(tgt-358)' is not an integer. Will attempt to use compatible set_action_override method.
2025-06-20 19:57:39,663 sats.satellite.ActSat-2 INFO <0.00> ActSat-2: Target(tgt-358) tasked for imaging
2025-06-20 19:57:39,665 sats.satellite.ActSat-2 INFO <0.00> ActSat-2: Target(tgt-358) window enabled: 1019.9 to 1136.4
2025-06-20 19:57:39,665 sats.satellite.ActSat-2 INFO <0.00> ActSat-2: setting timed terminal event at 1136.4
2025-06-20 19:57:39,889 sats.satellite.ActSat-2 INFO <1022.00> ActSat-2: imaged Target(tgt-358)
2025-06-20 19:57:39,891 data.base INFO <1022.00> Total reward: {'ActSat-2': 0.7276647940807758}
2025-06-20 19:57:39,892 comm.communication INFO <1022.00> Optimizing data communication between all pairs of satellites
2025-06-20 19:57:39,893 sats.satellite.ActSat-2 INFO <1022.00> ActSat-2: Satellite ActSat-2 requires retasking
2025-06-20 19:57:39,894 gym INFO <1022.00> Step reward: 0.7276647940807758