Plotting Workflow

The Plotting workflow in mesalab is dedicated to generating various visualizations from your processed MESA simulation grid. Currently, this workflow does not include specific plotting functionalities for GYRE outputs.

Purpose

This workflow automatically generates:

  • Hertzsprung-Russell (HR) Diagrams: Visualize the individual stellar evolutionary tracks.

  • Blue Loop Crossing Heatmap: Display the distribution of instability strip crossings across your grid of models. This can be particularly powerful for analyzing large parameter spaces.

  • Blue Loop Visualizations: mesalab generates HR Diagrams (HRD), Color-Magnitude Diagrams (CMD) for Gaia bands, and log_g vs. log_Teff plots. These visualizations are color-coded by metallicity (Z) and highlight every model that undergoes a blue loop and crosses the Instability Strip from the red side.

Input

The primary input for the Plotting workflow is the summarized data generated by the MESA Run Analysis Workflow (summary_results.csv file).

  • Implicit Input Path: mesalab will automatically look for the necessary input data in the analysis_results directory (which is located inside your main output_dir of the previous mesalab run). If summary_results.csv is missing, mesalab makes the reanalysis of the grid.

Image Files

mesalab generates a variety of plots to visualize your MESA simulation results:

  • Blue Loop & Instability Strip Diagrams:

    • CMD_Gaia_all_blue_loop_data.png: A Color-Magnitude Diagram (CMD) using Gaia bands, displaying all model points that undergo a blue loop and cross the Instability Strip.

    • HRD_all_blue_loop_data.png: An HR Diagram (HRD) showcasing all model points identified as undergoing a blue loop.

    • LogL_LogG_all_blue_loop_data.png: A $\log L$ vs. $\log g$ diagram for blue looping models.

    • mesa_grid_blue_loop_heatmap.png: A heatmap visualizing the blue loop crossing count across your MESA grid (generated from the crossing_count_grid.csv data).

  • Full Grid HR Diagrams:

    • HR_diagram_[dir]_z[Z_VALUE].png: An HR Diagram for the entire MESA grid, generated for each metallicity (Z) present in your simulations. The [dir] portion of the filename indicates the plot represents data from your main MESA grid input directory. These plots are color-coded by metallicity (Z).

      • Example: HR_diagram_MESA_grid_z0.0090.png or HR_diagram_MESA_grid_z0.0100.png.

Configuration Parameters

Plotting execution and layout are controlled by two distinct sections within your YAML configuration file:

1. plotting_settings section (Workflow Toggles)

These parameters determine which plots are generated by the pipeline:

  • generate_heatmaps: (Boolean) Set to true to generate heatmaps from cross-grid data, typically visualizing properties like instability strip crossing counts. Default: false.

  • generate_hr_diagrams: (String) Controls the generation of HR diagrams. Options are:

    • “none”: No HR diagrams are generated.

    • “all”: Generates HR diagrams for all models in the grid.

    • “drop_zams”: Generates HR diagrams but excludes the Zero-Age Main Sequence (ZAMS) phase.

    • Default: “none”.

  • generate_blue_loop_plots_with_bc: (Boolean) If true, mesalab will generate blue loop-specific plots, including bolometric corrections if applicable. Default: false.

2. plot_config section (Visual Style Overrides)

This optional, global section allows you to customize the visual aesthetics (sizes, resolutions, and margins) of the figures directly from the YAML file. If specified, these values dynamically overwrite the internal defaults defined in mesalab/plotting/plot_config.py.

Supported fields include:

  • figure: Customize figsize (as an [width, height] array) and dpi.

  • axes: Set title_size and label_size.

  • scatter: Adjust dot_size and plot properties.

  • all_hrd: Custom grid plotting rules (e.g., max_cols).

For a complete list of parameters and their detailed descriptions, please refer to the Understanding the YAML Configuration section.

Controlling Plot Generation

The Plotting workflow in mesalab is integrated with the data processing performed by the MESA Run Analysis Workflow It processes the generated CSVs (summary_results.csv, crossing_count_grid.csv).

Note

In the current version, the Plotting workflow is not designed to run as a completely independent module that solely loads and plots pre-existing data via the CLI. Instead, it operates within the context of mesalab’s overall data processing workflow.

Example Configuration for Plot Generation and Style Customization:

Here’s an example of how you can configure your YAML file to enable specific plot types and customize their appearance simultaneously:

general_settings:
  input_dir: path/to/your/grid
  output_dir: ./mesalab_output
  force_reanalysis: false

blue_loop_analysis:
  analyze_blue_loop: true

plotting_settings:
  generate_heatmaps: true                # Enable heatmap generation
  generate_hr_diagrams: "all"            # Generate HR diagrams for all models
  generate_blue_loop_plots_with_bc: true # Generate blue loop plots with bolometric corrections

# Global Style Overrides passed to Matplotlib
plot_config:
  figure:
    figsize: [10, 6]
    dpi: 150
  axes:
    title_size: 16
  scatter:
    dot_size: 32
  colorbar:
    pad: 0.02
  all_hrd:
    figsize: [12, 4]
    max_cols: 7

gyre_workflow:
  run_gyre_workflow: false # Ensure GYRE workflow is disabled