cosmic-popsynth 3.6.2__tar.gz → 3.7.0__tar.gz

cosmic_popsynth-3.7.0/.github/workflows/cmc-review.yml

@@ -0,0 +1,165 @@
+name: Flag CMC review for cosmic changes
+
+on:
+  pull_request_target:
+    types: [opened]
+    paths:
+      - 'src/cosmic/evolve.py'
+      - 'src/cosmic/data/cosmic-settings.json'
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  flag-cmc-review:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: decide whether to flag PR
+        id: decide
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+            const pull_number = context.payload.pull_request.number;
+
+            const SETTINGS_PATH = 'src/cosmic/data/cosmic-settings.json';
+
+            // helper: fetch file content at a specific ref (sha/branch)
+            async function fetchText(path, ref) {
+              const res = await github.rest.repos.getContent({ owner, repo, path, ref });
+              if (Array.isArray(res.data) || !res.data.content) {
+                throw new Error(`unexpected content response for ${path} at ${ref}`);
+              }
+              const buff = Buffer.from(res.data.content, res.data.encoding || 'base64');
+              return buff.toString('utf8');
+            }
+
+            // helper: count keys on the object with category === "bse"
+            // json is expected to be an array: [{category: "blah", ...}, {category: "bse", ...}]
+            // counts top-level keys excluding "category"
+            function bseKeyCount(jsonVal) {
+              if (!Array.isArray(jsonVal)) return 0;
+
+              const bseObj = jsonVal.find(
+                (x) => x && typeof x === 'object' && !Array.isArray(x) && x.category === 'bse'
+              );
+
+              if (!bseObj) return 0;
+
+              return Object.keys(bseObj).filter((k) => k === 'settings').length;
+            }
+
+            // list changed files in the PR
+            const files = await github.paginate(github.rest.pulls.listFiles, {
+              owner,
+              repo,
+              pull_number,
+              per_page: 100,
+            });
+
+            const changed = new Set(files.map(f => f.filename));
+            const changedEvolve = changed.has('src/cosmic/evolve.py');
+            const changedSettings = changed.has(SETTINGS_PATH);
+
+            let shouldFlag = false;
+            let reason = '';
+
+            // if evolve changed, always flag
+            if (changedEvolve) {
+              shouldFlag = true;
+              reason = 'evolve file changed, probably needs CMC review';
+            } else if (changedSettings) {
+              // only flag if bse key-count changes between base and head
+              const baseSha = context.payload.pull_request.base.sha;
+              const headSha = context.payload.pull_request.head.sha;
+
+              try {
+                const baseText = await fetchText(SETTINGS_PATH, baseSha);
+                const headText = await fetchText(SETTINGS_PATH, headSha);
+
+                const baseJson = JSON.parse(baseText);
+                const headJson = JSON.parse(headText);
+
+                const baseCount = bseKeyCount(baseJson);
+                const headCount = bseKeyCount(headJson);
+
+                if (baseCount !== headCount) {
+                  shouldFlag = true;
+                  reason = `bse key count changed (${baseCount} -> ${headCount})`;
+                } else {
+                  shouldFlag = false;
+                  reason = `bse key count unchanged (${baseCount})`;
+                }
+              } catch (err) {
+                // if parsing/fetching fails, be conservative and flag
+                shouldFlag = true;
+                reason = `could not compare bse key count safely (${err.message}); flagging for review`;
+              }
+            }
+
+            core.setOutput('should_flag', shouldFlag ? 'true' : 'false');
+            core.setOutput('reason', reason);
+
+      - name: add "needs-cmc-review" label
+        if: steps.decide.outputs.should_flag == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const labelName = 'needs-cmc-review';
+
+            // ensure the label exists, or create it
+            try {
+              await github.rest.issues.getLabel({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                name: labelName,
+              });
+            } catch (error) {
+              if (error.status === 404) {
+                await github.rest.issues.createLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: labelName,
+                  color: 'fbca04',
+                  description: 'PR touches cosmic core/settings and needs CMC review',
+                });
+              } else {
+                throw error;
+              }
+            }
+
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: [labelName],
+            });
+
+      - name: comment to request CMC review
+        if: steps.decide.outputs.should_flag == 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const reason = `${{ toJSON(steps.decide.outputs.reason) }}`.replace(/^"|"$/g, '');
+
+            const body = `
+            🚨 **CMC review requested**
+
+            This pull request modifies one or more of:
+            - \`src/cosmic/evolve.py\`
+            - \`src/cosmic/data/cosmic-settings.json\` (only flagged when \`category: "bse"\` key-count changes)
+
+            **Trigger:** ${reason}
+
+            A CMC developer should review this PR to ensure corresponding changes are propagated upstream as needed.
+            `;
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body,
+            });

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/.gitignore

