custom colors overhaul

star/test_suite/custom_colors/.gitignore

@@ -0,0 +1,28 @@
+# Ignore the data directory
+data/
+
+# Ignore compiled files (e.g., executables, object files, binaries)
+*.o
+*.out
+*.so
+*.a
+*.dll
+*.exe
+*.pyc
+*.pyo
+*.swp
+*.jpg
+*.png
+*.log
+*.tmp
+*.txz
+*.zip
+*.yml
+*.mod
+
+# Ignore other files you don't want to track
+fort.20
+LOGS/
+star
+photos/
+data/

star/test_suite/custom_colors/README.rst

@@ -1,161 +1,110 @@
-.. _custom_colors:
+MESA Colors Project
+====================
 
-*************
-custom_colors
-*************
+**MESA Colors** is an extension for the Modules for Experiments in Stellar Astrophysics (MESA) toolkit, designed to enable synthetic photometry calculations and provide additional stellar evolution diagnostics. By incorporating bolometric corrections and synthetic magnitudes, it allows for detailed analysis of stellar properties under various filter systems and atmospheric models.
 
-This test suite example shows how to use user-defined color filter and extinction files.
+Features
+--------
 
-This test case has 1 part. Click to see a larger view of a plot.
+- **Synthetic Magnitudes**: Compute magnitudes using arbitrary filter profiles.
+- **Custom History Columns**: Append photometric diagnostics to the MESA history output.
+- **SED Interpolation**: Interpolate between stellar models to generate spectral energy distributions (SEDs).
+- **Flexible Filter System Integration**: Easily incorporate custom filter profiles for synthetic photometry.
 
-* Part 1 (``inlist_1.0``) builds a 1.0 Msun, Z=0.02 metallicity, pre-main sequence model and evolves until core hydrogen depletion (mass fraction h1 < 0.1). This example loads the default |LCB98| color filter ''lcb98cor.dat'', a custom color filter ``data/blackbody_bc_v.txt`` which in this case is blackbody V band filter, and a custom extinction color correction file ``data/fake_av_v.txt``. Example color-color, color-magnitude, magnitude-color and magnitude-magnitude plots:
+Installation
+------------
 
-.. image:: ../../../star/test_suite/custom_colors/docs/Color_magnitude1_000241.svg
-   :width: 100%
+1. Clone or download the MESA Colors module to your MESA project directory.
+2. Ensure your `mesasdk` path is properly set.
+3. Clean and compile the module:
 
-.. image:: ../../../star/test_suite/custom_colors/docs/Color_magnitude2_000241.svg
-   :width: 100%
+   .. code-block:: bash
+      ./clean; ./mk
 
-.. image:: ../../../star/test_suite/custom_colors/docs/Color_magnitude3_000241.svg
-   :width: 100%
+4. The script will download a 35MB file containing JWST and Gaia filter transmission curves, Kurucz 2003 stellar atmosphere models, and precomputed blackbody curves. These files will be stored in the `data/` directory.
 
+Directory Structure
+-------------------
 
-pgstar commands used for the first 7 plots:
+.. code-block:: text
 
-.. code-block:: console
+   mesa_colors/
+   ├── src/
+   │   ├── run_star_extras.f90       # Main Fortran module
+   │   ├── utilities.f90             # Helper functions for interpolation and file handling
+   ├── data/
+   │   ├── stellar_models/           # Stellar models (Kurucz, PHOENIX, etc.)
+   │   ├── filters/                  # Filter profiles (e.g., GAIA, HST, JWST, etc.)
+   │   ├── extracted_marker          # Marker file to confirm data extraction
+   ├── inlist                        # Example inlist
 
- &pgstar
+Inlist Options
+--------------
 
-   file_white_on_black_flag = .true. ! white_on_black flags -- true means white foreground color on black background
-   file_device = 'png'            ! png
+- **x_character_ctrl(1)** : filepath/to/stellar_atmosphere_models/   -- Stellar atmosphere model - http://svo2.cab.inta-csic.es/theory/newov2/
+- **x_character_ctrl(2)** : filepath/to/filters/                     -- Photometric filter system - http://svo2.cab.inta-csic.es/theory/fps/
+- **x_character_ctrl(3)** : filepath/to/vega.sed                     -- Vega SED for Vega photometric system
+- **x_character_ctrl(4)** : true/false                               -- Save CSV files of each constructed SED
 
-   !file_device = 'vcps'          ! postscript
+Configuring a Stellar Atmosphere Model
+--------------------------------------
 
-    pgstar_interval = 1
+The stellar atmosphere models are grids of precomputed stellar SEDs. These SEDs are computed as a function of multiple stellar features, many of which are generated by MESA.
+We use those features to find the N closest SEDs which match our parameters.
+Each folder within the stellar atmosphere models contains two main features:
+- A grid of stellar models
+- A lookup table holding the metadata of those models (e.g., the Teff and Logg used to generate the SED)
 
