Merge pull request #181 from OpenMDAO/v2.0.0_beta

V2.0.0 - MPhys Variable Naming Convention Classes

.github/workflows/unit_tests_and_docs.yml

@@ -41,17 +41,18 @@ jobs:
           echo $CONDA/bin >> $GITHUB_PATH;
           conda create -n OpenMDAO -c conda-forge python=3.9 mamba=1.5.1 -q -y;
           conda activate OpenMDAO;
-          pip install --upgrade pip
+          pip install --upgrade pip;
+          conda install numpy=1.26 scipy=1.13 -q -y;
           echo "=============================================================";
           echo "Install PETSc";
           echo "=============================================================";
-          mamba install -c conda-forge mpi4py=3.1.4 petsc4py=3.19 -q -y;
+          mamba install -c conda-forge mpi4py petsc4py=3.20 -q -y;
           echo "=============================================================";
           echo "Install OpenMDAO";
           echo "=============================================================";
           cd ..;
           pip install testflo;
-          pip install redbaron
+          pip install redbaron;
           git clone -q https://github.com/OpenMDAO/OpenMDAO;
           cd OpenMDAO;
           pip install .[all];
@@ -71,14 +72,14 @@ jobs:
           echo "=============================================================";
           cd tests/unit_tests
           testflo
-          echo "=============================================================";
-          echo "Running integration tests";
-          echo "=============================================================";
-          cd ../input_files
-          chmod +x get-input-files.sh
-          ./get-input-files.sh
-          cd ../integration_tests
-          testflo test_tacs_* test_meld_* test_oas_*
+          #echo "=============================================================";
+          #echo "Running integration tests";
+          #echo "=============================================================";
+          #cd ../input_files
+          #chmod +x get-input-files.sh
+          #./get-input-files.sh
+          #cd ../integration_tests
+          #testflo test_tacs_* test_meld_* test_oas_*
           echo "=============================================================";
           echo "Making docs";
           echo "=============================================================";

.gitignore

@@ -13,6 +13,7 @@
 sfe_restart.cfg
 flow.*
 *sql
+reports
 
 *cgns
 *ugrid

README.md

@@ -33,13 +33,13 @@ Open-source codes with builders and components compatible with mphys:
 
 | Code                                                       | Recommended Version* | Analysis Type                  | Notes                                                                   |
 |------------------------------------------------------------|----------------------|--------------------------------|-------------------------------------------------------------------------|
