Add LBV_flag and change default LBV winds to follow Hurley+2000 (plus new docs stuff)

.gitignore

@@ -118,4 +118,6 @@ fort.99
 savefig/
 
 # ignore generated docs files
-_generated/
+_generated/
+docs/auto_examples/
+sg_execution_times.rst

changelog.md

@@ -101,4 +101,14 @@ This release contains _several_ fixes to how CO core masses/remnant masses are h
     - WD chandrasekhar check use ``mc_co`` instead of ``mc``
     - Remnant flags 0-4 inclusive use ``mc_co`` instead of ``mc``
     - Got rid of ``mcx`` in ``assign_remnant`` in favour of clearer ``m_proto`` and ``m_FeNi`` to match the papers
-    - [Very minor] Fryer Rapid was using <= instead of < everywhere
+    - [Very minor] Fryer Rapid was using <= instead of < everywhere
+
+
+## 3.7.3
+- Additions/changes:
+    - Add new setting ``LBV_flag`` which allows one to turn off LBV winds, use Hurley+2000, or use Belcyznski+2008
+    - Change the default LBV winds to Hurley
+
+- Documentation:
+    - Start new settings gallery in the documentation
+    - Tag settings/options with the version they were added in the docs page and auto link them to release

docs/_static/cosmic-docs.css

@@ -125,6 +125,16 @@ html[data-theme="dark"] .sd-card {
     max-width: 100%;
 }
 
+.setting-chooser .name-cont {
+    display: flex;
+    align-items: center;
+}
+
+.setting-chooser .name {
+    display: inline-block;
+    margin-right: 0.5rem;
+}
+
 .setting-chooser .description {
     margin-bottom: 0;
 }
@@ -134,6 +144,10 @@ html[data-theme="dark"] .sd-card {
     font-weight: bold;
 }
 
+.setting-chooser .version-added {
+    font-style: italic;
+}
+
 .options {
     overflow: hidden;
 }
@@ -152,6 +166,41 @@ html[data-theme="dark"] .sd-card {
     color: var(--color-brand-primary);
 }
 
