Source code for RCAIDE.Library.Mission.Common.Unpack_Unknowns.orientation

# RCAIDE/Library/Missions/Common/Unpack_Unknowns/orientation.py
# 
# 
# Created:  Jul 2023, M. Clarke
# ----------------------------------------------------------------------------------------------------------------------
#  Unpack Unknowns
# ----------------------------------------------------------------------------------------------------------------------


def orientation(segment): 
    """
    Updates vehicle orientation states from solver unknowns

    Parameters
    ----------
    segment : Segment
        The mission segment being analyzed
            - assigned_control_variables : Data
                Control configurations
                    - pitch_angle : Control
                        Body angle control settings
                    - bank_angle : Control
                        Bank angle control settings
                    - velocity : Control
                        Velocity control settings
                    - altitude : Control
                        Altitude control settings
            - lift_coefficient : float, optional
                Target lift coefficient for trim
            - angle_of_attack : float
                Fixed angle of attack [rad]
            - bank_angle : float
                Fixed bank angle [rad]
            - state : Data
                Current segment state
                - conditions : Data
                    Flight conditions
                        - frames.body.inertial_rotations : array
                            Body orientation angles [rad]
                        - frames.planet.true_heading : array
                            Vehicle heading [rad]
                        - frames.inertial.velocity_vector : array
                            Vehicle velocity [m/s]
                        - frames.inertial.position_vector : array
                            Vehicle position [m]
                - unknowns : Data
                    Solver variables
                        - pitch_angle : array
                            Body angle values [rad]
                        - bank_angle : array
                            Bank angle values [rad]
                        - velocity : array
                            Velocity values [m/s]
                        - altitude : array
                            Altitude values [m]
                - ones_row : function
                    Creates array of ones with specified columns

    Returns
    -------
    None
        Updates segment conditions directly

    Notes
    -----
    This function applies orientation-related solver values to the segment state,
    handling body angles, trim conditions, and trajectory controls. It manages
    both active control and fixed orientation cases.

    The function processes:
        1. Body angle control
            - Trim conditions
            - Active angle control
            - Fixed angle of attack
        2. Bank angle control
            - Active bank control
            - Fixed bank angle
        3. Heading alignment
        4. Velocity control
        5. Altitude control
    
    **Major Assumptions**
        * Valid angle definitions
        * Proper control assignments
        * Compatible trim conditions
        * Well-defined reference frames
    
    See Also
    --------
    RCAIDE.Framework.Mission.Segments
    """
    ctrls    = segment.assigned_control_variables 

    # Body Angle Control 
    if segment.lift_coefficient !=  None:
        segment.state.conditions.aerodynamics.coefficients.lift.total          = segment.lift_coefficient * segment.state.ones_row(1) 
        segment.state.conditions.aerodynamics.coefficients.lift.inviscid.total = segment.lift_coefficient / segment.analyses.aerodynamics.settings.fuselage_lift_correction   * segment.state.ones_row(1)    
    else: 
        if ctrls.pitch_angle.active: 
            segment.state.conditions.frames.body.inertial_rotations[:,1] = segment.state.unknowns.pitch_angle[:,0]  
        else: 
            segment.state.conditions.frames.body.inertial_rotations[:,1] = segment.angle_of_attack
            
    # Bank Angle 
    if ctrls.bank_angle.active: 
        segment.state.conditions.frames.body.inertial_rotations[:,0] = -segment.state.unknowns.bank_angle[:,0]
    else:
        segment.state.conditions.frames.body.inertial_rotations[:,0] = -segment.bank_angle 
    segment.state.conditions.frames.body.inertial_rotations[:,2] =  segment.state.conditions.frames.planet.true_heading[:,0]
    
    # Sideslip Angle
    if ctrls.sideslip_angle.active:
        # β is a free solver unknown — solver finds the trimmed sideslip
        segment.state.conditions.frames.wind.body_rotations[:,2] = segment.state.unknowns.sideslip_angle[:,0]
    elif segment.crosswind_speed != 0.0:
        # β computed kinematically from crosswind speed (crab/slip approach)
        import numpy as np
        beta = np.arcsin(np.clip(segment.crosswind_speed / segment.air_speed, -1.0, 1.0))
        segment.state.conditions.frames.wind.body_rotations[:,2] = beta
    else:
        # β prescribed directly on the segment (legacy behaviour)
        segment.state.conditions.frames.wind.body_rotations[:,2] = segment.sideslip_angle
    
    # Velocity Control
    if ctrls.velocity.active:
        segment.state.conditions.frames.inertial.velocity_vector[:,0] = segment.state.unknowns.velocity[:,0]
        
    # Altitude Control
    if ctrls.altitude.active:
        segment.state.conditions.frames.inertial.position_vector[:,2] = -segment.state.unknowns.altitude[:,0]
        
    return