@@ -115,4 +115,7 @@ binary.in
 binary.dat
 *.h5
 fort.99
-savefig/
+savefig/
+
+# ignore generated docs files
+_generated/

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cosmic-popsynth
-Version: 3.6.2
+Version: 3.7.0
 Summary: a Python-interfaced binary population synthesis suite
 Author: Scott Coughlin, Michael Zevin, Carl L. Rodriguez, Tom Wagg
 Author-Email: Katelyn Breivik <katie.breivik@gmail.com>

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/changelog.md

@@ -58,4 +58,15 @@ See the discussed changes in our previous releases here: https://github.com/COSM
 
 ## 3.6.2
  - Add functions to `cosmic.utils` for initC IO that's more efficient (`save_initC`, `load_initC`) by saving
- identical setting columns separately with only one copy - saves ~1kb per binary
+ identical setting columns separately with only one copy - saves ~1kb per binary
+ - Make He and CO core masses available in output
+ - Change defaults; `qcflag=5` and `eccfac=10`
+ - Prevent users from supplying both `qmin` and `m2_min`
+ - Prevent users from supplying both `sep` and `porb` when sampling, calculate `porb` from `sep` as necessary
+ - Define `binstate=-1` as single stars
+
+## 3.7.0
+ - Add `remnantflag=5`: The Mandel & Muller 2020 prescription for remnant masses
+ - Add `kickflag=6`: The Mandel & Muller 2020 prescription for natal kicks. This can be tuned with `mm_mu_ns` and `mm_mu_bh`
+ - Add `remnantflag=6`: The Maltsev+25 and Willcox+25 prescription for remnant masses. This can be tuned with `maltsev_mode` and `maltsev_fallback`
+ - (Docs) Any tutorial that uses a plain BSEDict now uses one that is drawn from the cosmic-settings.json file to avoid missing changes and saves us updating each docs page

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/docs/Makefile

@@ -55,6 +55,7 @@ clean:
 
 .PHONY: html
 html: apidoc
+	python generate_default_bsedict.py
 	python create_settings_html.py
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo

cosmic_popsynth-3.7.0/docs/_generated/README.md

@@ -0,0 +1,2 @@
+# _generated
+Generated docs files will be placed here

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/docs/conf.py

@@ -15,6 +15,9 @@
 import sys
 import os
 import re
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
 
 from cosmic import __version__ as cosmic_version
 
@@ -144,6 +147,12 @@ pygments_style = 'monokai'
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# this runs before each plot directive
+plot_pre_code = """
+from generate_default_bsedict import get_default_BSE_settings
+default_BSEDict = get_default_BSE_settings(to_python=True)
+"""
+
 
 # -- Options for HTML output ----------------------------------------------
 

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/docs/create_settings_html.py

@@ -198,5 +198,5 @@ for group in settings:
     soup.select_one(".container-fluid").append(new_group)
 
     # write the soup out to an HTML file for this category
-    with open(f"pages/config/config_insert_{group['category']}.html", "w") as f:
+    with open(f"_generated/config_insert_{group['category']}.html", "w") as f:
         f.write(str(soup))

cosmic_popsynth-3.7.0/docs/generate_default_bsedict.py

