across-tools 0.1.dev42__py3-none-any.whl

across/__init__.py

@@ -0,0 +1,21 @@
+"""
+NASA Docket No. GSC-19,469-1, and identified as "Astrophysics Cross-Observatory
+Science Support (ACROSS) System
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.“
+
+The copyright notice to be included in the software is as follows:
+
+Copyright © 2025 United States Government as represented by the Administrator
+of the National Aeronautics and Space Administration and The Penn State
+Research Foundation.  All rights reserved. This software is licensed under the
+Apache 2.0 License.
+"""

across/tools/__init__.py

@@ -0,0 +1,19 @@
+from .core import enums
+from .core.schemas import (
+    Coordinate,
+    EnergyBandpass,
+    FrequencyBandpass,
+    Polygon,
+    WavelengthBandpass,
+    convert_to_wave,
+)
+
+__all__ = [
+    "Coordinate",
+    "EnergyBandpass",
+    "FrequencyBandpass",
+    "Polygon",
+    "WavelengthBandpass",
+    "convert_to_wave",
+    "enums",
+]

across/tools/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.dev42'
+__version_tuple__ = version_tuple = (0, 1, 'dev42')
+
+__commit_id__ = commit_id = None

across/tools/core/config.py

@@ -0,0 +1,29 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class BaseConfig(BaseSettings):
+    """Base configuration for the application."""
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+
+class Config(BaseConfig):
+    """Configuration for the application.
+    The Config class extends BaseConfig and provides configuration settings for the application,
+    including environment, hosting, logging, and request-related parameters.
+
+    Attributes
+    ----------
+    SPACETRACK_USER : str
+        Space-Track.org username
+    SPACETRACK_PWD  : str
+        Space-Track.org password
+    """
+
+    SPACETRACK_USER: str | None = None
+    SPACETRACK_PWD: str | None = None
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+
+config = Config()

across/tools/core/enums/__init__.py

@@ -0,0 +1,7 @@
+from .constraint_type import ConstraintType
+from .depth_unit import DepthUnit
+from .energy_unit import EnergyUnit
+from .frequency_unit import FrequencyUnit
+from .wavelength_unit import WavelengthUnit
+
+__all__ = ["DepthUnit", "EnergyUnit", "FrequencyUnit", "WavelengthUnit", "ConstraintType"]

across/tools/core/enums/constraint_type.py

@@ -0,0 +1,16 @@
+from enum import Enum
+
+
+class ConstraintType(str, Enum):
+    """
+    Represents a constraint.
+    """
+
+    SUN = "Sun Angle"
+    MOON = "Moon Angle"
+    EARTH = "Earth Limb"
+    WINDOW = "Window"
+    UNKNOWN = "Unknown"
+    SAA = "South Atlantic Anomaly"
+    ALT_AZ = "Altitude/Azimuth Avoidance"
+    TEST = "Test Constraint"

across/tools/core/enums/depth_unit.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class DepthUnit(str, Enum):
+    """
+    Enum to represent the astronomical depth types
+    """
+
+    AB_MAG = "ab_mag"
+    VEGA_MAG = "vega_mag"
+    FLUX_ERG = "flux_erg"
+    FLUX_JY = "flux_jy"

across/tools/core/enums/energy_unit.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class EnergyUnit(str, Enum):
+    """
+    Enum to represent the bandpass energy types
+    """
+
+    eV = "eV"  # noqa: N815
+    keV = "keV"  # noqa: N815
+    MeV = "MeV"
+    GeV = "GeV"
+    TeV = "TeV"

across/tools/core/enums/frequency_unit.py

@@ -0,0 +1,13 @@
+from enum import Enum
+
+
+class FrequencyUnit(str, Enum):
+    """
+    Enum to represent the bandpass frequency types
+    """
+
+    Hz = "Hz"
+    kHz = "kHz"  # noqa: N815
+    MHz = "MHz"
+    GHz = "GHz"
+    THz = "THz"

