Docs overhaul and refactor to organize code (#41)

* Added initial doc and refactoring ideas to markdown file * Fixing highlighting * Trying again with new way to highlight note * Added TODO for Shugo's work * Added initial docs layout * Initial tutorial development * added mission analysis documentation * replaced with in comments; removed unused options * More work on minimal tutorial * Finished minimal tutorial * Added idea for integrator tutorial * Added N2 diagram download * Added integrator example * Added initial blurb with integrator tutorial results * Integrator tutorial progress * Finished minimal integrator tutorial * Slight change to tutorial wording * Added black and flake8 CI checks * Cleaned up TBM850 example and associated code and docs * Added publications and fixed TBM integration test * Added images and some code to turboprop tutorial * Moved N2 to use embed-n2 and automatically generate figures from example codes * Trying to fix example path errors in RTD build * Switched to using find_packages in setup * Temporary fix to import from within examples * Added matplotlib to requirements.txt for RTD * Added more to turboprop tutorial * More for turboprop and refined other tutorials * Finished turboprop tutorial * Moved examples folder into package * Added folders to package to begin refactor * Changed docs creation to remove extra files generated when examples are run * Moved aerodynamics to its own folder * Moved openaerostruct to aerodynamics folder * Moved atmospherics * Moved mission analysis stuff to mission folder * Moved propulsion, except batteries * Renamed OAS aero components * Added files for model descriptions * Moved battery * Updated GHA engine data location * Moved pre-made propulsion layouts from examples folder to propulsion * Moved turboprop cost models * added aero and prop models * Moved thermal comps * Moved liquid cooled battery and motor to battery and motor files and broke apart remaining components from heat sink file because it did not have a common theme * Moved weights out of examples folder * Removed api and promoted more from utilities for shorter import statements * Reorganized docs * Removed unused init files and added energy storage doc file * Added description of where to go next after finishing tutorials * Updated roadmap and added atmospherics docs * Added costs and a couple additional aerodynamics models * Moved liquid cooled motor and battery back to thermal, whoops * Added paths and consistency with class name in heading * Fixed my spelling error * More formatting stuff * Added propulsion docs * Added thermal docs * Added weights docs * Added utilities docs * Added package print to GHA * Add testing on multiple python versions * Fix GHA python version with quotes * Removed six dependency * Update readme * Added figure for readme * Added back example data init file, think it borked the docks * Added some spacing in RTD index * Added docs on mission groups * Text edits * Removed changes.md file with changes to make in this PR * Added aerodynamics summary * Added bibtex for raymer citation * Fixed pycycle typo * Fixed thermal typo * Added citations for weights * Removed old feature docs * Fixed NATO publication * Fixed integrator typo * Added constants file * Removed from __future__ import division * Explicitly wrote out HX test imports * Made heat pipe imports consistent with other tests * Made thermal test imports consistent with others * Removed SumComp * Removed dymos stuff that was copies of existing stuff Co-authored-by: kanekosh <[email protected]>
mdolab · Aug 10, 2022 · 1c407d9 · 1c407d9
1 parent 8a2fcb5
commit 1c407d9
Show file tree

Hide file tree

Showing 192 changed files with 4,767 additions and 4,479 deletions.
diff --git a/.github/workflows/openconcept.yaml b/.github/workflows/openconcept.yaml
@@ -9,11 +9,16 @@ on:
       - v*.*.*
 
 jobs:
+  black:
+    uses: mdolab/.github/.github/workflows/black.yaml@main
+  flake8:
+    uses: mdolab/.github/.github/workflows/flake8.yaml@main
   build:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest", "macos-latest"]
+        python-version: ["3.8", "3.9", "3.10"]
       fail-fast: false
     env:
       OMP_NUM_THREADS: 1
@@ -26,7 +31,7 @@ jobs:
       uses: conda-incubator/setup-miniconda@v2
       with:
         auto-update-conda: true
-        python-version: 3.8
+        python-version: ${{ matrix.python-version }}
     - name: Setup conda
       run: |
         conda config --set always_yes yes
@@ -35,15 +40,19 @@ jobs:
       run: |
         pip install .[testing]
         pip install .[docs]
+    - name: List Python and package info
+      run: |
+        python --version
+        pip list
     - name: Download engine deck surrogate model
       run: |
         curl -L -o engine_kriging_surrogate_model.tar.gz http://umich.edu/~mdolaboratory/repo_files/openconcept/engine_kriging_surrogate_model.tar.gz
     - name: Move engine deck files to appropriate location
       run: |
         tar -xvf engine_kriging_surrogate_model.tar.gz
-        mv cfm56* ./openconcept/components/empirical_data/cfm56
-        mv n3_hybrid* ./openconcept/components/empirical_data/n+3_hybrid
-        mv n3* ./openconcept/components/empirical_data/n+3
+        mv cfm56* ./openconcept/propulsion/empirical_data/cfm56
+        mv n3_hybrid* ./openconcept/propulsion/empirical_data/n+3_hybrid
+        mv n3* ./openconcept/propulsion/empirical_data/n+3
     - name: Build and Test
       run: |
         python -m pytest --cov-config=.coveragerc --cov=openconcept --cov-report=xml

diff --git a/docs/_static/images/full_parallel_system_chiller.png b/docs/_static/images/full_parallel_system_chiller.png
diff --git a/docs/_static/images/readme_charts.png b/docs/_static/images/readme_charts.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -15,6 +15,7 @@
 import os
 import sys
 import openconcept
+import subprocess
 
 from sphinx_mdolab_theme.config import *
 
@@ -157,6 +158,43 @@ def generate_src_docs(dir, top, packages):
     index.close()
 
 
+def run_file_move_result(file_name, output_files, destination_files, optional_cl_args=[]):
+    """
+    Run a file (as a subprocess) that produces output file(s) of interest.
+    This function then moves the file(s) to a specified location.
+
+    For example, a file may produce a figure that is used in the docs.
+    This function can be used to automatically generate the figure in the RTD build
+    and move it to a specific location in the RTD build.
+
+    Note that the file is run from the openconcept/docs directory and all relative paths
+    are relative to this directory. If the output file name is defined in the script
+    using a relative path remember to take it into account.
+
+    Parameters
+    ----------
+    file_name : str
+        Python file to be run
+    output_files : list of str
+        Output files produced by running file_name
+    destination_files : list of str
+        Destination paths/file names to move output_file to (must be same length as output_files)
+    optional_cl_args : list of str
+        Optional command line arguments to add when file_name is run by Python
+    """
+    # Error check
+    if len(output_files) != len(destination_files):
+        raise ValueError("The number of output files must be the same as destination file paths")
+
+    # Run the file
+    subprocess.run(["python", file_name] + optional_cl_args)
+
+    # Move the files
+    for output_file, destination_file in zip(output_files, destination_files):
+        os.makedirs(os.path.dirname(destination_file), exist_ok=True)
+        os.replace(output_file, destination_file)
+
+
 # Patch the Napoleon parser to find Inputs, Outputs, and Options headings in docstrings
 
 from sphinx.ext.napoleon.docstring import NumpyDocstring
@@ -210,7 +248,11 @@ def patched_parse(self):
 	'sphinx.ext.napoleon',
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
-    "sphinx_copybutton",
+    'sphinxcontrib.bibtex',
+    'sphinx_copybutton',
+    'sphinx_mdolab_theme.ext.embed_code',
+    'sphinx_mdolab_theme.ext.embed_compare',
+    'sphinx_mdolab_theme.ext.embed_n2',
 ]
 autodoc_inherit_docstrings = False
 autodoc_member_order = 'bysource'