@@ -0,0 +1,77 @@
+import json
+from pathlib import Path
+
+def get_default_BSE_settings(to_python=False):
+    """Get a copy of the default BSE settings from the COSMIC settings JSON file"""
+    json_path = (
+        Path(__file__).resolve().parent.parent
+        / "src"
+        / "cosmic"
+        / "data"
+        / "cosmic-settings.json"
+    )
+
+    with json_path.open(encoding="utf-8") as f:
+        cosmic_settings = json.load(f)
+
+    defaults = {}
+    # loop through settings to find bse
+    for cat in cosmic_settings:
+        if cat["category"] != "bse":
+            continue
+        
+        # go through each setting, finding the default option
+        for setting in cat["settings"]:
+            for option in setting["options"]:
+                if option.get("default", False):
+                    defaults[setting["name"]] = option["name"]
+
+    if to_python:
+        # ensure array settings are converted from strings to lists
+        for setting in ["qcrit_array", "natal_kick_array", "fprimc_array"]:
+            # this one requires special handling because of the fractions
+            if setting == "fprimc_array":
+                parts = defaults[setting].strip("[]").split(",")
+                defaults[setting] = [float(p.split("/")[0]) / float(p.split("/")[1]) for p in parts]
+            else:
+                defaults[setting] = json.loads(defaults[setting])
+
+    return defaults
+
+
+def generate_rst_bsedict(MAX_LINE_LENGTH=80):
+    """Generate the default BSE settings dictionary for use in documentation"""
+    defaults = get_default_BSE_settings()
+
+    indent_str = " " * 8
+
+    with open("_generated/default_bsedict.rst", "w") as f:
+        lines = [
+            ".. ipython:: python",
+            "",
+            "    BSEDict = {",
+        ]
+
+        first = True
+        current_line = indent_str
+        for k, v in defaults.items():
+            entry = f'"{k}": {v}'
+            if not first:
+                entry = ", " + entry
+            first = False
+
+            # check if adding this entry would exceed line length
+            if len(current_line) + len(entry) > MAX_LINE_LENGTH:
+                lines.append(current_line.rstrip() + ",")
+                current_line = indent_str + entry.lstrip(", ")
+            else:
+                current_line += entry
+
+        if current_line.strip():
+            lines.append(current_line.rstrip())
+        lines.append("    }")
+
+        f.write("\n".join(lines))
+
+if __name__ == "__main__":
+    generate_rst_bsedict()

cosmic_popsynth-3.7.0/docs/pages/evolve/evolve_sample.rst

@@ -0,0 +1,48 @@
+*****************************************
+Evolving a Monte-Carlo sampled population
+*****************************************
+Once an initial binary population is sampled, it can be evolved using the ``Evolve`` class just as we've done so far.
+You can read more about sampling initial binary populations in the :ref:`runpop` page.
+
+Note that the same process used other examples applies here as well: the ``BSEDict`` must be supplied,
+if the flags in the dictionary change from their defaults.
+
+First, let's import the necessary modules from COSMIC:
+
+.. ipython:: python
+
+    from cosmic.sample.initialbinarytable import InitialBinaryTable
+
+    from cosmic.evolve import Evolve
+
+
+Now let's use the independent sampler to generate an initial binary population. You can learn more 
+about the independent sampler in the :ref:`independent` page.
+
+.. ipython:: python
+
+    final_kstars = range(16)
+
+    InitialBinaries, mass_singles, mass_binaries, n_singles, n_binaries = \
+          InitialBinaryTable.sampler('independent', final_kstars, final_kstars,
+                                     binfrac_model=0.5, primary_model='kroupa01',
+                                     ecc_model='sana12', porb_model='sana12',
+                                     qmin=-1, SF_start=13700.0,
+                                     SF_duration=0.0, met=0.02, size=10, keep_singles=True)
+
+
+And finally, we can evolve the initial binary population using the Evolve class as we've done in the previous
+guides:
+
+.. include:: ../../_generated/default_bsedict.rst
+
+.. ipython:: python
+    :okwarning:
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(
+        initialbinarytable=InitialBinaries, BSEDict=BSEDict
+    )
+
+    print(bcm.iloc[:10])
+
+    print(bpp)

cosmic_popsynth-3.7.0/docs/pages/evolve/grid.rst

