Actions

Actions bsk_rl.act can be used to add actions to an agent.

To configure the observation, set the action_spec attribute of a Satellite subclass. For example:

class MyActionSatellite(Satellite):
    action_spec = [
        Charge(duration=60.0),
        Desat(duration=30.0),
        Downlink(duration=60.0),
        Image(n_ahead_image=10),
    ]

Actions in an action_spec should all be of the same subclass of Action. The following actions are currently available:

Discrete Actions

Use DiscreteAction for integer-indexable, discrete actions.

Action	Count	Description
`DiscreteFSWAction`	1	Call an arbitrary `@action` decorated function in the `FSWModel`.
`Charge`	1	Point the solar panels at the sun.
`Drift`	1	Do nothing.
`Desat`	1	Desaturate the reaction wheels with RCS thrusters. Needs to be called multiple times.
`Downlink`	1	Downlink data to any ground station that is in range.
`Image`	≥1	Image one of the next `N` upcoming, unimaged targets once in range.
`Scan`	1	Scan nadir, collecting data when pointing within a threshold.

Continuous Actions

Use ContinuousAction for actions with a continuous action space. Currently, satellites can only have a single continuous action in their action_spec.

Action	Dimension	Description
`ImpulsiveThrust`	4	Instantaneously change the satellite’s velocity, and drift for some duration.
`ImpulsiveThrustHill`	4	Like `ImpulsiveThrust`, but specified in the Hill frame of another satellite.

class Action(name: str = 'act')[source]

Bases: ABC, Resetable

Base class for all actions.

Parameters:: name (str) – Name of the action.

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

Execute code to perform an action.

Parameters:: action (Any)
Return type:: None

class DiscreteAction(name: str = 'discrete_act', n_actions: int = 1)[source]

Bases: Action

Base class for discrete, integer-indexable actions.

A discrete action may represent multiple indexed actions of the same type.

Optionally, discrete actions may have a set_action_override function defined. If the action passed to the satellite is not an integer, the satellite will iterate over the action_spec and attempt to call set_action_override on each action until one is successful.

Parameters:

name (str) – Name of the action.
n_actions (int) – Number of actions available.

abstract set_action(action: int, prev_action_key=None) → str[source]

Activate an action by local index.

Parameters:: action (int)
Return type:: str

class DiscreteFSWAction(fsw_action, name=None, duration: float | None = None, reset_task: bool = False)[source]

Bases: DiscreteAction

Discrete action to task a flight software action function.

This action executes a function of a FSWModel instance that takes no arguments, typically decorated with @action.

Parameters:

fsw_action – Name of the flight software function to task.
name – Name of the action. If not specified, defaults to the fsw_action name.
duration (float | None) – Duration of the action in seconds. Defaults to a large value so that the GeneralSatelliteTasking max_step_duration controls step length.
reset_task (bool) – If true, reset the action if the previous action was the same. Generally, this parameter should be false to ensure realistic, continuous operation of satellite modes; however, some Basilisk modules may require frequent resetting for normal operation.

set_action(action: int, prev_action_key=None) → str[source]

Activate the fsw_action function.

Parameters:

action (int) – Should always be 1.
prev_action_key – Previous action key.

Returns:

The name of the activated action.

Return type:

str

class Charge(name: str | None = None, duration: float | None = None)[source]

Bases: DiscreteFSWAction

Action to enter a sun-pointing charging mode (action_charge).

Charging will only occur if the satellite is in sunlight.

Parameters:

name (str | None) – Action name.
duration (float | None) – Time to task action, in seconds.

class Drift(name: str | None = None, duration: float | None = None)[source]

Bases: DiscreteFSWAction

Action to disable all FSW tasks (action_drift).

Parameters:

name (str | None) – Action name.
duration (float | None) – Time to task action, in seconds.

class Desat(name: str | None = None, duration: float | None = None)[source]

Bases: DiscreteFSWAction

Action to desaturate reaction wheels (action_desat).

This action must be called repeatedly to fully desaturate the reaction wheels.

Parameters:

name (str | None) – Action name.
duration (float | None) – Time to task action, in seconds.