across/tools/core/enums/wavelength_unit.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class WavelengthUnit(str, Enum):
+    """
+    Enum to represent the bandpass wavelength
+    """
+
+    NANOMETER = "nm"
+    ANGSTROM = "angstrom"
+    MICRON = "um"
+    MILLIMETER = "mm"

across/tools/core/math.py

@@ -0,0 +1,36 @@
+from collections import Counter
+
+import numpy as np
+import numpy.typing as npt
+
+
+def find_duplicates(input_list: list[int]) -> list[int]:
+    """
+    Finds duplicates in a list.
+    Taken from https://stackoverflow.com/questions/9835762/
+    """
+    return [item for item, count in Counter(input_list).items() if count > 1]
+
+
+def x_rot(theta_deg: float) -> npt.NDArray[np.float64]:
+    """
+    Performs matrix rotation around the cartesian x direction
+    """
+    theta = np.deg2rad(theta_deg)
+    return np.asarray([[1, 0, 0], [0, np.cos(theta), -np.sin(theta)], [0, np.sin(theta), np.cos(theta)]])
+
+
+def y_rot(theta_deg: float) -> npt.NDArray[np.float64]:
+    """
+    Performs matrix rotation around the cartesian y direction
+    """
+    theta = np.deg2rad(theta_deg)
+    return np.asarray([[np.cos(theta), 0, np.sin(theta)], [0, 1, 0], [-np.sin(theta), 0, np.cos(theta)]])
+
+
+def z_rot(theta_deg: float) -> npt.NDArray[np.float64]:
+    """
+    Performs matrix rotation around the cartesian z direction
+    """
+    theta = np.deg2rad(theta_deg)
+    return np.asarray([[np.cos(theta), -np.sin(theta), 0], [np.sin(theta), np.cos(theta), 0], [0, 0, 1]])

across/tools/core/schemas/__init__.py

@@ -0,0 +1,26 @@
+from .bandpass import EnergyBandpass, FrequencyBandpass, WavelengthBandpass, convert_to_wave
+from .base import BaseSchema
+from .coordinate import Coordinate
+from .custom_types import AstropyDateTime, AstropyTimeDelta
+from .healpix_order import HealpixOrder
+from .polygon import Polygon
+from .roll_angle import RollAngle
+from .visibility import ConstrainedDate, ConstraintReason, VisibilityWindow, Window
+
+__all__ = [
+    "Coordinate",
+    "Polygon",
+    "BaseSchema",
+    "RollAngle",
+    "HealpixOrder",
+    "EnergyBandpass",
+    "WavelengthBandpass",
+    "FrequencyBandpass",
+    "convert_to_wave",
+    "VisibilityWindow",
+    "ConstrainedDate",
+    "Window",
+    "ConstraintReason",
+    "AstropyDateTime",
+    "AstropyTimeDelta",
+]

across/tools/core/schemas/bandpass.py

