getting_started.md

Getting started {#getting_started}

Tickets 🎫 please: We are about to start! In this guide, we will show you how to set up your first mission using our mission_analysis tool.

Step-by-step

To be able to execute mission_analysis, you have to provide the following data beside your Aircraft Exchange File:

• mission_data (e.g. design_mission.xml)
• aero_data (polar files)
• engine_data (engine maps)

!!! note Those files are generated by Create Mission XML, Aerodynamic Assessment and Propulsion Design and shall not be edited manually!

To do so, you can either use:

• a pre-calculated aircraft configuration (e.g. from the Aircraft References repository),
• an aircraft project in which the Sizing Tools and the Aerodynamic Assessment tool have already been executed at least once.

Once your aircraft is ready, you only need to follow these steps to start your calculation:

1. Head over to mission_analysis_conf (more details here). Assuming this file represents the version of the develop branch, edit the following nodes within control_settings:
   • set aircraft exchange file_name and aircraft exchange file_directory to your respective settings,
   • set the plot_output to false if you don't have inkscape or gnuplot installed or define inkscape_path and gnuplot_path if their directories are not registered in your system environments.
2. Open your terminal within the mission_analysis folder and run the mission_analysis executable.
3. Fasten your seatbelt: We are ready for takeoff! ✈️

If everything is set up correctly, your first design_mission should land a few seconds later ⭐

First iteration results

!!! note If you are using a pre-calculated aircraft, mission_analysis will generate its results using parameters from the previous calculations. Therefore, the behavior for an initial execution can not be observed. Continue with Further Iterations.

Due to many dependencies between the sizing tools, performance data and component parameters are quite off within the first iteration. This can lead to an unstable aircraft configuration that will fail the design_mission (e.g. wrongly sized engines can't climb to the initial cruise altitude). To avoid this, the low-fidelity 3D Standard Mission (design_mission::breguet) is triggered if no previous mission calculation can be found. Unlike the ordinary mission calculation, this sub-version of the design_mission finishes after a rough estimation of the fuel consumption. Once this method is finished, the masses_cg_inertia/maximum_takeoff_mass/mass_properties/mass node is updated and this block is written into the Aircraft Exchange File:

XML output {#first_iterations_xml}

<mission description="Mission data" tool_level="0">
    <design_mission description="Data of design mission">
        <range description="Traveled range from break release to end of taxi at destination">
            <value>4500000</value>
            <unit>m</unit>
            <lower_boundary>0</lower_boundary>
            <upper_boundary>5000000</upper_boundary>
        </range>
        <loaded_mission_energy description="Amount of energy loaded into tanks (including reserves) for the mission">
            <mission_energy ID="0" description="Amount of energy loaded into tanks (including reserves) for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>7.0e+11</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </mission_energy>
        </loaded_mission_energy>
        <in_flight_energy description="Amount of energy needed for in-flight segments (all segments from takeoff to landing)">
            <trip_energy ID="0" description="Amount of energy needed for trip segments (all segments from takeoff to landing) for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>5.5e+11</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </trip_energy>
        </in_flight_energy>
        <taxi_energy description="Amount of energy needed for taxiing specified energy carrier">
            <taxi_out_energy ID="0" description="Amount of energy needed for taxiing at origin for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>1.0+10</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </taxi_out_energy>
            <taxi_in_energy ID="0" description="Amount of energy needed for taxiing at destination for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>5.0e9</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </taxi_in_energy>
        </taxi_energy>
    </design_mission>
</mission>

Further iterations {#further_iterations}

After the initial loop, we expect a robuster behavior which we can use to calculate the flight segments with an increased resolution. To achieve this, every segment is split into little time and way increments (only a few seconds/meters per increment) aiming for the trajectory points that were written into the mission file. In each increment, all relevant parameters are saved into a mission profile. After the calculation is done, said mission profile is exported as a CSV file into the mission_data directory. Within the Aircraft Exchange File the masses_cg_inertia/maximum_takeoff_mass/mass_properties/mass node is updated when calculating a design_mission; for a study_mission it's the mission/study_mission/takeoff_mass node. Having a higher resolution also increases the amount of data in the mission block:

XML output {#further_iterations_xml}

<mission description="Mission data" tool_level="0">
    <design_mission description="Data of design mission">
        <range description="Traveled range from break release to end of taxi at destination">
            <value>4500000</value>
            <unit>m</unit>
            <lower_boundary>0</lower_boundary>
            <upper_boundary>5000000</upper_boundary>
        </range>
        <loaded_mission_energy description="Amount of energy loaded into tanks (including reserves) for the mission">
            <mission_energy ID="0" description="Amount of energy loaded into tanks (including reserves) for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>7.0e+11</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </mission_energy>
        </loaded_mission_energy>
        <in_flight_energy description="Amount of energy needed for in-flight segments (all segments from takeoff to landing)">
            <trip_energy ID="0" description="Amount of energy needed for trip segments (all segments from takeoff to landing) for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>5.5e+11</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </trip_energy>
            <takeoff_energy ID="0" description="Amount of energy needed for takeoff segment for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>8.9e+9</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </takeoff_energy>
            <landing_energy ID="0" description="Amount of energy needed for landing segment for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>8.9e+9</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </landing_energy>
        </in_flight_energy>
        <taxi_energy description="Amount of energy needed for taxiing specified energy carrier">
            <taxi_out_energy ID="0" description="Amount of energy needed for taxiing at origin for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>1.0e+10</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </taxi_out_energy>
            <taxi_in_energy ID="0" description="Amount of energy needed for taxiing at destination for specified energy carrier">
                <consumed_energy description="Energy amount">
                    <value>5.6e+10</value>
                    <unit>J</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>1e+13</upper_boundary>
                </consumed_energy>
                <energy_carrier_ID description="See energy carrier specification node">
                    <value>0</value>
                    <unit>1</unit>
                    <lower_boundary>0</lower_boundary>
                    <upper_boundary>5</upper_boundary>
                </energy_carrier_ID>
            </taxi_in_energy>
        </taxi_energy>
        <block_time description="Block time for the whole mission: Time from break release to end of taxiing after landing">
            <value>21000.0</value>
            <unit>s</unit>
            <lower_boundary>0</lower_boundary>
            <upper_boundary>45000</upper_boundary>
        </block_time>
        <flight_time description="Flight time for the whole mission">
            <value>20000.0</value>
            <unit>s</unit>
            <lower_boundary>0</lower_boundary>
            <upper_boundary>44500</upper_boundary>
        </flight_time>
        <takeoff_engine_derate description="Engine power demand">
            <value>1</value>
            <unit>1</unit>
            <lower_boundary>0</lower_boundary>
            <upper_boundary>1</upper_boundary>
        </takeoff_engine_derate>
        <cruise description="Characteristics of the cruise segment">
            <average_lift_coefficient description="Lift coefficient CL_average: Arithmetic mean over the entire cruise flight">
                <value>0.52</value>
                <unit>1</unit>
                <lower_boundary>-0.01</lower_boundary>
                <upper_boundary>1</upper_boundary>
            </average_lift_coefficient>
            <minimum_lift_coefficient description="Minimum cruise flight lift coefficient CL_min">
                <value>0.49</value>
                <unit>1</unit>
                <lower_boundary>-0.01</lower_boundary>
                <upper_boundary>1</upper_boundary>
            </minimum_lift_coefficient>
            <maximum_lift_coefficient description="Maximum cruise flight lift coefficient CL_max">
                <value>0.56</value>
                <unit>1</unit>
                <lower_boundary>-0.01</lower_boundary>
                <upper_boundary>1</upper_boundary>
            </maximum_lift_coefficient>
            <top_of_climb_mass description="Total aircraft mass at top of climb (= start of initial cruise altitude (ICA))">
                <value>77000.0</value>
                <unit>kg</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>150000</upper_boundary>
            </top_of_climb_mass>
            <top_of_descend_mass description="Total aircraft mass at top of descend (TOD)">
                <value>66000.0</value>
                <unit>kg</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>150000</upper_boundary>
            </top_of_descend_mass>
            <top_of_climb_range description="Flown range from takeoff to top of climb (= start of initial cruise altitude (ICA))">
                <value>220000.0</value>
                <unit>kg</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>500000</upper_boundary>
            </top_of_climb_range>
            <top_of_descend_range description="Flown range from takeoff to top of descend">
                <value>4300000.0</value>
                <unit>kg</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>5000000</upper_boundary>
            </top_of_descend_range>
            <cruise_steps description="Cruise step information">
                <cruise_step ID="0" description="Data of a cruise step">
                    <relative_end_of_cruise_step description="End of cruise step relative to total cruise length">
                        <value>0.5</value>
                        <unit>1</unit>
                        <lower_boundary>0</lower_boundary>
                        <upper_boundary>1</upper_boundary>
                    </relative_end_of_cruise_step>
                    <altitude description="Altitude of cruise step">
                        <value>10058.4</value>
                        <unit>m</unit>
                        <lower_boundary>0</lower_boundary>
                        <upper_boundary>15000</upper_boundary>
                    </altitude>
                </cruise_step>
                <cruise_step ID="1" description="Data of a cruise step">
                    <relative_end_of_cruise_step description="End of cruise step relative to total cruise length">
                        <value>1</value>
                        <unit>1</unit>
                        <lower_boundary>0</lower_boundary>
                        <upper_boundary>1</upper_boundary>
                    </relative_end_of_cruise_step>
                    <altitude description="Altitude of cruise step">
                        <value>10668.0</value>
                        <unit>m</unit>
                        <lower_boundary>0</lower_boundary>
                        <upper_boundary>15000</upper_boundary>
                    </altitude>
                </cruise_step>
            </cruise_steps>
        </cruise>
        <takeoff_performance_parameters description="Performance parameters for takeoff steps from 0 ft to screen height (35 ft).">
            <lift_off_speed description="Speed at lift-off">
                <value>65</value>
                <unit>m/s</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>350</upper_boundary>
            </lift_off_speed>
            <takeoff_stall_speed description="Stall speed until screen height (35 ft)">
                <value>55</value>
                <unit>m/s</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>350</upper_boundary>
            </takeoff_stall_speed>
            <lift_off_coefficient description="Lift coefficient at lift-off">
                <value>2.0</value>
                <unit>1</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>100</upper_boundary>
            </lift_off_coefficient>
            <lift_off_angle_of_attack description="Angle of attack at lift-off">
                <value>0.15</value>
                <unit>rad</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>1.57</upper_boundary>
            </lift_off_angle_of_attack>
            <takeoff_climb_angle description="Climb angle towards screen height (35 ft)">
                <value>0.15</value>
                <unit>rad</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>1.57</upper_boundary>
            </takeoff_climb_angle>
        </takeoff_performance_parameters>
        <landing_performance_parameters description="Performance parameters for landing steps from 50 ft to touchdown.">
            <maximum_landing_angle_of_attack description="Maximum angle of attack while landing (between 50 ft and touchdown)">
                <value>0.15</value>
                <unit>rad</unit>
                <lower_boundary>0</lower_boundary>
                <upper_boundary>1.57</upper_boundary>
            </maximum_landing_angle_of_attack>
        </landing_performance_parameters>
    </design_mission>
</mission>

Additional Output

Beside the output written into the aircraft XML, mission_analysis generates a few more files you and even other tools can work with.

Mission Data CSV {#csv_file}

Remember that nice graph from this tool's introduction? This is a simple visualization of this CSV file we described above. Depending on the amount of engines, used energy carriers and other inputs, the CSV file may differ a bit, but usually you can expect the following parameters there:

• Time [s]
• Range [m]
• Altitude [m]
• FL [100 ft]
• Mode name [-]
• Total mass [kg]
• Energy carrier (ID)
• Thrust [N]
• Fuelflow [kg/s]
• Fuel consumed (kerosene | ID = 0) [kg]
• Energy consumed (kerosene | ID = 0) [J]
• Mach [-]
• CAS [m/s]
• TAS [m/s]
• TAS [kts]
• ROC [fpm]
• SAR [m/kg]
• Aero Config [-]
• C_L [-]
• L over D [-]
• Spoiler Factor [-]
• Reynolds Number [-]
• Engine Rating [-]
• Engine N1 (PW1127G-JM | ID = 0) [-]
• Engine N1 (PW1127G-JM | ID = 1) [-]
• Shaft power offtake [W]
• Bleed [kg/s]
• Angle of attack [deg]
• Glidepath angle [deg]
• Incidence angle (stabilizer) [deg]

The High Fidelity Method will provide in addition:

• Latitude [deg]
• Longitude [deg]

Beside being a neat dataset to show-off, Ecological Assessment can go through it to calculate the ecological impact of an aircraft flying the displayed mission.

Reporting

If you don't want to edit your data on your own, but need to see some basic characteristics of your mission, you can simply go to the reporting directory next to your Aircraft Exchange File. Within report_html, we already provide many graphs and useful insights which might come in handy. If something went wrong or you need to know what mission_analysis has done in detail, there is also a .log file next to your executable in which the shell output is tracked.

Mission Configuration {#configuration}

Now that we have successfully generated our first mission output, let's see how you can tweak our tool a little bit 😎

Aircraft Exchange File {#acxml}

Within the requirements_and_specifications block of the aircraft_exchange_file, the following nodes can affect the behavior of mission_analysis (descriptions to be found within that file):

requirements_and_specifications
└── mission_files
    ├── design_mission_file
    ├── study_mission_file
    ├── requirements_mission_file
└── design_specification
    ├── propulsion
    ├── skinning
    │   ├── thickness
    ├── configuration
    │   ├── tank_definition
    ├── energy_carriers
└── requirements
    ├── top_level_aircraft_requirements
    │   ├── maximum_structrual_payload_mass
    │   ├── design_mission
    │   ├── study_mission
    │   ├── takeoff_distance
    │   ├── landing_field_length
    │   ├── icao_aerodrome_reference_code (once 4D missions are ready)
    │   ├── flight_envelope
    │   │   ├── maximum_operating_mach_number
    │   │   ├── maximum_operating_velocity
    │   │   ├── maximum_approach_speed
    │   │   ├── maximum_operating_altitude
    │   │   ├── maximum_altitude_one_engine_inoperative
    │   │   ├── climb_or_descend_segment_gradient
    ├── additional_requirements
    │   ├── landing_gear

The mission_files node simply saves the names of said files. Within design_specification, we extract everything from the propulsion system (including tanks) in order to analyze fuel consumption and thrust generation. In the top_level_aircraft_requirements node, we can find performance maxima and characteristics for design_mission and study_mission. The later provide nodes for the mission planning (initial cruise altitude and speed, fuel planning etc.). In additional_requirements, the landing_gear node tells us with which friction_coefficient and braking_coefficient our aircraft will be slowed down after touchdown.

Configuration File {#config_file}

The control_settings are standardized in UNICADO and will not be described in detail here. The program settings are structured like this (descriptions are in the mission_analysis_conf.xml):

Program Settings
└── Program Specific
    ├── Specific Air Range Plot
    ├── Exit If Fuel Limit Reached
    │   ├── Enable
    │   ├── Allowed Relative Overshoot
    ├── Exit If Maximum Takeoff Mass Limit Reached
    │   ├── Enable
    │   ├── Allowed Relative Overshoot
└── General
    ├── Fuel Planning
    │   ├── Fuel Estimation
    │   │   ├── Fuel Estimation Switch
    │   │   ├── Joint Aviation Requirements Parameters
    │   │   │   ├── Contingency Fuel
    │   │   │   ├── Use Additional Fuel
    │   │   │   ├── Extra Fuel
    │   │   ├── Federal Aviation Regulations Parameter
    │   │   │   ├── Use Additional Fuel
    │   ├── Fuel Flow Factor Taxiing
    │   ├── Holding
    │   │   ├── Holding Mach Number
    │   │   ├── Holding Altitude
    │   │   ├── Use Economical Speed
    ├── Increase Engine Rating During Climb
    ├── Glideslope Interception Distance
    ├── Use Breguet Estimation In Cruise
    ├── Iterate Top Of descend Mass
    ├── Landing
    │   ├── Rotation Time
    │   ├── Thrust Reverser
    │   │   ├── Enable
    │   │   ├── Deactivation Speed
    │   │   ├── Efficiency
    │   ├── Runway Exit Speed
└── Mode
    ├── Mission Methods
    │   ├── Fidelity Level
    │   ├── Mission Type
    │   ├── Center Of Gravity Method
    ├── Interpolate Polars
    ├── Rate Of Climb Switch
└── Precision
    ├── Acceleration Increment
    ├── Mach Acceleration Increment
    ├── Altitude Increment
    ├── Way Increment
    ├── Specific Air Range Check Increment

In the program_specific node, you can specify if the specific air range (SAR) is plotted (when plotting is turned on in the control_Settings). In addition, you can allow the tool to exceed the maximum takeoff mass and fuel mass during the design loop. This can be useful when operating at extreme conditions where fluctuation above the maxima shall not trigger an exit immediately.

In general you can decide how the needed fuel is estimated and you can tell mission_analysis in which way it shall behave in different flight segments.

The mode node lets you choose the methods that are applied. Using the keyword low/mid/high you will trigger the low-fidelity/mid-fidelity/high-fidelity version of the Standard Mission method. It also has three sub-methods to differentiate between design_mission, study_mission and requirements_mission which can be selected in the mission_type node. Please mind that the low-fidelity method only accepts the design_mission and the high-fidelity method will NOT except the requirements mission. After the first iteration, the Weight and Balance tool delivers vectors containing center of gravity positions in addition to the aircraft mass (center of gravity shift due to defueling). To take that into account, you can activate interpolate_polars. For kerosene based propulsion, the effects are rather small, but once H2 is involved you should consider using it. Furthermore, the rate_of_climb_switch will only affect the Climb to Ceiling step of the requirements_mission. With this option, mission_analysis calculates the optimum rate of climb towards service ceiling.

Finally, in precision you can set the parameters which will define the before mentioned increments of your mission profile.