RSO Inspection

This example demonstrates the configuration of a resident space object (RSO) inspection environment, in which a servicer spacecraft circumnavigates a RSO to image the illuminated facets.

[1]:
from importlib.metadata import version
from bsk_rl import sats, obs, act, ConstellationTasking, scene, data
from bsk_rl.obs.relative_observations import rso_imaged_regions
from bsk_rl.utils.orbital import fibonacci_sphere
from bsk_rl.sim import dyn, fsw
import types
import numpy as np
from Basilisk.architecture import bskLogging
from functools import partial
from bsk_rl.utils.orbital import random_orbit, random_unit_vector, relative_to_chief
from Basilisk.utilities.orbitalMotion import elem2rv
from Basilisk.utilities.RigidBodyKinematics import C2MRP

bskLogging.setDefaultLogLevel(bskLogging.BSK_WARNING)

RLlib is actively developed and can change significantly from version to version. For this script, the following version is used:

[2]:
version("ray")  # Parent package of RLlib
[2]:
'2.35.0'

Defining the Satellites

First, the RSO satellite is configured. It is given support for nadir pointing through the ImagingDynModel and Downlink action.

[3]:
class RSOSat(sats.Satellite):
    observation_spec = [
        obs.SatProperties(dict(prop="one", fn=lambda _: 1.0)),
    ]
    action_spec = [act.Downlink(duration=1e9)]
    dyn_type = types.new_class(
        "Dyn", (dyn.ImagingDynModel, dyn.ConjunctionDynModel, dyn.RSODynModel)
    )
    fsw_type = fsw.ContinuousImagingFSWModel

Arguments for the satellite are configured for smooth pointing behavior.

[4]:
rso_sat_args = dict(
    conjunction_radius=2.0,
    K=7.0 / 20,
    P=35.0 / 20,
    Ki=1e-6,
    dragCoeff=0.0,
    batteryStorageCapacity=1e9,
    storedCharge_Init=1e9,
    wheelSpeeds=[0.0, 0.0, 0.0],
    u_max=1.0,
)

The inspector satellite has a more complex configuration. First, an observation function for the sun vector is defined.

[5]:
def sun_hat_chief(self, other):
    r_SN_N = (
        self.simulator.world.gravFactory.spiceObject.planetStateOutMsgs[
            self.simulator.world.sun_index
        ]
        .read()
        .PositionVector
    )
    r_BN_N = self.dynamics.r_BN_N
    r_SN_N = np.array(r_SN_N)
    r_SB_N = r_SN_N - r_BN_N
    r_SB_N_hat = r_SB_N / np.linalg.norm(r_SB_N)
    HN = other.dynamics.HN
    return HN @ r_SB_N_hat

The inspector satellite is configured with observations relating to the relative state and the mission objectives. The satellite is given an action for impulsively thrusting and drifting. The dynamics and flight software models introduce a maximum range check, collision checking orbital maneuvers, and RSO inspection.

[6]:
class InspectorSat(sats.Satellite):
    observation_spec = [
        obs.SatProperties(
            dict(prop="dv_available", norm=10),
            dict(prop="inclination", norm=np.pi),
            dict(prop="eccentricity", norm=0.1),
            dict(prop="semi_major_axis", norm=7000),
            dict(prop="ascending_node", norm=2 * np.pi),
            dict(prop="argument_of_periapsis", norm=2 * np.pi),
            dict(prop="true_anomaly", norm=2 * np.pi),
            dict(prop="beta_angle", norm=np.pi),
        ),
        obs.ResourceRewardWeight(),
        obs.RelativeProperties(
            dict(prop="r_DC_Hc", norm=500),
            dict(prop="v_DC_Hc", norm=5),
            dict(
                prop="rso_imaged_regions",
                fn=partial(
                    rso_imaged_regions,
                    region_centers=fibonacci_sphere(15),
                    frame="chief_hill",
                ),
            ),
            dict(prop="sun_hat_Hc", fn=sun_hat_chief),
            chief_name="RSO",
        ),
        obs.Eclipse(norm=5700),
        obs.Time(),
    ]
    action_spec = [
        act.ImpulsiveThrustHill(
            chief_name="RSO",
            max_dv=1.0,
            max_drift_duration=5700.0 * 2,
            fsw_action="action_inspect_rso",
        )
    ]
    dyn_type = types.new_class(
        "Dyn",
        (
            dyn.MaxRangeDynModel,
            dyn.ConjunctionDynModel,
            dyn.RSOInspectorDynModel,
        ),
    )
    fsw_type = types.new_class(
        "FSW",
        (
            fsw.SteeringFSWModel,
            fsw.MagicOrbitalManeuverFSWModel,
            fsw.RSOInspectorFSWModel,
        ),
    )

