Satellites

bsk_rl.sats defines satellite agents for the environments.

A reference for working with satellites is given below. For a step-by-step guide, see this example.

Configuring a Satellite

A subclass of a Satellite type must be defined before can be used as an agent. Two fields (observation_spec and action_spec) must be specified: these define the observation and action spaces for the satellite. Actions and Observations provide more information on specifying the observation and action spaces.

Two other fields (dyn_model and fsw_model) may be specified to select the underlying dynamics and FSW models used by the Basilisk simulation. Some actions, communication methods, or other environment configurations may necessitate the use of a specific dynamics or FSW model. See FSW Sims and Dynamics Sims for more information on selecting these models.

In practice, configuring a satellite and passing it to an environment is straightforward:

class MySatellite(Satellite):
    observation_spec = [obs.Time(), ...]  # list of observations
    action_spec = [act.Drift(), ...]  # list of actions
    dyn_model = MyDynamicsModel  # dynamics model type
    fsw_model = MyFSWModel  # FSW model type

my_sat = MySatellite(name="my_satellite")
env = gym.make("SatelliteTasking-v1", satellite=my_sat, ...)

Setting Satellite Parameters

To specify satellite parameters such as physical properties and controller gains, a sat_args dictionary can be passed to the satellite constructor, which in turn is used when initializing the FSW and dynamics simulations. Call the class method default_sat_args to list what parameters are available:

>>> MySatellite.default_sat_args()

{'mass': 100.0, 'Kp': 0.1, 'Ki': 0.01, 'Kd': 0.01, ...}

These parameters are documented in FSW Sims and Dynamics Sims. To override the default parameters, pass a dictionary with the desired values. Parameters can be set by value, or by passing a function that returns a value. In the latter case, the randomizer function will be called each time the simulation is reset. For example:

>>> my_sat = MySatellite(
        name="my_satellite",
        sat_args={"mass": lambda: np.random.uniform(95.0, 105.0), "Kp": 0.3}
    )
>>> env = gym.make("SatelliteTasking-v1", satellite=my_sat, ...)
>>> env.reset()
>>> my_sat.sat_args

{'mass': 98.372, 'Kp': 0.3, 'Ki': 0.01, 'Kd': 0.01, ...}

If one attempts to set a parameter that is not recognized, an error will be raised.

Helpful Methods for Debugging

A variety of methods are available for debugging and introspection:

observation_description - Returns a human-interpretable description of the observation. For array-type observations, this can be useful to map indices to specific observation elements.
action_description - Returns a human-interpretable description of the actions. For discrete actions, this will be a list of action names.
observation_space - Returns the observation space for the single agent.
action_space - Returns the action space for the single agent.
is_alive - Returns whether the satellite is still operational based on @aliveness_checker s in the FSW and dynamics simulators.

Helpful Methods for Extending

When extending the satellite class, certain convenience methods are available:

reset_pre_sim_init - Called on reset before the simulation is constructed.
reset_post_sim_init - Called on reset after the simulation is constructed.
logger.info/warning/debug - Logs a message to INFO, associating it with the satellite.

Satellite Varieties

AccessSatellite - Provides methods for determining when a satellite has access to a ground location based on elevation angle. Can return ordered lists of upcoming opportunities.
ImagingSatellite - Extends AccessSatellite to provide methods for interacting with bsk_rl.scene.Target objects.

class Satellite(name: str, sat_args: dict[str, ~typing.Any] | None = None, obs_type=<class 'numpy.ndarray'>, variable_interval: bool = True)[source]

Bases: ABC, Resetable

The base satellite agent class.

Parameters:

name (str) – Identifier for satellite; does not need to be unique.
sat_args (dict[str, Any] | None) – Arguments for DynamicsModel and FSWModel construction. Should be in the form of a dictionary with keys corresponding to the arguments of the constructor and values that are either the desired value or a function that takes no arguments and returns a randomized value.
obs_type – Observation format for the satellite. The bsk_rl.obs.observations.ObservationBuilder will convert the observation to this format.
variable_interval (bool) – Whether to stop the simulation at terminal events. If False, only the max_step_duration setting in GeneralSatelliteTasking will stop the simulation.

