Merge branch 'OpenMDAO:main' into multi_mission_opt

Author: jsonirobots

aviary/docs/misc_resources/comparison_to_flops.md

@@ -93,7 +93,8 @@ complex than for a traditional tube-and-wing configuration.
 
 FLOPS allows for the input of a maximum of two engine types, each with its own
 engine deck, whereas in Aviary an unlimited number of engine types may be
-defined. Aviary retains many of the relations used by FLOPS to scale engine mass and
+defined. This means that Aviary supports arbitrary numbers of heterogenous
+engines, each of which has unique characteristics and can use different methodologies for sizing and performance estimation. Aviary retains many of the relations used by FLOPS to scale engine mass and
 performance as a function of change in target thrust. Aviary introduces the
 capability to define these scaling relations on a per-engine-type basis, instead
 of using the same scaling relations for all engine types.
@@ -180,7 +181,7 @@ Since the detailed takeoff and landing trajectories are built up from modular
 sequences of phases, they are more flexible than the fixed sequence defined in
 FLOPS and can be used to model more complex operations. For example, a
 higher-fidelity aerodynamic model can be used, or rotation can be controlled
-using thrust vectoring. 
+using thrust vectoring.
 
 Aviary also includes the ability to calculate extended takeoff and landing
 profiles for use in noise analysis. This capability exists within the same set

aviary/docs/misc_resources/glossary.md

@@ -39,6 +39,18 @@ design variable
 flight envelope
     The limits of speed, altitude, and load factor that an aircraft can safely operate within. Understanding the flight envelope is critical for aircraft design and operation.
 
+homogeneous engines
+    An individual engine or set of engines that all have identical performance characteristics.
+    E.g. you might have four engines on an aircraft, but they are all assumed to have the same thrust, fuel consumption, etc.
+    All engines in a homogenous set use the same `EngineModel` object in Aviary.
+    See also; heterogeneous engines.
+
+heterogeneous engines
+    Multiple sets of homogenous engines, with each set having unique performance characteristics.
+    This is useful if you are modeling an aircraft with engines of different sizes or types.
+    Each set of unique engines uses a different `EngineModel` object in Aviary.
+    See also; homogeneous engines.
+
 mission analysis
     The process of determining the trajectory of an aircraft.
     This includes determining the aircraft's flight path, velocity, and acceleration as a function of time.

aviary/docs/user_guide/propulsion.ipynb

@@ -13,7 +13,11 @@
     "\n",
     "Aviary supports an arbitrary number of propulsor models on a vehicle, each with their own unique properties such as performance characteristics, scaling behaviors, and number of propulsors for that given type. \n",
     "<!-- A diagram would be helpful here, showing X propulsors of type A and Y propulsors of type B on an outline of an aircraft -->\n",