Generous configurations are used for the inspector, allowing for “sloppy” attitude control with a low simulation step rate.

[7]:
inspector_sat_args = dict(
    imageAttErrorRequirement=1.0,
    imageRateErrorRequirement=None,
    instrumentBaudRate=1,
    dataStorageCapacity=1e6,
    batteryStorageCapacity=1e9,
    storedCharge_Init=1e9,
    conjunction_radius=2.0,
    dv_available_init=10.0,
    max_range_radius=1000,
    chief_name="RSO",
    u_max=1.0,
)

Environment Generation

A satellite argument randomizer is defined to configure the initial state of the satellites. The RSO is put into a random orbit with an apogee and perigee between 500 km and 1100 km. The inspector is placed in the region 250 to 750 meters from the RSO, with up to 1 m/s of relative velocity. Finally, the RSO’s attitude and body rate are set up to be in the nadir-pointing initial configuration.

[8]:
def sat_arg_randomizer(satellites):
    # Generate the RSO orbit
    R_E = 6371.0  # km
    a = R_E + np.random.uniform(500, 1100)
    e = np.random.uniform(0.0, min(1 - (R_E + 500) / a, (R_E + 1100) / a - 1))
    chief_orbit = random_orbit(a=a, e=e)

    inspectors = [sat for sat in satellites if "Inspector" in sat.name]
    rso = [satellite for satellite in satellites if satellite.name == "RSO"][0]

    # Generate the inspector initial states.
    args = {}
    for inspector in inspectors:
        relative_randomizer = relative_to_chief(
            chief_name="RSO",
            chief_orbit=chief_orbit,
            deputy_relative_state={
                inspector.name: lambda: np.concatenate(
                    (
                        random_unit_vector() * np.random.uniform(250, 750),
                        random_unit_vector() * np.random.uniform(0, 1.0),
                    )
                ),
            },
        )
        args.update(relative_randomizer([rso, inspector]))

    # Align RSO Hill frame for initial nadir pointing
    mu = rso.sat_args_generator["mu"]
    r_N, v_N = elem2rv(mu, args[rso]["oe"])

    r_hat = r_N / np.linalg.norm(r_N)
    v_hat = v_N / np.linalg.norm(v_N)
    x = r_hat
    z = np.cross(r_hat, v_hat)
    z = z / np.linalg.norm(z)
    y = np.cross(z, x)
    HN = np.array([x, y, z])
    BH = np.eye(3)

    a = chief_orbit.a
    T = np.sqrt(a**3 / mu) * 2 * np.pi
    omega_BN_N = z * 2 * np.pi / T

    args[rso]["sigma_init"] = C2MRP(BH @ HN)
    args[rso]["omega_init"] = BH @ HN @ omega_BN_N

    return args

The scenario is configured to set the RSO geometry as a sphere with 100 points at a radius of 1 meter. Points must be imaged within 30 degrees of their normal, with illumination coming from no more than 60 degrees from normal. The inspector must be within 250 meters to inspect the RSO.

[9]:
scenario = scene.SphericalRSO(
    n_points=100,
    radius=1.0,
    theta_max=np.radians(30),
    range_max=250,
    theta_solar_max=np.radians(60),
)

This scenario uses two rewarders. For the RSO inspection component of the task, a bonus of 1.0 is yielded once at least 90% of the illuminated points have been inspected. The ResourceReward is used to penalize fuel use, with some basic logic add to only apply the reward to the Inspector.

[10]:
rewarders = (
    data.RSOInspectionReward(
        completion_bonus=1.0,
        completion_threshold=0.90,
    ),
    data.ResourceReward(
        resource_fn=lambda sat: sat.fsw.dv_available
        if isinstance(sat.fsw, fsw.MagicOrbitalManeuverFSWModel)
        else 0.0,
        reward_weight=np.random.uniform(0.0, 0.5),
    ),
)