dyn_type: type[dyn.DynamicsModel]

fsw_type: type[fsw.FSWModel]

observation_spec: list[Observation]

action_spec: list[Action]

classmethod default_sat_args(**kwargs) → dict[str, Any][source]

Compile default arguments for DynamicsModel and FSWModel, replacing those specified.

Parameters:: **kwargs – Arguments to override in the default arguments.
Returns:: Dictionary of arguments for simulation models.
Return type:: dict[str, Any]

property id: str: Unique human-readable identifier.

generate_sat_args(**kwargs) → None[source]

Instantiate sat_args from any randomizers in provided sat_args.

Parameters:: **kwargs – Arguments to override in the default arguments.
Return type:: None

reset_overwrite_previous() → None[source]

Overwrite attributes from previous episode.

Return type:: None

reset_pre_sim_init() → None[source]

Called during environment reset, before Basilisk simulation initialization.

Return type:: None

reset_post_sim_init() → None[source]

Called during environment reset, after Basilisk simulation initialization.

Return type:: None

property observation_space: Space

Observation space for single satellite, determined from observation.

Returns:: gymanisium observation space

get_obs() → Any[source]

Construct the satellite’s observation.

Returns:: satellite observation
Return type:: Any

property observation_description: Any: Human-interpretable description of observation space.

property action_space: Space

Action space for single satellite.

Returns:: gymanisium action space

set_action(action: Any) → None[source]

Enable certain processes in the simulator to command the satellite task.

Parameters:: action (Any) – Action to take, according to the action_spec
Return type:: None

property action_description: Any: Human-interpretable description of action space.

is_alive(log_failure=True) → bool[source]

Check if the satellite is violating any aliveness requirements.

Checks aliveness checkers in dynamics and FSW models.

Returns:: is_alive
Return type:: bool

record_death(time: float) → None[source]

Record the time of death of the satellite, if not already recorded.

Parameters:: time (float) – Time of death [s]
Return type:: None

update_timed_terminal_event(t_close: float, info: str = '', extra_actions: list[str] = []) → None[source]

Create a simulator event that stops the simulation a certain time.

Parameters:

t_close (float) – Termination time [s]
info (str) – Additional identifying info to log at terminal time
extra_actions (list[str]) – Additional actions to perform at terminal time

Return type:

None

disable_timed_terminal_event() → None[source]

Turn off simulator termination due to update_timed_terminal_event.

Return type:: None

class AccessSatellite(*args, generation_duration: float = 600.0, initial_generation_duration: float | None = None, **kwargs)[source]

Bases: Satellite

Satellite that detects access opportunities for ground locations.

This satellite can be used to computes access opportunities for ground locations such as imaging targets or ground stations. The satellite will calculate upcoming opportunities for each location and order the opportunities by close time. Opportunities are calculated based on a per-location minimum elevation angle.

Parameters:

args – Passed through to Satellite constructor.
generation_duration (float) – [s] Duration to calculate additional opportunities for when the simulation time reaches the current calculation time. If None, generate opportunities for the simulation time_limit unless the simulation is infinite.
initial_generation_duration (float | None) – [s] Period to calculate opportunities for on environment reset.
kwargs – Passed through to Satellite constructor.

reset_overwrite_previous() → None[source]

Overwrite previous opportunities and locations.

Return type:: None

add_location_for_access_checking(object: Any, r_LP_P: ndarray, min_elev: float, type: str) → None[source]

Add a location to be included in opportunity calculations.

Warning

The added location will only be considered in future calls to calculate_additional_windows; opportunities are not computed retroactively.

Parameters:

object (Any) – Object for with to compute opportunities.
r_LP_P (ndarray) – [m] Objects planet-fixed location.
min_elev (float) – [rad] Minimum elevation angle for access.
type (str) – Category of opportunity target provides.

