paroto.viz.mermaid
==================

.. py:module:: paroto.viz.mermaid

.. autoapi-nested-parse::

   Mermaid diagram generators for optimization problem visualization.

   This module provides utilities to create Mermaid graph diagrams showing
   relationships between parameters, models, and constraints, with support for
   hierarchical parameter visualization.

   Diagram Conventions
   -------------------
   - Parameters (all levels): Green circles ((symbol)) - #90EE90
   - Models: Blue rectangles [name] - #87CEEB
   - Constraints: Pink diamonds {equation} - #FFB6C1
   - Subgraphs: Transparent background (fill:none, stroke:none)
   - Node labels: Simplified to core symbol/name only
   - Hierarchy: Shown by left-to-right position, not by color/shape variation



Attributes
----------

.. autoapisummary::

   paroto.viz.mermaid.LEVEL_COLORS
   paroto.viz.mermaid.PARAM_SYMBOLS
   paroto.viz.mermaid.MERMAID_SHAPES


Functions
---------

.. autoapisummary::

   paroto.viz.mermaid.get_param_label
   paroto.viz.mermaid.get_level_color
   paroto.viz.mermaid.get_mermaid_node_def
   paroto.viz.mermaid.generate_simple_graph
   paroto.viz.mermaid.generate_hierarchical_graph
   paroto.viz.mermaid.generate_simplified_hierarchical_graph


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

.. py:function:: get_param_label(node_name)

   Get parameter symbol or simple label.

   :param node_name: Full node name
   :type node_name: :py:class:`str`

   :returns: Parameter symbol if in mapping, otherwise simplified label
   :rtype: :py:class:`str`


.. py:data:: LEVEL_COLORS

.. py:data:: PARAM_SYMBOLS

.. py:data:: MERMAID_SHAPES

.. py:function:: get_level_color(level, nodes_at_level, max_level)

   Get Mermaid color for a hierarchy level.

   :param level: Hierarchy level number
   :type level: :py:class:`int`
   :param nodes_at_level: Node dictionaries at this level (to check for constraints)
   :type nodes_at_level: :py:class:`list` of :py:class:`dict`
   :param max_level: Maximum level for gradient calculation
   :type max_level: :py:class:`int`

   :returns: Hex color code
   :rtype: :py:class:`str`

   .. rubric:: Notes

   - Level 0: Green (primary parameters)
   - Levels with constraints: Pink
   - Other levels: Yellow gradient


.. py:function:: get_mermaid_node_def(node_id, label, node_type)

   Get Mermaid node definition string.

   :param node_id: Node identifier (e.g., "N1")
   :type node_id: :py:class:`str`
   :param label: Display label for node
   :type label: :py:class:`str`
   :param node_type: Node type ('primary_param', 'constraint', etc.)
   :type node_type: :py:class:`str`

   :returns: Mermaid syntax for node (e.g., 'N1[("label")]')
   :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:: 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_simplified_hierarchical_graph(graph, output_path, orientation='LR')

   Generate simplified hierarchical diagram with subsystem-level abstraction.

   Similar to generate_hierarchical_graph but groups variables by subsystem
   for a cleaner, higher-level view.

   :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 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`