Scenario

bsk_rl.scene provides scenarios, or the underlying environment in which the satellite can collect data.

Scenarios typically correspond to certain type(s) of Data & Reward systems.

For Earth observation, the following scenarios have been implemented:

UniformTargets: Uniformly distributed targets to be imaged by an ImagingSatellite.
CityTargets: Targets distributed near population centers.
UniformNadirScanning: Uniformly desireable data over the surface of the Earth.

For RSO Inspection tasks, the following scenario has been implemented:

SphericalRSO: A RSO with spherical points and radial normals.

These RSO scenarios can be used with RSOInspectionReward.

class Scenario[source]

Bases: ABC, Resetable

Base scenario class.

link_satellites(satellites: list[Satellite]) → None[source]

Link the environment satellite list to the scenario.

Parameters:: satellites (list[Satellite]) – List of satellites to communicate between.
Return type:: None

validate_satellite_names(satellites: list[Satellite]) → None[source]

Optionally validate original participant names before automatic renaming.

The default permits existing environment name normalization. Scenarios with explicit identity bindings can reject ambiguous original names.

Parameters:: satellites (list[Satellite])
Return type:: None

after_step(sim_time: float) → None[source]

Update scenario conditions after reward and before communication/observation.

The default does nothing. Scheduled scenarios can override this hook without putting scenario-specific logic in the environment.

Parameters:: sim_time (float)
Return type:: None

class UniformTargets(n_targets: int | tuple[int, int], priority_distribution: Callable | None = None, radius: float = 6378136.6)[source]

Bases: Scenario

An environment with evenly-distributed static targets.

Can be used with UniqueImageReward.

Parameters:

n_targets (int | tuple[int, int]) – Number of targets to generate. Can also be specified as a range (low, high) where the number of targets generated is uniformly selected low ≤ n_targets ≤ high.
priority_distribution (Callable | None) – Function for generating target priority. Defaults to lambda: uniform(0, 1) if not specified.
radius (float) – [m] Radius to place targets from body center. Defaults to Earth’s equatorial radius.

reset_overwrite_previous() → None[source]

Overwrite target list from previous episode.

Return type:: None

reset_pre_sim_init() → None[source]

Regenerate target set for new episode.

Return type:: None

reset_during_sim_init() → None[source]

Visualize targets in Vizard on reset.

Return type:: None

visualize_target(target, vizSupport=None, vizInstance=None)[source]: Visualize target in Vizard.

regenerate_targets() → None[source]

Regenerate targets uniformly.

Override this method (as demonstrated in CityTargets) to generate other distributions.

Return type:: None

class CityTargets(n_targets: int | tuple[int, int], n_select_from: int | None = None, location_offset: float = 0, priority_distribution: Callable | None = None, radius: float = 6378136.6)[source]

Bases: UniformTargets

Construct environment with static targets around population centers.

Uses the simplemaps Word Cities Database for population center locations.

Parameters:

n_targets (int | tuple[int, int]) – Number of targets to generate, as a fixed number or a range.
n_select_from (int | None) – Generate targets from the top n_select_from most populous cities. Will use all cities in the database if not specified.
location_offset (float) – [m] Offset targets randomly from the city center by up to this amount.
priority_distribution (Callable | None) – Function for generating target priority.
radius (float) – Radius to place targets from body center.

class UniformNadirScanning(value_per_second: float = 1.0)[source]

Bases: Scenario

Construct uniform data over the surface of the planet.

Can be used with ScanningTimeReward.

Parameters:: value_per_second (float) – Reward per second for imaging nadir.

class RSOPoints[source]

Bases: Scenario

reset_overwrite_previous() → None[source]

Overwrite target list from previous episode.

Return type:: None

reset_pre_sim_init() → None[source]

Identify RSO and Inspector satellites.

Return type:: None

reset_during_sim_init() → None[source]

Add points to dynamics and fsw of RSO.

Return type:: None

visualize_rso_point(rso_point: RSOPoint, vizSupport=None, vizInstance=None)[source]

Visualize target in Vizard.

Parameters:: rso_point (RSOPoint)

setup_inspector_camera(inspector: Satellite, vizSupport=None, vizInstance=None) → None[source]

Visualize camera view in Vizard panel.

Parameters:: inspector (Satellite)
Return type:: None

abstractmethod generate_points() → list[RSOPoint][source]

Generate a list of RSOPoint objects based on some spacecraft geometry.

Return type:: list[RSOPoint]

class SphericalRSO(n_points: int = 100, radius: float = 1.0, theta_max: float = np.float64(0.7853981633974483), range_max: float = -1, theta_solar_max: float = np.float64(1.0471975511965976), min_illumination_factor: float = 0.1)[source]

Bases: RSOPoints

Generate points on a sphere using the Fibonacci sphere method.

Parameters:

n_points (int) – Number of points to generate on the sphere.
radius (float) – [m] Radius of the sphere.
theta_max (float) – [rad] Maximum angle from the normal for inspection.
range_max (float) – [m] Maximum range for inspection.
theta_solar_max (float) – [rad] Minimum solar incidence angle for illumination.
min_illumination_factor (float) – Minimum illumination factor for imaging.

generate_points() → list[RSOPoint][source]

Generate a list of RSOPoint objects on a sphere.

Return type:: list[RSOPoint]

