Observations

Observations are found at bsk_rl.obs.

Satellite observation types can be used to add information to the observation. Observation provides an interface for creating new observation types. To configure the observation, set the observation_spec attribute of a Satellite subclass. For example:

class MyObservationSatellite(Satellite):
    observation_spec = [
        SatProperties(
            dict(prop="r_BN_P", module="dynamics", norm=REQ_EARTH * 1e3),
            dict(prop="v_BN_P", module="dynamics", norm=7616.5),
        ),
        obs.OpportunityProperties(
            dict(prop="priority"),
            dict(prop="r_LP_P", norm=REQ_EARTH * 1e3),
            n_ahead_observe=16,
        ),
        obs.Time(),
    ]

The format of the observation can setting the obs_type attribute of the Satellite. The default is np.ndarray, but it can also be set to a human-readable dict or a list.

Some commonly used observations are provided:

SatProperties - Add arbitrary dynamics and fsw properties.
RelativeProperties - Add arbitrary properties relative to some other satellite.
Time - Add simulation time to the observation.
OpportunityProperties - Add information about upcoming targets or other ground access points to the observation.
Eclipse - Add a tuple of the next orbit start and end.
ResourceRewardWeight - Reports the weights of any randomized ResourceReward.

class Observation(name: str = 'obs')[source]

Bases: ABC, Resetable

Construct an observation.

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

abstract get_obs() → Any[source]

Return the observation.

Return type:: Any

class SatProperties(*obs_properties: dict[str, Any], name='sat_props')[source]

Bases: Observation

Include properties from fsw and dynamics in the observation.

For each desired property, a dictionary specifying the property name and settings is passed. For example, to query the position and velocity of the satellite, the following would be used:

SatProperties(
    dict(prop="r_BN_P", module="dynamics", norm=REQ_EARTH * 1e3),
    dict(prop="v_BN_P", module="dynamics", norm=7616.5, name="velocity"),
),

Parameters:

obs_properties (dict[str, Any]) –
Property that can be found in fsw or dynamics that are to be appended to the the observation. Properties are optionally normalized by some factor. Each observation is a dictionary with the keys:
- prop: Name of property in fsw and dynamics to query
- module optional: Module (dynamics or fsw) that holds the property. Can be inferred if None.
- norm optional: Value to normalize property by. Defaults to 1.0.
- name optional: Name of the observation element. Defaults to the value of prop.
- fn optional: Alternatively, call a function that takes the satellite as an argument.
name – Name of the observation.

class RelativeProperties(*rel_properties: dict[str, Any], chief_name: str, name='rel_props')[source]

Bases: Observation

Include properties relative to another satellite.

Within the observation specification for the deputy satellite, this would look like.

obs.RelativeProperties(
    dict(prop="r_DC_N", norm=1e3),
    dict(prop="v_DC_N", norm=1e3),
    chief_name="ChiefSat",
),

Parameters:

rel_properties (dict[str, Any]) –
Property specifications. Properties are optionally normalized by some factor. Each observation is a dictionary with the keys:
- prop: Name of a function in Relative Properties.
- norm optional: Value to normalize property by. Defaults to 1.0.
- name optional: Name of the observation element. Defaults to the value of prop.
- fn optional: Alternatively, call a function that takes the deputy (self) and chief (other) as arguments.
chief_name (str) – Name of the satellite to compare against.
name – Name of the observation.

class Time(norm=None, name='time', observe_time_remaining=False)[source]

Bases: Observation

Include the simulation time in the observation.

Parameters:

norm – Time to normalize by. If None, the time is normalized by the simulation time limit.
name – Name of the observation.
observe_time_remaining – If True, return the time remaining until the simulation time limit.

class OpportunityProperties(*target_properties: dict[str, Any], n_ahead_observe: int, type='target', name=None)[source]

Bases: Observation

Include information about upcoming access opportunities in the observation..

For each desired property, a dictionary specifying the property name and settings is passed. These can include preset properties or arbitrary functions of the satellite and opportunity.

OpportunityProperties(
    dict(prop="r_LP_P", norm=REQ_EARTH * 1e3),
    dict(prop="double_priority", fn=lambda sat, opp: opp["target"].priority * 2.0),
    n_ahead_observe=16,
)

Parameters:

target_properties (dict[str, Any]) –
Property that is a function of the opportunity to be appended to the the observation. Properties are optionally normalized by some factor. Each observation is a dictionary with the keys:
- name optional: Name of the observation element.
- fn optional: Function to calculate property, in the form fn(satellite, opportunity). If not provided, the key prop will be used to look up a preset function:
  - priority: Priority of the target.
  - r_LP_P: Location of the target in the planet-fixed frame.
  - r_LB_H: Location of the target in the Hill frame.
  - opportunity_open: Time until the opportunity opens.
  - opportunity_mid: Time until the opportunity midpoint.
  - opportunity_close: Time until the opportunity closes.
  - target_angle: Angle between the target and the satellite instrument direction.
  - target_angle_rate: Rate difference between the target pointing frame and the body frame.
- norm optional: Value to normalize property by. Defaults to 1.0.
n_ahead_observe (int) – Number of upcoming targets to consider.
type – The type of opportunity to consider. Can be target, ground_station, or any other type of opportunity that has been added via add_location_for_access_checking.
name – Name of the observation.

class Eclipse(norm=1.0, name='eclipse')[source]

Bases: Observation

Include a tuple of the next eclipse start and end times in the observation.

Parameters:

norm – Value to normalize by.
name – Name of the observation.

class ResourceRewardWeight(name='resource_reward_weight', norm: float | ndarray = 1.0)[source]

Bases: Observation

Include the resource reward weight in the observation.

Parameters:

name – Name of the observation.
norm (float | ndarray) – Value to normalize the resource reward weight by. If a vector, it should be the same length as the number of resource rewards in the environment.

reset_overwrite_previous() → None[source]

Prepare weights to be saved by rewarders.

Return type:: None

get_obs() → float[source]

Return the resource reward weight.

Return type:: float