class Downlink(name: str | None = None, duration: float | None = None)[source]

Bases: DiscreteFSWAction

Action to transmit data from the data buffer (action_downlink).

If not in range of a ground station (defined in GroundStationWorldModel), no data will be downlinked.

Parameters:

name (str | None) – Action name.
duration (float | None) – Time to task action, in seconds.

class Image(n_ahead_image: int, max_duration: float | None = None, name: str = 'action_image')[source]

Bases: DiscreteAction

Actions to image upcoming target (action_image).

Adds n_ahead_image actions to the action space, corresponding to the next n_ahead_image unimaged targets. The action may be unsuccessful if the target exits the satellite’s field of regard before the satellite settles on the target and takes an image. The action with stop as soon as the image is successfully taken, or when the the target exits the field of regard.

This action implements a set_action_override that allows a target to be tasked based on the target’s ID string or the Target object.

Parameters:

n_ahead_image (int) – Number of unimaged, along-track targets to consider.
max_duration (float | None) – Maximum time to task the action, in seconds. If None, tasks until the end of the next opportunity.
name (str) – Action name.

set_action(action: int, prev_action_key: str | None = None) → str[source]

Image a target by local index.

Parameters:

action (int) – Index of the target to image.
prev_action_key (str | None) – Previous action key.

Meta_private:

Return type:

str

set_action_override(action: Target | str, prev_action_key: str | None = None) → str[source]

Image a target by target index, Target, or ID.

Parameters:

action (Target | str) – Target to image in the form of a Target object, target ID, or target index.
prev_action_key (str | None) – Previous action key.

Meta_private:

Return type:

str

class Scan(name: str | None = None, duration: float | None = None)[source]

Bases: DiscreteFSWAction

Action to collect data from a UniformNadirScanning (action_nadir_scan).

Parameters:

name (str | None) – Action name.
duration (float | None) – Time to task action, in seconds.

class Broadcast(name: str = 'action_broadcast', duration: float | None = None)[source]

Bases: DiscreteAction

Action to broadcast data to all satellites in the simulation.

Should be used with a BroadcastCommunication-derived communication method to limit communication to broadcasting satellites.

Parameters:

name (str) – Action name.
duration (float | None) – [s] Time to idle before communicating.

reset_post_sim_init() → None[source]

Log previous action key.

Return type:: None

set_action(action: int, prev_action_key=None) → str[source]

Activate an action by local index.

Parameters:: action (int)
Return type:: str

class ContinuousAction(name: str = 'discrete_act')[source]

Bases: Action

Base class for actions with a continuous action space.

Parameters:: name (str) – Name of the action.

abstract property space: Box: Return the action space.

abstract property action_description: list[str]: Return a description of the action space.

abstract set_action(action: ndarray) → None[source]

Activate an action by a continuous value.

Parameters:: action (ndarray)
Return type:: None

class ImpulsiveThrust(name: str = 'thrust_act', max_dv: float = inf, max_drift_duration: float = inf, fsw_action: str | None = None)[source]

Bases: ContinuousAction

Perform an impulsive thrust and drift for some duration.

Parameters:

name (str) – Name of the action.
max_dv (float) – Maximum delta-V that can be applied. [m/s]
max_drift_duration (float) – Maximum duration to drift after applying the delta-V. [s]
fsw_action (str | None) – Name of the FSW action to activate during the drift period.

property space: Box: Return the action space.

property action_description: list[str]: Description of the continuous action space.

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

Thrust the satellite with a given inertial delta-V and drift for some duration.

Parameters:: action (ndarray) – vector of [dV_N_x, dV_N_y, dV_N_z, duration] in [m/s] and [s]
Return type:: None

class ImpulsiveThrustHill(chief_name, *args, **kwargs)[source]

Bases: ImpulsiveThrust

Impulsive thrusts in the Hill frame.

Parameters:

chief_name – Chief to use for Hill frame.
*args – Passed to ImpulsiveThrust.
**kwargs – Passed to ImpulsiveThrust.

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

Activate the action by setting the continuous value.

Parameters:: action (ndarray)
Return type:: None