Return type:

None

calculate_additional_windows(duration: float) → None[source]

Use a multiroot finding method to evaluate imaging windows for each location.

Parameters:: duration (float) – Time to calculate windows from end of previous window.
Return type:: None

property upcoming_opportunities: list[dict]: Ordered list of opportunities that have not yet closed.

opportunities_dict(types: str | list[str] | None = None, filter: Callable | None | list = None) → dict[Any, list[tuple[float, float]]][source]

Make dictionary of opportunities that maps objects to lists of windows.

Parameters:

types (str | list[str] | None) – Types of opportunities to include. If None, include all types.
filter (Callable | None | list) – Function that takes an opportunity dictionary and returns a boolean if the opportunity should be included in the output.

Return type:

dict[Any, list[tuple[float, float]]]

upcoming_opportunities_dict(types: str | list[str] | None = None, filter: Callable | None | list = None) → dict[Any, list[tuple[float, float]]][source]

Get dictionary of upcoming opportunities.

Maps objects to lists of windows that have not yet closed.

Parameters:

types (str | list[str] | None) – Types of opportunities to include. If None, include all types.
filter (Callable | None | list) – Function that takes an opportunity dictionary and returns a boolean if the opportunity should be included in the output.

Return type:

dict[Any, list[tuple[float, float]]]

next_opportunities_dict(types: str | list[str] | None = None, filter: Callable | None | list = None) → dict[Any, tuple[float, float]][source]

Make dictionary of opportunities that maps objects to the next open windows.

Parameters:

types (str | list[str] | None) – Types of opportunities to include. If None, include all types.
filter (Callable | None | list) – Function that takes an opportunity dictionary and returns a boolean if the opportunity should be included in the output.

Return type:

dict[Any, tuple[float, float]]

find_next_opportunities(n: int, pad: bool = True, max_lookahead: int = 100, types: str | list[str] | None = None, filter: Callable | None | list = None) → list[dict][source]

Find the n nearest opportunities, sorted by window close time.

Parameters:

n (int) – Number of opportunities to attempt to include.
pad (bool) – If true, duplicates the last target if the number of opportunities found is less than n.
max_lookahead (int) – Maximum times to call calculate_additional_windows.
types (str | list[str] | None) – Types of opportunities to include. If None, include all types.
filter (Callable | None | list) – Function that takes an opportunity dictionary and returns a boolean if the opportunity should be included in the output.

Returns:

n nearest opportunities, ordered

Return type:

list[dict]

add_access_filter(access_filter_fn: Callable, types: str | list[str] | None = None)[source]

Add an access filter function to the list of access filters.

Calls to opportunities_dict, find_next_opportunities, and similar functions will use the boolean AND of all access filter functions, unless otherwise specified.

Access filters are used by various other aspects of the environment to limit which opportunities are considered based on the satellite’s local knowledge of the environment.

Parameters:

access_filter_fn (Callable)
types (str | list[str] | None)

class ImagingSatellite(*args, **kwargs)[source]

Bases: AccessSatellite

Satellite with agile imaging capabilities.

Stop the simulation when a target is imaged or missed so that time is not wasted on an inaccessible or already imaged target.

dyn_type: alias of ImagingDynModel

fsw_type: alias of ImagingFSWModel

property known_targets: list[Target]: List of known targets.

reset_overwrite_previous() → None[source]

Overwrite statistics about previous episode.

Return type:: None

parse_target_selection(target_query: int | Target | str)[source]

Identify a target from a query.

Parses an upcoming target index, Target object, or target id.

Parameters:: target_query (int | Target | str) – Target upcoming index, object, or id.

enable_target_window(target: Target)[source]

Enable a timed opportunity close event and a successfully imaged event.

Parameters:: target (Target) – Target to terminate the step on imaging or when out of range.

task_target_for_imaging(target: Target)[source]

Task the satellite to image a target.

Parameters:: target (Target) – Selected target