Dynamics Sims

Basilisk dynamics models are given in bsk_rl.sim.dyn.

The dynamics model is the core of the satellite simulation, representing the physical properties of the satellite and its interactions with the environment. The dynamics model can be customized to represent different satellite configurations, actuator models, and instrument models.

The dynamics model is selected using the dyn_type class property of the Satellite. Certain environment elements may require specific dynamics models, such as LOSCommunication requiring a dynamics model that inherits from LOSCommDynModel or ImagingSatellite requiring a dynamics model that inherits from ImagingDynModel.

Setting Parameters

Customization of the dynamics model parameters is achieved through the sat_args dictionary passed to the Satellite constructor. This dictionary is passed on to the dynamics model setup functions, which are called each time the simulator is reset.

Properties

The dynamics model provides a number of properties for easy access to the satellite state. These can be accessed directly from the dynamics model instance, or in the observation via the SatProperties observation.

Aliveness Checking

Certain functions in the dynamics model are decorated with the aliveness_checker() decorator. These functions are called at each step to check if the satellite is still operational, returning true if the satellite is still alive.

class DynamicsModel(satellite: Satellite, dyn_rate: float, priority: int = 200, **kwargs)[source]

Bases: ABC

The abstract base dynamics model.

One DynamicsModel is instantiated for each satellite in the environment each time the environment is reset and new simulator is created.

Parameters:

  • satellite (Satellite) – Satellite represented by this model.

  • dyn_rate (float) – [s] Rate of dynamics simulation.

  • priority (int) – Model priority.

  • kwargs – Passed through to setup functions.

property simulator: Simulator

Reference to the episode simulator.

property world: WorldModel

Reference to the episode world model.

is_alive(log_failure=False) → bool[source]

Check if the dynamics model has failed any aliveness requirements.

Returns:

True if the satellite dynamics are still alive.

Return type:

bool

reset_for_action() → None[source]

Reset whenever a flight software action is called.

Return type:

None

class BasicDynamicsModel(*args, **kwargs)[source]

Bases: DynamicsModel

A dynamics model with a basic feature set.

Includes the following:

  • Spacecraft hub physical properties

  • Gravity

  • Constant disturbance torque (defaults to none)

  • Aerodynamic drag

  • Eclipse checking for power generation

  • Reaction wheels

  • Momentum desaturation thrusters

  • Solar panels, battery, and power system

Parameters:

  • *args – Passed to superclass

  • **kwargs – Passed to superclass

property sigma_BN

Body attitude MRP relative to inertial frame.

property BN

Body relative to inertial frame rotation matrix.

property omega_BN_B

Body rate relative to inertial frame in body frame [rad/s].

property BP

Body relative to planet freame rotation matrix.

property r_BN_N

Body position relative to inertial origin in inertial frame [m].

property r_BN_P

Body position relative to inertial origin in planet frame [m].

property v_BN_N

Body velocity relative to inertial origin in inertial frame [m/s].

property v_BN_P

Planet-frame derivative of r_BN.

property omega_BP_P

Body angular velocity relative to planet frame in plant frame [rad/s].

property omega_BH_H

Body angular velocity relative to Hill frame in Hill frame [rad/s].

property battery_charge

Battery charge [W*s].

property battery_charge_fraction

Battery charge as a fraction of capacity.

property wheel_speeds

Wheel speeds [rad/s].

property wheel_speeds_fraction

Wheel speeds normalized by maximum allowable speed.

setup_spacecraft_hub(mass: float, width: float, depth: float, height: float, sigma_init: Iterable[float], omega_init: Iterable[float], oe: Iterable[float] | None, rN: Iterable[float] | None, vN: Iterable[float] | None, mu: float, priority: int = 2000, **kwargs) → None[source]

Set up the spacecraft hub physical properties and state.

The hub is assumed to be a uniform-density rectangular prism with the center of mass at the center.

Parameters:

  • mass (float) – [kg] Hub mass.

  • width (float) – [m] Hub width.

  • depth (float) – [m] Hub depth.

  • height (float) – [m] Hub height.

  • sigma_init (Iterable[float]) – Initial attitude MRP.

  • omega_init (Iterable[float]) – [rad/s] Initial body rate.

  • oe (Iterable[float] | None) – Orbital element tuple of (semimajor axis [km], eccentricity, inclination [rad], ascending node [rad], argument of periapsis [rad], initial true anomaly [rad]). Either oe and mu or rN and vN must be provided, but not both.

  • mu (float) – Gravitational parameter (used only with oe).

  • rN (Iterable[float] | None) – [m] Initial inertial position.

  • vN (Iterable[float] | None) – [m/s] Initial inertial velocity.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_gravity_bodies() → None[source]

Set up gravitational bodies from the WorldModel to included in the simulation.

Return type:

None

setup_disturbance_torque(disturbance_vector: Iterable[float] | None = None, **kwargs) → None[source]

Set up a constant disturbance torque acting on the satellite.