@@ -0,0 +1,43 @@
+*********************************
+Evolving a fixed grid of binaries
+*********************************
+
+Sometimes it is helpful to run a fixed grid of initial binaries to explore how
+changing a single parameter affects the evolved binary. Let's start by importing the necessary modules and
+setting up the BSEDict settings as we've done in the previous examples.
+
+.. ipython:: python
+
+    from cosmic.sample.initialbinarytable import InitialBinaryTable
+
+    from cosmic.evolve import Evolve
+
+.. include:: ../../_generated/default_bsedict.rst
+
+
+Here we evolve the same system that produces a GW150914-like binary, but run over several initial orbital
+periods spaced evenly in log space.
+
+.. ipython:: python
+    :okwarning:
+
+    n_grid = 10
+
+    binary_grid = InitialBinaryTable.InitialBinaries(
+        m1=np.ones(n_grid)*100.0,
+        m2=np.ones(n_grid)*85.0,
+        porb=np.logspace(3,5,n_grid),
+        ecc=np.ones(n_grid)*0.65,
+        tphysf=np.ones(n_grid)*13700.0,
+        kstar1=np.ones(n_grid),
+        kstar2=np.ones(n_grid),
+        metallicity=np.ones(n_grid)*0.005
+    )
+
+    print(binary_grid)
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(initialbinarytable=binary_grid, BSEDict=BSEDict)
+
+    print(bpp)
+
+    print(bcm)

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/docs/pages/evolve/interface.rst

@@ -26,29 +26,15 @@ samples ~100 binaries and evolving them.
     import matplotlib.pyplot as plt
     import numpy as np
 
+.. include:: ../../_generated/default_bsedict.rst
+
+.. ipython:: python
+
     InitialBinaries, mass_singles, mass_binaries, n_singles, n_binaries = InitialBinaryTable.sampler(
         'independent', [13, 14], [13, 14], binfrac_model=0.5, primary_model='kroupa01',
         ecc_model='sana12', porb_model='sana12', qmin=-1, SF_start=13700.0, SF_duration=0.0,
         met=0.002, size=1000)
 
-    BSEDict = {
-        'xi': 1.0, 'bhflag': 1, 'neta': 0.5, 'windflag': 3, 'wdflag': 1, 'alpha1': 1.0,
-        'pts1': 0.001, 'pts3': 0.02, 'pts2': 0.01, 'epsnov': 0.001, 'hewind': 0.5, 'ck': 1000,
-        'bwind': 0.0, 'lambdaf': 0.0, 'mxns': 3.0, 'beta': -1.0, 'tflag': 1, 'acc2': 1.5,
-        'grflag' : 1, 'remnantflag': 4, 'ceflag': 0, 'eddfac': 1.0, 'ifflag': 0, 'bconst': 3000,
-        'sigma': 265.0, 'gamma': -2.0, 'pisn': 45.0,
-        'natal_kick_array' : [[-100.0,-100.0,-100.0,-100.0,0.0], [-100.0,-100.0,-100.0,-100.0,0.0]],
-        'bhsigmafrac' : 1.0, 'polar_kick_angle' : 90,
-        'qcrit_array' : [0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],
-        'cekickflag' : 2, 'cehestarflag' : 0, 'cemergeflag' : 0, 'ecsn' : 2.25, 'ecsn_mlow' : 1.6,
-        'aic' : 1, 'ussn' : 0, 'sigmadiv' :-20.0, 'qcflag' : 1, 'eddlimflag' : 0,
-        'fprimc_array' : [2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0],
-        'bhspinflag' : 0, 'bhspinmag' : 0.0, 'rejuv_fac' : 1.0, 'rejuvflag' : 0, 'htpmb' : 1,
-        'ST_cr' : 1, 'ST_tide' : 1, 'bdecayfac' : 1, 'rembar_massloss' : 0.5, 'kickflag' : 5,
-        'zsun' : 0.014, 'bhms_coll_flag' : 0, 'don_lim' : -1, 'acc_lim' : -1, 'rtmsflag' : 0,
-        'wd_mass_lim': 1
-    }
-
     bpp, bcm, initC, kick_info = Evolve.evolve(initialbinarytable=InitialBinaries, BSEDict=BSEDict)
 
 Now we can create a ``COSMICOutput`` object quite easily (with an optional label):

cosmic_popsynth-3.7.0/docs/pages/evolve/multiple.rst