+If you wish to add more stellar atmosphere models, a good place to start would be SVO: http://svo2.cab.inta-csic.es/theory/newov2/.
 
- !# Color Magnitude Panels
-   ! Plots either color-color, color-magnitude, magnitude-color or magnitude-magnitude
+Your lookup table only requires some formatting rules:
+- The file name is the first column.
+- At least one of `Teff`, `Logg`, `Z` must be present.
 
-      !### Color_magnitude1
+Here is an example of the first few lines of the lookup table for the Kurucz2003 stellar atmospheres:
 
-         Color_magnitude1_win_flag = .true.
+.. code-block:: text
 
-         Color_magnitude1_win_width = 15
-         Color_magnitude1_win_aspect_ratio = 0.75 ! aspect_ratio = height/width
+   #file_name, alpha, lh, logg, meta, teff, vtur
+   Kurucz2003all_fid16202.txt,0,1.25,3.5,-0.5,10500,2
+   Kurucz2003all_fid16203.txt,0,1.25,4,-0.5,10500,2
+   Kurucz2003all_fid16204.txt,0,1.25,4.5,-0.5,10500,2
+   Kurucz2003all_fid16205.txt,0,1.25,5,-0.5,10500,2
+   Kurucz2003all_fid16206.txt,0,1.25,2,-0.5,10750,2
+   Kurucz2003all_fid16207.txt,0,1.25,2.5,-0.5,10750,2
+   Kurucz2003all_fid16208.txt,0,1.25,3,-0.5,10750,2
+   Kurucz2003all_fid16209.txt,0,1.25,3.5,-0.5,10750,2
 
-         Color_magnitude1_xleft = 0.15
-         Color_magnitude1_xright = 0.85
-         Color_magnitude1_ybot = 0.15
-         Color_magnitude1_ytop = 0.85
-         Color_magnitude1_txt_scale = 1.0
-         Color_magnitude1_title = 'Color_magnitude1'
+Configuring a photometric filter system
+--------------------------------------
 
-         ! setup default
-         Color_magnitude1_num_panels = 2
+The phtometric filters are configered similarly to the stellar atmosphere models. Indeed, they are sourced from the same website -- http://svo2.cab.inta-csic.es/theory/fps/
 
-         ! Plots xaxis1-xaxis2 leave xaxis2 blank if you only want to plot xaxis1.
-         Color_magnitude1_xaxis1_name = 'model_number'
-         Color_magnitude1_xaxis2_name = ''
+The filteres are ready by the code with the assumption that they are stored as:
 
+```data/filters/{TELESCOPE}/{INTRUMENT}/FILTER1.csv, FILTER2.csv...```
 
-         ! Plots yaxis1-yaxis2 leave yaxis2 blank if you only want to plot yaxis1.
-         Color_magnitude1_yaxis1_name(1) = 'bc_B'
-         Color_magnitude1_yaxis2_name(1) = 'bc_U'
-         Color_magnitude1_yaxis_reversed(1) = .false.
 
-         ! Plots `other_yaxis1-other_yaxis2` leave `other_yaxis2` blank if you only want to plot `other_yaxis1`.
-         Color_magnitude1_other_yaxis1_name(1) = 'abs_mag_V'
-         Color_magnitude1_other_yaxis2_name(1) = ''
-         Color_magnitude1_other_yaxis_reversed(1) = .true.
 
+Outputs
+-------
 
-         Color_magnitude1_yaxis1_name(2) = 'bc_B'
-         Color_magnitude1_other_yaxis1_name(2) = 'bc_U'
+- **History Columns**: Bolometric magnitudes and fluxes will be appended to the MESA history output.
+- **SED.csv**: If ``x_character_ctrl(4) = 'false'``, this will save CSV files of each constructed SED.
 
-         ! Enables calling a subroutine to add extra information to a plot
-         ! see `$MESA_DIR/star/other/pgstar_decorator.f90`
-         Color_magnitude1_use_decorator = .true.
+Dependencies
+------------
 
-         ! file output
-         Color_magnitude1_file_flag = .true.
-         Color_magnitude1_file_dir = 'png'
-         Color_magnitude1_file_prefix = 'Color_magnitude1_'
-         Color_magnitude1_file_interval = 5 ! output when `mod(model_number,Color_magnitude1_file_interval)==0`
-         Color_magnitude1_file_width = -1 ! (inches) negative means use same value as for window
-         Color_magnitude1_file_aspect_ratio = -1 ! negative means use same value as for window
+- **MESA** (Version 24.06.1 or higher recommended)
+- **Fortran Compiler** (e.g., `gfortran`, `ifort`)
+- **Python Helpers**:
+  - Python 3
+  - `numpy`
+  - `matplotlib`
+  - `mesa_reader`
 
