models

cosmica.models

NodeGID module-attribute

NodeGID = NewType('NodeGID', str)

__all__ module-attribute

__all__ = [
    "CircularSatelliteOrbitModel",
    "CommunicationTerminal",
    "ConstantCommunicationDemand",
    "ConstellationSatellite",
    "Demand",
    "EllipticalSatelliteOrbitModel",
    "Gateway",
    "GatewayOGS",
    "GravityModel",
    "Internet",
    "Node",
    "NodeGID",
    "OneTimeCommunicationDemand",
    "OpticalCommunicationTerminal",
    "RFCommunicationTerminal",
    "Satellite",
    "SatelliteTerminal",
    "Scenario",
    "StationaryOnGroundUser",
    "User",
    "UserOpticalCommunicationTerminal",
    "UserSatellite",
    "load_demands_from_toml_file",
    "load_users_from_toml_file",
]

CircularSatelliteOrbitModel

Bases: SatelliteOrbitModel

epoch instance-attribute

epoch: datetime64

inclination instance-attribute

inclination: float

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

phase_at_epoch instance-attribute

phase_at_epoch: float

raan instance-attribute

raan: float

semi_major_axis instance-attribute

semi_major_axis: float

CommunicationTerminal dataclass

CommunicationTerminal(*, id: T)

Bases: Node[T]

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/terminal.py

@classmethod
@override
def class_name(cls) -> str:
    return "CT"

ConstantCommunicationDemand dataclass

ConstantCommunicationDemand(
    *,
    id: T,
    source: NodeGID,
    destination: NodeGID,
    distribution: Literal["uniform", "poisson"],
    transmission_rate: float
)

Bases: Demand[T]

Constant communication demand model.

destination instance-attribute

destination: NodeGID

distribution instance-attribute

distribution: Literal['uniform', 'poisson']

id instance-attribute

id: T

source instance-attribute

source: NodeGID

transmission_rate instance-attribute

transmission_rate: float

parse_demand_item classmethod

parse_demand_item(item: Mapping[str, Any]) -> Self

Source code in src/cosmica/models/demand.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_demand_item(cls, item: Mapping[str, Any]) -> Self:
    return cls(
        id=item["id"],
        source=item["src_gid"],
        destination=item["dst_gid"],
        transmission_rate=item["transmission_rate_bps"],
        distribution=item["distribution"],
    )

ConstellationSatellite dataclass

ConstellationSatellite(
    *, id: T, orbit: SatelliteOrbitModel | None = None
)

Bases: Satellite[T]

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

orbit class-attribute instance-attribute

orbit: SatelliteOrbitModel | None = None

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/satellite.py

@classmethod
@override
def class_name(cls) -> str:
    return "CSAT"

Demand dataclass

Demand(*, id: T)

Bases: ABC

Base model for a demand.

id instance-attribute

id: T

parse_demand_item abstractmethod classmethod

parse_demand_item(item: Mapping[str, Any]) -> Self

Parse a demand item.

Source code in src/cosmica/models/demand.py

@classmethod
@abstractmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_demand_item(cls, item: Mapping[str, Any]) -> Self:
    """Parse a demand item."""
    ...

EllipticalSatelliteOrbitModel

Bases: SatelliteOrbitModel

argpo instance-attribute

argpo: float

drag_coeff instance-attribute

drag_coeff: float

eccentricity instance-attribute

eccentricity: float

epoch instance-attribute

epoch: datetime64

gravity_model class-attribute instance-attribute

gravity_model: GravityModel = WGS84

inclination instance-attribute

inclination: float

model_config class-attribute instance-attribute

model_config = ConfigDict(arbitrary_types_allowed=True)

phase_at_epoch instance-attribute

phase_at_epoch: float

raan instance-attribute

raan: float

satnum instance-attribute

satnum: int

semi_major_axis instance-attribute

semi_major_axis: float

Gateway dataclass

Gateway(
    *,
    id: T,
    latitude: float,
    longitude: float,
    minimum_elevation: float,
    altitude: float = 0.0,
    n_terminals: int = 1
)

Bases: Node[T]

altitude class-attribute instance-attribute

altitude: float = field(default=0.0, compare=False)

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

latitude class-attribute instance-attribute

latitude: float = field(compare=False)

longitude class-attribute instance-attribute

longitude: float = field(compare=False)

minimum_elevation class-attribute instance-attribute

