Skip to content
Snippets Groups Projects
Commit 59a7bf06 authored by Moritz Barnert's avatar Moritz Barnert Committed by Florian Schültke
Browse files

First draft of the performance assessment description.

parent 402c1165
Branches
No related tags found
2 merge requests!73Initial open source version,!59First draft of the performance assessment description.
Showing
with 502 additions and 1 deletion
...@@ -89,7 +89,7 @@ The module `calculatePerformance` is used to evaluate the mission performance of ...@@ -89,7 +89,7 @@ The module `calculatePerformance` is used to evaluate the mission performance of
|Module Version|Language|License|Documentation| |Module Version|Language|License|Documentation|
|:---:|:---:|:---:|---| |:---:|:---:|:---:|---|
|2.1.0|:simple-cplusplus:| GPLv3 |-| |2.1.0|:simple-cplusplus:| GPLv3 |[Link](analysis/performance_assessment/index.md)|
--- ---
......
# Software architecture
This site is currently under development. :construction:
<!--
## Module structure
'main.py' runs the following functions:
1. 'data_preprocessing' (from 'datapreprocessing.py')<sup>1</sup>
- 1.1
2. 'run_module' (from 'methodexecutionpackage' library)<sup>2</sup>
- 2.1
3. 'data_postprocessing' (from 'datapostprocessing.py')<sup>3</sup>
<sup>1</sup> data preprocessing runs: \
<sup>2</sup> \
<sup>3</sup> data_postprocessing runs: ...
...
### Routing layers
The tank design module has the following layer structure:
1. Aircraft configuration
- Implemented: 'tube_and_wing'
- Not yet implemented: 'blended_wing_body'
2. Calculation method fidelity
- Implemented: 'empirical'
3. Calculation method
- Implemented: 'tank_design_tu_berlin'
4. Energy carrier <sup>1</sup>
- Implemented: 'kerosene'
- Not yet implemented: 'liquid_hydrogen', 'hybrid'
<sup>1</sup> The used energy carrier is determined automatically in the 'read_energy_carrier_and_tank_configuration' function. -->
# Software architecture
This site is currently under development. :construction:
<!--
## Module structure
'main.py' runs the following functions:
1. 'data_preprocessing' (from 'datapreprocessing.py')<sup>1</sup>
- 1.1
2. 'run_module' (from 'methodexecutionpackage' library)<sup>2</sup>
- 2.1
3. 'data_postprocessing' (from 'datapostprocessing.py')<sup>3</sup>
<sup>1</sup> data preprocessing runs: \
<sup>2</sup> \
<sup>3</sup> data_postprocessing runs: ...
...
### Routing layers
The tank design module has the following layer structure:
1. Aircraft configuration
- Implemented: 'tube_and_wing'
- Not yet implemented: 'blended_wing_body'
2. Calculation method fidelity
- Implemented: 'empirical'
3. Calculation method
- Implemented: 'tank_design_tu_berlin'
4. Energy carrier <sup>1</sup>
- Implemented: 'kerosene'
- Not yet implemented: 'liquid_hydrogen', 'hybrid'
<sup>1</sup> The used energy carrier is determined automatically in the 'read_energy_carrier_and_tank_configuration' function. -->
# Getting started
This section will guide you through the necessary steps to get the performance assessment module up and running. It contains all information on tool requirements and design parameters. First, it is essential to ensure that all necessary input data are available. The performance assessment module requires the following files to be provided:
- [Module configuration file](#module-configuration-file)
- [Aircraft exchange file](#aircraft-exchange-file)
- [Additional requirements](#additional-requirements)
!!! note
It is assumed that you have the `UNICADO package` installed including the executables and UNICADO libraries.
## Module configuration file {#module-configuration-file}
The module configuration file (_configXML_) is the file through which the user controls the performance assessment tool. the configXML is split into two main parts. The control and the program settings. The control settings are standardized in UNICADO and will not be described in detail here. But to get started, you have to change at least
- the `aircraft_exchange_file_name` and `aircraft_exchange_file_directory` to your respective settings,
- the `console_output` at least to `mode_1`, and
- the `plot_output` to false (or define `inkscape_path` and `gnuplot_path`).
!!! note
If the tool is executed via the workflow, those settings are set by the workflow settings.
The program settings in the `performance_assessment_conf.xml` can further be divided into:
- the `module_strategy`
- the `performance_checks`
- the `constants_for_performance_checks`
- the `modes`
Under module_strategy you can chose the strategy that you would like to use. Currently only the `default_methods` as a strategy is available. Under the tab `performance_checks` the fidelity level of the checks for the climb, takeoff and landing performance as well as for the payload range diagram can be selected. Currently the selection is reduced to only `low`. The tab `constants_for_performance_checks` provides the ability to set a `runway_slop` as well as a `head_wind` speed. Finally, under `modes` the user can chose if the study mission instead of the design mission shell be used for the performance assessment and wether the MTOM of the aircraft shall be redetermined.
## Aircraft exchange file {#aircraft-exchange-file}
Since the performance assessment module is an assessment tool, it is assumed that a converged aircraft design and therefore all the necessary data are already available. Due to the abundance of data read in by the module not all parameters will be covered in this section. Only the essential parameters for the overall functionality of the workflow will be covered here. For a more profound description of the relevant parameters please refer to the different capabilities. One of the main task of the performance assessment module is to validate, that the aircraft configuration designed achieves the requirements set be the user through the definition in the acXML. The performance characteristics checked are divided into top level aircraft requirements and certification.
The following top level aircraft requirements are checked:
- the `design takeoff distance`
- the `design landing field length`
- the `design approach speed`
- the `span limit`
As well as the following certification requirements:
- the `climb gradient of the second takeoff segment`
- the `climb gradient of the final takeoff segment`
- the `climb gradient approach one engine inoperative`
- the `climb gradient all engine operative`
The checked parameters are saved in the acXML under `requirement_compliance`:
```xml
<requirement_compliance description="Compliance of given requirements">
<top_level_aircraft_requirements description="Compliance of top level aircraft requirements">
<initial_cruise_altitude description="Compliance check of the initial cruise altitude.">
<maintainable description="Value shows if the requirement can be achieved by the aircraft.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</initial_cruise_altitude>
<initial_cruise_mach_number description="Compliance check of the initial cruise mach number.">
<maintainable description="Value shows if the requirement can be achieved by the aircraft.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</initial_cruise_mach_number>
<maximum_operating_altitude description="Compliance check of the maximum operating altitude.">
<maintainable description="Value shows if the requirement can be achieved by the aircraft.">
<value>false</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</maximum_operating_altitude>
<maximum_altitude_one_engine_inoperative description="Compliance check of the maximum altitude one engine inoperative.">
<maintainable description="Value shows if the requirement can be achieved by the aircraft.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</maximum_altitude_one_engine_inoperative>
<design_time_to_climb description="Compliance check of the design time to climb.">
<maintainable description="Value shows if the requirement can be achieved by the aircraft.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</design_time_to_climb>
<design_takeoff_distance description="Compliance check of the design takeoff distance.">
<maintainable description="Switch indicating if design takeoff distance can be maintained.">
<value>false</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</design_takeoff_distance>
<design_landing_field_length description="Compliance check of the design landing field length.">
<maintainable description="Switch indicating if landing field length can be maintained.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</design_landing_field_length>
<design_approach_speed description="Compliance check of the design approach speed.">
<maintainable description="Switch indicating if approach speed can be maintained.">
<value>false</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</design_approach_speed>
<span_limit>
<maintainable description="Switch indicating if the span limit according to ICAO aerodrome ref code is maintained.">
<value>true</value>
</maintainable>
</span_limit>
</top_level_aircraft_requirements>
<certification>
<climb_gradient_of_second_takeoff_segment>
<maintainable description="Switch indicating if climb gradient of second takeoff segment can be maintained.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</climb_gradient_of_second_takeoff_segment>
<climb_gradient_of_final_takeoff_segment>
<maintainable description="Switch indicating if climb gradient of final takeoff segment can be maintained.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</climb_gradient_of_final_takeoff_segment>
<climb_gradient_approach_one_engine_inoperative>
<maintainable description="Switch indicating if climb gradient approach one engine inoperative can be maintained.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</climb_gradient_approach_one_engine_inoperative>
<climb_gradient_all_engines_operative>
<maintainable description="Switch indicating if climb gradient with all engines operative can be maintained.">
<value>true</value>
</maintainable>
<checked description="Indicates if the value has been checked against the requirement.">
<value>true</value>
</checked>
</climb_gradient_all_engines_operative>
</certification>
```
The checks of the performance characteristics will be conducted based on calculation capabilities implemented in this module. A description of those capabilities can be found under the tab `capabilities`.
## Additional requirements {#additional-requirements}
The tool requires aerodynamic data, mission-dependent data as well as engine-dependent data of the designed aircraft configuration. To run the code smoothly please ensure, that the `aero_data`,`mission_data` ,and `engine_data` folder, are located in the directory of the aircraft exchange file.
# Introduction {#mainpage}
Welcome to the **performance_assessment** module in UNICADO. The module will give you a set of tools to analyze the performance of your aircraft in order to compare it with other aircraft designs. Furthermore, it will calculate performance characteristics within the design loop to check and validate performance requirements set by other tools within UNICADO.
## Summary of features
Here’s a quick rundown of what the tool currently does, along with a sneak peek at what's planned:
| Configuration | Energy carrier | Status |
|------------------|-----------------|:------------------------------------:|
|Tube-and-wing |Kerosene |running :white_check_mark: |
| |Liquid hydrogen |under development :construction:|
|Blended-wing-body |Kerosene |under development :construction:|
| |Liquid hydrogen |under development :construction:|
Performance Assessment has the capabilities of evaluating the following performances:
- Payload Range Diagram
- Takeoff Performance
- Landing Performance
- Flight Envelope
- Ceiling Performance
Coming soon! The following performance assessments are in the making and will be available soon:
- Fuel Planning
- Engine Performance
- Specific Air Range (SAR) Performance
- Balanced Field Length
- V-n-Diagram
## A user's guide to performance assessment
The performance_assessment tool is your key to accurately calculating and visualizing the performance of an aircraft. In this user documentation, you’ll find all the information you need to understand the tool, as well as the necessary inputs and configurations to run a performance assessment from the ground up.
[Getting started](getting_started.md) will give you an introduction to and walk you through the performance assessment process in UNICADO.
For a comprehensive description of the individual performance assessment capabilities please refer to the one of interest:
- [Payload Range Diagram](payload_range_diagram.md)
- [Takeoff Performance](takeoff_performance.md)
- [Landing Performance](landing_performance.md)
- [Flight Envelope](flight_envelope.md)
- [Ceiling Performance](ceiling_performance.md)
<!-- ## You are a Developer?
If you are familiar with these concepts and want to contribute - head over to the developers guide to get your own method running in UNICADO!
The following pages will help you understand the code structure:
- [Prerequisites](prerequisites.md)
- [Build the code](build-the-code.md)
- [Cost estimation module structure](wing-module-structure.md)
- [Available methods](available-methods.md)
- [Method template](method-template.md)
We appreciate it! -->
\ No newline at end of file
# Software architecture
This site is currently under development. :construction:
<!--
## Module structure
'main.py' runs the following functions:
1. 'data_preprocessing' (from 'datapreprocessing.py')<sup>1</sup>
- 1.1
2. 'run_module' (from 'methodexecutionpackage' library)<sup>2</sup>
- 2.1
3. 'data_postprocessing' (from 'datapostprocessing.py')<sup>3</sup>
<sup>1</sup> data preprocessing runs: \
<sup>2</sup> \
<sup>3</sup> data_postprocessing runs: ...
...
### Routing layers
The tank design module has the following layer structure:
1. Aircraft configuration
- Implemented: 'tube_and_wing'
- Not yet implemented: 'blended_wing_body'
2. Calculation method fidelity
- Implemented: 'empirical'
3. Calculation method
- Implemented: 'tank_design_tu_berlin'
4. Energy carrier <sup>1</sup>
- Implemented: 'kerosene'
- Not yet implemented: 'liquid_hydrogen', 'hybrid'
<sup>1</sup> The used energy carrier is determined automatically in the 'read_energy_carrier_and_tank_configuration' function. -->
# The payload-range diagram
UNICADO has the ability to generate a payload-range diagram based on the performance characteristics of your aircraft design. The payload-range diagram is one of the most essential ways of visualizing the transport capabilities of your configuration. Furthermore, it combines performance characteristics from aerodynamic, engine to payload. With an abundance of information it is a fundamental tool in comparing aircraft designs as well as airline fleet planing.
## Input
In order to perform the payload-range diagram generation the following input parameters or input files are needed:
- Payload capabilities
- Mission profile
- Initial cruise Mach number
- Aerodynamic polars
- Engine decks
## Calculation method
The calculation of the payload-range diagram is based on the Breguet range equation as stated below.
$$
R = \frac{V \cdot \frac{L}{D}}{g \cdot SFC} \cdot ln\left(\frac{m_{initial}}{m_{final}} \right)
$$
The used parameters are defined as follows:
- $V$ - speed
- $L$ - lift
- $D$ - drag
- $g$ - gravitational constant
- $SFC$ - specific fuel consumption
- $m_{initial}$ - mass at the beginning of the cruise segment
- $m_{final}$ - mass at the end of the cruise segment
The equation is valid for steady, level flight and is based on the assumption, that the change in mass of an aircraft is proportional to the fuel mass flow.
For the use in UNICADO the Breguet range equation is adapted as follows:
$$
R = \frac{V \cdot \frac{L}{D}}{g \cdot SFC} \cdot ln\left(\frac{0.9065 \cdot TOM}{OME + m_{payload}} \right) \cdot CF
$$
In contrast to the original Breguet range equation the initial mass of the cruise segment $m_{initial}$ is approximated through 90.65% of the take off mass (TOM). Hence, accounting for the fuel consumed until reaching cruise altitude. Furthermore, a calibration factor (CF) is introduced. The calibration factor is calculated based on the ratio of the design range, as defined in the acXML by the user, and the range calculated from the adapted Breguet range equation (assuming a CF of 1 for this purpose) under design point conditions.
In order to approximate the ambient condition for a multi step cruise flight, the cruise altitude is averaged over the weighted segment lengths. Thereafter, the ambient condition is calculated following the International Standard Atmosphere. Based on the previously mentioned assumptions, and for the cruise Mach number at the initial cruise altitude the lift, drag as well as SFC are calculated.
## Output
The output of the payload-range diagram generation can be found in the folder `reporting` where beside the individual plot in .svg format a html report depicting the plot as well as the data of the corner points and design point. Furthermore the ranges of the corner points of the payload-range diagram can be found under the tab `performance/range`.
\ No newline at end of file
# Run your first cost estimation
Let's dive into the fun part and crunch some numbers! :moneybag:
## Tool single execution
The tool can be executed from the console directly if all paths are set. The following will happen:
- [Console output](#console-output)
- [Generation of reports and plots](#reporting)
- [Writing output to aircraft exchange file](#write-data-to-acxml)
Some of the above mentioned steps did not work? Check out the [troubleshooting](#troubleshooting) section for advices. Also, if you need some additional information on the underlying methodology, check out the page on the [cost estimation method](operating_cost_method.md).
So, feel free to open the terminal and run `python.exe cost_estimation.py` to see what happens...
### Console output {#console-output}
Firstly, you see output in the console window. Let's go through it step by step...
```
2024-12-06 11:37:30,205 - PRINT - Cost estimation started...
2024-12-06 11:37:30,224 - PRINT - ----------------------------------------------------------
2024-12-06 11:37:30,224 - PRINT - Operating cost estimation results for design mission.
2024-12-06 11:37:30,224 - PRINT - ----------------------------------------------------------
2024-12-06 11:37:30,226 - PRINT - Capital costs: 5,852,515 €
2024-12-06 11:37:30,226 - PRINT - Crew costs (per year): 4,779,200 €
2024-12-06 11:37:30,227 - PRINT - ROUTE INDEPENDENT COSTS (per year): 10,631,715 €
2024-12-06 11:37:30,227 - PRINT - *
2024-12-06 11:37:30,319 - PRINT - Fuel costs (per year): 22,744,718 €
2024-12-06 11:37:30,322 - PRINT - Handling costs (per year): 3,119,900 €
2024-12-06 11:37:30,322 - PRINT - Landing costs (per year): 1,290,968 €
2024-12-06 11:37:30,348 - PRINT - Air traffic control costs (per year): 9,271,834 €
2024-12-06 11:37:30,351 - PRINT - Maintenance costs (per year): 8,038,461 €
2024-12-06 11:37:30,377 - PRINT - ROUTE DEPENDENT COSTS (per year): 44,465,883 €
2024-12-06 11:37:30,377 - PRINT - *
2024-12-06 11:37:30,420 - PRINT - DIRECT OPERATING COSTS (per year): 55,097,598 €
2024-12-06 11:37:30,420 - PRINT - ----------------------------------------------------------
2024-12-06 11:37:30,607 - WARNING - No calculation method for indirect operating costs (IOC) implemented. IOC set to 0.
```
To this point, the module started and calculated the operating costs for the design mission.
There is also a warning that the indirect operating cost method is not implemented yet.
```
2024-12-06 11:37:30,607 - WARNING - Warning: Operating cost estimation of study mission not possible due to missing data. No operating costs calculated.
2024-12-06 11:37:30,608 - PRINT - ----------------------------------------------------------
```
The tool continues to check if an off-design study exists and tries to calculate the respective costs. In this example, there is no off-design data available and thus, the direct operating costs cannot be determined for the study mission.
```
2024-12-06 11:37:30,641 - PRINT - Plots are generated and saved...
2024-12-06 11:37:38,187 - PRINT - HTML report is generated and saved...
2024-12-06 11:37:38,188 - PRINT - Method-specific data are written to 'cost_estimation_results.xml'...
2024-12-06 11:37:38,192 - WARNING - Warning: "tex_output" switch in module configuration file set to "False". No TeX report file generated.
2024-12-06 11:37:38,192 - PRINT - Cost estimation finished.
```
Finally, you receive information about the reports and plots created (depending on your settings, see next section) and the tool is successfully completed.
### Reporting {#reporting}
In the following, a short overview is given on the generated reports:
- A `cost_estimation.log` file is written within the directory of the executable
- Depending on your settings, the following output is generated and saved in the `reporting` folder, located in the directory of the aircraft exchange file:
- an HTML report in the `report_html` folder
- a TeX report in the `report_tex` folder (not implemented yet)
- an XML file with additional output data in the `report_xml` folder
- plots in the `plots` folder
### Write data to the aircraft exchange file {#write-data-to-acxml}
!!! note
The _acXML_ is an exchange file - we agreed on that only data will be saved as output that is needed by another tool!
Results are saved in the aircraft exchange file at the `aircraft_exchange_file/assessment/cost_estimation/operating_cost` node. The following information is written to the _acXML_:
```
Direct operating cost
|- Flights per year (design mission)
|- Flights per year (study mission) - only if off-design analysis available
|- Route independent cost annual
|- Route dependent cost annual
|- Direct operating cost annual
```
When implemented, the indirect operating costs are going to be saved at `aircraft_exchange_file/assessment/cost_estimation/operating_cost/indirect_operating_cost`.
## Troubleshooting {#troubleshooting}
- The tool does not run properly? *Make sure you have all the paths set up correctly and the specified elements exist.*
# Software architecture
This site is currently under development. :construction:
<!--
## Module structure
'main.py' runs the following functions:
1. 'data_preprocessing' (from 'datapreprocessing.py')<sup>1</sup>
- 1.1
2. 'run_module' (from 'methodexecutionpackage' library)<sup>2</sup>
- 2.1
3. 'data_postprocessing' (from 'datapostprocessing.py')<sup>3</sup>
<sup>1</sup> data preprocessing runs: \
<sup>2</sup> \
<sup>3</sup> data_postprocessing runs: ...
...
### Routing layers
The tank design module has the following layer structure:
1. Aircraft configuration
- Implemented: 'tube_and_wing'
- Not yet implemented: 'blended_wing_body'
2. Calculation method fidelity
- Implemented: 'empirical'
3. Calculation method
- Implemented: 'tank_design_tu_berlin'
4. Energy carrier <sup>1</sup>
- Implemented: 'kerosene'
- Not yet implemented: 'liquid_hydrogen', 'hybrid'
<sup>1</sup> The used energy carrier is determined automatically in the 'read_energy_carrier_and_tank_configuration' function. -->
...@@ -150,6 +150,14 @@ plugins: ...@@ -150,6 +150,14 @@ plugins:
FILE_PATTERNS: "*.cpp *.h" FILE_PATTERNS: "*.cpp *.h"
RECURSIVE: True RECURSIVE: True
EXTRACT_ALL: YES EXTRACT_ALL: YES
performance_assessment:
src-dirs: ../aircraft-design/performance_assessment/
full-doc: True
output: docs/propulsion_design
doxy-cfg:
FILE_PATTERNS: "*.cpp *.h"
RECURSIVE: True
EXTRACT_ALL: YES
aerodynamic_analysis: aerodynamic_analysis:
src-dirs: ../aircraft-design/aerodynamic_analysis/ src-dirs: ../aircraft-design/aerodynamic_analysis/
full-doc: true full-doc: true
...@@ -320,6 +328,15 @@ nav: # Customizes the main navigation struc ...@@ -320,6 +328,15 @@ nav: # Customizes the main navigation struc
- Basic Concepts: documentation/analysis/weight_and_balance_analysis/basic-concepts.md - Basic Concepts: documentation/analysis/weight_and_balance_analysis/basic-concepts.md
- Usage: documentation/analysis/weight_and_balance_analysis/usage.md - Usage: documentation/analysis/weight_and_balance_analysis/usage.md
# # - API Reference: # TODO define for Python # # - API Reference: # TODO define for Python
- Performance Assessment:
- Introduction: documentation/analysis/performance_assessment/index.md
- Getting Started: documentation/analysis/performance_assessment/getting_started.md
- Capabilities:
- Payload-Range Diagram: documentation/analysis/performance_assessment/payload_range_diagram.md
- Takeoff Performance: documentation/analysis/performance_assessment/takeoff_performance.md
- Landing Performance: documentation/analysis/performance_assessment/landing_performance.md
- Flight Envelope: documentation/analysis/performance_assessment/flight_envelope.md
- Ceiling Performance: documentation/analysis/performance_assessment/ceiling_performance.md
- Cost Estimation: - Cost Estimation:
- Introduction: documentation/analysis/cost_estimation/index.md - Introduction: documentation/analysis/cost_estimation/index.md
- Getting Started: documentation/analysis/cost_estimation/getting_started.md - Getting Started: documentation/analysis/cost_estimation/getting_started.md
......
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment