"""Orbital state type for position, velocity, and acceleration.

The OrbitState NamedTuple represents the instantaneous state of an orbiting
body at a specific time. It contains position, velocity, and acceleration
vectors in the ECI (Earth-Centered Inertial) J2000 reference frame.

This type is the output of orbit propagation and can be used as input for
determining orbital elements from state vectors.

References:
    - Vallado, D. "Fundamentals of Astrodynamics and Applications", 4th ed.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, NamedTuple

if TYPE_CHECKING:
    import numpy as np
    from numpy.typing import NDArray


class OrbitState(NamedTuple):
    """Orbital state (position, velocity, acceleration) at a specific time.

    All vectors are in the ECI (Earth-Centered Inertial) J2000 reference frame.
    The acceleration is the gravitational acceleration only (two-body problem),
    computed as -mu/r^3 * r.

    Attributes:
        position_eci_m: Position vector in ECI frame, meters. Shape (3,).
            Components are [x, y, z] where x points to vernal equinox,
            z points to celestial north pole.
        velocity_eci_ms: Velocity vector in ECI frame, m/s. Shape (3,).
            Time derivative of position.
        acceleration_eci_ms2: Acceleration vector in ECI frame, m/s^2. Shape (3,).
            For Keplerian (two-body) motion, this is purely gravitational:
            a = -mu/|r|^3 * r, where mu is Earth's gravitational parameter.

    Example:
        >>> import numpy as np
        >>> # Circular orbit at ~400 km altitude
        >>> state = OrbitState(
        ...     position_eci_m=np.array([6778000.0, 0.0, 0.0]),
        ...     velocity_eci_ms=np.array([0.0, 7668.0, 0.0]),
        ...     acceleration_eci_ms2=np.array([-8.67, 0.0, 0.0]),
        ... )
        >>> state.position_eci_m
        array([6778000.,       0.,       0.])
    """

    position_eci_m: NDArray[np.floating]
    velocity_eci_ms: NDArray[np.floating]
    acceleration_eci_ms2: NDArray[np.floating]