@@ -0,0 +1,199 @@
+from typing import Any, Literal
+
+from astropy import units as u  # type: ignore[import-untyped]
+
+from ..enums import EnergyUnit, FrequencyUnit, WavelengthUnit
+from .base import BaseSchema
+from .exceptions import BandwidthValueError, MinMaxValueError
+
+
+class BaseBandpass(BaseSchema):
+    """
+    A base class for defining bandpass filters with a specified range.
+
+    Attributes:
+        filter_name (str): The name of the filter, if provided.
+        min (float | None): The minimum value of the bandpass range.
+        max (float | None): The maximum value of the bandpass range.
+    """
+
+    filter_name: str | None = None
+    min: float | None = None
+    max: float | None = None
+
+
+class WavelengthBandpass(BaseBandpass):
+    """
+    A class representing a bandpass filter defined in terms of wavelength.
+
+    Inherits from `BaseBandpass`, this class specializes the filter to operate in the
+    wavelength domain and provides additional functionality for wavelength-based filters.
+
+    Attributes:
+        type (Literal['WAVELENGTH']): A constant string indicating the type of the bandpass filter.
+        central_wavelength (float | None): The central wavelength of the filter.
+        bandwidth (float | None): The bandwidth of the filter.
+        unit (WavelengthUnit): The unit of measurement for the wavelength.
+
+    Methods:
+        model_post_init(__context: Any) -> None:
+            Performs validation and calculation of central wavelength and bandwidth based on the min/max range
+    """
+
+    type: Literal["WAVELENGTH"] = "WAVELENGTH"
+    central_wavelength: float | None = None
+    peak_wavelength: float | None = None
+    bandwidth: float | None = None
+    unit: WavelengthUnit
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        Validates the min and max values of the wavelength bandpass and calculates the central wavelength
+        and bandwidth if they are not provided. Also ensures the values are positive and that the max
+        wavelength is greater than the min wavelength. Lastly, it converts the units to angstroms.
+
+        Raises:
+            ValueError: If the min/max values are invalid or if the calculated values for central wavelength
+                        or bandwidth are non-positive.
+        """
+        if (self.min and not self.max) or (self.max and not self.min):
+            raise MinMaxValueError("Both min and max must be defined.")
+
+        if self.min and self.max:
+            if self.max < self.min:
+                raise MinMaxValueError("Max wavelength cannot be less than min wavelength.")
+
+            if not all([self.min > 0, self.max > 0]):
+                raise MinMaxValueError("Wavelength values must be positive.")
+
+            self.bandwidth = 0.5 * (self.max - self.min)
+            self.central_wavelength = self.min + self.bandwidth
+
+        if not (self.central_wavelength and self.bandwidth):
+            raise BandwidthValueError("Both central wavelength and bandwidth must be defined.")
+
+        if not all([self.central_wavelength > 0, self.bandwidth > 0]):
+            raise BandwidthValueError("Central wavelength and bandwidth must be positive.")
+
+        self.bandwidth = float(
+            (self.bandwidth * u.Unit(self.unit.value)).to(u.Unit(WavelengthUnit.ANGSTROM.value)).value
+        )
+
+        self.central_wavelength = float(
+            (self.central_wavelength * u.Unit(self.unit.value))
+            .to(u.Unit(WavelengthUnit.ANGSTROM.value))
+            .value
+        )
+
+        self.min = self.central_wavelength - self.bandwidth
+
+        self.max = self.central_wavelength + self.bandwidth
+
+        self.unit = WavelengthUnit.ANGSTROM
+
+
+class EnergyBandpass(BaseBandpass):
+    """
+    A class representing a bandpass filter defined in terms of energy.
+
+    Inherits from `BaseBandpass`, this class specializes the filter to operate in the energy domain.
+
+    Attributes:
+        type (Literal['ENERGY']): A constant string indicating the type of the bandpass filter.
+        unit (EnergyUnit): The unit of measurement for the energy.
+
+    Methods:
+        model_post_init(__context: Any) -> None:
+            Ensures the min and max energy values are positive and valid.
+    """
+
+    type: Literal["ENERGY"] = "ENERGY"
+    unit: EnergyUnit
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        Validates that the min and max energy values are positive.
+
+        Raises:
+            ValueError: If the min or max energy values are not defined, are non-positive, and max is greater
+            than min.
+        """
+        if not (self.min and self.max):
+            raise MinMaxValueError("Both min and max energy values must be defined.")
+
+        if not all([self.min > 0, self.max > 0]):
+            raise MinMaxValueError("Energy values must be positive.")
+
+        if self.max < self.min:
+            raise MinMaxValueError("Max wavelength cannot be less than min wavelength.")
+
+
+class FrequencyBandpass(BaseBandpass):
+    """
+    A class representing a bandpass filter defined in terms of frequency.
+
+    Inherits from `BaseBandpass`, this class specializes the filter to operate in the frequency domain.
+
+    Attributes:
+        type (Literal['FREQUENCY']): A constant string indicating the type of the bandpass filter.
+        unit (FrequencyUnit): The unit of measurement for the frequency.
+
+    Methods:
+        model_post_init(__context: Any) -> None:
+            Ensures the min and max frequency values are positive and valid.
+    """
+
+    type: Literal["FREQUENCY"] = "FREQUENCY"
+    unit: FrequencyUnit
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        Validates that the min and max frequency values are positive.
+
+        Raises:
+            ValueError: If the min or max energy values are not defined, are non-positive, and max is greater
+            than min.
+        """
+        if not (self.min and self.max):
+            raise MinMaxValueError("Both min and max frequency values must be defined.")
+
+        if not all([self.min > 0, self.max > 0]):
+            raise MinMaxValueError("Frequency values must be positive.")
+
+        if self.max < self.min:
+            raise MinMaxValueError("Max wavelength cannot be less than min wavelength.")
+
+
+def convert_to_wave(bandpass: EnergyBandpass | FrequencyBandpass) -> WavelengthBandpass:
+    """
+    Converts a given EnergyBandpass or FrequencyBandpass to a WavelengthBandPass.
+
+    Args:
+        bandpass (EnergyBandpass | FrequencyBandpass): The bandpass filter in energy or frequency domain.
+
+    Returns:
+        WavelengthBandPass: The corresponding bandpass filter in the wavelength domain.
+
+    Important Note:
+        When converting from Energy/Frequency to wavelength, the min/max values are inverted
+        in relation to their corresponding wavelengths. Thus, the min/max values are switched during
+        conversion.
+    """
+    bandpass_min_angstrom = (
+        (bandpass.max * u.Unit(bandpass.unit.value))
+        .to(u.Unit(WavelengthUnit.ANGSTROM.value), equivalencies=u.spectral())
+        .value
+    )
+
+    bandpass_max_angstrom = (
+        (bandpass.min * u.Unit(bandpass.unit.value))
+        .to(u.Unit(WavelengthUnit.ANGSTROM.value), equivalencies=u.spectral())
+        .value
+    )
+
+    return WavelengthBandpass(
+        min=bandpass_min_angstrom,
+        max=bandpass_max_angstrom,
+        unit=WavelengthUnit.ANGSTROM,
+        filter_name=bandpass.filter_name,
+    )

across/tools/core/schemas/base.py

@@ -0,0 +1,16 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class BaseSchema(BaseModel):
+    """
+    Base class for schemas.
+
+    This class provides a base implementation for schemas and defines the `from_attributes` method.
+    Subclasses can inherit from this class and override the `from_attributes` method to define their
+        own schema logic.
+    """
+
+    model_config = ConfigDict(from_attributes=True, arbitrary_types_allowed=True)
+
+    def __hash__(self) -> int:
+        return hash((type(self),) + tuple(self.__dict__.values()))

across/tools/core/schemas/coordinate.py

@@ -0,0 +1,42 @@
+from typing import Any
+
+import numpy as np
+from pydantic import Field
+
+from .base import BaseSchema
+
+
+class Coordinate(BaseSchema):
+    """
+    Class that represents a point in spherical space
+    """
+
+    ra: float = Field(ge=-360, le=360)
+    dec: float = Field(ge=-90, le=90)
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        Pydantic post-init hook
+
+        Post-Init validations.
+            Ensure the RA is positive, and rounded to an appropriate precision
+        """
+        self.ra = round(360 + self.ra, 5) if self.ra < 0 else round(self.ra, 5)
+        self.dec = round(self.dec, 5)
+
+    def __repr__(self) -> str:
+        """
+        Overrides the print statement
+        """
+        return f"{self.__class__.__name__}(ra={self.ra}, dec={self.dec})"
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Overrides the coordinate equals
+        """
+        if not isinstance(other, Coordinate):
+            return NotImplemented
+
+        ra_eq = np.isclose(self.ra, other.ra, atol=1e-5)
+        dec_eq = np.isclose(self.dec, other.dec, atol=1e-5)
+        return bool(ra_eq and dec_eq)

across/tools/core/schemas/custom_types.py

@@ -0,0 +1,17 @@
+from typing import Annotated
+
+from astropy.time import Time, TimeDelta  # type: ignore[import-untyped]
+from pydantic import PlainSerializer, PlainValidator
+
+# Custom pydantic type to handle serialization of Astropy Time
+AstropyDateTime = Annotated[
+    Time,
+    PlainValidator(lambda x: Time(x)),
+    PlainSerializer(lambda x: x.utc.datetime if x.isscalar else x.utc.to_datetime().tolist()),
+]
+
+AstropyTimeDelta = Annotated[
+    TimeDelta,
+    PlainValidator(lambda x: TimeDelta(x)),
+    PlainSerializer(lambda x: x.to_datetime()),
+]

across/tools/core/schemas/exceptions.py

@@ -0,0 +1,16 @@
+class MinMaxValueError(ValueError):
+    """
+    Exception raise for invalid bandpass min/max values
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class BandwidthValueError(ValueError):
+    """
+    Exception raise for invalid bandpass central_wavelength/bandwidth values
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)

across/tools/core/schemas/healpix_order.py

@@ -0,0 +1,12 @@
+from pydantic import Field
+
+from .base import BaseSchema
+
+
+class HealpixOrder(BaseSchema):
+    """
+    Class to represent and validate a Healpix Order
+        constraint: Must be (0 >= a >= 13)
+    """
+
+    value: int = Field(gt=0, lt=13, default=10)

across/tools/core/schemas/polygon.py

@@ -0,0 +1,65 @@
+from typing import Any
+
+from .base import BaseSchema
+from .coordinate import Coordinate
+
+
+class Polygon(BaseSchema):
+    """
+    Class to represent a spherical polygon
+    """
+
+    coordinates: list[Coordinate]
+
+    def model_post_init(self, __context: Any) -> None:
+        """
+        Pydantic post-init hook
+
+        Post-Init validations.
+            1.) a polygon must contain a list of coordinates
+            1.) a polygon's first and final coordinates must be the same (wrapping)
+            2.) a polygon has more than 3 unique coordinates
+        """
+
+        if not len(self.coordinates):
+            raise ValueError("Invalid polygon, coordinates cannot be empty.")
+
+        first_coordinate = self.coordinates[0]
+        last_coordinate = self.coordinates[len(self.coordinates) - 1]
+
+        if first_coordinate != last_coordinate:
+            self.coordinates.append(first_coordinate)
+
+        if len(self.coordinates) < 4:
+            raise ValueError("Invalid polygon, must contain more than 3 unique coordinates to be a polygon")
+
+    def __repr__(self) -> str:
+        """
+        Overrides the print statement
+        """
+        statement = f"{self.__class__.__name__}(\n"
+
+        for coordinate in self.coordinates:
+            statement += f"\t{coordinate.__class__.__name__}({coordinate.ra}, {coordinate.dec}),\n"
+
+        statement += ")"
+
+        return statement
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Overrides the coordinate equals
+        """
+        if not isinstance(other, Polygon):
+            return NotImplemented
+
+        if len(self.coordinates) != len(other.coordinates):
+            return False
+
+        else:
+            equivalence: list[bool] = []
+            for coordinate_iterable in range(len(self.coordinates)):
+                equivalence.append(
+                    self.coordinates[coordinate_iterable] == other.coordinates[coordinate_iterable]
+                )
+            return all(equivalence)

across/tools/core/schemas/roll_angle.py

@@ -0,0 +1,12 @@
+from pydantic import Field
+
+from .base import BaseSchema
+
+
+class RollAngle(BaseSchema):
+    """
+    Class to represent and validate a roll angle
+        constraint: Must be (-360.0 >= a >= 360.0)
+    """
+
+    value: float = Field(ge=-360, le=360)