-    "Each unique type of engine is referred to as an engine model<!-- Link to wherever this class is described - theory guide? -->. In Aviary, an engine model contains information on how to size and estimate performance for a single instance of an engine of that type. During analysis, Aviary handles summing performance data to a system level. This way, information is available on the performance of both a single instance of an engine, as well as aircraft-level totals, for other Aviary subsystems to utilize."
+    "Each unique type of engine is referred to as an engine model<!-- Link to wherever this class is described - theory guide? -->. In Aviary, an engine model contains information on how to size and estimate performance for a single instance of an engine of that type. During analysis, Aviary handles summing performance data to a system level. This way, information is available on the performance of both a single instance of an engine, as well as aircraft-level totals, for other Aviary subsystems to utilize.\n",
+    "\n",
+    "```{note}\n",
+    "In Aviary, when we refer to multiple engines of the same type, we say they are homogenous. When you are dealing with multiple engines of different types, we say they are heterogeneous.\n",
+    "``` "
    ]
   },
   {
@@ -202,7 +206,7 @@
     "\n",
     "Engine models are defined in Aviary using an `EngineModel` object. An `EngineModel` is responsible for handling many tasks required to prepare an engine for use in Aviary, such as reading engine data from a file in the case of an `EngineDeck` (which is a child class of `EngineModel`). <!-- link to theory guide? -->\n",
     "\n",
-    "An `EngineModel` (and classes inheriting it) can be manually created and added to the Aviary problem. This is extremely useful when setting up an aircraft with multiple engine types, each with unique properties, or using a custom engine model. An `EngineModel` requires an `AviaryValues` object containing the variables required for that engine (such as those outlined in the Beginner Guide example for `EngineDecks`)<!-- link to that subsection -->."
+    "An `EngineModel` (and classes inheriting it) can be manually created and added to the Aviary problem. This is extremely useful when setting up an aircraft with multiple heterogenous types, each with unique properties, or using a custom engine model. An `EngineModel` requires an `AviaryValues` object containing the variables required for that engine (such as those outlined in the Beginner Guide example for `EngineDecks`)<!-- link to that subsection -->."
    ]
   },
   {
@@ -278,7 +282,7 @@
    "id": "bbabdf30",
    "metadata": {},
    "source": [
-    "In this example, *aviary_options* is modified in-place with updated values from *engine_model*, as well as properly configuring engine-related variables into vectors. When working with multiple engines, simply provide `preprocess_propulsion()` with a list of all `EngineModels`, like so:"
+    "In this example, *aviary_options* is modified in-place with updated values from *engine_model*, as well as properly configuring engine-related variables into vectors. When working with multiple heterogenous engines, simply provide `preprocess_propulsion()` with a list of all `EngineModels`, like so:"
    ]
   },
   {

aviary/examples/external_subsystems/battery/run_multiphase_mission.py

@@ -1,11 +1,9 @@
 from aviary.interface.methods_for_level2 import AviaryProblem
-import os
-import pkg_resources
 
 from aviary.examples.external_subsystems.battery.battery_builder import BatteryBuilder
-from aviary.examples.external_subsystems.battery.battery_variables import Aircraft
 from aviary.examples.external_subsystems.battery.battery_variable_meta_data import ExtendedMetaData
 from aviary.api import default_height_energy_phase_info as phase_info
+from aviary.utils.functions import get_aviary_resource_path
 
 
 battery_builder = BatteryBuilder(include_constraints=False)
@@ -15,17 +13,13 @@
 phase_info['cruise']['external_subsystems'] = [battery_builder]
 phase_info['descent']['external_subsystems'] = [battery_builder]
 
-up_dir = os.path.dirname(os.path.dirname(os.path.realpath(__file__)))
-input_file = pkg_resources.resource_filename(
-    "aviary", "models/test_aircraft/aircraft_for_bench_FwFm.csv")
-
 prob = AviaryProblem()
 
 # Load aircraft and options data from user
 # Allow for user overrides here
+input_file = get_aviary_resource_path('models/test_aircraft/aircraft_for_bench_FwFm.csv')
 prob.load_inputs(input_file, phase_info, meta_data=ExtendedMetaData)
 
-
 # Preprocess inputs
 prob.check_and_preprocess_inputs()
 

aviary/examples/external_subsystems/engine_NPSS/table_engine_builder.py

@@ -7,7 +7,7 @@
 from aviary.examples.external_subsystems.engine_NPSS.engine_variable_meta_data import ExtendedMetaData
 from aviary.examples.external_subsystems.engine_NPSS.engine_variables import Aircraft, Dynamic
 from aviary.examples.external_subsystems.engine_NPSS.table_engine_connected_variables import vars_to_connect
-import pkg_resources
+from aviary.utils.functions import get_aviary_resource_path
 import os
 import numpy as np
 
@@ -57,12 +57,9 @@ def build_mission(self, num_nodes, aviary_inputs):
         engine = om.MetaModelSemiStructuredComp(
             method=interp_method, extrapolate=True, vec_size=num_nodes, training_data_gradients=True)
 
-        csv_path = pkg_resources.resource_filename(
-            "aviary",
-            os.path.join("examples", "external_subsystems", "engine_NPSS",
-                         "NPSS_Model", "Output",  "RefEngine.outputAviary")
-        )
-
+        ref = os.path.join("examples", "external_subsystems", "engine_NPSS",
+                           "NPSS_Model", "Output",  "RefEngine.outputAviary")
+        csv_path = get_aviary_resource_path(ref)
         engine_data = np.genfromtxt(csv_path, skip_header=0)
 
         # Sort the data by Mach, then altitude, then throttle

aviary/interface/download_models.py

@@ -1,57 +1,8 @@
 import os
 from pathlib import Path
 import argparse
-import pkg_resources
 import shutil
-
-
-def aviary_resource(resource_name: str) -> str:
-    return pkg_resources.resource_filename("aviary", resource_name)
-
-
-def get_model(file_name: str, verbose=False) -> Path:
-    '''
-    This function attempts to find the path to a file or folder in aviary/models
-    If the path cannot be found in any of the locations, a FileNotFoundError is raised.
-
-    Parameters
-    ----------
-    path : str or Path
-        The input path, either as a string or a Path object.
-
-    Returns
-    -------
-    aviary_path
-        The absolute path to the file.
-
-    Raises
-    ------
-    FileNotFoundError
-        If the path is not found.
-    '''
-
-    # Get the path to Aviary's models
-    path = Path('models', file_name)
-    aviary_path = Path(aviary_resource(str(path)))
-
-    # If the file name was provided without a path, check in the subfolders
-    if not aviary_path.exists():
-        sub_dirs = [x[0] for x in os.walk(aviary_resource('models'))]
-        for sub_dir in sub_dirs:
-            temp_path = Path(sub_dir, file_name)
-            if temp_path.exists():
-                # only return the first matching file
-                aviary_path = temp_path
-                continue
-
-    # If the path still doesn't exist, raise an error.
-    if not aviary_path.exists():
-        raise FileNotFoundError(
-            f"File or Folder not found in Aviary's hangar"
-        )
-    if verbose:
-        print('found', aviary_path, '\n')
-    return aviary_path
+from aviary.utils.functions import get_model
 
 
 def save_file(aviary_path: Path, outdir: Path, verbose=False) -> Path:

aviary/interface/test/test_cmd_entry_points.py

@@ -2,7 +2,7 @@
 import unittest
 from pathlib import Path
 
-import pkg_resources
+from aviary.utils.functions import get_aviary_resource_path
 from openmdao.utils.testing_utils import require_pyoptsparse, use_tempdirs
 
 
@@ -18,7 +18,7 @@ def run_and_test_cmd(self, cmd):
             self.fail(f"Command '{cmd}' failed.  Return code: {err.returncode}")
 
     def get_file(self, filename):
-        filepath = pkg_resources.resource_filename('aviary', filename)
+        filepath = get_aviary_resource_path(filename)
         if not Path(filepath).exists():
             self.skipTest(f"couldn't find {filepath}")
         return filepath
@@ -50,34 +50,34 @@ def bench_test_phase_info_cmd(self):
 
 class fortran_to_aviaryTestCases(CommandEntryPointsTestCases):
     def test_diff_configuration_conversion(self):
-        filepath = pkg_resources.resource_filename('aviary',
-                                                   'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
+        filepath = get_aviary_resource_path(
+            'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
         outfile = Path.cwd() / 'test_aircraft/converter_configuration_test_data_GwGm' / 'output.dat'
         cmd = f'aviary fortran_to_aviary {filepath} -o {outfile} -l GASP'
         self.run_and_test_cmd(cmd)
 
     def test_small_single_aisle_conversion(self):
-        filepath = pkg_resources.resource_filename('aviary',
-                                                   'models/small_single_aisle/small_single_aisle_GwGm.dat')
+        filepath = get_aviary_resource_path(
+            'models/small_single_aisle/small_single_aisle_GwGm.dat')
         outfile = Path.cwd() / 'small_single_aisle' / 'output.dat'
         cmd = f'aviary fortran_to_aviary {filepath} -o {outfile} -l GASP'
         self.run_and_test_cmd(cmd)
 
     def test_FLOPS_conversion(self):
-        filepath = pkg_resources.resource_filename('aviary',
-                                                   'models/N3CC/N3CC_generic_low_speed_polars_FLOPSinp.txt')
+        filepath = get_aviary_resource_path(
+            'models/N3CC/N3CC_generic_low_speed_polars_FLOPSinp.txt')
         outfile = Path.cwd() / 'N3CC' / 'output.dat'
         cmd = f'aviary fortran_to_aviary {filepath} -o {outfile} -l FLOPS'
         self.run_and_test_cmd(cmd)
 
     def test_force_conversion(self):
-        filepath = pkg_resources.resource_filename('aviary',
-                                                   'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
+        filepath = get_aviary_resource_path(
+            'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
         outfile = Path.cwd() / 'output.dat'
         cmd1 = f'aviary fortran_to_aviary {filepath} -o {outfile} -l GASP'
         self.run_and_test_cmd(cmd1)
-        filepath = pkg_resources.resource_filename('aviary',
-                                                   'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
+        filepath = get_aviary_resource_path(
+            'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
         cmd2 = f'aviary fortran_to_aviary {filepath} -o {outfile} --force -l GASP'
         self.run_and_test_cmd(cmd2)
 

aviary/interface/test/test_download_models.py

@@ -3,7 +3,7 @@
 from pathlib import Path
 import shutil
 
-import pkg_resources
+from aviary.utils.functions import get_aviary_resource_path
 from openmdao.utils.testing_utils import use_tempdirs
 from aviary.interface.download_models import get_model, save_file
 
@@ -54,12 +54,11 @@ def test_single_file_custom_outdir(self):
         shutil.rmtree(out_dir)
 
     def test_expected_path(self):
-        filename = f'test_aircraft/converter_configuration_test_data_GwGm.dat'
         aviary_path = get_model('converter_configuration_test_data_GwGm.dat')
 
-        expected_path = pkg_resources.resource_filename('aviary',
-                                                        'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
-        self.assertTrue(str(aviary_path) == expected_path)
+        expected_path = get_aviary_resource_path(
+            'models/test_aircraft/converter_configuration_test_data_GwGm.dat')
+        self.assertTrue(str(aviary_path) == str(expected_path))
 
 
 if __name__ == "__main__":

aviary/interface/test/test_interface_bugs.py

@@ -1,5 +1,4 @@
 from copy import deepcopy
-import pkg_resources
 import unittest
 
 import openmdao.api as om
@@ -9,6 +8,7 @@
 from aviary.interface.default_phase_info.height_energy import phase_info as ph_in
 from aviary.variable_info.variables import Aircraft
 from aviary.variable_info.enums import Verbosity
+from aviary.utils.functions import get_aviary_resource_path
 from openmdao.utils.testing_utils import use_tempdirs
 
 
@@ -70,13 +70,11 @@ def test_post_mission_promotion(self):
 
         prob = AviaryProblem()
 
-        csv_path = pkg_resources.resource_filename(
-            "aviary", "models/test_aircraft/aircraft_for_bench_GwFm.csv")
-
+        csv_path = get_aviary_resource_path(
+            'models/test_aircraft/aircraft_for_bench_GwFm.csv')
         prob.load_inputs(csv_path, phase_info)
 
-
-# Preprocess inputs
+        # Preprocess inputs
         prob.check_and_preprocess_inputs()
 
         prob.add_pre_mission_systems()

aviary/mission/flight_phase_builder.py

@@ -175,7 +175,7 @@ def build_phase(self, aviary_options: AviaryValues = None, phase_type=EquationsO
             rate_targets = ['dh_dr']
             rate2_targets = ['d2h_dr2']
 
-        # For multi-engine cases, we may have throttle allocation control.
+        # For heterogeneous-engine cases, we may have throttle allocation control.
         if phase_type is EquationsOfMotion.HEIGHT_ENERGY and num_engine_type > 1:
             allocation = user_options.get_val('throttle_allocation')
 

aviary/subsystems/aerodynamics/flops_based/skin_friction.py

@@ -47,7 +47,7 @@ def setup(self):
             Aircraft.VerticalTail.NUM_TAILS, zero_count)
         num_fuselages, _ = aviary_options.get_item(
             Aircraft.Fuselage.NUM_FUSELAGES, zero_count)
-        # TODO does not used vectorized multi-engine. Temp using single engine
+        # TODO does not used vectorized heterogeneous engines. Temp using single engine
         num_engines, _ = aviary_options.get_item(
             Aircraft.Engine.NUM_ENGINES, zero_count)
         self.nc = nc = 2 + num_tails + num_fuselages + int(sum(num_engines))

aviary/subsystems/aerodynamics/gasp_based/test/test_table_based.py

@@ -1,16 +1,14 @@
 import unittest
-import os
 
 import numpy as np
 import openmdao
 import openmdao.api as om
-import pkg_resources
+from aviary.utils.functions import get_aviary_resource_path
 from openmdao.utils.assert_utils import assert_check_partials, assert_near_equal
 from packaging import version
 
 from aviary.subsystems.aerodynamics.gasp_based.table_based import (
     TabularCruiseAero, TabularLowSpeedAero)
-from aviary.variable_info.options import get_option_defaults
 from aviary.variable_info.variables import Aircraft, Dynamic
 
 
@@ -52,8 +50,8 @@ def test_climb(self):
                      "Older version of OpenMDAO does not properly skip Metamodel.")
     def test_cruise(self):
         prob = om.Problem()
-        fp = pkg_resources.resource_filename(
-            "aviary", f"subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_free.txt")
+        ref = 'subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_free.txt'
+        fp = get_aviary_resource_path(ref)
         prob.model = TabularCruiseAero(num_nodes=2, aero_data=fp)
         prob.setup(force_alloc_complex=True)
 
@@ -81,12 +79,12 @@ class TestLowSpeedAero(unittest.TestCase):
     # takeoff flap deflection (deg)
     flap_defl_to = 10
 
-    free_data = pkg_resources.resource_filename(
-        "aviary", f"subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_free.txt")
-    flaps_data = pkg_resources.resource_filename(
-        "aviary", f"subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_flaps.txt")
-    ground_data = pkg_resources.resource_filename(
-        "aviary", f"subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_ground.txt")
+    free_data = get_aviary_resource_path(
+        "subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_free.txt")
+    flaps_data = get_aviary_resource_path(
+        "subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_flaps.txt")
+    ground_data = get_aviary_resource_path(
+        "subsystems/aerodynamics/gasp_based/data/large_single_aisle_1_aero_ground.txt")
 
     @unittest.skipIf(version.parse(openmdao.__version__) < version.parse("3.26"),
                      "Older version of OpenMDAO does not properly skip Metamodel.")

aviary/subsystems/mass/flops_based/landing_gear.py

@@ -299,7 +299,7 @@ def setup_partials(self):
 
     def compute(self, inputs, outputs, discrete_inputs=None, discrete_outputs=None):
         options: AviaryValues = self.options['aviary_options']
-        # TODO temp using first engine, multi-engine not supported
+        # TODO temp using first engine, heterogeneous engines not supported
         num_eng = options.get_val(Aircraft.Engine.NUM_ENGINES)[0]
         num_wing_eng = options.get_val(Aircraft.Engine.NUM_WING_ENGINES)[0]
 
@@ -339,7 +339,7 @@ def compute(self, inputs, outputs, discrete_inputs=None, discrete_outputs=None):
 
     def compute_partials(self, inputs, partials, discrete_inputs=None):
         options: AviaryValues = self.options['aviary_options']
-        # TODO temp using first engine, multi-engine not supported
+        # TODO temp using first engine, heterogeneous engines not supported
         num_eng = options.get_val(Aircraft.Engine.NUM_ENGINES)[0]
         num_wing_eng = options.get_val(Aircraft.Engine.NUM_WING_ENGINES)[0]
 

aviary/subsystems/mass/flops_based/misc_engine.py

@@ -16,7 +16,7 @@ class EngineMiscMass(om.ExplicitComponent):
     Calculates total sum of all misc engine mass on the aircraft
 
     Currently using engine-level additional mass (scaled by num_engines)
-    and propulsion-level starter and controls mass, not multi-engine safe!
+    and propulsion-level starter and controls mass, not heterogeneous engine safe!
     '''
 
     def initialize(self):