+Acknowledgments
+---------------
 
-      !### Color_magnitude2
-
-         Color_magnitude2_win_flag = .true.
-
-         Color_magnitude2_win_width = 15
-         Color_magnitude2_win_aspect_ratio = 0.75 ! aspect_ratio = height/width
-
-         Color_magnitude2_xleft = 0.15
-         Color_magnitude2_xright = 0.85
-         Color_magnitude2_ybot = 0.15
-         Color_magnitude2_ytop = 0.85
-         Color_magnitude2_txt_scale = 1.0
-         Color_magnitude2_title = 'Color_magnitude2'
-
-         ! Plots xaxis1-xaxis2 leave xaxis2 blank if you only want to plot xaxis1.
-         Color_magnitude2_xaxis1_name = 'abs_mag_B'
-         Color_magnitude2_xaxis2_name = 'abs_mag_U'
-
-         ! Plots yaxis1-yaxis2 leave yaxis2 blank if you only want to plot yaxis1.
-         Color_magnitude2_yaxis1_name(1) = 'abs_mag_R'
-         Color_magnitude2_yaxis2_name(1) = 'abs_mag_J'
-
-         ! setup default
-         Color_magnitude2_num_panels = 1
-         ! file output
-         Color_magnitude2_file_flag = .true.
-         Color_magnitude2_file_dir = 'png'
-         Color_magnitude2_file_prefix = 'Color_magnitude2_'
-         Color_magnitude2_file_interval = 5 ! output when `mod(model_number,Color_magnitude2_file_interval)==0`
-         Color_magnitude2_file_width = -1 ! (inches) negative means use same value as for window
-         Color_magnitude2_file_aspect_ratio = -1 ! negative means use same value as for window
-
-
-      !### Color_magnitude3
-
-         Color_magnitude3_win_flag = .true.
-
-         Color_magnitude3_win_width = 15
-         Color_magnitude3_win_aspect_ratio = 0.75 ! aspect_ratio = height/width
-
-         Color_magnitude3_xleft = 0.15
-         Color_magnitude3_xright = 0.85
-         Color_magnitude3_ybot = 0.15
-         Color_magnitude3_ytop = 0.85
-         Color_magnitude3_txt_scale = 1.0
-         Color_magnitude3_title = 'Color_magnitude3'
-
-         ! Plots xaxis1-xaxis2 leave xaxis2 blank if you only want to plot xaxis1.
-         Color_magnitude3_xaxis1_name = 'model_number'
-         Color_magnitude3_xaxis2_name = ''
-
-         ! Plots yaxis1-yaxis2 leave yaxis2 blank if you only want to plot yaxis1.
-         Color_magnitude3_yaxis1_name(1) = 'bc_v_bb'
-
-         Color_magnitude3_other_yaxis1_name(1) = 'av_v'
-
-         ! setup default
-         Color_magnitude3_num_panels = 1
-         ! file output
-         Color_magnitude3_file_flag = .true.
-         Color_magnitude3_file_dir = 'png'
-         Color_magnitude3_file_prefix = 'Color_magnitude3_'
-         Color_magnitude3_file_interval = 5 ! output when `mod(model_number,Color_magnitude3_file_interval)==0`
-         Color_magnitude3_file_width = -1 ! (inches) negative means use same value as for window
-         Color_magnitude3_file_aspect_ratio = -1 ! negative means use same value as for window
-
-
- / ! end of pgstar namelist
-
-.. |LCB98| replace:: `Lejeune, Cuisinier, & Buser (1998) <https://ui.adsabs.harvard.edu/abs/1998A%26AS..130...65L/abstract>`__
-
-Last-Updated: 05Jun2021 (MESA 5be9e57) by fxt
+This project was inspired by the need for more detailed synthetic photometry in stellar evolution simulations. It incorporates insights from MESA's development community and builds upon the work of Rob Farmer and the MESA Team.
 

star/test_suite/custom_colors/custom_colors_history_columns.list

@@ -52,18 +52,21 @@
 
       ! Note the filter names are case sensitive and must match what is used in your color
       ! data file
-      bc V
-      bc v_bb
-      bc B
-      bc U
-      abs_mag R
-      abs_mag J
-      abs_mag V
-      abs_mag B
-      abs_mag U
-
+      !bc H
+      !bc J_bb
+      !bc J
+      !abs_mag H
+      !abs_mag J
+      !abs_mag V
+      !abs_mag B
+      !abs_mag U
+      star_age
+      Teff
+      log_Teff
+      log_L
+      log_R
+      log_g
       !Custom Av values are handled in the run_star_extras
-
 
 !----------------------------------------------------------------------------------------------
 
@@ -74,3 +77,4 @@
    !## solver iterations
 
       num_iters ! same as num_newton_iterations
+