Documentation for new components

doc/features/aerodynamics.rst

@@ -28,6 +28,22 @@ In run script, users should set the values for the following aircraft design par
       - Zero-lift drag coefficient
 
 
+Drag buildups
+=============
+A drag buildup can provide a first estimate of an aircraft's drag coefficient.
+It uses empirical estimates for the drag of individual components, such as the fuselage and engine, and sums them to predict the total drag.
+Empirical interference factors included in the summation account for drag caused by the interaction of components.
+
+In OpenConcept, the drag buildups return CD0, the zero-lift drag coefficient.
+Drag buildups for two configurations are included.
+For a conventional tube and wing configuration, use ``ParasiteDragCoefficient_JetTransport``.
+For a blended wing body configuration, use ``ParasiteDragCoefficient_JetTransport``.
+This value can then be used either with the simple drag polar (``PolarDrag``) or one of the OpenAeroStruct-based drag models to add in the lift-induced component of drag.
+OpenAeroStruct already includes the zero-lift drag of the wing.
+To prevent double counting this drag, the ``ParasiteDragCoefficient_JetTransport`` has an option called ``include_wing``, which should be set to ``False`` when using OpenAeroStruct for drag prediction.
+
+The source code describes details of the implementation, including sources for the individual empirical equations and constants.
+
 Using OpenAeroStruct
 ====================
 Instead of the simple drag polar model, you can use `OpenAeroStruct <https://github.com/mdolab/OpenAeroStruct>`_ to compute the drag.