With all the components defined, the environment can be instantiated.

[11]:
env = ConstellationTasking(
    satellites=[
        RSOSat("RSO", sat_args=rso_sat_args),
        InspectorSat("Inspector", sat_args=inspector_sat_args, obs_type=dict),
    ],
    sat_arg_randomizer=sat_arg_randomizer,
    scenario=scenario,
    rewarder=rewarders,
    time_limit=60000,
    sim_rate=5.0,
    log_level="INFO",
)

Environment Interaction

The environment is reset and randomly stepped through.

Future Work: This example will be updated with an actual trained policy in the future.

[12]:
env.reset()
for i in range(4):
    env.step(dict(RSO=0, Inspector=env.action_space("Inspector").sample()))
2025-09-30 17:49:41,102 gym                            INFO       Resetting environment with seed=2014701272
2025-09-30 17:49:41,257 gym                            INFO       <0.00> Environment reset
/opt/hostedtoolcache/Python/3.11.13/x64/lib/python3.11/site-packages/gymnasium/spaces/box.py:130: UserWarning: WARN: Box bound precision lowered by casting to float32
  gym.logger.warn(f"Box bound precision lowered by casting to {self.dtype}")
2025-09-30 17:49:41,259 gym                            INFO       <0.00> === STARTING STEP ===
2025-09-30 17:49:41,260 sats.satellite.RSO             INFO       <0.00> RSO: action_downlink tasked for 1000000000.0 seconds
2025-09-30 17:49:41,261 sats.satellite.RSO             INFO       <0.00> RSO: setting timed terminal event at 1000000000.0
2025-09-30 17:49:41,262 sats.satellite.Inspector       INFO       <0.00> Inspector: Thrusting with inertial dV [0.60944346 0.35473119 0.41363071] with 9955.7607421875 second drift.
2025-09-30 17:49:41,263 sats.satellite.Inspector       INFO       <0.00> Inspector: setting timed terminal event at 9955.8
2025-09-30 17:49:41,264 sats.satellite.Inspector       INFO       <0.00> Inspector: FSW action action_inspect_rso activated.
2025-09-30 17:49:41,311 sats.satellite.Inspector       INFO       <940.00> Inspector: Exceeded maximum range of 1000 m from RSO
2025-09-30 17:49:41,315 data.rso_inspection            INFO       <940.00> Inspected/Illuminated/Total: 0/39/100
2025-09-30 17:49:41,316 data.composition               INFO       <940.00> ResourceReward reward: {'Inspector': np.float64(-0.3760745094582285)}
2025-09-30 17:49:41,316 data.base                      INFO       <940.00> Total reward: {'Inspector': np.float64(-0.3760745094582285)}
2025-09-30 17:49:41,317 sats.satellite.Inspector       WARNING    <940.00> Inspector: failed range_valid check
2025-09-30 17:49:41,323 gym                            INFO       <940.00> Step reward: {'Inspector': np.float64(-1.3760745094582285)}
2025-09-30 17:49:41,323 gym                            INFO       <940.00> Episode terminated: ['Inspector']
2025-09-30 17:49:41,324 gym                            INFO       <940.00> === STARTING STEP ===
2025-09-30 17:49:41,325 sats.satellite.RSO             INFO       <940.00> RSO: action_downlink tasked for 1000000000.0 seconds
2025-09-30 17:49:41,326 sats.satellite.RSO             INFO       <940.00> RSO: setting timed terminal event at 1000000940.0
2025-09-30 17:49:41,327 sats.satellite.Inspector       INFO       <940.00> Inspector: Thrusting with inertial dV [-0.54720316 -0.33207471 -0.26960498] with 8802.3818359375 second drift.
2025-09-30 17:49:41,328 sats.satellite.Inspector       INFO       <940.00> Inspector: setting timed terminal event at 9742.4
2025-09-30 17:49:41,329 sats.satellite.Inspector       INFO       <940.00> Inspector: FSW action action_inspect_rso activated.
2025-09-30 17:49:41,721 sats.satellite.Inspector       INFO       <9745.00> Inspector: timed termination at 9742.4
2025-09-30 17:49:41,736 data.rso_inspection            INFO       <9745.00> Inspected/Illuminated/Total: 0/81/100
2025-09-30 17:49:41,737 data.composition               INFO       <9745.00> ResourceReward reward: {'Inspector': np.float64(-0.3195017123068847)}
2025-09-30 17:49:41,738 data.base                      INFO       <9745.00> Total reward: {'Inspector': np.float64(-0.3195017123068847)}
2025-09-30 17:49:41,738 sats.satellite.Inspector       INFO       <9745.00> Inspector: Satellite Inspector requires retasking
2025-09-30 17:49:41,740 gym                            INFO       <9745.00> Step reward: {}
2025-09-30 17:49:41,740 gym                            INFO       <9745.00> === STARTING STEP ===
2025-09-30 17:49:41,741 sats.satellite.RSO             INFO       <9745.00> RSO: action_downlink tasked for 1000000000.0 seconds
2025-09-30 17:49:41,742 sats.satellite.RSO             INFO       <9745.00> RSO: setting timed terminal event at 1000009745.0
2025-09-30 17:49:41,743 sats.satellite.Inspector       INFO       <9745.00> Inspector: Thrust clamped from 1.1571608690908115 m/s to 1.0 m/s.
2025-09-30 17:49:41,744 sats.satellite.Inspector       INFO       <9745.00> Inspector: Thrusting with inertial dV [-0.9394185  -0.07733306  0.33393484] with 6136.1123046875 second drift.
2025-09-30 17:49:41,745 sats.satellite.Inspector       INFO       <9745.00> Inspector: setting timed terminal event at 15881.1
2025-09-30 17:49:41,746 sats.satellite.Inspector       INFO       <9745.00> Inspector: FSW action action_inspect_rso activated.
2025-09-30 17:49:42,061 sats.satellite.Inspector       INFO       <15885.00> Inspector: timed termination at 15881.1
2025-09-30 17:49:42,073 data.rso_inspection            INFO       <15885.00> Inspected/Illuminated/Total: 0/81/100
2025-09-30 17:49:42,074 data.composition               INFO       <15885.00> ResourceReward reward: {'Inspector': np.float64(-0.46001633055694524)}
2025-09-30 17:49:42,074 data.base                      INFO       <15885.00> Total reward: {'Inspector': np.float64(-0.46001633055694524)}
2025-09-30 17:49:42,075 sats.satellite.Inspector       INFO       <15885.00> Inspector: Satellite Inspector requires retasking
2025-09-30 17:49:42,077 gym                            INFO       <15885.00> Step reward: {}
2025-09-30 17:49:42,078 gym                            INFO       <15885.00> === STARTING STEP ===
2025-09-30 17:49:42,078 sats.satellite.RSO             INFO       <15885.00> RSO: action_downlink tasked for 1000000000.0 seconds
2025-09-30 17:49:42,079 sats.satellite.RSO             INFO       <15885.00> RSO: setting timed terminal event at 1000015885.0
2025-09-30 17:49:42,080 sats.satellite.Inspector       INFO       <15885.00> Inspector: Thrusting with inertial dV [ 0.20281754 -0.61256887 -0.51964268] with 6743.05078125 second drift.
2025-09-30 17:49:42,081 sats.satellite.Inspector       INFO       <15885.00> Inspector: setting timed terminal event at 22628.1
2025-09-30 17:49:42,082 sats.satellite.Inspector       INFO       <15885.00> Inspector: FSW action action_inspect_rso activated.
2025-09-30 17:49:42,398 sats.satellite.Inspector       INFO       <22630.00> Inspector: timed termination at 22628.1
2025-09-30 17:49:42,409 data.rso_inspection            INFO       <22630.00> Inspected/Illuminated/Total: 0/81/100
2025-09-30 17:49:42,409 data.composition               INFO       <22630.00> ResourceReward reward: {'Inspector': np.float64(-0.3811212632831819)}
2025-09-30 17:49:42,410 data.base                      INFO       <22630.00> Total reward: {'Inspector': np.float64(-0.3811212632831819)}
2025-09-30 17:49:42,411 sats.satellite.Inspector       INFO       <22630.00> Inspector: Satellite Inspector requires retasking
2025-09-30 17:49:42,413 gym                            INFO       <22630.00> Step reward: {}