class RSOTarget(id: str, satellite_name: str, rN: tuple[float, float, float], vN: tuple[float, float, float], priority: float = 1.0, sigma_init: tuple[float, float, float] = (0.0, 0.0, 0.0), omega_init: tuple[float, float, float] = (0.0, 0.0, 0.0), wheel_speeds_rpm: tuple[float, float, float] = (0.0, 0.0, 0.0), disturbance_torque_Nm: tuple[float, float, float] = (0.0, 0.0, 0.0), physical_parameters: tuple[tuple[str, float], ...] = ())[source]

Bases: object

Immutable definition of one independently orbiting imaging target.

IDs are nonempty strings; they have no relationship to simulator indices. satellite_name is name, the environment’s agent identifier. It is distinct from the Basilisk spacecraft model’s name and binds exactly one explicitly supplied satellite, rather than a group. Physical parameters are optional (sat_args key, scalar value) pairs.

Parameters:

id (str)
satellite_name (str)
rN (tuple[float, float, float])
vN (tuple[float, float, float])
priority (float)
sigma_init (tuple[float, float, float])
omega_init (tuple[float, float, float])
wheel_speeds_rpm (tuple[float, float, float])
disturbance_torque_Nm (tuple[float, float, float])
physical_parameters (tuple[tuple[str, float], ...])

id: str

satellite_name: str

rN: tuple[float, float, float]

vN: tuple[float, float, float]

priority: float = 1.0

sigma_init: tuple[float, float, float] = (0.0, 0.0, 0.0)

omega_init: tuple[float, float, float] = (0.0, 0.0, 0.0)

wheel_speeds_rpm: tuple[float, float, float] = (0.0, 0.0, 0.0)

disturbance_torque_Nm: tuple[float, float, float] = (0.0, 0.0, 0.0)

physical_parameters: tuple[tuple[str, float], ...] = ()

sat_args() → dict[str, Any][source]

Return deterministic target dynamics arguments for this epoch.

Return type:: dict[str, Any]

class RSOTargetCatalog(targets: tuple[RSOTarget, ...], utc_init: str | None = None, priority_events: tuple[RSOPriorityEvent, ...] = ())[source]

Bases: object

Replayable target definitions, ordering, optional epoch, and priority events.

If utc_init is omitted, target states refer to the environment’s realized epoch on each reset. After reset, catalog contains that explicit epoch and can be saved for replay. An explicitly supplied catalog epoch must match the environment; states are never silently retimed.

Parameters:

targets (tuple[RSOTarget, ...])
utc_init (str | None)
priority_events (tuple[RSOPriorityEvent, ...])

targets: tuple[RSOTarget, ...]

utc_init: str | None = None

priority_events: tuple[RSOPriorityEvent, ...] = ()

to_dict() → dict[str, Any][source]

Return a versioned, JSON-compatible mission target definition.

Return type:: dict[str, Any]

save(path: str | Path) → None[source]

Save target definitions and their optional epoch without rounding.

Save env.scenario.catalog after reset to include the realized epoch when the original definition omitted it.

Parameters:: path (str | Path)
Return type:: None

classmethod from_dict(values: dict[str, Any]) → RSOTargetCatalog[source]

Validate and load the supported schema and units.

Parameters:: values (dict[str, Any])
Return type:: RSOTargetCatalog

classmethod load(path: str | Path) → RSOTargetCatalog[source]

Load a saved catalog without resampling any target.

Parameters:: path (str | Path)
Return type:: RSOTargetCatalog

class RSOPriorityEvent(time_s: float, priorities: tuple[tuple[str, float], ...])[source]

Bases: object

Priority changes applied at the first decision boundary at/after time_s.

Changes occur after the preceding step’s reward and before its observation. Events at zero occur before the initial observation. They do not clear pending images or cooldowns. Pairs are (target ID, new priority).

Parameters:

time_s (float)
priorities (tuple[tuple[str, float], ...])

time_s: float

priorities: tuple[tuple[str, float], ...]

class RSOTargets(catalog: RSOTargetCatalog, imager_names: list[str])[source]

Bases: Scenario

Select participants by explicit identity, independently of list order.

Parameters:

catalog (RSOTargetCatalog)
imager_names (list[str])

property catalog: RSOTargetCatalog

Configured catalog before reset, or the epoch-resolved episode snapshot.

The input definition remains immutable. Save this property after reset to retain the realized epoch without pinning subsequent episode resets.

validate_satellite_names(satellites) → None[source]

Reject ambiguous/missing original names before the environment renames.

Return type:: None

link_satellites(satellites) → None[source]

Bind only the copied participants used by the actual environment.

Return type:: None

reset_overwrite_previous() → None[source]

Drop runtime bindings, centralized eligibility, and event history.

Return type:: None

reset_pre_sim_init() → None[source]

Bind this episode’s objects and override only catalog target conditions.

Return type:: None

static partition_name(target_id: str) → str[source]

Bounded simulator-safe partition name, independent of array position.

Parameters:: target_id (str)
Return type:: str

reset_during_sim_init() → None[source]

Register each target separately in each imager’s access model.

Return type:: None

is_eligible(target_id: str, time_s: float) → bool[source]

Centralized pending visibility and quality-verified shared cooldown.

Parameters:

target_id (str)
time_s (float)

Return type:

bool

after_step(sim_time: float) → None[source]

Apply due priority events after reward, before the next observation.

Parameters:: sim_time (float)
Return type:: None