Parameters:

  • disturbance_vector (Iterable[float] | None) – [N*m] Constant disturbance torque in the body frame.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_density_model() → None[source]

Set up the atmospheric density model effector.

Return type:

None

setup_drag_effector(width: float, depth: float, height: float, panelArea: float, dragCoeff: float, priority: int = 999, **kwargs) → None[source]

Set up the satellite drag effector.

The drag effector causes aerodynamic forces and torques to act on the satellite. For purposes of this model, the satellite is assumed to be a rectangular prism with a solar panel on one end.

Parameters:

  • width (float) – [m] Hub width.

  • depth (float) – [m] Hub depth.

  • height (float) – [m] Hub height.

  • panelArea (float) – [m^2] Solar panel surface area.

  • dragCoeff (float) – Drag coefficient.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_simple_nav_object(priority: int = 1400, **kwargs) → None[source]

Set up the navigation module.

Parameters:

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

altitude_valid() → bool[source]

Decorated with aliveness_checker

Check that satellite has not deorbited.

Checks if altitude is greater than 200km above Earth’s surface.

Return type:

bool

setup_reaction_wheel_dyn_effector(wheelSpeeds: Iterable[float], maxWheelSpeed: float, u_max: float, priority: int = 997, **kwargs) → None[source]

Set the reaction wheel state effector parameters.

Three reaction wheels modeled on the HR16 wheel are used.

Parameters:

  • wheelSpeeds (Iterable[float]) – [rpm] Initial speeds of each wheel.

  • maxWheelSpeed (float) – [rpm] Failure speed for wheels.

  • u_max (float) – [N*m] Maximum torque producible by each wheel.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

rw_speeds_valid() → bool[source]

Decorated with aliveness_checker

Check if any wheel speed exceeds the maxWheelSpeed.

Return type:

bool

setup_thruster_dyn_effector(priority: int = 996) → None[source]

Set up the thruster state effector.

Parameters:

priority (int) – Model priority.

Return type:

None

setup_thruster_power(thrusterPowerDraw, priority: int = 899, **kwargs) → None[source]

Set up the thruster power draw.

When momentum desaturating using wheels, power is consumed at this rate.

Parameters:

  • thrusterPowerDraw – [W] Constant power draw desat mode is active.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_eclipse_object() → None[source]

Add the spacecraft to the eclipse module.

Return type:

None

setup_solar_panel(panelArea: float, panelEfficiency: float, nHat_B: Iterable[float], priority: int = 898, **kwargs) → None[source]

Set the solar panel parameters for power generation.

Power generation takes into account panel size and efficiency, the eclipse state, and the angle of solar incidence.

Parameters:

  • panelArea (float) – [m^2] Solar panel area.

  • panelEfficiency (float) – Efficiency coefficient of solar to electrical power conversion.

  • nHat_B (Iterable[float]) – Body-fixed array normal vector.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_battery(batteryStorageCapacity: float, storedCharge_Init: float, priority: int = 799, **kwargs) → None[source]

Set the battery model parameters.

Parameters:

  • batteryStorageCapacity (float) – [W*s] Maximum battery charge.

  • storedCharge_Init (float) – [W*s] Initial battery charge.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

battery_valid() → bool[source]

Decorated with aliveness_checker

Check if the battery has charge remaining.

Note that this check is instantaneous. If a satellite runs out of power during a environment step but then recharges to have positive power at the end of the step, the satellite will still be considered alive.

Return type:

bool

setup_power_sink(basePowerDraw: float, priority: int = 897, **kwargs) → None[source]

Set the instrument power sink parameters.

Parameters:

  • basePowerDraw (float) – [W] Baseline satellite power draw. Should be negative.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_reaction_wheel_power(rwBasePower: float, rwMechToElecEfficiency: float, rwElecToMechEfficiency: float, priority: int = 987, **kwargs) → None[source]

Set the reaction wheel power draw.

Parameters:

  • rwBasePower (float) – [W] Constant power draw when operational.

  • rwMechToElecEfficiency (float) – Efficiency factor to convert mechanical power to electrical power.

  • rwElecToMechEfficiency (float) – Efficiency factor to convert electrical power to mechanical power.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

class LOSCommDynModel(*args, **kwargs)[source]

Bases: BasicDynamicsModel

Allow for line-of-sight checking between satellites.

Necessary for LOSCommunication to function.

setup_los_comms(losMaximumRange: float, priority: int = 500, **kwargs) → None[source]

Set up line-of-sight visibility checking between satellites.

Parameters:

  • losMaximumRange (float) – [m] Maximum range for line-of-sight visibility. -1 for unlimited.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

class ImagingDynModel(*args, **kwargs)[source]

Bases: BasicDynamicsModel

Equips the satellite with an instrument, storage unit, and transmitter.

This dynamics model is used with ImagingSatellite. It provides the satellite with the ability to take images of a point target. To enable downlink, use GroundStationDynModel and GroundStationWorldModel.

property storage_level

Storage level [bits].

property storage_level_fraction

Storage level as a fraction of capacity.