@@ -0,0 +1,73 @@
+**************************
+Evolving multiple binaries
+**************************
+
+Following on from `evolving a single binary <single.html>`_, we can also evolve multiple binaries.
+Let's start by importing the necessary modules:
+
+.. ipython:: python
+
+    from cosmic.sample.initialbinarytable import InitialBinaryTable
+
+    from cosmic.evolve import Evolve
+
+
+And use the same BSE dict as before:
+
+.. include:: ../../_generated/default_bsedict.rst
+
+Below is an example for systems that could form GW150914 and GW170817 - like binaries.
+
+.. ipython:: python
+    :okwarning:
+
+    binary_set = InitialBinaryTable.InitialBinaries(
+        m1=[85.543645, 11.171469], m2=[84.99784, 6.67305],
+        porb=[446.795757, 170.758343], ecc=[0.448872, 0.370],
+        tphysf=[13700.0, 13700.0],
+        kstar1=[1, 1], kstar2=[1, 1],
+        metallicity=[0.002, 0.02]
+    )
+
+    print(binary_set)
+
+    import numpy as np
+
+    np.random.seed(5)
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(initialbinarytable=binary_set, BSEDict=BSEDict)
+
+As before, bpp, bcm, and initC are returned as pandas DataFrames which assign an
+index to each binary system we evolve. We can access each binary as follows:
+
+.. ipython:: python
+
+    print(bpp.loc[0])
+
+    print(bcm.loc[0])
+
+    print(initC.loc[0])
+
+    print(bpp.loc[1])
+
+The plotting function can also take in multiple binaries. Let's plot both the GW150914-like
+progenitor evolution and the GW170817-like progenitor evolutions. For the GW170817-like
+progenitor, we expect most of the evolution to take place in the first ~60 Myr.
+
+.. ipython:: python
+    :okwarning:
+    :okexcept:
+
+    from cosmic.plotting import evolve_and_plot
+    fig = evolve_and_plot(binary_set, t_min=None, t_max=[6.0, 60.0], BSEDict=BSEDict, sys_obs={})
+
+
+.. plot::
+
+    from cosmic.sample.initialbinarytable import InitialBinaryTable
+    from cosmic.plotting import evolve_and_plot
+    import numpy as np
+    np.random.seed(5)
+    binary_set = InitialBinaryTable.InitialBinaries(m1=[85.543645, 11.171469], m2=[84.99784, 9.67305], porb=[446.795757, 370.758343], ecc=[0.448872, 0.370], tphysf=[13700.0, 13700.0], kstar1=[1, 1], kstar2=[1, 1], metallicity=[0.002, 0.02])
+    fig = evolve_and_plot(binary_set, t_min=None, t_max=[6.0, 60.0], BSEDict=default_BSEDict, sys_obs={})
+

{cosmic_popsynth-3.6.2 → cosmic_popsynth-3.7.0}/docs/pages/evolve/rerun.rst

@@ -20,21 +20,9 @@ First, let's evolve a binary and save the initC table.
     from cosmic.sample.initialbinarytable import InitialBinaryTable
     from cosmic.evolve import Evolve
 