-| [ADflow](https://github.com/mdolab/adflow)                 | 2.8.0                | Aerodynamics                   | Structured multi-block and overset CFD.                                 |
-| [DAfoam](https://github.com/mdolab/dafoam)                 | 3.0.5                | Aerodynamics                   | Discrete Adjoint with OpenFOAM.                                         |
-| [OpenAeroStruct](https://github.com/mdolab/openaerostruct) | 2.6.0                | Aerodynamics                   | Vortex lattice aerodynamics written using OpenMDAO.                     |
-| [MELD](https://github.com/smdogroup/funtofem)              | 0.1.0                | Load and Displacement Transfer | Point cloud based transfer scheme. Part of the FUNtoFEM package.        |
-| [pyCycle](https://github.com/OpenMDAO/pyCycle)             | 4.2.1                | Propulsion                     | Thermodynamic cycle modeling library for engines.                       |
-| [pyGeo](https://github.com/mdolab/pygeo)                   | 1.12.3               | Geometric Parameterization     | Wrapper for ESP, OpenVSP, and a free-form deformation parameterization. |
-| [TACS](https://github.com/smdogroup/tacs)                  | 3.5.0                | Structures                     | Parallel Finite Element Analysis. |
+| [ADflow](https://github.com/mdolab/adflow)                 | 2.12.0               | Aerodynamics                   | Structured multi-block and overset CFD.                                 |
+| [DAfoam](https://github.com/mdolab/dafoam)                 | 3.2.0                | Aerodynamics                   | Discrete Adjoint with OpenFOAM.                                         |
+| [OpenAeroStruct](https://github.com/mdolab/openaerostruct) | 2.10.0               | Aerodynamics                   | Vortex lattice aerodynamics written using OpenMDAO.                     |
+| [FunToFEM](https://github.com/smdogroup/funtofem)          | 0.3.8                | Load and Displacement Transfer | Point cloud based transfer scheme. Part of the FUNtoFEM package.        |
+| [pyCycle](https://github.com/OpenMDAO/pyCycle)             | 4.3.0                | Propulsion                     | Thermodynamic cycle modeling library for engines.                       |
+| [pyGeo](https://github.com/mdolab/pygeo)                   | 1.15.0               | Geometric Parameterization     | Wrapper for ESP, OpenVSP, and a free-form deformation parameterization. |
+| [TACS](https://github.com/smdogroup/tacs)                  | 3.8.0                | Structures                     | Parallel Finite Element Analysis. |
 
 \* Recommended version to run mphys examples. Older versions may still be supported.
 

docs/_exts/embed_code.py

@@ -10,7 +10,7 @@
 
 from docutils.parsers.rst.directives import unchanged, images
 
-from mphys.doc_utils._utils.docutil import get_source_code, remove_docstrings, \
+from mphys.utils.docs._utils.docutil import get_source_code, remove_docstrings, \
     remove_initial_empty_lines, replace_asserts_with_prints, \
     strip_header, dedent, insert_output_start_stop_indicators, run_code, \
     get_skip_output_node, get_interleaved_io_nodes, get_output_block_node, \

docs/_exts/embed_compare.py

@@ -4,7 +4,7 @@
 
 import sphinx
 from docutils.parsers.rst import Directive
-from mphys.doc_utils._utils.docutil import get_source_code
+from mphys.utils.docs._utils.docutil import get_source_code
 
 
 class ContentContainerDirective(Directive):

docs/basics/builders.rst

@@ -1,10 +1,10 @@
 .. _builders:
 
-########
+========
 Builders
-########
+========
 
-In large multiphysics problems, creation and connection of the OpenMDAO can be complicated and time-consuming.
+In large multiphysics problems, creation and connection of the OpenMDAO model can be complicated and time-consuming.
 The design of MPhys is based on builder classes in order to reduce the burden on the user.
 Most of the assembly of the OpenMDAO model with MPhys is handled by a set of builder helper objects.
 
@@ -13,7 +13,8 @@ Not all builders need to implement all the methods.
 For example, a transfer scheme builder may not need a precoupling post coupling subsystem in the scenario.
 
 
-.. automodule:: mphys.builder
+.. automodule:: mphys
+  :noindex:
 
 .. autoclass:: Builder
   :members:

docs/basics/model_assembly.rst

@@ -0,0 +1,79 @@
+.. _model_assembly:
+
+=========================
+Assembling an MPhys Model
+=========================
+
+
+MPhys seeks to automate most of its model assembly process using the builder software design pattern.
+If using a :class:`MultipointParallel <mphys.MultipointParallel>` group,
+skip steps 3-4 as these are handled within the Scenario since each Scenario will have its own MPI communicator.
+
+
+
+.. code-block:: python
+
+	import openmdao.api as om
+	from mphys import Multipoint, MPhysVariables
+	from mphys.scenarios import  ScenarioAerodynamic
+
+	from my_aero_code import AeroBuilder
+
+	# Step 1
+	class MyMPhysModel(Multipoint):
+	    def setup(self):
+
+	        dvs = self.add_subsystem('dvs', om.IndepVarComp())
+	        dvs.add_output('aoa', val=0.0, units='deg')
+
+	        # Step 2
+	        aero_builder = AeroBuilder(mesh="naca0012.ugrid")
+
+	        # Step 3
+	        aero_builder.initialize(self.comm)
+
+	        # Step 4
+	        self.add_subsystem("aero_mesh", aero_builder.get_mesh_coordinate_subsystem())
+
+	        # Step 5
+	        scenario = ScenarioAerodynamic(aero_builder=aero_builder)
+
+	        # Step 6
+	        self.mphys_add_scenario("cruise", scenario)
+
+	        # Step 7
+	        self.connect("dvs.aoa", "cruise.aoa")
+	        self.connect(MPhysVariables.Aerodynamics.Mesh.COORDINATES,
+	                     MPhysVariables.Aerodynamics.Surface.COORDINATES)
+
+1. Define an :class:`Multipoint <mphys.Multipoint>` group.
+2. In the ``setup()`` method of the Multipoint group, instantiate
+   the :ref:`Builder <builders>` associated with the disciplinary solvers you intend to use.
+3. Initialize the disciplinary Builders with the MPI communicator of the Multipoint group.
+   This should be done in the ``setup()`` method of the Multipoint group after the builder is instantiated.
+   For example, ``aero_builder.initialize(self.comm)``
+4. If applicable to the discipline, add a subsystem for the initial mesh coordinates from the builder's :func:`get_mesh_coordinate_subsystem <mphys.Builder.get_mesh_coordinate_subsystem>` function.
+   This subsystem allows the disciplinary solver to dictate the parallel decomposition of its mesh.
+   Any geometry manipulation subsystems, data transfer scheme subsystems, etc. will then be connected to the mesh subsystem's mesh coordinate output.
+5. Create an MPhys scenario from the :ref:`scenario_library`.
+6. Use :func:`mphys_add_scenario <mphys.Multipoint.mphys_add_scenario>` to add the scenario to the Multipoint group.
+   Add customized coupled nonlinear and linear solvers to the scenario in this function call.
+7. Connect inputs to the scenarios. Since MPhys uses :ref:`tagged_promotion`,
+   these inputs will have been promoted to ``{scenario_name}.{variable_name}``.
+   Typically the inputs that need to be connected are the design variables of the disciplinary solvers
+   and mesh coordinates (if applicable to the discipline).
+   These mesh coordinates may come from the initial mesh, or be altered by a geometry tool.
+8. Repeat steps 5-7 until your Multipoint group is fully defined.
+
+.. figure:: mphys_model_assembly.png
+	:scale: 50 %
+	:alt: Flow chart of MPhys model assembly
+
+
+--------
+Examples
+--------
+
+
+- The `supersonic panel example <https://github.com/OpenMDAO/mphys/blob/main/examples/aerostructural/supersonic_panel/run.py>`_ provides an example of this model assembly and usage in a self-contained problem (no external disciplinary solvers).
+- The `oas_tacs_wing example <https://github.com/OpenMDAO/mphys/blob/main/examples/aerostructural/oas_tacs_wing/run_oas_tacs_wing.py>`_ is another relatively simple example case that uses open-source disciplinary solvers.

docs/basics/model_hierarchy.rst

@@ -1,86 +1,99 @@
-***************
+===============
 Model Hierarchy
-***************
+===============
 
-MPhys uses a pattern to build multiphysics optimization problems.
-Each level of the pattern is a different type of group that MPhys provides.
+MPhys uses a hierarchical set of OpenMDAO groups to build multiphysics models.
+Each level of the hierarchy is a different OpenMDAO group that MPhys provides.
 
 The highest level of the model is the multipoint group.
-The multipoint group consist of scenarios which represent different conditions and/or types of multiphysics analyses to performed.
+The multipoint group consists of scenarios which represent different conditions and/or types of multiphysics analyses to be performed.
 Within the scenario is the coupling group which represents the primary multiphysics problem for the scenario.
 
+See :ref:`model_assembly` for guidance on how to create this model hierarchy for a particular problem.
 
 :ref:`builders` are used to help populate these levels of the model hierarchy with subsystems from the solvers.
 :ref:`tagged_promotion` is used to promote specific variables to the level of scenario.
 
 .. _coupling_groups:
 
-===============
+---------------
 Coupling Groups
-===============
+---------------
 
 The CouplingGroup is the primary physics coupling being solved.
-That is it contains physics modules, such as an aerodynamic or structural solver,
-and potentially modules that transfer or interpolate between the physics modules, such as a load or displacement transfer schemes.
+That is, it contains physics modules, such as an aerodynamic or structural solver,
+and potentially modules that transfer or interpolate between the physics modules, such as a load or displacement transfer scheme.
 
 Each type of scenario typically has an associated coupling group that it will add automatically given the proper builders.
 Within the Scenario group, the coupling group will have the name 'coupling'.
 The scenario-specific coupling group will have a default nonlinear and linear solvers,
-but these can be overwritten with the optional arguments to :func:`~mphys.multipoint.Multipoint.mphys_add_scenario`.
+but these can be overwritten with the optional arguments to :func:`~mphys.Multipoint.mphys_add_scenario`.
 
 .. _scenario_groups:
 
-===============
+---------------
 Scenario Groups
-===============
+---------------
 The scenario level is an OpenMDAO group that represents a specific condition in a multipoint optimization.
 For example, a scenario could be a cruise flight condition that requires a coupling group to determine the lift and drag.
 The scenario group contains a coupling group and any scenario-specific computation that needs to occur before or after the associated coupled problem is solved.
-For example, a sonic boom propagator requires the flow solution as an input but this one-way coupling does not require it to be in the coupling group; therefore, it should be put in the scenario group to be solved after the coupling group converges.
+The subsystems before the coupled problem are referred to as 'pre_coupling' subsystems.
+The subsystems after the coupled problem are referred to as 'post_coupling' subsystems.
+An example post_coupling subsystem would be a sonic boom propagation analysis after an aeropropulsive coupling analysis.
+
+
+.. figure:: scenario_example.png
+	:scale: 50 %
+	:alt: Example Scenario
 
 MPhys provides a library of these Scenario groups designed for specific type problems.
 See :ref:`scenario_library` for details about specific standardized scenarios.
-If a particular multiphysics problem is not covered by the MPhys library, new scenarios and coupling groups can be created by subclassing the :class:`~mphys.mphys_group.MphysGroup`.
+If a particular multiphysics problem is not covered by the MPhys library, new scenarios and coupling groups can be created by subclassing the :class:`~mphys.MPhysGroup`.
 
 
-=================
+-----------------
 Multipoint Groups
-=================
+-----------------
 
 There are two versions of the multipoint group:
 
 1. ``Multipoint`` is derived from the standard OpenMDAO ``Group``
 2. ``MultipointParallel`` is derived for the OpenMDAO ``ParallelGroup``.
 
-For both versions have a function,  :func:`~mphys.multipoint.Multipoint.mphys_add_scenario`, is used to populate
+For both versions, a function :func:`~mphys.Multipoint.mphys_add_scenario` is used to populate
 the lower levels of the model hierarchy.
 
-----------
+.. figure:: multipoint_example.png
+	:scale: 50 %
+	:alt: Example Multipoint Group
+
+
+^^^^^^^^^^
 Multipoint
-----------
+^^^^^^^^^^
 The ``Multipoint`` group will sequentially evaluate the scenario groups.
 The ``Multipoint`` group can be the top group of the OpenMDAO model or a subsystem.
 
 In the ``setup`` method of the Multipoint group, the following steps must be done:
 
 1. Instantiate the builders
-2. Call :func:`~mphys.builder.Builder.initialize` for each builder with the Multipoint's comm (``self.comm``)
+2. Call :func:`~mphys.core.builder.Builder.initialize` for each builder with the Multipoint's comm (``self.comm``)
 3. Add the mesh components and/or other mesh coordinate source like geometry.
 4. Add the scenarios
 5. Connect the mesh coordinates to the scenarios
 
 Additionally, the Multipoint group can hold the design variables or other inputs and subsystems to be evaluated after the scenarios.
 These extra subsystem can then be connected to the scenarios by the user.
 
-.. automodule:: mphys.multipoint
+.. automodule:: mphys
 
 .. autoclass:: Multipoint
     :members:
     :exclude-members: configure
 
-------------------
+^^^^^^^^^^^^^^^^^^
 MultipointParallel
-------------------
+^^^^^^^^^^^^^^^^^^
 If given a number of MPI ranks greater than or equal to the number of scenarios, the ``MultipointParallel`` group will simultaneously evaluate the scenario groups.
 Unlike the sequential Multipoint group, the MPI communicators are different for each scenario in MultipointParallel, so the scenarios will call the builder's initialize method.