custom_colors#

This test suite case demonstrates the functionality of the MESA colors module, a framework introduced in MESA r25.10.1 for calculating synthetic photometry and bolometric quantities during stellar evolution.

What is MESA colors?#

MESA colors is a post-processing and runtime module that allows users to generate “observer-ready” data directly from stellar evolution models. Instead of limiting output to theoretical quantities like Luminosity (\(L\)) and Surface Temperature (\(T_{\rm eff}\)), the colors module computes:

Bolometric Magnitude (\(M_{\rm bol}\))
Bolometric Flux (\(F_{\rm bol}\))
Synthetic Magnitudes in specific photometric filters (e.g., Johnson V, Gaia G, 2MASS J).

This bridges the gap between theoretical evolutionary tracks and observational color-magnitude diagrams (CMDs).

How does the MESA colors module work?#

The module operates by coupling the stellar structure model with pre-computed grids of stellar atmospheres.

Interpolation: At each timestep, the module takes the star’s current surface parameters—Effective Temperature (\(T_{\rm eff}\)), Surface Gravity (\(\log g\)), and Metallicity ([M/H])—and queries a user-specified library of stellar atmospheres (defined in stellar_atm). It interpolates within this grid to construct a specific Spectral Energy Distribution (SED) for the stars current features.
Convolution: This specific SED is then convolved with filter transmission curves (defined in instrument) to calculate the flux passing through each filter.
Integration: The fluxes are converted into magnitudes using the user-selected magnitude system (AB, ST, or Vega).

The Test Suite#

This test suite evolves a complete stellar model (from the pre–main sequence onward) while the colors module runs continuously in the background. At every timestep, MESA computes synthetic photometry by interpolating a stellar atmosphere grid and convolving the resulting SED with the filters you specify in the inlist.

During the run, the module automatically appends new photometric columns to the history.data file. You do not need to list these in history_columns.list—the module detects the available filters by inspecting the directory defined in the instrument parameter.

What the Test Suite Produces#

The standard output of the test suite includes:

Mag_bol The bolometric magnitude computed from the star’s instantaneous bolometric flux.
Flux_bol The bolometric flux (cgs units) after distance dilution is applied. The default distance is 10 pc, producing absolute magnitudes unless changed.
[Filter_Name] A synthetic magnitude column for every filter in the instrument directory.

For example, if your filter directory contains:

filters/Generic/Johnson/
    B.dat
    V.dat
    R.dat
    Johnson

then your history file will include:

B, V, R

as new magnitude columns generated automatically at runtime.

What the Test Suite Actually Does#

The provided inlist_colors configures a full evolution run with the colors module activated:

Starts from a pre–main-sequence model
Evolves the model through multiple phases while computing synthetic photometry
Uses the Johnson filter set
Uses the Kurucz2003all atmosphere grid
Outputs bolometric and filter-specific magnitudes to history.data every step

Because the test suite’s inlist also defines a set of PGSTAR panels, you automatically get real-time plots of:

HR diagram (log L vs. log Teff)
A light curve based on any synthetic magnitude (the test suite uses V)

Real-Time Visualization (Enabled by Default)#

The test suite’s pgstar block is configured so that, as the star evolves:

Panel 1: HR diagram (theoretical)
Panel 2: Light curve in the Johnson V band

These update automatically as the model runs.

Purpose of the Test Suite#

This test problem is designed to demonstrate:

That MESA can compute synthetic photometry at runtime, without external tools.
How atmosphere grids and filters affect magnitude evolution.
How to configure your own inlists for scientific use.
How the colors module integrates with PGSTAR visualization.
How synthetic magnitudes appear in history.data and how to use them for CMDs, light curves, and population modeling.

Inlist Options & Parameters#

The colors module is controlled via the &colors namelist. Below is a detailed guide to the key parameters.

instrument#

Default: ‘/colors/data/filters/Generic/Johnson’

This points to the directory containing the filter transmission curves you wish to use. The path must be structured as facility/instrument.