-    BSEDict = {'xi': 1.0, 'bhflag': 1, 'neta': 0.5, 'windflag': 3, 'wdflag': 1, 'alpha1': 1.0,
-               'pts1': 0.001, 'pts3': 0.02, 'pts2': 0.01, 'epsnov': 0.001, 'hewind': 0.5, 'ck': 1000,
-               'bwind': 0.0, 'lambdaf': 0.0, 'mxns': 3.0, 'beta': -1.0, 'tflag': 1, 'acc2': 1.5,
-               'grflag' : 1, 'remnantflag': 4, 'ceflag': 0, 'eddfac': 1.0, 'ifflag': 0,
-               'bconst': 3000, 'sigma': 265.0, 'gamma': -2.0, 'pisn': 45.0,
-               'natal_kick_array' : [[-100.0,-100.0,-100.0,-100.0,0.0], [-100.0,-100.0,-100.0,-100.0,0.0]],
-               'bhsigmafrac' : 1.0, 'polar_kick_angle' : 90,
-               'qcrit_array' : [0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0,0.0],
-               'cekickflag' : 2, 'cehestarflag' : 0, 'cemergeflag' : 0, 'ecsn' : 2.25,
-               'ecsn_mlow' : 1.6, 'aic' : 1, 'ussn' : 0, 'sigmadiv' :-20.0, 'qcflag' : 1, 'eddlimflag' : 0,
-               'fprimc_array' : [2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0,2.0/21.0],
-               'bhspinflag' : 0, 'bhspinmag' : 0.0, 'rejuv_fac' : 1.0, 'rejuvflag' : 0, 'htpmb' : 1,
-               'ST_cr' : 1, 'ST_tide' : 1, 'bdecayfac' : 1, 'rembar_massloss' : 0.5, 'kickflag' : 1,
-               'zsun' : 0.014, 'bhms_coll_flag' : 0, 'don_lim' : -1, 'acc_lim' : -1, 'rtmsflag' : 0,
-               'wd_mass_lim': 1}
+.. include:: ../../_generated/default_bsedict.rst
+
+.. ipython:: python
 
     binary = InitialBinaryTable.InitialBinaries(
         m1=20, m2=15, porb=100, ecc=0.1, tphysf=13700.0, kstar1=1, kstar2=1, metallicity=0.02

cosmic_popsynth-3.7.0/docs/pages/evolve/resolution.rst

@@ -0,0 +1,97 @@
+***********************
+Dynamic time resolution
+***********************
+
+COSMIC has the ability to set time resolution of the bcm array depending on the current state of the evolution.
+
+.. ipython:: python
+
+    from cosmic.sample.initialbinarytable import InitialBinaryTable
+
+    from cosmic.evolve import Evolve
+
+General syntax
+==============
+
+The timestep resolution for the bcm array can be set using ``timestep_conditions`` parameter. The format of
+this parameter is a list of lists, where each sublist contains zero or more conditions followed by the desired
+resolution. The conditions are in the form of a string with the format ``'column_name=condition'``. The resolution
+is in the form of a string with the format ``'dtp=resolution'``.
+
+The conditions are evaluated at each time step and if the condition is met, the resolution is set to the desired value. If multiple conditions are specified, a timestep is outputted if **any** of the conditions are met.
+
+The resolution can be any positive float value given in units of Myr. If the resolution is set to 0.0, every time step will be outputted in the bcm array.
+
+Examples
+========
+
+Below we demonstrate three scenarios, setting dtp only during mass transfer, setting dtp to the same resolution for all of the evolution except for after the system merges or is disrupted, and finally an example of setting dtp only during the HMXB stage of the evolution.
+
+All steps during mass transfer
+------------------------------
+
+First, print all time steps during mass transfer
+
+.. ipython:: python
+    :okwarning:
+
+    single_binary = InitialBinaryTable.InitialBinaries(
+        m1=7.806106, m2=5.381412, porb=2858.942021,
+        ecc=0.601408, tphysf=13700.0, kstar1=1, kstar2=1, metallicity=0.02
+    )
+
+
+.. include:: ../../_generated/default_bsedict.rst
+
+
+.. ipython:: python
+    :okwarning:
+
+    # Define the condition for the time step
+    timestep_conditions = [['RRLO_1>=1', 'dtp=0.0'], ['RRLO_2>=1', 'dtp=0.0']]
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(
+        initialbinarytable=single_binary, BSEDict=BSEDict,
+        timestep_conditions=timestep_conditions
+    )
+    print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'RRLO_1', 'RRLO_2']])
+
+
+Condition on binary state
+-------------------------
+Second, pick a certain resolution for the bcm array until the system merges or is disrupted and then only print the final state
+
+.. ipython:: python
+    :okwarning:
+
+    timestep_conditions = [['binstate=0', 'dtp=1.0']]
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(
+        initialbinarytable=single_binary, BSEDict=BSEDict,
+        timestep_conditions=timestep_conditions
+    )
+
+    print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'bin_state']])
+
+
+Condition on evolutionary state
+-------------------------------
+Finally, we show how to print a fine resolution only during the HMXB stage of the evolution.
+
+.. ipython:: python
+    :okwarning:
+
+    single_binary = InitialBinaryTable.InitialBinaries(
+        m1=85.543645, m2=84.99784, porb=446.795757,
+        ecc=0.448872, tphysf=13700.0,
+        kstar1=1, kstar2=1, metallicity=0.002
+    )
+
+    timestep_conditions = [['kstar_1=14', 'kstar_2<10','dtp=0.1'], ['kstar_2=14', 'kstar_1<10','dtp=0.1']]
+
+    bpp, bcm, initC, kick_info = Evolve.evolve(
+        initialbinarytable=single_binary, BSEDict=BSEDict,
+        timestep_conditions=timestep_conditions
+    )
+
+    print(bcm[['tphys', 'kstar_1', 'kstar_2', 'mass_1', 'mass_2', 'bin_state']])