.. _about_mesalab:

About `mesalab`
===============

The Python package `mesalab` is designed for **processing and analyzing stellar evolution simulations performed with**  `MESA <https://docs.mesastar.org/en/latest/>`_ (Modules for Experiments in Stellar Astrophysics). It is developed to efficiently handle **large grids of simulations**, such as those where stellar mass (M) and metallicity (Z) are systematically varied.

The primary goal of this pipeline is to take your MESA outputs and automatically:
    1.  Analyze each simulation within your grid.
    2.  Identify if the star enters the *blue loop* phase and crosses the instability strip.
    3.  Based on these findings, prepare `GYRE <https://gyre.readthedocs.io/>`_ input files and run the corresponding pulsation simulations.

.. note::
   The current version of `mesalab` is optimized for MESA version **23.05.01** and GYRE version **7.0**.


The `mesalab` pipeline goes through the following steps:

1.  **Data Collection:**
    The pipeline gathers all relevant data from your MESA simulation output directories. This includes:

    * **From MESA** ``LOGS/history.data`` **files:**
        * ``log_g``
        * ``log_Teff``
        * ``log_L``
        * ``mass``
        * ``star_age``
        * ``log_R``
        * ``center_h1``
        * ``center_he4``

    * **From MESA** ``inlist`` **files:**
        * ``initial_mass``
        * ``initial_Z``


2.  **Plotting Evolutionary Tracks (Optional):**
    
    * In this phase  `mesalab` generates individual Hertzsprung-Russell (HR) diagrams, plotting the evolutionary tracks for all stars within your simulation grid.

3.  **Blue Loop & Instability Strip Identification and Filtering:**
    
    * The pipeline checks which stars undergo a *blue loop* phase and enter, or cross the instability strip during their evolution.
    * Then `mesalab` filters and extracts the data for these specific evolutionary phases.
    * Optionally, it can create a heatmap visualizing the number of instability strip edge crossings across your grid.

4.  **Generating Color-Magnitude, and HR Diagrams for the Selected Model Numbers (Optional):**
   
    * For the filtered stellar models, it applies bolometric corrections using the `MIST Bolometric Correction Tables <https://waps.cfa.harvard.edu/MIST/model_grids.html#bolometric>`_.
    * Then it generates Color-Magnitude Diagrams (CMDs) tailored to Gaia observational bands.
    * Additional HR-diagrams and ``log_g`` vs ``log_Teff`` diagrams can also be generated.

5.  **GYRE Inlist Generation:**
   
    * For the filtered stellar models (or optionally for all models, based on your configuration), `mesalab` creates the necessary input files (e.g., ``gyre.in``) for the `GYRE <https://gyre.readthedocs.io/>`_ pulsation code.

6.  **GYRE Workflow Execution:**
  
    * In this is phase the pipeline runs the GYRE pulsation code using the generated inlist files to perform the asteroseismic analysis.

----

About this Documentation
------------------------

This documentation uses `Sphinx <https://www.sphinx-doc.org>`_ and `MyST Markdown <https://myst-parser.readthedocs.io>`_.
Initial content drafts, formatting suggestions, and phrasing were partially assisted by large language models (Google's Gemini and OpenAI's ChatGPT), while all final decisions and edits were made by the author.

Similarly, a significant portion of the **unit tests** were also initially generated by these large language models. This approach aided in rapidly building a foundational test suite and achieving initial code coverage. All LLM-generated tests have undergone thorough human review, verification, and refinement to ensure their correctness and effectiveness.