The directory must contain a file named after the instrument (e.g., Johnson) which acts as an index.
The module will read every .dat file listed in that directory and create a corresponding history column for it.

Example:

instrument = '/colors/data/filters/GAIA/GAIA'

stellar_atm#

Default: ‘/colors/data/stellar_models/Kurucz2003all/’

Specifies the path to the directory containing the grid of stellar atmosphere models. This directory must contain:

lookup_table.csv: A map linking filenames to physical parameters (\(T_{\rm eff}\), \(\log g\), [M/H]).
SED files: The actual spectra (text or binary format).
flux_cube.bin: (Optional but recommended) A binary cube for rapid interpolation.

The module queries this grid using the star’s current parameters. If the star evolves outside the grid boundaries, the module may clamp to the nearest edge or extrapolate, depending on internal settings.

Example:

stellar_atm = '/colors/data/stellar_models/sg-SPHINX/'

distance#

Default: 3.0857d19 (10 parsecs in cm)

The distance to the star in centimeters.

This value is used to convert surface flux to observed flux.
Default Behavior: It defaults to 10 parsecs (\(3.0857 \times 10^{19}\) cm), resulting in Absolute Magnitudes.
Custom Usage: You can set this to a specific source distance (e.g., distance to Betelgeuse) to calculate Apparent Magnitudes.

Example:

distance = 5.1839d20

make_csv#

Default: .false.

If set to .true., the module exports the full calculated SED at every profile interval.

Destination: Files are saved to the directory defined by colors_results_directory.
Format: CSV files containing Wavelength vs. Flux.
Use Case: useful for debugging or plotting the full spectrum of the star at a specific age.

Example:

make_csv = .true.

colors_results_directory#

Default: ‘SED’

The folder where csv files (if make_csv = .true.) and other debug outputs are saved.

Example:

colors_results_directory = 'sed'

mag_system#

Default: ‘Vega’

Defines the zero-point system for magnitude calculations. Options are:

'AB': Based on a flat spectral flux density of 3631 Jy.
'ST': Based on a flat spectral flux density per unit wavelength.
'Vega': Calibrated such that the star Vega has magnitude 0 in all bands.

Example:

mag_system = 'AB'

vega_sed#

Default: ‘/colors/data/stellar_models/vega_flam.csv’

Required only if mag_system = 'Vega'. This points to the reference SED file for Vega. The default path points to a file provided with the MESA data distribution.

Example:

vega_sed = '/another/file/for/vega_SED.csv'

Data Preparation (SED_Tools)#

The colors module requires pre-processed stellar atmospheres and filter profiles organized in a very specific directory structure. To automate this entire workflow, we provide the dedicated repository:

Repository: SED_Tools

SED_Tools downloads, validates, and converts raw spectral atmosphere grids and filter transmission curves from the following public archives:

These sources provide heterogeneous formats and file organizations. SED_Tools standardizes them into the exact structure required by MESA:

lookup_table.csv
Raw SED files (text or/and HDF5)
flux_cube.bin (binary cube for fast interpolation)
Filter index files and *.dat transmission curves

SED_Tools produces:

data/
├── stellar_models/<ModelName>/
│   ├── flux_cube.bin
│   ├── lookup_table.csv
│   ├── *.txt / *.h5
└── filters/<Facility>/<Instrument>/
    ├── *.dat
    └── <Instrument>

These directories can be copied or symlinked directly into your MESA installation.

A browsable online mirror of the processed SED_Tools output is also available:

SED Tools Web Interface (mirror)

This server provides a live view of:

All downloaded stellar atmosphere grids
All available filter facilities and instruments
File counts, disk usage, and metadata
Direct links to the directory structure used by MESA

Defaults Reference#

Below are the default values for the colors module parameters as defined in colors.defaults. These are used if you do not override them in your inlist.