@@ -240,6 +282,8 @@ def patched_parse(self):
 # Usually you set "language" from the command line for these cases.
 language = 'en'
 
+# This sets the bibtex bibliography file(s) to reference in the documentation
+bibtex_bibfiles = ['ref.bib']
 
 # -- Options for HTML output -------------------------------------------------
 
@@ -308,6 +352,16 @@ def patched_parse(self):
 
 # -- Extension configuration -------------------------------------------------
 
+# -- Run examples to get figures for docs ------------------------------------
+run_file_move_result("../openconcept/examples/minimal.py", ["minimal_example_results.svg"], ["tutorials/assets/minimal_example_results.svg"], optional_cl_args=["--hide_visuals"])
+run_file_move_result("../openconcept/examples/minimal_integrator.py", ["minimal_integrator_results.svg"], ["tutorials/assets/minimal_integrator_results.svg"], optional_cl_args=["--hide_visuals"])
+run_file_move_result("../openconcept/examples/TBM850.py", ["turboprop_takeoff_results.svg", "turboprop_mission_results.svg"], ["tutorials/assets/turboprop_takeoff_results.svg", "tutorials/assets/turboprop_mission_results.svg"], optional_cl_args=["--hide_visuals"])
+
+# Remove the N2 diagrams it also created
+files_remove = ["minimal_example_n2.html", "minimal_integrator_n2.html", "turboprop_n2.html"]
+for file in files_remove:
+    os.remove(file)
+
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
@@ -324,11 +378,16 @@ def patched_parse(self):
     # subprocess.call(['sphinx-apidoc','-o','_srcdocs_native','../openconcept'])
     # os.rename('_srcdocs_native/modules.rst','_srcdocs_native/index.rst')
     # openmdao way
