Docs overhaul, part 1: Getting Started, partial User's Guide, and Examples

.github/workflows/test_docs.yml

@@ -33,7 +33,7 @@ jobs:
         uses: ./actions/.github/actions/prepare_environment
         with:
             NAME: 'latest'
-            PY: 3.12
+            PY: 3.13
             NUMPY: 2.2
             SCIPY: 1.16
             PYOPTSPARSE: 'v2.14.4'

aviary/api.py

@@ -26,6 +26,7 @@
 from aviary.variable_info.functions import (
     add_aviary_input,
     add_aviary_output,
+    add_aviary_option,
     get_units,
     override_aviary_vars,
     setup_model_options,
@@ -51,7 +52,6 @@
 from aviary.models.missions.energy_state_default import (
     phase_info as default_energy_state_phase_info,
 )
-from aviary.interface.run_aviary import run_aviary_cmd
 from aviary.interface.run_aviary import run_aviary
 from aviary.core.aviary_problem import AviaryProblem, reload_aviary_problem
 from aviary.utils.engine_deck_conversion import convert_engine_deck

aviary/core/aviary_problem.py

@@ -1,6 +1,5 @@
 import csv
 import json
-import math
 import os
 import warnings
 from copy import deepcopy
@@ -37,14 +36,6 @@ class AviaryProblem(om.Problem):
     """
     Main class for instantiating, formulating, and solving Aviary problems.
 
-    On a basic level, this problem object is all the conventional user needs
-    to interact with. Looking at the three "levels" of use cases, from simplest
-    to most complicated, we have:
-
-    Level 1: users interact with Aviary through input files (.csv or .yaml, TBD)
-    Level 2: users interact with Aviary through a Python interface
-    Level 3: users can modify Aviary's workings through Python and OpenMDAO
-
     This Problem object is simply a specialized OpenMDAO Problem that has
     additional methods to help users create and solve Aviary problems.
     """
@@ -1974,6 +1965,9 @@ def reload_aviary_problem(
     filename : str, Path
         User specified name and relative path of json file containing the sized aircraft data
 
+    phase_info : dict, Path
+        phase_info dictionary used by the original problem
+
     metadata : dict (optional)
         Custom metadata if needed to read all variables present in the json output file
 

aviary/docs/_toc.yml

@@ -2,76 +2,78 @@
 # Learn more at https://jupyterbook.org/customize/toc.html
 
 format: jb-book
-root: intro
+root: introduction
 parts:
 - caption: Getting Started
   chapters:
+    - file: getting_started/getting_started
     - file: getting_started/installation
-    - file: getting_started/what_aviary_does
-    - file: getting_started/tools_that_aviary_uses
     - file: getting_started/expected_user_knowledge
-    - file: getting_started/onboarding
-      sections:
-        - file: getting_started/onboarding_level1
-        - file: getting_started/onboarding_level2
-        - file: getting_started/onboarding_level3
-        - file: getting_started/onboarding_ext_subsystem
-        - file: getting_started/input_csv_phase_info
-    - file: getting_started/now_what
+    - file: getting_started/tools_that_aviary_uses
+    - file: getting_started/whats_next
 
 - caption: User Guide
   chapters:
-    - file: user_guide/user_interface
+    - file: user_guide/aviary_fundamentals
       sections:
-      - file: user_guide/UI_Levels
-      - file: user_guide/examples_of_the_same_mission_at_different_UI_levels
-      - file: user_guide/aviary_commands
-      - file: user_guide/input_files
-      - file: user_guide/phase_info
-      - file: user_guide/phase_info_detailed
-      - file: user_guide/phase_info_conversion
-    - file: user_guide/drawing_and_running_simple_missions
-    - file: user_guide/pre_mission_and_mission
-    - file: user_guide/postprocessing_and_visualizing_results
-    - file: user_guide/variable_metadata
-    - file: user_guide/features_and_functionalities
+        - file: user_guide/fundamentals/variables
+        - file: user_guide/fundamentals/input_files
+          sections:
+            - file: user_guide/fundamentals/aircraft_definition
+            - file: user_guide/fundamentals/mission_definition
+            - file: user_guide/fundamentals/data_files
+        - file: user_guide_unreviewed/outputs
+        - file: user_guide_unreviewed/UI_levels
+        # - file: user_guide/user_interface
+        # - file: new file with recommended examples to view next
+    - file: user_guide_unreviewed/onboarding_level2
+    - file: user_guide_unreviewed/examples_of_the_same_mission_at_different_UI_levels
+    - file: user_guide_unreviewed/aviary_commands
+    - file: user_guide_unreviewed/drawing_and_running_simple_missions
+    - file: user_guide_unreviewed/pre_mission_and_mission
+    - file: user_guide_unreviewed/visualizing_results
+    - file: user_guide_unreviewed/features_and_functionalities
+    - file: user_guide_unreviewed/custom_variable_hierarchies
+    - file: user_guide_unreviewed/subsystems/subsystems
       sections:
-      - file: user_guide/aerodynamics
-      - file: user_guide/external_aero
-      - file: user_guide/atmosphere
-      - file: user_guide/propulsion
-        sections:
-          - file: user_guide/creating_a_turboprop_engine.ipynb
-          - file: user_guide/hamilton_standard
-          - file: user_guide/motor_electric
-      - file: user_guide/mass
-      - file: user_guide/fuel
-      - file: user_guide/subsystems
-      - file: user_guide/using_external_subsystems
-      - file: user_guide/step_by_step_external_guide
-      - file: user_guide/battery_subsystem_example
-      - file: user_guide/features/overriding
-      - file: user_guide/FLOPS_based_detailed_takeoff_and_landing
-      - file: user_guide/reserve_missions
-      - file: user_guide/multi_mission
-      - file: user_guide/off_design_missions
-      - file: user_guide/payload_range_functionality
-      - file: user_guide/features/blended_wing_body_GASP
-      - file: user_guide/features/blended_wing_body_FLOPS
-    - file: user_guide/troubleshooting
+        - file: user_guide_unreviewed/subsystems/aerodynamics
+          sections:
+            - file: user_guide_unreviewed/subsystems/external_aero
+        - file: user_guide_unreviewed/subsystems/atmosphere
+        - file: user_guide_unreviewed/subsystems/propulsion
+          sections:
+            - file: user_guide_unreviewed/subsystems/electric_motor
+            - file: user_guide_unreviewed/subsystems/hamilton_standard
+            - file: user_guide_unreviewed/subsystems/creating_a_turboprop_engine
+        - file: user_guide_unreviewed/subsystems/mass
+          sections:
+            - file: user_guide_unreviewed/subsystems/fuel
+            - file: user_guide_unreviewed/subsystems/blended_wing_body_GASP
+            - file: user_guide_unreviewed/subsystems/blended_wing_body_FLOPS
+        - file: user_guide_unreviewed/subsystems/using_external_subsystems
+        - file: user_guide_unreviewed/subsystems/step_by_step_external_guide
+        - file: user_guide_unreviewed/subsystems/battery_subsystem_example
+    - file: user_guide_unreviewed/features/overriding
+    - file: user_guide_unreviewed/FLOPS_based_detailed_takeoff_and_landing
+    - file: user_guide_unreviewed/reserve_missions
+    - file: user_guide_unreviewed/multi_mission
+    - file: user_guide_unreviewed/off_design_missions
+    - file: user_guide_unreviewed/payload_range_functionality
+    - file: user_guide_unreviewed/troubleshooting
 
 - caption: Examples
   chapters:
     - file: examples/intro
-    - file: examples/simple_mission_example
-    - file: examples/more_advanced_example
-    - file: examples/coupled_aircraft_mission_optimization
-    - file: examples/additional_flight_phases
-    - file: examples/reserve_missions
-    - file: examples/multi_mission
-    - file: examples/off_design_example
-    - file: examples/OAS_subsystem
-    - file: examples/level_2_detailed_takeoff_and_landing
+    - file: examples/simple_mission
+    - file: examples/custom_optimization
+    - file: examples/reserve_mission
+    - file: examples_unreviewed/more_advanced_example
+    - file: examples/off_design_missions
+    - file: examples_unreviewed/detailed_takeoff_landing
+    - file: examples_unreviewed/multi_mission
+    - file: examples/external_subsystems
+    - file: examples_unreviewed/OAS_subsystem
+    - file: examples_unreviewed/deconstructed_example
 
 - caption: Theory Guide
   chapters:
@@ -88,30 +90,31 @@ parts:
           - file: theory_guide/turboprop
     - file: theory_guide/optimization_algorithms
     - file: theory_guide/validation
+    - file: theory_guide/comparison_to_flops
     - file: theory_guide/gasp_based_bwb
 
 - caption: Developer Guide
   chapters:
     - file: developer_guide/codebase_overview
     - file: developer_guide/coding_standards
-    - file: developer_guide/ai_policy.md
+    - file: developer_guide/ai_policy
     - file: developer_guide/unit_tests
     - file: developer_guide/contributing_guidelines
     - file: developer_guide/how_to_contribute_docs
       sections:
-      - file: developer_guide/doctape.ipynb
-      - file: developer_guide/doctape_examples.ipynb
+      - file: developer_guide/doctape
+      - file: developer_guide/doctape_examples
     - file: developer_guide/debugging_env_from_github
 
+- caption: Source Docs
+  chapters:
+    - file: source_docs/variable_metadata
+    - file: source_docs/phase_info_detailed
+    - file: source_docs/subsystem_builder
+    - file: _srcdocs/index
+
 - caption: Miscellaneous Resources
   chapters:
-    - file: misc_resources/modeling_exercise
     - file: misc_resources/FAQ
-    - file: misc_resources/glossary
     - file: misc_resources/resources
-    - file: misc_resources/externally_supported_subsystems
-    - file: misc_resources/feature_comparison
-      sections:
-      - file: misc_resources/comparison_to_flops
-    - file: misc_resources/planned_future_features
-    - file: _srcdocs/index
+    - file: misc_resources/phase_info_conversion

aviary/docs/developer_guide/coding_standards.ipynb

@@ -16,7 +16,7 @@
     "\n",
     "Verbosity = av.Verbosity\n",
     "verbosity = get_attribute_name(av.Settings, av.Settings.VERBOSITY)\n",
-    "glue_variable('VERBOSITY', verbosity, md_code=True)\n",
+    "glue_variable('Settings.VERBOSITY', verbosity, md_code=False)\n",
     "glue_variable(get_variable_name(Verbosity), md_code=True)\n",
     "glue_variable('QUIET', av.Verbosity.QUIET.name, md_code=True)\n",
     "glue_variable('BRIEF', av.Verbosity.BRIEF.name, md_code=True)\n",
@@ -44,42 +44,24 @@
     "The Aviary repository contains a configuration file that defines what is run when commits are made and with what options enabled. Currently this is limited to formatting with ruff.\n",
     "\n",
     "### Controlling Display Levels\n",
-    "To make debugging issues easier, it is strongly recommended to make use of the {glue:md}`Verbosity` enum (_located in aviary/variable_info/enums.py_). This allows control over how much information is displayed to a user; too much information makes finding relevant information difficult and not enough information can make tracking difficult. Aviary uses a sliding scale of possible verbosity settings, loosly based off of [Ubuntu's format](https://discourse.ubuntu.com/t/cli-verbosity-levels/26973):\n",
+    "To make debugging issues easier, it is strongly recommended to make use of the {glue:md}`Verbosity` enum (_located in aviary/variable_info/enums.py_). This allows control over how much information is displayed to a user; too much information makes finding relevant information difficult and not enough information can make tracking difficult. Aviary uses a sliding scale of possible verbosity settings, loosly based off of [Ubuntu's recommendations](https://discourse.ubuntu.com/t/cli-verbosity-levels/26973):\n",
     "| Verbosity Level | Numerical Value | Description |\n",
     "| :--- | :--- | :--- |\n",
-    "| `QUIET` | 0 | All output except errors are suppressed |\n",
-    "| `BRIEF` | 1 | Only important information is output, in human-readable format |\n",
-    "| `VERBOSE` | 2 | All user-relevant information is output, in human-readable format |\n",
-    "| `DEBUG` | 3 | Any information can be outputted, including warnings, intermediate calculations, etc., with no formatting requirement |\n",
+    "| QUIET | 0 | All output except errors are suppressed |\n",
+    "| BRIEF | 1 | Only important information is output, in human-readable format |\n",
+    "| VERBOSE | 2 | All user-relevant information is output, in human-readable format |\n",
+    "| DEBUG | 3 | Any information can be outputted, including warnings, intermediate calculations, etc., with no formatting requirement |\n",
     "\n",
     "Verbosity levels are defined in Aviary using the {glue:md}`Verbosity` Enum. Each verbosity level is paired with an integer value. In source code, verbosity level can be checked either through comparison with the Enum, or through equality or inequality comparisons with the matching integer value. This allows for code to be triggered not just at a specific level, but for any level above or below the desired setting. Numerical comparisons are recommended for several reasons: they don't require importing the {glue:md}`Verbosity` Enum, and activation is more flexible through the use of inequality comparators, preventing issues like a message only being outputted during {glue:md}`BRIEF` but not {glue:md}`VERBOSE` or {glue:md}`DEBUG`, which a user would expect to also see in higher verbosity settings.\n",
-    "{glue:md}`BRIEF` is the default setting and is used in most cases; however, {glue:md}`QUIET` should be used for tests.\n",
+    "{glue:md}`BRIEF` is the default setting and is appropriate for most cases; however, {glue:md}`QUIET` should be used for tests.\n",
     "\n",
-    "It is preferred that within source code, the full Enums are used for better readability (e.g. {glue:md}`Verbosity.BRIEF`). For tests, scripts, examples, and other places where Aviary is called (rather than defined), it is ok to use the integer representations of verbosity to shorten lines and remove the need to import the {glue:md}`Verbosity` Enum (e.g. passing `0` as the verbosity argument to a function when {glue:md}`QUIET` is desired). An example of this is: *options.set_val(Settings.VERBOSITY, 0)* instead of *options.set_val(Settings.VERBOSITY, Verbosity.QUIET)*. Of course, it is always acceptable to use the full Enum in these cases for the same readability reasons."
-   ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "remove-cell"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "# Testing Cell\n",
-    "import aviary.api as av\n",
-    "\n",
-    "av.Verbosity.BRIEF\n",
-    "av.Verbosity.QUIET"
+    "It is preferred that within source code, the full Enums are used for better readability (e.g. {glue:md}`Verbosity.BRIEF`). For tests, scripts, examples, and other places where Aviary is called (rather than defined), it is ok to use the integer representations of verbosity to shorten lines and remove the need to import the {glue:md}`Verbosity` Enum (e.g. passing `0` as the verbosity argument to a function when {glue:md}`QUIET` is desired). An example of this is: *options.set_val({glue.md}Settings.VERBOSITY, 0)* instead of *options.set_val({glue:md}Settings.VERBOSITY, Verbosity.{glue.md}QUIET)*. Of course, it is always acceptable to use the full Enum in these cases for the same readability reasons."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\n",
     "## Naming Conventions\n",
     "### Variables\n",
     "When it comes to variable naming, always be verbose! The Aviary team considers long but clear and descriptive names superior to shortened or vague names. Typing out a long name is only difficult once, as most IDEs will help you auto-complete long variable names, but the readability they add lasts a lifetime!\n",
@@ -101,7 +83,7 @@
     "\n",
     "## Import statements\n",
     "\n",
-    "Ruff's linting rules allow both absolute and relative paths in `import` statements. Aviary uses absolute paths only. Following PEP8, imports should be grouped in the following order:\n",
+    "Ruff's linting rules allow both absolute and relative paths in import statements. Aviary uses absolute paths only. Following PEP8, imports should be grouped in the following order:\n",
     "\n",
     "1. Standard library imports (e.g. warnings, numpy).\n",
     "2. Related third party imports (e.g. openmdao.api).\n",
@@ -130,7 +112,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.3"
+   "version": "3.13.12"
   }
  },
  "nbformat": 4,

aviary/docs/developer_guide/doctape.ipynb

@@ -20,19 +20,6 @@
     "</details>\n"
    ]
   },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "tags": [
-     "remove-cell"
-    ]
-   },
-   "outputs": [],
-   "source": [
-    "# Testing Cell\n"
-   ]
-  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -82,7 +69,7 @@
     "    'glue_variable': 'glue a variable for later use in markdown cells of notebooks (can auto format for code)',\n",
     "    'glue_keys': 'recursively glue all of the keys from a dict of dicts',\n",
     "    'glue_actions': 'glue all Aviary CLI options for a given command',\n",
-    "    'glue_class_functions': 'glue all class functions for a gen class',\n",
+    "    'glue_class_methods': 'glue all class methods for a given class',\n",
     "    'glue_function_arguments': 'glue all function arguments and default for a given function',\n",
     "    'glue_class_options': 'glue all class options for a given class',\n",
     "}\n",
@@ -198,7 +185,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "base",
+   "display_name": "aviary",
    "language": "python",
    "name": "python3"
   },
@@ -212,7 +199,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.13.12"
   }
  },
  "nbformat": 4,