use_colors = .false.
instrument = '/colors/data/filters/Generic/Johnson'
vega_sed = '/colors/data/stellar_models/vega_flam.csv'
stellar_atm = '/colors/data/stellar_models/Kurucz2003all/'
distance = 3.0857d19  ! 10 parsecs in cm (Absolute Magnitude)
make_csv = .false.
colors_results_directory = 'SED'
mag_system = 'Vega'
vega_sed = '/colors/data/stellar_models/vega_flam.csv'

Visual Summary of Data Flow#

+----------------+
|   MESA Model   |
| (Teff, logg, Z)|
+----------------+
        |
        v
+-------------------------------------------------------------------------+
|                        MESA COLORS MODULE                               |
| 1. Query Stellar Atmosphere Grid with input model                       |
| 2. Interpolate grid to construct specific SED                           |
| 3. Convolve SED with filters to generate band flux                      |
| 2. Apply distance flux dilution to generate bolometric flux -> Flux_bol |
| 4. Apply zero point (Vega/AB/ST) to  generate magnitudes                |
|                                    (Both bolometric and per filter)     |
+-------------------------------------------------------------------------+
        |
        v
+----------------------+
|    history.data      |
| age, Teff, ...       |
| Mag_bol, Flux_bol    |
| V, B, I, ...         |
+----------------------+

Python Helper Scripts#

A collection of Python scripts is provided in the python_helpers/ directory to assist with real-time monitoring, visualization, and analysis of the colors module output.

Dependencies:

matplotlib
numpy
mesa_reader (ensure this is installed/accessible)
ffmpeg (optional, for movie generation)

HISTORY_check.py#

Usage: python python_helpers/HISTORY_check.py

A real-time dashboard that monitors your history.data file as MESA runs. It automatically refreshes when new data is written.

Plots:

HR Diagram (Color vs. Magnitude): Points colored by evolutionary phase.
Theoretical HR (Teff vs. Log L): Standard theoretical track.
Color Evolution: Color index vs. Age.
Light Curves: Absolute magnitude vs. Age for all filters.

Requirements: Ensure phase_of_evolution is present in your history_columns.list for phase-based coloring.

SED_check.py#

Usage: python python_helpers/SED_check.py

Monitors the colors_results_directory (default: SED/) for new CSV output.

Features:

Plots the full high-resolution stellar spectrum (black line).
Plots the filter-convolved fluxes (colored lines corresponding to filters).
Displays stellar parameters (Mass, Z, Distance) parsed from your inlist.
Updates automatically if make_csv = .true. in your inlist and MESA overwrites the files.

interactive_cmd_3d.py#

Usage: python python_helpers/interactive_cmd_3d.py

Generates an interactive 3D Color-Magnitude Diagram.

X-axis: Color Index (e.g., B-V or Gbp-Grp).
Y-axis: Magnitude (e.g., V or G).
Z-axis: User-selectable column from the history file (e.g., Interp_rad, star_age, log_R). The script will prompt you to choose a column at runtime.

Movie Makers#

Scripts to generate MP4 animations of your run. Requires ffmpeg.

make_history_movie.py: Creates history.mp4, an animated version of the HISTORY_check.py dashboard showing the evolution over time.
make_CMD_InterpRad_movie.py: Creates cmd_interp_rad_rotation.mp4, a rotating 3D view of the Color-Magnitude Diagram with the Interpolation Radius on the Z-axis. Useful for visualizing grid coverage and interpolation quality.

custom_colors

Contents

custom_colors#

What is MESA colors?#

How does the MESA colors module work?#

The Test Suite#

What the Test Suite Produces#

What the Test Suite Actually Does#

Real-Time Visualization (Enabled by Default)#

Purpose of the Test Suite#

Inlist Options & Parameters#

instrument#

stellar_atm#

distance#

make_csv#

colors_results_directory#

mag_system#

vega_sed#

Data Preparation (SED_Tools)#

Defaults Reference#

Visual Summary of Data Flow#

Python Helper Scripts#

HISTORY_check.py#

SED_check.py#

interactive_cmd_3d.py#

Movie Makers#