usersatellite_gateway_to_constellation

cosmica.topology.usersatellite_gateway_to_constellation

__all__ module-attribute

__all__ = [
    "HybridUS2CG2CTopologyBuilder",
    "build_hybrid_us2c_g2c_topology",
]

logger module-attribute

logger = getLogger(__name__)

HybridUS2CG2CTopologyBuilder

HybridUS2CG2CTopologyBuilder(
    max_distance: float = float("inf"),
    max_relative_angular_velocity: float = float("inf"),
    sun_exclusion_angle: float = 0.0,
)

Hybrid topology builder for user satellites and ground stations to constellation.

This builder combines the functionality of MaxConnectionTimeUS2CTopologyBuilder and MaxVisibilityHandOverG2CTopologyBuilder. It prioritizes user satellite connections and then optimizes ground station connections based on maximum visibility duration.

For user satellites, constraints include distance, sun exclusion angle, and relative angular velocity. For ground stations, constraints include elevation angle and sun exclusion angle.

Source code in src/cosmica/topology/usersatellite_gateway_to_constellation.py

def __init__(
    self,
    max_distance: float = float("inf"),
    max_relative_angular_velocity: float = float("inf"),
    sun_exclusion_angle: float = 0.0,
) -> None:
    self.max_distance = max_distance
    self.max_relative_angular_velocity = max_relative_angular_velocity
    self.sun_exclusion_angle = sun_exclusion_angle

max_distance instance-attribute

max_distance = max_distance

max_relative_angular_velocity instance-attribute

max_relative_angular_velocity = (
    max_relative_angular_velocity
)

sun_exclusion_angle instance-attribute

sun_exclusion_angle = sun_exclusion_angle

build

build(
    *,
    constellation: Constellation,
    user_satellites: Collection[UserSatellite],
    ground_nodes: Collection[
        Gateway | StationaryOnGroundUser
    ],
    dynamics_data: DynamicsData
) -> list[Graph]

Build hybrid topology connecting user satellites and ground stations to constellation.

Source code in src/cosmica/topology/usersatellite_gateway_to_constellation.py

def build(
    self,
    *,
    constellation: Constellation,
    user_satellites: Collection[UserSatellite],
    ground_nodes: Collection[Gateway | StationaryOnGroundUser],
    dynamics_data: DynamicsData,
) -> list[nx.Graph]:
    """Build hybrid topology connecting user satellites and ground stations to constellation."""
    return build_hybrid_us2c_g2c_topology(
        constellation=constellation,
        user_satellites=user_satellites,
        ground_nodes=ground_nodes,
        dynamics_data=dynamics_data,
        max_distance=self.max_distance,
        max_relative_angular_velocity=self.max_relative_angular_velocity,
        sun_exclusion_angle=self.sun_exclusion_angle,
    )

build_hybrid_us2c_g2c_topology

build_hybrid_us2c_g2c_topology(
    constellation: Constellation,
    *,
    user_satellites: Collection[UserSatellite],
    ground_nodes: Collection[
        Gateway | StationaryOnGroundUser
    ],
    dynamics_data: DynamicsData,
    max_distance: float = float("inf"),
    max_relative_angular_velocity: float = float("inf"),
    sun_exclusion_angle: float = 0.0
) -> list[Graph]

Build hybrid topology connecting user satellites and ground stations to constellation.

Combines user-satellite and ground-station connectivity. User satellite connections are prioritized, then ground station connections are optimized based on maximum visibility duration.

This function only needs the satellite set, so it accepts Constellation with any SatelliteId type.

PARAMETER	DESCRIPTION
constellation	Constellation (any SatelliteId type). TYPE: Constellation
user_satellites	User satellites to connect. TYPE: Collection[UserSatellite]
ground_nodes	Ground stations or users. TYPE: Collection[Gateway | StationaryOnGroundUser]
dynamics_data	Time-series dynamics data. TYPE: DynamicsData
max_distance	Maximum distance constraint for user satellite links. TYPE: float DEFAULT: float('inf')
max_relative_angular_velocity	Maximum relative angular velocity constraint. TYPE: float DEFAULT: float('inf')
sun_exclusion_angle	Sun exclusion angle constraint (radians). TYPE: float DEFAULT: 0.0

RETURNS	DESCRIPTION
list[Graph]	A list of networkx Graphs, one per time step.

Source code in src/cosmica/topology/usersatellite_gateway_to_constellation.py

def build_hybrid_us2c_g2c_topology(
    constellation: Constellation,
    *,
    user_satellites: Collection[UserSatellite],
    ground_nodes: Collection[Gateway | StationaryOnGroundUser],
    dynamics_data: DynamicsData,
    max_distance: float = float("inf"),
    max_relative_angular_velocity: float = float("inf"),
    sun_exclusion_angle: float = 0.0,
) -> list[nx.Graph]:
    """Build hybrid topology connecting user satellites and ground stations to constellation.

    Combines user-satellite and ground-station connectivity. User satellite
    connections are prioritized, then ground station connections are optimized
    based on maximum visibility duration.

    This function only needs the satellite set, so it accepts `Constellation`
    with any `SatelliteId` type.

    Args:
        constellation: Constellation (any SatelliteId type).
        user_satellites: User satellites to connect.
        ground_nodes: Ground stations or users.
        dynamics_data: Time-series dynamics data.
        max_distance: Maximum distance constraint for user satellite links.
        max_relative_angular_velocity: Maximum relative angular velocity constraint.
        sun_exclusion_angle: Sun exclusion angle constraint (radians).

    Returns:
        A list of networkx Graphs, one per time step.

    """
    logger.info(
        f"Building hybrid topology for {len(user_satellites)} user satellites and {len(ground_nodes)} ground nodes",
    )
    logger.info(f"Number of time steps: {len(dynamics_data.time)}")

    user_satellites_list = list(user_satellites)
    ground_nodes_list = list(ground_nodes)
    constellation_satellites = list(constellation.satellites.values())

    n_time = len(dynamics_data.time)

    # Calculate user satellite visibility
    logger.info("Calculating user satellite visibility...")
    user_visibility = _calculate_user_satellite_visibility(
        user_satellites_list,
        constellation_satellites,
        dynamics_data,
        max_distance=max_distance,
        max_relative_angular_velocity=max_relative_angular_velocity,
        sun_exclusion_angle=sun_exclusion_angle,
    )

    # Calculate ground node visibility
    logger.info("Calculating ground node visibility...")
    ground_visibility = _calculate_ground_visibility(
        ground_nodes_list,
        constellation_satellites,
        dynamics_data,
        sun_exclusion_angle=sun_exclusion_angle,
    )

    # Calculate remaining connection times (backward pass)
    user_remaining = _calculate_remaining_connection_time(user_visibility)
    ground_remaining = _calculate_remaining_connection_time(ground_visibility)

    # Build topology for each time step
    logger.info("Building topology graphs for each time step...")
    return _build_topology_graphs(
        n_time=n_time,
        constellation_satellites=constellation_satellites,
        user_satellites=user_satellites_list,
        ground_nodes=ground_nodes_list,
        user_visibility=user_visibility,
        ground_visibility=ground_visibility,
        user_remaining=user_remaining,
        ground_remaining=ground_remaining,
    )