+.options .opt-badge-cont {
+    margin-left: 0.5rem;
+    font-style: italic;
+}
+
+/* base badge */
+.badge {
+  display: inline-block;
+  padding: 0.35em 0.65em;
+  font-size: 0.75em;
+  font-weight: 700;
+  line-height: 1;
+  color: #fff;
+  text-align: center;
+  white-space: nowrap;
+  vertical-align: baseline;
+  border-radius: 0.375rem;
+}
+
+/* pill style */
+.badge.rounded-pill {
+  border-radius: 50rem;
+}
+
+.badge-primary    { background-color: #0d6efd; }
+.badge-secondary  { background-color: #6c757d; }
+.badge-success    { background-color: #198754; }
+.badge-danger     { background-color: #dc3545; }
+.badge-warning    { background-color: #ffc107; color: #000; }
+.badge-info       { background-color: #0dcaf0; color: #000; }
+.badge-light      { background-color: #f8f9fa; color: #000; }
+.badge-dark       { background-color: #212529; }
+
+
+
 .setting .col-3 label {
     cursor: pointer;
 }
@@ -469,4 +518,19 @@ select.form-control {
 .btn-toggle.active {
     filter: brightness(1.1);
     font-weight: bold;
+}
+
+/* Centre gallery thumbnail labels and titles */
+.sphx-glr-thumbcontainer[tooltip]:hover::after,
+.sphx-glr-thumbnail-title {
+    text-align: center;
+}
+
+/* vertically align content in the thumbnails */
+.sphx-glr-thumbcontainer {
+    justify-content: center;
+}
+
+.link-white {
+    color: white!important;
 }

docs/_static/gallery.mplstyle

@@ -0,0 +1,14 @@
+font.family: serif
+text.usetex: False
+figure.figsize: 12, 8
+axes.titlesize: 24
+legend.title_fontsize: 18
+legend.fontsize: 16
+axes.labelsize: 24
+xtick.labelsize: 21
+ytick.labelsize: 21
+axes.linewidth: 1.1
+xtick.major.size: 7
+xtick.minor.size: 4
+ytick.major.size: 7
+ytick.minor.size: 4

docs/conf.py

@@ -62,6 +62,7 @@ def setup(app):
     'numpydoc',
     'sphinx_design',
     'sphinx_copybutton',
+    'sphinx_gallery.gen_gallery',
 ]
 
 # -- Extensions ---------------------------------------------------------------
@@ -76,6 +77,15 @@ def setup(app):
 autoclass_content = 'class'
 autodoc_default_flags = ['show-inheritance', 'members', 'inherited-members']
 
+# -- sphinx_gallery -----------------------------
+
+sphinx_gallery_conf = {
+    'examples_dirs': 'settings_examples',   # path to your example scripts
+    'gallery_dirs': 'auto_examples',  # path to where to save gallery generated output
+    'download_all_examples': False,
+    'remove_config_comments': True,
+}
+
 # -- autosummary --------------------------------
 
 autosummary_generate = True

docs/create_settings_html.py

@@ -10,6 +10,22 @@
 import bs4
 import json
 import pandas as pd
+from cosmic import __version__ as cosmic_version
+
+# how many versions in the past should we show as badges for when options were added?
+VERSION_CUTOFFS = {
+    "major": 0,
+    "minor": 3,
+    "patch": 1000
+}
+
+def version_is_recent(version_string):
+    version_nums = version_string.split(".")
+    cosmic_nums = cosmic_version.split(".")
+    for i, label in enumerate(["major", "minor", "patch"]):
+        if int(cosmic_nums[i]) - int(version_nums[i]) > VERSION_CUTOFFS[label]:
+            return False
+    return True
 
 # blame BS4 for me calling this soup
 main_soup = """<!-- This file should be created using create_settings_html.py -->
@@ -29,7 +45,7 @@
 settings_template = """<div class="setting">
                 <div class="row align-items-center setting-chooser">
                     <div class="col-9">
-                        <h3 class="name"><code></code></h3>
+                        <div class='name-cont'><h3 class="name"><code></code></h3><span class="version-added"></span></div>
                         <p class="description"></p>
                         <p class="default"></p>
                     </div>
@@ -43,7 +59,7 @@
             </div>"""
 
 # same as above, but for an option for a setting, this will go in the <ul> element
-option_template = """<li><code class="docutils literal notranslate"><span class="pre opt-val"></span></code>: <span class="opt-desc"></span></li>"""
+option_template = """<li><code class="docutils literal notranslate"><span class="pre opt-val"></span></code>: <span class="opt-desc"></span><span class="opt-badge-cont"></span></li>"""
 
 # read the settings file
 with open("../src/cosmic/data/cosmic-settings.json") as f:
@@ -93,6 +109,12 @@
         new_setting.select_one(".description").clear()
         new_setting.select_one(".description").append(bs4.BeautifulSoup(setting["description"],
                                                                         'html.parser'))
+
+        # add the version added if it's there
+        if "version_added" in setting:
+            if version_is_recent(setting["version_added"]):
+                new_setting.select_one(".version-added").append(bs4.BeautifulSoup(
+                    f"""<span class="badge badge-success version-added"><a class="link-white" href="https://github.com/COSMIC-PopSynth/COSMIC/releases/tag/v{setting['version_added']}">Added in v{setting['version_added']}</a></span>""", 'html.parser'))
 
         # colour the sublinks the same as the border of the group
         new_setting.select_one(".options-expander")["style"] = "color: " + group["docs-colour"] + ";"
@@ -165,6 +187,12 @@
             new_option_expl = bs4.BeautifulSoup(option_template, 'html.parser')
             new_option_expl.select_one(".opt-val").string = str(option["name"])
             new_option_expl.select_one(".opt-desc").append(bs4.BeautifulSoup(option["description"], 'html.parser'))
+
+            if "version_added" in option:
+                if version_is_recent(option["version_added"]):
+                    new_option_expl.select_one(".opt-badge-cont").append(bs4.BeautifulSoup(
+                        f"""<span class="badge badge-success version-added"><a class="link-white" href="https://github.com/COSMIC-PopSynth/COSMIC/releases/tag/v{option['version_added']}">Added in v{option['version_added']}</a></span>""", 'html.parser'
+                    ))
             new_setting.select_one(".options").ul.append(new_option_expl)
 
         # convert the default options to a string and display it

docs/pages/reference_material.rst

@@ -27,4 +27,15 @@ Configuration and output
 
             output_info.rst
 
-        Descriptions of the output files generated by COSMIC simulations.
+        Descriptions of the output files generated by COSMIC simulations.
+
+    .. grid-item-card::
+        :link: gallery
+        :link-type: ref
+
+        .. toctree::
+            :maxdepth: 1
+
+            ../auto_examples/index.rst
+
+        Examples of the effects of different configuration options on the evolution of binaries.

docs/settings_examples/GALLERY_HEADER.rst

@@ -0,0 +1,9 @@
+Impact of settings on evolution
+===============================
+
+This gallery shows examples of how different settings affect the evolution of binaries.
+
+.. admonition:: Under construction
+    :class: warning
+
+    This page is still being developed, but will eventually contain examples of how all settings affect the evolution of binaries. For now it's just a few.

docs/settings_examples/plot_LBV_flag.py

@@ -0,0 +1,104 @@
+"""
+``LBV_flag``
+============
+
+This example shows the effect of the ``LBV_flag`` on the evolution of massive stars.
+
+The ``LBV_flag`` controls which prescription to use for LBV-like mass loss for stars that are above the Humphreys-Davidson limit. The plots below show the evolution of a few single stars and highlight the LBV regime in which we'd expect to see differences with this flag.
+"""
+
+#----------------------------------------------------------------------------------
+#----------------------------------------------------------------------------------
+## You'll want to edit this part locally to use your own BSEDict and style sheet!
+
+import sys
+sys.path.append("..")
+import generate_default_bsedict
+BSEDict = generate_default_bsedict.get_default_BSE_settings(to_python=True)
+
+import matplotlib.pyplot as plt
+plt.style.use("../_static/gallery.mplstyle")
+#----------------------------------------------------------------------------------
+#----------------------------------------------------------------------------------
+
+import numpy as np
+import astropy.units as u
+import astropy.constants as consts
+
+from cosmic.sample import InitialBinaryTable
+from cosmic.evolve import Evolve
+from cosmic.output import kstar_translator
+
+def LBV_limit(T_eff):
+    """ Compute the luminosity of the LBV limit given a certain temperature """
+    return np.maximum(np.sqrt(1e10 * u.Rsun**2 * u.Lsun * (4 * np.pi * consts.sigma_sb * (T_eff * u.K)**4)).to(u.Lsun), np.repeat(6e5 * u.Lsun, len(T_eff)))
+
+
+# create a small grid of single stars
+masses = [30, 33, 36, 40, 45, 50]
+grid = InitialBinaryTable.InitialBinaries(
+    m1=masses,
+    m2=np.zeros(len(masses)),
+    porb=np.ones(len(masses))*-1.0,
+    ecc=np.ones(len(masses))*0.0,
+    tphysf=np.ones(len(masses))*13700.0,
+    kstar1=np.ones(len(masses)),
+    kstar2=np.ones(len(masses)),
+    metallicity=np.ones(len(masses))*0.014*0.01
+)
+
+# loop over different flag choices
+for LBV_flag, label in zip([0, 1, 2], ["No LBV mass loss", "LBV mass loss following Hurley+2000",
+                                       "LBV mass loss following Belczynski+2008"]):
+    # evolve with updated BSEDict
+    BSEDict["LBV_flag"] = LBV_flag
+    bpp, bcm, initC, kick_info = Evolve.evolve(
+        initialbinarytable=grid, BSEDict=BSEDict,
+        dtp=0
+    )
+
+    # plot a HR diagram of the evolution of these stars, colour coded by kstar
+    fig, ax = plt.subplots(figsize=(10, 16))
+
+    for i, bin_num in enumerate(np.unique(bcm["bin_num"])):
+        log_teff = np.log10(bcm[bcm["bin_num"] == bin_num]["teff_1"].values)
+        log_lum = np.log10(bcm[bcm["bin_num"] == bin_num]["lum_1"].values)
+        kstar = bcm[bcm["bin_num"] == bin_num]["kstar_1"].values
+
+        mask = kstar < 10
+
+        ax.scatter(log_teff[mask], log_lum[mask], c=[kstar_translator[k]["colour"] for k in kstar[mask]],
+                   s=5)
+        ax.plot(log_teff[mask], log_lum[mask], color='grey', alpha=0.5, lw=0.5, zorder=-1)
+
+        # annotate the first point with the initial mass
+        ax.annotate(f'{bcm[bcm["bin_num"] == bin_num]["mass_1"].values[0]:.0f} M$_\odot$', (log_teff[0], log_lum[0]),
+                    fontsize=14, ha="right", color='black', va='top')
+
+    # annotate the various kstar types
+    for k in bcm["kstar_1"].unique():
+        if k < 10:
+            ax.scatter([], [], color=kstar_translator[k]["colour"], label=kstar_translator[k]["short"], s=50)
+    ax.legend()
+
+    # make some fairly reasonable temperature range
+    T_eff_range = np.logspace(3.5, 5.4, 1000)
+
+    # plot a line at the HD limit and fill the area
+    ax.plot(np.log10(T_eff_range), np.log10(LBV_limit(T_eff_range).value), color="grey", linestyle="dotted")
+    ax.fill_between(np.log10(T_eff_range), np.log10(LBV_limit(T_eff_range).value), 9, color="black", lw=2, alpha=0.03)
+
+    # annotate the regime with a custom location
+    ax.annotate("LBV Regime", xy=(0.77, 0.93), xycoords="axes fraction", ha="center", va="center",
+                fontsize=20, color="grey", zorder=10)
+
+    ax.set(
+        xlabel=r"$\log_{10}(T_{\rm eff} \, [\rm K])$",
+        ylabel=r"$\log_{10}(L \, [\rm L_{\odot}])$",
+        title=f"LBV_flag = {LBV_flag}\n{label}",
+        ylim=(5, 6.2)
+    )
+
+    ax.invert_xaxis()
+
+    plt.show()