paroto.viz.mermaid#

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#

LEVEL_COLORS

PARAM_SYMBOLS

MERMAID_SHAPES

Functions#

get_param_label(node_name)

Get parameter symbol or simple label.

get_level_color(level, nodes_at_level, max_level)

Get Mermaid color for a hierarchy level.

get_mermaid_node_def(node_id, label, node_type)

Get Mermaid node definition string.

generate_simple_graph(graph, output_path)

Generate a simple Mermaid flowchart showing system connectivity.

generate_hierarchical_graph(graph, output_path[, ...])

Generate hierarchical Mermaid diagram showing parameter dependencies.

generate_simplified_hierarchical_graph(graph, output_path)

Generate simplified hierarchical diagram with subsystem-level abstraction.

Module Contents#

paroto.viz.mermaid.get_param_label(node_name)#

Get parameter symbol or simple label.

Parameters:

node_name (str) – Full node name

Returns:

Parameter symbol if in mapping, otherwise simplified label

Return type:

str

paroto.viz.mermaid.LEVEL_COLORS#
paroto.viz.mermaid.PARAM_SYMBOLS#
paroto.viz.mermaid.MERMAID_SHAPES#
paroto.viz.mermaid.get_level_color(level, nodes_at_level, max_level)#

Get Mermaid color for a hierarchy level.

Parameters:

  • level (int) – Hierarchy level number

  • nodes_at_level (list of dict) – Node dictionaries at this level (to check for constraints)

  • max_level (int) – Maximum level for gradient calculation

Returns:

Hex color code

Return type:

str

Notes

  • Level 0: Green (primary parameters)

  • Levels with constraints: Pink

  • Other levels: Yellow gradient

paroto.viz.mermaid.get_mermaid_node_def(node_id, label, node_type)#

Get Mermaid node definition string.

Parameters:

  • node_id (str) – Node identifier (e.g., “N1”)

  • label (str) – Display label for node

  • node_type (str) – Node type (‘primary_param’, ‘constraint’, etc.)

Returns:

Mermaid syntax for node (e.g., ‘N1[(“label”)]’)

Return type:

str

paroto.viz.mermaid.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.

Parameters:

  • graph (ProblemGraph) – Problem graph from extract_hierarchy()

  • output_path (str) – File path where the Mermaid diagram will be saved

Returns:

The output file path where the diagram was saved

Return type:

str

paroto.viz.mermaid.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.

Parameters:

  • graph (ProblemGraph) – Problem graph from extract_hierarchy()

  • output_path (str) – File path where the Mermaid diagram will be saved

  • max_level (int, optional) – Maximum hierarchy level to display. If None, shows all levels

  • orientation (str, optional) – Graph orientation: “LR” (left-right) or “TD” (top-down). Default: “LR”

Returns:

The output file path where the diagram was saved

Return type:

str

paroto.viz.mermaid.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.

Parameters:

  • graph (ProblemGraph) – Problem graph from extract_hierarchy()

  • output_path (str) – File path where the Mermaid diagram will be saved

  • orientation (str, optional) – Graph orientation: “LR” (left-right) or “TD” (top-down). Default: “LR”

Returns:

The output file path where the diagram was saved

Return type:

str