pysmo.tools.azdist

def azimuth(
    location_1: Location, location_2: Location, ellps: str = DEFAULT_ELLPS
) -> float:
    """Calculate azimuth between two points.

    Args:
        location_1: Origin location. Any object implementing the [`Location`][pysmo.Location] protocol.
        location_2: Target location. Any object implementing the [`Location`][pysmo.Location] protocol.
        ellps: Ellipsoid to use for azimuth calculation.

    Returns:
        Azimuth in degrees from location 1 to location 2.

    Examples:
        ```python
        >>> from pysmo.classes import SAC
        >>> from pysmo.tools.azdist import azimuth
        >>> sac = SAC.from_file("example.sac")
        >>> # the SAC class provides both event and station
        >>> azimuth(sac.event, sac.station)
        181.91993
        >>> # Use Clarke 1966 instead of default
        >>> azimuth(sac.event, sac.station, ellps='clrk66')
        181.92002
        >>>
        ```
    """
    return _azdist(location_1=location_1, location_2=location_2, ellps=ellps)[0]

def backazimuth(
    location_1: Location, location_2: Location, ellps: str = DEFAULT_ELLPS
) -> float:
    """Calculate backazimuth between two points.

    Args:
        location_1: Origin location. Any object implementing the [`Location`][pysmo.Location] protocol.
        location_2: Target location. Any object implementing the [`Location`][pysmo.Location] protocol.
        ellps: Ellipsoid to use for backazimuth calculation.

    Returns:
        Backazimuth in degrees from point 2 to point 1.

    Examples:
        ```python
        >>> from pysmo.classes import SAC
        >>> from pysmo.tools.azdist import backazimuth
        >>> sac = SAC.from_file("example.sac")
        >>> # the SAC class provides both event and station
        >>> backazimuth(sac.event, sac.station)
        2.467753
        >>> # Use Clarke 1966 instead of default
        >>> backazimuth(sac.event, sac.station, ellps='clrk66')
        2.467847
        >>>
        ```
    """
    return _azdist(location_1=location_1, location_2=location_2, ellps=ellps)[1]

def distance(
    location_1: Location, location_2: Location, ellps: str = DEFAULT_ELLPS
) -> float:
    """Calculate the great circle distance (in metres) between two locations.

    Args:
        location_1: Origin location. Any object implementing the [`Location`][pysmo.Location] protocol.
        location_2: Target location. Any object implementing the [`Location`][pysmo.Location] protocol.
        ellps: Ellipsoid to use for distance calculation.

    Returns:
        Great Circle Distance in metres.

    Examples:
        ```python
        >>> from pysmo.classes import SAC
        >>> from pysmo.tools.azdist import distance
        >>> sac = SAC.from_file("example.sac")
        >>> # the SAC class provides both event and station
        >>> distance(sac.event, sac.station)
        1889154.994
        >>> # Use Clarke 1966 instead of default
        >>> distance(sac.event, sac.station, ellps='clrk66')
        1889121.778
        >>>
        ```
    """
    return _azdist(location_1=location_1, location_2=location_2, ellps=ellps)[2]

def haversine(location_1: Location, location_2: Location) -> float:
    """Calculate the great circle distance in degrees between two locations.

    Uses the haversine formula on a spherical Earth, which is the conventional
    model for seismological epicentral distance.

    Args:
        location_1: Origin location. Any object implementing the [`Location`][pysmo.Location] protocol.
        location_2: Target location. Any object implementing the [`Location`][pysmo.Location] protocol.

    Returns:
        Epicentral distance in degrees.

    Examples:
        ```python
        >>> from pysmo.classes import SAC
        >>> from pysmo.tools.azdist import haversine
        >>> sac = SAC.from_file("example.sac")
        >>> # the SAC class provides both event and station
        >>> haversine(sac.event, sac.station)
        17.013880
        >>> # compare with the SAC gcarc header (spherical law of cosines)
        >>> float(sac.gcarc)
        17.013880
        >>>
        ```
    """
    lat1 = math.radians(location_1.latitude)
    lat2 = math.radians(location_2.latitude)
    dlat = lat2 - lat1
    dlon = math.radians(location_2.longitude - location_1.longitude)
    a = (
        math.sin(dlat / 2) ** 2
        + math.cos(lat1) * math.cos(lat2) * math.sin(dlon / 2) ** 2
    )
    # Clamp to guard against floating-point rounding pushing a fraction
    # above 1.0 for near-identical or near-antipodal coordinates.
    a = min(1.0, max(0.0, a))
    return math.degrees(2 * math.asin(math.sqrt(a)))