-    packages = ['analysis',
-                'analysis.openaerostruct',
-                'analysis.atmospherics',
-                'analysis.performance',
-                'components',
-                'utilities',
-                'utilities.math']
+    packages = [
+        'aerodynamics',
+        'aerodynamics.openaerostruct',
+        'atmospherics',
+        'energy_storage',
+        'mission',
+        'propulsion',
+        'propulsion.systems',
+        'thermal',
+        'utilities',
+        'utilities.math'
+    ]
     generate_src_docs(".", "../openconcept", packages)
diff --git a/docs/developer/roadmap.rst b/docs/developer/roadmap.rst
@@ -4,13 +4,11 @@
 Development Roadmap
 *******************
 
-OpenConcept is still very much alpha and is basically the product of one conference paper and a few months of work by one person.
-
 Known issues to be addressed include:
     - No distinction right now between calibrated, equivalent, indicated airspeeds (compressibility effects) in the standard atmosphere
-    - Spotty automated testing coverage
-    - Spotty documentation coverage
     - Limited validation of the takeoff performance code (it is hard to find actual CLmax and drag polar data!)
 
 Future ideas include:
-    - Unifying the ODE integration math with NASA's Dymos toolkit
+    - Unifying the ODE integration math with NASA's Dymos toolkit
+    - Adding locations to weights to be able to include stability constraints and trim OpenAeroStruct aerodynamic models
+    - Incorporate OpenVSP for visualizations of the configuration
diff --git a/docs/features/aerodynamics.rst b/docs/features/aerodynamics.rst
@@ -0,0 +1,144 @@
+.. _Aerodynamics:
+
+************
+Aerodynamics
+************
+
+OpenConcept's aerodynamics components provide an estimate of drag as a function of lift coefficient, flight conditions, and other parameters.
+
+Simple drag polar: ``PolarDrag``
+================================
+
+``PolarDrag`` is the most basic aerodynamic model and uses a parabolic drag polar.
+This component computes the drag force given the flight condition (dynamic pressure and lift coefficient) at each node along the mission profile.
+In run script, users should set the values for the following aircraft design parameters, or declare them as design variables.
+
+.. list-table:: Aircraft design variables for drag polar model
+    :header-rows: 1
+
+    * - Variable name
+      - Property
+    * - ac|geom|wing|S_ref
+      - Reference wing area
+    * - ac|geom|wing|AR
+      - Wing aspect ratio
+    * - e
+      - Wing Oswald efficiency
+    * - CD0
+      - Zero-lift drag coefficient
+
+
+Using OpenAeroStruct
+====================
+Instead of the simple drag polar model, you can use `OpenAeroStruct <https://github.com/mdolab/OpenAeroStruct>`_ to compute the drag.
+This allows you to parametrize the aircraft wing design in more details and explore the effects of wing geometry, including taper, sweep, and twist.
+OpenAeroStruct implements the vortex-lattice method (VLM) for aerodynamics and beam-based finite element method (FEM) for structures (in the case of the aerostructural drag polar).
+For more detail, please check the `documentation <https://mdolab-openaerostruct.readthedocs-hosted.com/en/latest/>`_.
+
+The wing is currently limited to simple planform geometries.
+Additionally, the wing does not include a tail to trim it because there is no OpenConcept weight position model with which to trim.
+
+OpenConcept uses a surrogate model trained by OpenAeroStruct analyses to reduce the computational cost.
+The data generation and surrogate training is automated; specifying the training grid manually may improve accuracy or decrease computational cost.
+
+VLM-based aerodynamic model: ``VLMDragPolar``
+------------------------------------------------
+This model uses the vortex-lattice method (VLM) to compute the drag.
+The inputs to this model are the flight conditions (Mach number, altitude, dynamic pressure, lift coefficient) and aircraft design parameters.
+
+Users should set the following design parameters and options in the run script.
+
+.. list-table:: Aircraft design variables for VLM-based model
+    :header-rows: 1
+
+    * - Variable name
+      - Property
+      - Type
+    * - ac|geom|wing|S_ref
+      - Reference wing area
+      - float
+    * - ac|geom|wing|AR
+      - Wing aspect ratio
+      - float
+    * - ac|geom|wing|taper
+      - Taper ratio
+      - float
+    * - ac|geom|wing|c4sweep
+      - Sweep angle at quarter chord
+      - float
+    * - ac|geom|wing|twist
+      - Spanwise distribution of twist, from wint tip to root.
+      - 1D ndarray, lendth ``num_twist``
+    * - ac|aero|CD_nonwing
+      - Drag coefficient of components other than the wing; e.g. fuselage,
+        tail, interference drag, etc.
+      - float
+    * - fltcond|TempIncrement
+      - Temperature increment for non-standard day
+      - float
+
+.. list-table:: Options for VLM-based model
+    :widths: 30 50 20
+    :header-rows: 1
+
+    * - Variable name
+      - Property
+      - Type
+    * - ``num_x``
+      - VLM mesh size (number of vertices) in chordwise direction.
+      - int
+    * - ``num_y``
+      - VLM mesh size (number of vertices) in spanwise direction.
+      - int
+    * - ``num_twist``
+      - Number of spanwise control points for twist distribution.
+      - int
+
+There are other advanced options, e.g., the surrogate training points in Mach-alpha-altitude space.
+The default settings should work fine for these advanced options, but if you want to make changes, please refer to the source docs.
+
+Aerostructural model: ``AeroStructDragPolar``
+-----------------------------------------------------
+This model is similar to the VLM-based aerodynamic model, but it performs aerostructural analysis (that couples VLM and structural FEM) instead of aerodynamic analysis (just FEM).
+This means that we now consider the wing deformation due to aerodynamic loads, which is important for high aspect ratio wings.
+The structural model does not include point loads (e.g., for the engine) or distributed fuel loads.
+
+The additional input variables users need to set in the run script are listed below.
+Like the ``num_twist`` option, you may need to set ``num_toverc``, ``num_skin``, and ``num_spar``.
+
+.. list-table:: Additional design variables for aerostructural model
+    :widths: 30 50 20
+    :header-rows: 1
+
+    * - Variable name
+      - Property
+      - Type
+    * - ac|geom|wing|toverc
+      - Spanwise distribution of thickness to chord ratio.
+      - 1D ndarray, lendth ``num_toverc``
+    * - ac|geom|wing|skin_thickness
+      - Spanwise distribution of skin thickness.
+      - 1D ndarray, lendth ``num_skin``
+    * - ac|geom|wing|spar_thickness
+      - Spanwise distribution of spar thickness.
+      - 1D ndarray, lendth ``num_spar``
+
+In addition to the drag, the aerostructural model also outputs the structural failure indicator (``failure``) and wing weight (``ac|weights|W_wing``).
+The `failure` variable must be negative (``failure <= 0``) to constrain wingbox stresses to be less than the yield stress.
+
+Understanding the surrogate modeling
+------------------------------------
+
+OpenConcept uses surrogate models based on OpenAeroStruct analyses to reduce the computational cost for mission analysis.
+The surrogate models are trained in the 3D input space of Mach number, angle of attack, and altitude.
+The outputs of the surrogate models are CL and CD (and failure for ``AeroStructDragPolar``).
+
+For more details about the surrogate models, see our `paper <https://mdolab.engin.umich.edu/bibliography/Adler2022a>`_.
+
+Other models
+============
+
+The aerodynamics module also includes a couple components that may be useful to be aware of:
+
+  - ``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
diff --git a/docs/features/atmospherics.rst b/docs/features/atmospherics.rst
@@ -0,0 +1,32 @@
+.. _Atmospherics:
+
+************
+Atmospherics
+************
+
+Most of OpenConcept's atmospheric models use the 1976 Standard Atmosphere.
+For more details, see the source documentation for the ``ComputeAtmosphericProperties`` component.
+
+Models for specific atmospheric properties are also available on their own:
+
+    - ``TrueAirspeedComp``
+    - ``EquivalentAirpseedComp``
+    - ``TemperatureComp``
+    - ``SpeedOfSoundComp``
+    - ``PressureComp``
+    - ``MachNumberComp``
+    - ``DynamicPressureComp``
+    - ``DensityComp``
+
+The code is adapted from this paper, with permission:
+
+.. code:: bibtex
+
+    @conference{Jasa2018b,
+        Address = {Orlando, FL},
+        Author = {John P. Jasa and John T. Hwang and Joaquim R. R. A. Martins},
+        Booktitle = {2018 AIAA/ASCE/AHS/ASC Structures, Structural Dynamics, and Materials Conference; AIAA SciTech Forum},
+        Month = {January},
+        Title = {Design and Trajectory Optimization of a Morphing Wing Aircraft},
+        Year = {2018}
+    }
diff --git a/docs/features/costs.rst b/docs/features/costs.rst
@@ -0,0 +1,10 @@
+.. _Costs:
+
+*****
+Costs
+*****
+
+OpenConcept's existing cost model is rather rudimentary and computes operating costs for a turboprop.
+The component is called ``TurbopropOperatingCost``.
+Unfortunately, there are not example aircraft that use this model, but the source code is relatively readable to figure out what inputs and outputs are needed.
+Other cost models may be added in the future.
diff --git a/docs/features/energy_storage.rst b/docs/features/energy_storage.rst
@@ -0,0 +1,28 @@
+.. _Energy-storage:
+
+**************
+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
+==============
+
+``SimpleBattery``
+-----------------
+
+This component simple uses a simple equation to relate the electrical power draw to the heat generated: :math:`\text{heat} = \text{electricity load} (1 - \eta)`.
+Cost is assumed to be a linear function of weight.
+Component sizing margin is computed which describes the electrical load to the max power of the battery (defined by battery weight and specific power).
+This is not automatically forced to be less than one, so the user is responsible for checking/enforcing this in an analysis or optimization.
+
+.. warning::
+    This component does not track its state of charge, so without an additional integrator there is no way to know when the battery has been depleted. For this reason, it is recommended to use the ``SOCBattery``.
+
+``SOCBattery``
+--------------
+
+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).