Merge pull request #426 from florentLutz/master

Adding a new serie of tutorials

src/fastoad/notebooks/02_From_Python_to_FAST-OAD/.gitignore

@@ -0,0 +1,2 @@
+*/workdir/*
+**/.ipynb_checkpoints/**

src/fastoad/notebooks/02_From_Python_to_FAST-OAD/01_summary.ipynb

@@ -0,0 +1,226 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "2d4f211a",
+   "metadata": {},
+   "source": [
+    "<div class=\"row\">\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/logo-onera.png\" width=\"200\">\n",
+    "  </div>\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/logo-ISAE_SUPAERO.png\" width=\"200\">\n",
+    "  </div>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a91fe5f8",
+   "metadata": {},
+   "source": [
+    "# Gradual introduction to OpenMDAO and FAST-OAD\n",
+    "\n",
+    "This serie of tutorials aims to guide the user in how to write multidisciplinary problems using the OpenMDAO and FAST-OAD framework. Complementary information can be found in the [OpenMDAO documentation](https://openmdao.org/newdocs/versions/latest/main.html) and in the [FAST-OAD documentation](https://fast-oad.readthedocs.io/).\n",
+    "\n",
+    "In order to do so, we will consider a very simple multidisciplinary analysis under the form of the sizing of an aircraft with very basic formulae. This problem will be written in different formats - from very basic Python to FAST-OAD syntax - and the differences and advantages will be explained along the way. This problem has been thought to showcase the capabilities of the FAST-OAD framework and, even though the formulae used were largely inspired from the ones used for the sizing of a CS-23 aircraft, they have been tweaked to reduce the number of variables in the problem. They are not representative of what can be found in the [FAST-OAD_CS23 plugin](https://github.com/supaero-aircraft-design/FAST-GA) (models for general aviation aircraft) nor in the [FAST-OAD_CS25 plugin](https://github.com/fast-aircraft-design/FAST-OAD_CS25) (models for commercial transport aircraft)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0f1359f3",
+   "metadata": {},
+   "source": [
+    "## Description of the problem\n",
+    "\n",
+    "In this problem, we will size an aircraft according to a reduced set of requirements: \n",
+    "* The Maximum Take-Off Weight (**MTOW**) will be computed based on the fuel consumed on a given mission defined as carrying a given **payload mass** over a given **range**. \n",
+    "* The structural weight (**OWE**) will be divided into two parts: the wing and the wingless structure. The wing weight will be computed based on the **MTOW**, its **area** and its **AR** (aspect ratio) while rest of the structure will be computed as a fraction of the **MTOW**. \n",
+    "* The lift-to-drag ratio (**L/D**) will be computed based on the cruise equilibrium and a very simple quadratic drag model. The **constant drag** part will be split into two parts: the **wing profile drag** which will depend on the **wing area**, and the **profile drag of the rest of the fuselage** which will be kept constant. The **induced drag coefficient**, as for it, will be computed solely based on the wing **AR**. \n",
+    "* Finally, the **wing area** will be computed based on the **MTOW** assuming a **constant wing loading**.\n",
+    "\n",
+    "At this point, a remark can be made: the **MTOW** is both an output of the process and an input of one of its model. We will call that a sizing loop, and we will need to iterate to find a **MTOW** for which both the input and the output is equal. Once the loop is converged, we will have a sized aircraft. In this first case, all input data are fixed to the value chosen by the designer but even so, loops still have to be resolved (e.g. the loops mentionned above), this is what is called a multidisciplinary analysis or MDA.\n",
+    "\n",
+    "A visual illustration of the global process is presented below.\n",
+    "\n",
+    "<div class=\"row\">\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/global_process.png\" width=\"600\">\n",
+    "  </div>\n",
+    "</div>\n",
+    "\n",
+    "For the reader already familiar with the world of aircraft design, another remark can be made: based on the value of the **AR**, the aircaft **L/D** might increase (and so, the fuel consumption will decrease). However, as the **AR** increases so will the wing bending moment and thus, so will the wing mass. Consequently, the **OWE** will be greater. Based on those observations, we can guess there will be an \"ideal\" **AR** for which the aircraft will be able to fly its design mission with the lowest **MTOW**. This is a multidisciplinary optimization or MDO and the aspect ratio will be considered a design variable! This is nothing but an added layer to the MDA where, instead of having only fixed parameter, we allow one to vary (here, the aspect ratio) and we observe the change in the converged aircraft at the end. The optimizer will then try different value of the aspect ratio until the optimal one is found.\n",
+    "\n",
+    "A visual illustration of the MDO process is presented below.\n",
+    "\n",
+    "<div class=\"row\">\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/mdo.png\" width=\"700\">\n",
+    "  </div>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "4c22a16f",
+   "metadata": {},
+   "source": [
+    "## Description of the models\n",
+    "\n",
+    "In this section, we will describe the model and formulae we will use for this problem. As it might have been guessed from the previous graph, we will organise them by module to echo what is done in FAST-OAD and to keep things organized.\n",
+    "\n",
+    "### Geometry\n",
+    "\n",
+    "The geometry model is very simple as it only contains the computation of the wing area $S_{w}$ which is:\n",
+    "\n",
+    "$$S_{w} = \\frac{MTOW}{(MTOW/S_w)_{data}}$$\n",
+    "\n",
+    "The ratio $(MTOW/S_w)_{data}$ is called the wing loading and is an input of the model.\n",
+    "\n",
+    "\n",
+    "### Aerodynamics\n",
+    "\n",
+    "The main output of the aerodynamics model will be the lift-to-drag ratio (**L/D** or l_d in the following code) in cruise conditions. In order to calculate it, we will compute the constant drag and the lift induced drag based on the lift equilibrium in cruise conditions. Then, we will divide the lift by the sum of the two drag sources obtained. A graph representing the model is shown below."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f91743ea",
+   "metadata": {},
+   "source": [
+    "<div class=\"row\">\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/aerodynamics.png\" width=\"600\">\n",
+    "  </div>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "787a9dd8",
+   "metadata": {},
+   "source": [
+    "The constant (also named profile or zero-lift) drag will be computed as:\n",
+    "\n",
+    "$$C_{d0} = \\frac{C_{d0_{other}}*S_{ref,alt}}{S_{ref}} + c $$\n",
+    "\n",
+    "where $C_{d0_{other}}$ and $c$ are constants which respectively accounts for the profile drag from the aircraft without the wing and wing profile drag. They were obtained based on a more thorough computation using a different reference area $S_{ref,alt}$. The wing area will be taken as the reference area in the rest of the computation.\n",
+    "\n",
+    "The $k$ coefficient (lift-induced drag coefficient) will be computed using a formula from [1]:\n",
+    "\n",
+    "$$k = \\frac{1}{\\pi * AR * e} $$\n",
+    "\n",
+    "with $e$, the Oswald efficiency factor computed with:\n",
+    "\n",
+    "$$e = 1.78(1-0.045*AR^{0.68})-0.64$$\n",
+    "\n",
+    "We can now obtain the total drag using a simple quadratic model:\n",
+    "\n",
+    "$$C_d = C_{d0} + C_{di} = C_{d0} + k * C_l^2$$\n",
+    "\n",
+    "with $C_l$ obtained using the lift equilibrium in cruise conditions: \n",
+    "\n",
+    "$$C_l = \\frac{MTOW * g}{0.5*\\rho*V^2*S_w}$$\n",
+    "\n",
+    "with $g$ the free-fall acceleration constant, $\\rho$ the air density at the cruise altitude and $V$ the cruise speed.\n",
+    "\n",
+    "### Mass\n",
+    "\n",
+    "The mass model is described in the following picture:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a037dfac",
+   "metadata": {},
+   "source": [
+    "<div class=\"row\">\n",
+    "  <div class=\"column\">\n",
+    "    <img src=\"./img/mass.png\" width=\"600\">\n",
+    "  </div>\n",
+    "</div>"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "9fed326f",
+   "metadata": {},
+   "source": [
+    "The wing mass will be computed using a modified version of the formula presented by [1] and originating from [2]:\n",
+    "\n",
+    "$$\n",
+    "m_W = 96.948*\\left[\\left(\\frac{5.7*MTOW}{10^5}\\right)^{0.65}*AR^{0.57}*\\left(\\frac{S_W}{100}\\right)^{0.61}*2.5\\right]^{0.993}\n",
+    "$$\n",
+    "\n",
+    "where **MTOW** is in lbm and $S_W$ is in ft²\n",
+    "\n",
+    "Then, for the **OWE**, we will used a formula similar to what is presented in [1], which we will modify to account for the fact that the wing mass is computed on its own:\n",
+    "\n",
+    "$$\n",
+    "OWE = MTOW * ( 0.41 + 0.0066 * ln( MTOW ) ) + m_W\n",
+    "$$\n",
+    "\n",
+    "### Performance\n",
+    "\n",
+    "For the computation of the fuel consumed during the mission, we will use the Breguet range equation re-arranged to make the fuel appear:\n",
+    "\n",
+    "$$\n",
+    "m_{fuel} = (OWE + Payload) * \\left(e^{\\dfrac{Range * TSFC * (1/(L/D) * g)}{V_{\\infty}}} - 1\\right)\n",
+    "$$\n",
+    "\n",
+    "In this formula, the **range** and the **payload** define the aircraft design mission by describing how much weight it needs to carry over which distance. The $TSFC$, or thrust specific fuel consumption, is a technological factor that characterizes the fuel consumed by unit force produced.\n",
+    "\n",
+    "### MTOW\n",
+    "\n",
+    "We can now compute our new MTOW with:\n",
+    "\n",
+    "$$ MTOW = OWE + Payload + m_{fuel} $$\n",
+    "\n",
+    "## Content of the tutorial\n",
+    "\n",
+    "The following notebooks are dedicated to the implementation of this problem under various forms. In every case, we will split the models in different files and folders to keep it organized.\n",
+    "\n",
+    "* [The second notebook](02_pure_Python.ipynb) is dedicated to the python implementation of the base formulae, how to define the sizing process without using any optimization modules and how to solve it and simulate an MDO with very simple tools.\n",
+    "\n",
+    "* [The third notebook](03_scipy.ipynb) will show you how to use scipy to resolve the MDA and how to implement an MDO, still using scipy.\n",
+    "\n",
+    "* [The forth notebook](04_OpenMDAO.ipynb) will explain how this all translates in OpenMDAO and it will highlight the benefits of using this framework.\n",
+    "\n",
+    "* [The fifth notebook](05_FAST-OAD.ipynb)'s aims is to show how to use the FAST-OAD framework and what it brings compared to OpenMDAO."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "121d8a68",
+   "metadata": {},
+   "source": [
+    "## Bibliography\n",
+    "[1] Gudmundsson, Snorri. General aviation aircraft design: Applied Methods and Procedures. Butterworth-Heinemann, 2013.\n",
+    "\n",
+    "[2] Nicolai, Leland M., and Grant E. Carichner. Fundamentals of aircraft and airship design, Volume 1–Aircraft Design. American Institute of Aeronautics and Astronautics, 2010."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}