paroto.viz.hierarchy
====================

.. py:module:: paroto.viz.hierarchy

.. autoapi-nested-parse::

   Hierarchy extraction from OpenMDAO problems.

   This module extracts parameter hierarchy by analyzing the data flow through
   an OpenMDAO Problem. It assigns hierarchy levels automatically based on dependencies.



Functions
---------

.. autoapisummary::

   paroto.viz.hierarchy.extract_hierarchy
   paroto.viz.hierarchy.simplify_hierarchy


Module Contents
---------------

.. py:function:: extract_hierarchy(prob, primary_params, constraint_names=None)

   Extract parameter hierarchy from an OpenMDAO Problem.

   Analyzes the connection structure of an OpenMDAO problem to determine
   which parameters are primary (design variables), secondary (outputs of models
   consuming primary parameters), and so on.

   :param prob: Configured OpenMDAO problem (should call setup() called)
   :type prob: :py:class:`openmdao.api.Problem`
   :param primary_params: List of primary parameter names (design variables)
                          These can be partial names that will be matched
   :type primary_params: :py:class:`list` of :py:class:`str`
   :param constraint_names: List of constraint output names. If None, attempts to detect constraints
   :type constraint_names: :py:class:`list` of :py:class:`str`, *optional*

   :returns: Graph abstraction with nodes, edges, and hierarchy levels
   :rtype: :py:class:`ProblemGraph`

   .. rubric:: Notes

   Hierarchy levels:
   - Level 0: Primary parameters (user-specified design variables)
   - Level N: Parameters/outputs that depend only on levels 0 through N-1
   - Constraints are assigned their own level based on dependencies


.. py:function:: simplify_hierarchy(graph, include_constraints=True, max_level=None)

   Simplify hierarchy by removing intermediate variables and grouping by subsystems.

   :param graph: Hierarchy graph from extract_hierarchy()
   :type graph: :py:class:`ProblemGraph`
   :param include_constraints: Whether to include constraint nodes (default: True)
   :type include_constraints: :py:class:`bool`, *optional*
   :param max_level: Maximum hierarchy level to include. If None, includes all levels
   :type max_level: :py:class:`int`, *optional*

   :returns: Simplified hierarchy with:
             - 'parameters': list of primary parameter names
             - 'models': list of model/subsystem names
             - 'constraints': list of constraint names
             - 'connections': list of (source, target) tuples
   :rtype: :py:class:`dict`