@@ -95,10 +111,35 @@ The outputs of the surrogate models are CL and CD (and failure for ``AeroStructD
 
 For more details about the surrogate models, see our `paper <https://mdolab.engin.umich.edu/bibliography/Adler2022d>`_.
 
+:math:`C_{L, \text{max}}` estimates
+==================================
+Accurately predicting :math:`C_{L, \text{max}}`, the maximum lift coefficient, is a notoriously challenging task, but doing so is crucial for estimating stall speed and takeoff field length.
+
+Empirical fits
+--------------
+In conceptual design, empirical estimates are often used.
+OpenConcept's ``CleanCLmax`` uses a method from :footcite:t:`raymer2006aircraft` to model the maximum lift coefficient of a clean wing (without high lift devices extended).
+The ``FlapCLmax`` component adds a delta to the clean :math:`C_{L, \text{max}}` to account for flaps and slats, using fits of data from :footcite:t:`roskam1989VI`.
+
+With OpenAeroStruct
+-------------------
+An alternative way to predict :math:`C_{L, \text{max}}` is to use the critical section method with a panel code.
+In this method, the wing angle of attack is increased until the wing's sectional lift coefficient first hits the airfoil's :math:`C_{l, \text{max}}` at some point along the span.
+As with before, the sectional :math:`C_{l, \text{max}}` is often predicted using empirical estimates.
+
+OpenConcept includes a method to use OpenAeroStruct to carry out the critical section method.
+The first step is to perform an OpenAeroStruct analysis of the wing.
+Next, the difference between the spanwise sectional lift coefficient computed by OpenAeroStruct and the associated :math:`C_{l, \text{max}}` is aggregated to smoothly compute the nearest point to stall.
+Finally, a solver varies OpenAeroStruct's angle of attack to drive the aggregated :math:`\max(C_l - C_{l, \text{max}})` to zero.
+A Newton solver is capable of this system, but it is very slow because it needs to invert the whole system's Jacobian.
+A better method is to use OpenMDAO's ``NonlinearSchurSolver``, but it may not be available in your OpenMDAO distribution.
+
 Other models
 ============
 
 The aerodynamics module also includes a couple components that may be useful:
 
   - ``StallSpeed``, which uses :math:`C_{L, \text{max}}`, aircraft weight, and wing area to compute the stall speed
   - ``Lift``, which computes lift force using lift coefficient, wing area, and dynamic pressure
+
+.. footbibliography::

doc/features/energy_storage.rst

@@ -5,7 +5,6 @@ Energy Storage
 **************
 
 This module contains components that can store energy.
-For now this consists only of battery models, but hydrogen tanks would go here too, for example.
 
 Battery models
 ==============
@@ -26,3 +25,13 @@ This is not automatically forced to be less than one, so the user is responsible
 
 This component uses the same model as the ``SimpleBattery``, but adds an integrator to compute the state of charge (from 0.0 to 1.0).
 By default, it starts at a state of charge of 1.0 (100% charge).
+
+Hydrogen tank model
+===================
+
+``LH2TankNoBoilOff``
+--------------------
+
+This provides a physics-based structural weight model of a liquid hydrogen tank.
+It includes an integrator for computing the current mass of LH2 inside the tank.
+For details, see the source code.

doc/features/geometry.rst

@@ -0,0 +1,43 @@
+.. _Geometry:
+
+********
+Geometry
+********
+
+This module includes tools for computing useful geometry quantities.
+
+Wing geometry
+=============
+
+``WingMACTrapezoidal``
+----------------------
+This component computes the mean aerodynamic chord of a trapezoidal wing planform (defined by area, aspect ratio, and taper).
+
+``WingSpan``
+------------
+This component computes the span of an arbitrary wing as :math:`\sqrt{S_{ref} AR}`, where :math:`S_{ref}` is the wing planform area and :math:`AR` is the wing aspect ratio.
+
+``WingAspectRatio``
+-------------------
+This component computes the aspect ratio of an arbitrary wing as :math:`b^2 / S_{ref}` where :math:`b` is the wing span and :math:`S_{ref}` is the wing planform area.
+
+``WingSweepFromSections``
+-------------------------
+This component computes the average quarter chord sweep angle of a wing defined in linearly-varying piecewise sections in the spanwise direction.
+The average sweep angle is weighted by section areas.
+
+``WingAreaFromSections``
+-------------------------
+This component computes the planform area of a wing defined in linearly-varying piecewise sections in the spanwise direction.
+
+.. warning::
+    If you are using this component in conjunction with ``SectionPlanformMesh`` and the inputs you are passing to this component are the same as those passed to ``SectionPlanformMesh``, ensure that you have set the ``scale_area`` option in ``SectionPlanformMesh`` to ``False``.
+    Otherwise, the resulting wing area will be off by a factor.
+
+``WingMACFromSections``
+-------------------------
+This component computes the mean aerodynamic chord of a wing defined in linearly-varying piecewise sections in the spanwise direction.
+It returns both the mean aerodynamic chord and the longitudinal position of the mean aerodynamic chord's quarter chord.
+
+Other quantities
+================

doc/features/mission.rst

@@ -65,6 +65,11 @@ Additional variables you need to set in the run script are
 - reserve range ``reserve_range`` and altitude ``reserve|h0``.
 - loiter duration ``loiter_duration`` and loiter altitude ``loiter|h0``.
 
+Full mission with reserve: ``MissionWithReserve``
+--------------------------------------------
+This mission combines ``FullMissionAnalysis`` and ``MissionWithReserve``, so it includes takeoff phases, climb, cruise, descent, and a reserve mission.
+Refer to the documentation for ``FullMissionAnalysis`` and ``MissionWithReserve`` to determine which parameters must be set.
+
 Phase types
 ===========
 A phase is a building block of a mission profile.

doc/features/propulsion.rst

@@ -88,4 +88,11 @@ It uses either a fractional or fixed split method where fractional splits the in
 The efficiency can be changed from the default of 100%, which results in some heat being generated.
 Cost and weight are modeled as linear functions of the power rating.
 
+Rubber turbofan: ``RubberizedTurbofan``
+---------------------------------------
+
+This model enables the pyCycle-based CFM56 and N+3 turbofan models to be scaled to different thrust ratings.
+The scaling is done by multiplying thrust and fuel flow by the same value.
+The model also has an option to use hydrogen, which scales the fuel flow to maintain the same thrust-specific energy consumption (see :footcite:t:`Adler2023` for a definition) as the kerosene-powered CFM56 and N+3 engine models.
+
 .. footbibliography::

doc/features/stability.rst

@@ -0,0 +1,14 @@
+.. _Stability:
+
+*********
+Stability
+*********
+
+Tail volume coefficients
+========================
+
+In conceptual aircraft design, required horizontal and vertical tail areas of conventional configurations can be approximated using tail volume coefficients.
+This method considers the wing area, wing mean aerodynamic chord, and distance between the wing's quarter mean aerodynamic chord and tail's quarter mean aerodynamic chord.
+``HStabVolumeCoefficientSizing`` and ``VStabVolumeCoefficientSizing`` use tail volume coefficient relationships from :footcite:t:`raymer2006aircraft` to predict horizontal and vertical tail reference areas, respectively.
+
+.. footbibliography::

doc/features/weights.rst

@@ -5,9 +5,42 @@ Weights
 *******
 
 This module provides empty weight approximations using mostly empirical textbook methods.
-For now there are only models for small turboprop-sized aircraft, but more may be added in the future.
 Component positions within the aircraft are not considered; all masses are accumulated into a single number.
 
+Conventional jet transport aircraft OEW: ``JetTransportEmptyWeight``
+====================================================================
+
+This model combines estimates from :footcite:t:`raymer2006aircraft`, :footcite:t:`roskam2019airplane`, and others to estimate the operating empty weight of a jet transport aircraft.
+The model includes two correction factor options: ``structural_fudge`` that multiplies structural weights and another ``total_fudge`` which multiplies the final total weight.
+A complete list of the required inputs and outputs can be found in OpenConcept's API documentation, and more details are available in the source code.
+
+This model uses the following components from the `openconcept.weights` module to estimate the total empty weight:
+
+- ``WingWeight_JetTransport``
+- ``HstabConst_JetTransport``
+- ``HstabWeight_JetTransport``
+- ``VstabWeight_JetTransport``
+- ``FuselageKws_JetTransport``
+- ``FuselageWeight_JetTransport``
+- ``MainLandingGearWeight_JetTransport``
+- ``NoseLandingGearWeight_JetTransport``
+- ``EngineWeight_JetTransport``
+- ``EngineSystemsWeight_JetTransport``
+- ``NacelleWeight_JetTransport``
+- ``FurnishingWeight_JetTransport``
+- ``EquipmentWeight_JetTransport``
+
+Blended wing body jet OEW: ``BWBEmptyWeight``
+=============================================
+
+This blended wing body empty weight model is a modified version of the ``JetTransportEmptyWeight`` buildup.
+It contains the following changes from the conventional configuration jet transport empty weight buildup:
+
+- Separate model for the weight of the pressurized portion of the centerbody for passengers or cargo (``CabinWeight_BWB`` component)
+- Separate model for the weight of the unpressurized portion of the centerbody behind the passengers or cargo (``AftbodyWeight_BWB`` component)
+- Removed fuselage and tail weights
+
+
 Single-engine turboprop OEW: ``SingleTurboPropEmptyWeight``
 ===========================================================
 

doc/index.rst

@@ -137,8 +137,10 @@ Eytan J. Adler and Joaquim R.R.A. Martins, "Efficient Aerostructural Wing Optimi
    features/atmospherics.rst
    features/costs.rst
    features/energy_storage.rst
+   features/geometry.rst
    features/mission.rst
    features/propulsion.rst
+   features/stability.rst
    features/thermal.rst
    features/weights.rst
    features/utilities.rst

doc/ref.bib

@@ -14,4 +14,24 @@ @book{roskam2019airplane
     address={Lawrence, Kansas},
     year={2019},
     isbn={978-1-994995-50-1},
-}
+}
+
+@book{roskam1989VI,
+    author      = {Jan Roskam},
+    title       = {Airplane Design Part VI: Preliminary Calculation of Aerodynamic, Thrust, and Power Characteristics},
+    publisher   = {{DARcorporation}},
+    year        = {1989},
+    isbn        = {978-1-884885-52-5},
+}
+
+@article{Adler2023,
+    author      = {Eytan J. Adler and Joaquim R. R. A. Martins},
+    title       = {Hydrogen-Powered Aircraft: Fundamental Concepts, Key Technologies, and Environmental Impacts},
+    doi         = {10.1016/j.paerosci.2023.100922},
+    journal     = {Progress in Aerospace Sciences},
+    month       = {August},
+    pages       = {100922},
+    pdfurl      = {https://www.researchgate.net/publication/366157885},
+    volume      = {141},
+    year        = {2023},
+}

doc/tutorials/more_examples.rst

@@ -45,3 +45,4 @@ Other useful places to look
 ===========================
 
 The ``B738_VLM_drag.py`` and ``B738_aerostructural.py`` examples show how to use the OpenAeroStruct VLM and aerostructural models.
+The ``B738_sizing.py`` example demonstrates the use of the weight buildup, drag buildup, and :math:`C_{L, \text{max}}` estimate.