minimum_elevation: float = field(compare=False)

n_terminals class-attribute instance-attribute

n_terminals: int = field(default=1, compare=False)

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/gateway.py

@classmethod
@override
def class_name(cls) -> str:
    return "GW"

from_toml_file classmethod

from_toml_file(toml_file_path: Path | str) -> list[Self]

Source code in src/cosmica/models/gateway.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def from_toml_file(cls, toml_file_path: Path | str) -> list[Self]:
    toml_file_path = Path(toml_file_path)
    with toml_file_path.open("rb") as f:
        toml_data = tomllib.load(f)
    return list(map(cls.parse_gateway_item, toml_data["gateways"]))

parse_gateway_item classmethod

parse_gateway_item(item: MutableMapping[str, Any]) -> Self

Source code in src/cosmica/models/gateway.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_gateway_item(cls, item: MutableMapping[str, Any]) -> Self:
    item["latitude"] = np.deg2rad(item.pop("lat_deg"))
    item["longitude"] = np.deg2rad(item.pop("lon_deg"))
    item["minimum_elevation"] = np.deg2rad(item.pop("min_el_deg"))
    return cls(**item)

GatewayOGS dataclass

GatewayOGS(
    *,
    id: T,
    latitude: float,
    longitude: float,
    minimum_elevation: float,
    altitude: float = 0.0,
    n_terminals: int = 1,
    aperture_size: float = 1.0,
    rytov_variance: float = 0.5
)

Bases: Node[T]

altitude class-attribute instance-attribute

altitude: float = field(default=0.0, compare=False)

aperture_size class-attribute instance-attribute

aperture_size: float = field(default=1.0, compare=False)

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

latitude class-attribute instance-attribute

latitude: float = field(compare=False)

longitude class-attribute instance-attribute

longitude: float = field(compare=False)

minimum_elevation class-attribute instance-attribute

minimum_elevation: float = field(compare=False)

n_terminals class-attribute instance-attribute

n_terminals: int = field(default=1, compare=False)

rytov_variance class-attribute instance-attribute

rytov_variance: float = field(default=0.5, compare=False)

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/gateway.py

@classmethod
@override
def class_name(cls) -> str:
    return "GW_OGS"

from_toml_file classmethod

from_toml_file(toml_file_path: Path | str) -> list[Self]

Source code in src/cosmica/models/gateway.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def from_toml_file(cls, toml_file_path: Path | str) -> list[Self]:
    toml_file_path = Path(toml_file_path)
    with toml_file_path.open("rb") as f:
        toml_data = tomllib.load(f)
    return list(map(cls.parse_gateway_item, toml_data["gateways"]))

parse_gateway_item classmethod

parse_gateway_item(item: MutableMapping[str, Any]) -> Self

Source code in src/cosmica/models/gateway.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_gateway_item(cls, item: MutableMapping[str, Any]) -> Self:
    item["latitude"] = np.deg2rad(item.pop("lat_deg"))
    item["longitude"] = np.deg2rad(item.pop("lon_deg"))
    item["minimum_elevation"] = np.deg2rad(item.pop("min_el_deg"))
    item["aperture_size"] = item.pop("aperture_size_m")
    item["rytov_variance"] = item.pop("rytov_variance")

    return cls(**item)

GravityModel

Bases: Enum

WGS72 class-attribute instance-attribute

WGS72 = WGS72

WGS72OLD class-attribute instance-attribute

WGS72OLD = WGS72OLD

WGS84 class-attribute instance-attribute

WGS84 = WGS84

Internet dataclass

Internet(*, id: T | None = None)

Bases: Node[T | None]

The Internet node.

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id class-attribute instance-attribute

id: T | None = None

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/internet.py

@classmethod
@override
def class_name(cls) -> str:
    return "Internet"

Node dataclass

Node(*, id: T)

Bases: ABC

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Class name as a string used for the key generation.

Override this method if you want to use a different class name for the key generation.

Source code in src/cosmica/models/node.py

@classmethod
def class_name(cls) -> str:
    """Class name as a string used for the key generation.

    Override this method if you want to use a different class name for the key generation.
    """
    return cls.__name__

OneTimeCommunicationDemand dataclass

OneTimeCommunicationDemand(
    *,
    id: T,
    source: NodeGID,
    destination: NodeGID,
    data_size: float,
    generation_time: datetime64,
    deadline: datetime64
)

