paroto.viz ========== .. py:module:: paroto.viz .. autoapi-nested-parse:: Visualization module for Paroto. This module provides tools for visualizing optimization problems, parameter hierarchies, and model connectivity in multiple formats. Main Functions -------------- extract_hierarchy : Extract parameter hierarchy from OpenMDAO Problem generate_hierarchical_graph : Generate hierarchical Mermaid diagram generate_simple_graph : Generate simple all-to-all Mermaid diagram to_networkx : Convert hierarchy to NetworkX DiGraph model_graph_to_cytoscape : Convert graph to Cytoscape format for Dash Submodules ---------- .. toctree:: :maxdepth: 1 /_api/paroto/viz/cytoscape/index /_api/paroto/viz/hierarchy/index /_api/paroto/viz/mermaid/index /_api/paroto/viz/networkx_export/index /_api/paroto/viz/problem_graph/index /_api/paroto/viz/utils/index Classes ------- .. autoapisummary:: paroto.viz.ProblemGraph Functions --------- .. autoapisummary:: paroto.viz.get_cytoscape_layout paroto.viz.get_cytoscape_stylesheet paroto.viz.model_graph_to_cytoscape paroto.viz.extract_hierarchy paroto.viz.generate_hierarchical_graph paroto.viz.generate_simple_graph paroto.viz.analyze_hierarchy paroto.viz.export_graphml paroto.viz.export_json paroto.viz.plot_hierarchy paroto.viz.to_networkx Package Contents ---------------- .. py:function:: get_cytoscape_layout() Get default Cytoscape layout configuration. :returns: Cytoscape layout configuration :rtype: :py:class:`dict` .. py:function:: get_cytoscape_stylesheet() Get default Cytoscape stylesheet for model graphs. :returns: Cytoscape stylesheet :rtype: :py:class:`list` .. py:function:: model_graph_to_cytoscape(parameters, models, constraints, connections=None) Convert model graph to Cytoscape elements format. :param parameters: List of parameter names :type parameters: :py:class:`list` of :py:class:`str` :param models: List of model names :type models: :py:class:`list` of :py:class:`str` :param constraints: List of constraint names :type constraints: :py:class:`list` of :py:class:`str` :param connections: List of (source, target) tuples for explicit connections. If None, auto-generates all-to-all connections :type connections: :py:class:`list` of :py:class:`tuple`, *optional* :returns: Cytoscape elements list with nodes and edges :rtype: :py:class:`list` .. 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:: generate_hierarchical_graph(graph, output_path, max_level=None, orientation='LR') Generate hierarchical Mermaid diagram showing parameter dependencies. Creates a layered graph where nodes are organized by hierarchy level, showing actual connections between parameters, models, and constraints. :param graph: Problem graph from extract_hierarchy() :type graph: :py:class:`ProblemGraph` :param output_path: File path where the Mermaid diagram will be saved :type output_path: :py:class:`str` :param max_level: Maximum hierarchy level to display. If None, shows all levels :type max_level: :py:class:`int`, *optional* :param orientation: Graph orientation: "LR" (left-right) or "TD" (top-down). Default: "LR" :type orientation: :py:class:`str`, *optional* :returns: The output file path where the diagram was saved :rtype: :py:class:`str` .. py:function:: generate_simple_graph(graph, output_path) Generate a simple Mermaid flowchart showing system connectivity. Creates a graph with three layers: parameters (inputs), models (processing), and constraints (outputs/checks). Automatically extracts nodes from the ProblemGraph. :param graph: Problem graph from extract_hierarchy() :type graph: :py:class:`ProblemGraph` :param output_path: File path where the Mermaid diagram will be saved :type output_path: :py:class:`str` :returns: The output file path where the diagram was saved :rtype: :py:class:`str` .. py:function:: analyze_hierarchy(graph) Analyze hierarchy structure and return statistics. :param graph: Graph to analyze :type graph: :py:class:`networkx.DiGraph` :returns: Statistics including: - 'num_nodes': total number of nodes - 'num_edges': total number of edges - 'num_levels': number of hierarchy levels - 'nodes_by_level': dict mapping level -> count - 'nodes_by_type': dict mapping type -> count - 'max_in_degree': maximum number of inputs to a node - 'max_out_degree': maximum number of outputs from a node :rtype: :py:class:`dict` .. py:function:: export_graphml(graph, output_path) Export NetworkX graph to GraphML format. GraphML is supported by tools like yEd, Gephi, and Cytoscape. :param graph: Graph to export :type graph: :py:class:`networkx.DiGraph` :param output_path: Output file path (.graphml extension recommended) :type output_path: :py:class:`str` :returns: The output file path :rtype: :py:class:`str` .. py:function:: export_json(graph, output_path) Export NetworkX graph to JSON format. Exports in node-link format compatible with D3.js and other JavaScript libraries. :param graph: Graph to export :type graph: :py:class:`networkx.DiGraph` :param output_path: Output file path (.json extension recommended) :type output_path: :py:class:`str` :returns: The output file path :rtype: :py:class:`str` .. py:function:: plot_hierarchy(graph, output_path, figsize=(12, 8), dpi=150) Generate static image of hierarchy using matplotlib. :param graph: Graph to plot :type graph: :py:class:`networkx.DiGraph` :param output_path: Output file path (extension determines format: .png, .pdf, .svg) :type output_path: :py:class:`str` :param figsize: Figure size in inches (width, height). Default: (12, 8) :type figsize: :py:class:`tuple`, *optional* :param dpi: Resolution for raster outputs. Default: 150 :type dpi: :py:class:`int`, *optional* :returns: The output file path :rtype: :py:class:`str` .. py:function:: to_networkx(graph) Convert ProblemGraph to NetworkX DiGraph. :param graph: Problem graph from extract_hierarchy() :type graph: :py:class:`ProblemGraph` :returns: Directed graph with node attributes: - 'level': hierarchy level (int) - 'type': node type (str) - 'units': variable units (str) - 'value': variable value - 'label': simplified display name :rtype: :py:class:`networkx.DiGraph` .. py:class:: ProblemGraph(prob, primary_params = None, constraint_markers = None) Unified graph abstraction for OpenMDAO Problem visualization. This class wraps an OpenMDAO Problem and provides a clean, unified interface for extracting graph structure that can be consumed by any visualization backend. :param prob: OpenMDAO problem (must have setup() called) :type prob: :py:class:`openmdao.api.Problem` :param primary_params: List of primary parameter names (design variables). Can be partial names that will be matched :type primary_params: :py:class:`list` of :py:class:`str`, *optional* :param constraint_markers: Keywords to identify constraint variables (e.g., ['margin', 'constraint']) :type constraint_markers: :py:class:`list` of :py:class:`str`, *optional* .. attribute:: nodes Mapping of node_id -> node attributes (type, level, units, value, label, subsystem) :type: :py:class:`dict` .. attribute:: edges List of (source, target) connections :type: :py:class:`list` of :py:class:`tuple` .. attribute:: primary_params Full names of primary parameters :type: :py:class:`list` .. py:attribute:: prob .. py:attribute:: model .. py:attribute:: nodes :type: Dict[str, Dict[str, Any]] .. py:attribute:: edges :type: List[Tuple[str, str]] :value: [] .. py:attribute:: primary_params :type: List[str] :value: [] .. py:method:: get_nodes_by_level(max_level = None) Get nodes organized by hierarchy level. :param max_level: Maximum level to include. If None, includes all levels :type max_level: :py:class:`int`, *optional* :returns: Mapping of level -> list of node_ids :rtype: :py:class:`dict` .. py:method:: get_nodes_by_subsystem() Get nodes organized by subsystem. :returns: Mapping of subsystem_name -> list of node_ids :rtype: :py:class:`dict` .. py:method:: get_nodes_by_type() Get nodes organized by type. :returns: Mapping of node_type -> list of node_ids :rtype: :py:class:`dict` .. py:method:: filter_by_level(max_level) Get filtered view with nodes up to max_level. :param max_level: Maximum hierarchy level to include :type max_level: :py:class:`int` :returns: (filtered_nodes, filtered_edges) dictionaries :rtype: :py:class:`tuple` .. py:method:: get_statistics() Get graph statistics. :returns: Statistics including node counts, edge counts, level distribution :rtype: :py:class:`dict`