setup_instrument(instrumentBaudRate: float, priority: int = 895, **kwargs) → None[source]

Set up the instrument data collection model.

Parameters:

  • instrumentBaudRate (float) – [bits] Data generated by an image.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_transmitter(transmitterBaudRate: float, instrumentBaudRate: float, transmitterNumBuffers: int, priority: int = 798, **kwargs) → None[source]

Set up the transmitter model for downlinking data.

Parameters:

  • transmitterBaudRate (float) – [baud] Rate of data downlink. Should be negative.

  • instrumentBaudRate (float) – [bits] Image size, used to set packet size.

  • transmitterNumBuffers (int) – Number of transmitter buffers

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_instrument_power_sink(instrumentPowerDraw: float, priority: int = 897, **kwargs) → None[source]

Set the instrument power sink parameters.

The instrument draws power when in an imaging task, representing the power cost of operating the instrument.

Parameters:

  • instrumentPowerDraw (float) – [W] Power draw when instrument is enabled.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_transmitter_power_sink(transmitterPowerDraw: float, priority: int = 896, **kwargs) → None[source]

Set the transmitter power sink parameters.

The transmitter draws power when in a downlink task, representing the power cost of downlinking data.

Parameters:

  • transmitterPowerDraw (float) – [W] Power draw when transmitter is enabled.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_storage_unit(dataStorageCapacity: int, storageUnitValidCheck: bool, storageInit: int, transmitterNumBuffers: int | None = None, bufferNames: Iterable[str] | None = None, priority: int = 699, **kwargs) → None[source]

Configure the storage unit and its buffers.

Separate buffers can be used to track imaging of different targets. Often, the buffer names will be set up by satellite based on the scenario configuration.

Parameters:

  • dataStorageCapacity (int) – [bits] Maximum data that can be stored.

  • transmitterNumBuffers (int | None) – Number of unit buffers. Not necessary if bufferNames are given.

  • bufferNames (Iterable[str] | None) – List of buffer names to use. Named by number if None.

  • storageUnitValidCheck (bool) – If True, enforce that the storage level is below the storage capacity when checking aliveness.

  • storageInit (int) – [bits] Initial storage level.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

data_storage_valid() → bool[source]

Decorated with aliveness_checker

Check that the buffer has not run out of space.

Only is checked if storageUnitValidCheck is True; otherwise, a full storage unit will prevent additional data from being stored but will not cause the satellite to be considered dead.

Return type:

bool

setup_imaging_target(groundLocationPlanetRadius: float, imageTargetMinimumElevation: float, imageTargetMaximumRange: float, priority: int = 2000, **kwargs) → None[source]

Add a generic imaging target to dynamics.

The target must be updated with a particular location when used.

Parameters:

  • groundLocationPlanetRadius (float) – [m] Radius of ground locations from center of planet.

  • imageTargetMinimumElevation (float) – [rad] Minimum elevation angle from target to satellite when imaging.

  • imageTargetMaximumRange (float) – [m] Maximum range from target to satellite when imaging. -1 to disable.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None[source]

Shut off power sinks unless the transmitter or instrument is being used.

Return type:

None

class ContinuousImagingDynModel(*args, **kwargs)[source]

Bases: ImagingDynModel

Equips the satellite for continuous nadir imaging.

Equips satellite with an instrument, storage unit, and transmitter for continuous nadir imaging. A single data buffer is used for storage, and data is accumulated continuously while imaging. The imaging target is fixed at the center of the Earth for nadir imaging.

setup_instrument(instrumentBaudRate: float, priority: int = 895, **kwargs) → None[source]

Set up the continuous instrument model.

Parameters:

  • instrumentBaudRate (float) – [baud] Data generation rate step when continuously imaging.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_storage_unit(dataStorageCapacity: int, storageUnitValidCheck: bool, storageInit: int, priority: int = 699, **kwargs) → None[source]

Configure the storage unit and its buffers.

Parameters:

  • dataStorageCapacity (int) – [bits] Maximum data that can be stored.

  • storageUnitValidCheck (bool) – If True, check that the storage level is below the storage capacity.

  • storageInit (int) – [bits] Initial storage level.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_imaging_target(imageTargetMaximumRange: float = -1, priority: int = 2000, **kwargs) → None[source]

Add a imaging target at the center of the Earth.

Parameters:

  • imageTargetMaximumRange (float) – [m] Maximum range from target to satellite when imaging. -1 to disable.

  • priority (int) – Model priority.

  • kwargs – Passed to other setup functions.

Return type:

None

class GroundStationDynModel(*args, **kwargs)[source]

Bases: ImagingDynModel

Model that connects satellite to world ground stations.

This model enables the use of ground stations defined in GroundStationWorldModel for data downlink.

setup_ground_station_locations() → None[source]

Connect the transmitter to ground stations.

Return type:

None

class FullFeaturedDynModel(*args, **kwargs)[source]

Bases: GroundStationDynModel, LOSCommDynModel

Convenience class for an imaging satellite with ground stations and line-of-sight communication.