Bases: Demand[T]

One-time communication demand model.

This model is used for the communication demand to transfer a certain amount of data from a source to a destination. The data is generated at the source at a certain time and the communication demand is created at the same time. The time by which the data transfer should be completed is also given.

data_size instance-attribute

data_size: float

deadline instance-attribute

deadline: datetime64

destination instance-attribute

destination: NodeGID

generation_time instance-attribute

generation_time: datetime64

id instance-attribute

id: T

source instance-attribute

source: NodeGID

parse_demand_item classmethod

parse_demand_item(item: Mapping[str, Any]) -> Self

Source code in src/cosmica/models/demand.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_demand_item(cls, item: Mapping[str, Any]) -> Self:
    return cls(
        id=item["id"],
        source=item["src_gid"],
        destination=item["dst_gid"],
        data_size=item["data_size"],
        generation_time=item["generation_time"],
        deadline=item["deadline"],
    )

OpticalCommunicationTerminal dataclass

OpticalCommunicationTerminal(
    *,
    id: T,
    azimuth_min: float,
    azimuth_max: float,
    elevation_min: float,
    elevation_max: float,
    angular_velocity_max: float
)

Bases: CommunicationTerminal[T]

angular_velocity_max instance-attribute

angular_velocity_max: float

azimuth_max instance-attribute

azimuth_max: float

azimuth_min instance-attribute

azimuth_min: float

elevation_max instance-attribute

elevation_max: float

elevation_min instance-attribute

elevation_min: float

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/terminal.py

@classmethod
@override
def class_name(cls) -> str:
    return "OCT"

RFCommunicationTerminal dataclass

RFCommunicationTerminal(*, id: T)

Bases: CommunicationTerminal[T]

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/terminal.py

@classmethod
@override
def class_name(cls) -> str:
    return "RFCT"

Satellite dataclass

Satellite(*, id: T)

Bases: Node[T], ABC

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Class name as a string used for the key generation.

Override this method if you want to use a different class name for the key generation.

Source code in src/cosmica/models/node.py

@classmethod
def class_name(cls) -> str:
    """Class name as a string used for the key generation.

    Override this method if you want to use a different class name for the key generation.
    """
    return cls.__name__

SatelliteTerminal dataclass

SatelliteTerminal(
    *,
    id: T,
    terminal_id: T,
    azimuth_min: float,
    azimuth_max: float,
    elevation_min: float,
    elevation_max: float,
    angular_velocity_max: float
)

Bases: Satellite[T]

angular_velocity_max instance-attribute

angular_velocity_max: float

azimuth_max instance-attribute

azimuth_max: float

azimuth_min instance-attribute

azimuth_min: float

elevation_max instance-attribute

elevation_max: float

elevation_min instance-attribute

elevation_min: float

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

terminal property

terminal: OpticalCommunicationTerminal[T]

terminal_id instance-attribute

terminal_id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Class name as a string used for the key generation.

Override this method if you want to use a different class name for the key generation.

Source code in src/cosmica/models/node.py

@classmethod
def class_name(cls) -> str:
    """Class name as a string used for the key generation.

    Override this method if you want to use a different class name for the key generation.
    """
    return cls.__name__

Scenario dataclass

Scenario(
    *,
    time: NDArray[datetime64],
    gateways: list[Gateway] = list(),
    users: list[User] = list(),
    demands: list[Demand] = list()
)

The simulation scenario.

demands class-attribute instance-attribute

demands: list[Demand] = field(default_factory=list)

gateways class-attribute instance-attribute

gateways: list[Gateway] = field(default_factory=list)

time instance-attribute

time: NDArray[datetime64]

users class-attribute instance-attribute

users: list[User] = field(default_factory=list)

build_topology

build_topology() -> None

Build the topology of the scenario.

Source code in src/cosmica/models/scenario.py

def build_topology(self) -> None:
    """Build the topology of the scenario."""

StationaryOnGroundUser dataclass

StationaryOnGroundUser(
    *,
    id: T,
    terminals: list[
        CommunicationTerminal[Hashable]
    ] = list(),
    latitude: float,
    longitude: float,
    altitude: float = 0.0,
    minimum_elevation: float
)

Bases: User[T]

Model for a stationary user on the ground.

altitude class-attribute instance-attribute

altitude: float = field(default=0.0, compare=False)

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

latitude class-attribute instance-attribute

latitude: float = field(compare=False)

longitude class-attribute instance-attribute

longitude: float = field(compare=False)

minimum_elevation class-attribute instance-attribute

minimum_elevation: float = field(compare=False)

terminals class-attribute instance-attribute

terminals: list[CommunicationTerminal[Hashable]] = field(
    default_factory=list, compare=False
)

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Class name as a string used for the key generation.

Override this method if you want to use a different class name for the key generation.

Source code in src/cosmica/models/node.py

@classmethod
def class_name(cls) -> str:
    """Class name as a string used for the key generation.

    Override this method if you want to use a different class name for the key generation.
    """
    return cls.__name__

parse_user_item classmethod

parse_user_item(item: Mapping[str, Any]) -> Self

Source code in src/cosmica/models/user.py

@classmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_user_item(cls, item: Mapping[str, Any]) -> Self:
    return cls(
        id=item["id"],
        latitude=np.deg2rad(item["lat_deg"]),
        longitude=np.deg2rad(item["lon_deg"]),
        altitude=item["alt_m"],
        minimum_elevation=np.deg2rad(item["min_el_deg"]),
    )

User dataclass

User(
    *,
    id: T,
    terminals: list[
        CommunicationTerminal[Hashable]
    ] = list()
)

Bases: Node[T], ABC

Base model for a user.

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

terminals class-attribute instance-attribute

terminals: list[CommunicationTerminal[Hashable]] = field(
    default_factory=list
)

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Class name as a string used for the key generation.

Override this method if you want to use a different class name for the key generation.

Source code in src/cosmica/models/node.py

@classmethod
def class_name(cls) -> str:
    """Class name as a string used for the key generation.

    Override this method if you want to use a different class name for the key generation.
    """
    return cls.__name__

parse_user_item abstractmethod classmethod

parse_user_item(item: Mapping[str, Any]) -> Self

Parse a user item.

Source code in src/cosmica/models/user.py

@classmethod
@abstractmethod
@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def parse_user_item(cls, item: Mapping[str, Any]) -> Self:
    """Parse a user item."""
    ...

UserOpticalCommunicationTerminal dataclass

UserOpticalCommunicationTerminal(
    *,
    id: T,
    azimuth_min: float,
    azimuth_max: float,
    elevation_min: float,
    elevation_max: float,
    angular_velocity_max: float
)

Bases: OpticalCommunicationTerminal[T]

angular_velocity_max instance-attribute

angular_velocity_max: float

azimuth_max instance-attribute

azimuth_max: float

azimuth_min instance-attribute

azimuth_min: float

elevation_max instance-attribute

elevation_max: float

elevation_min instance-attribute

elevation_min: float

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/terminal.py

@classmethod
@override
def class_name(cls) -> str:
    return "UOCT"

UserSatellite dataclass

UserSatellite(*, id: T)

Bases: Satellite[T]

global_id property

global_id: NodeGID

The universally unique identifier of the node.

id instance-attribute

id: T

__str__

__str__() -> str

Source code in src/cosmica/models/node.py

def __str__(self) -> str:
    return self.global_id

class_name classmethod

class_name() -> str

Source code in src/cosmica/models/satellite.py

@classmethod
@override
def class_name(cls) -> str:
    return "USAT"

load_demands_from_toml_file

load_demands_from_toml_file(
    toml_file_path: str | Path,
) -> list[Demand[Hashable]]

Load demands from a TOML file.

Source code in src/cosmica/models/demand.py

@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def load_demands_from_toml_file(toml_file_path: str | Path) -> list[Demand[Hashable]]:
    """Load demands from a TOML file."""
    toml_file_path = Path(toml_file_path)
    with toml_file_path.open("rb") as f:
        toml_data = tomllib.load(f)
    return list(map(parse_demand_item, toml_data["demands"]))

load_users_from_toml_file

load_users_from_toml_file(
    toml_file_path: str | Path,
) -> list[User[Hashable]]

Load users from a TOML file.

Source code in src/cosmica/models/user.py

@deprecated("Construction of objects from TOML files is deprecated and will be removed in future versions.")
def load_users_from_toml_file(toml_file_path: str | Path) -> list[User[Hashable]]:
    """Load users from a TOML file."""
    toml_file_path = Path(toml_file_path)
    with toml_file_path.open("rb") as f:
        toml_data = tomllib.load(f)
    return list(map(parse_user_item, toml_data["users"]))