From 35717f93435611fa99939af4c2dffa109e0baba6 Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:05:39 -0400 Subject: [PATCH 01/11] add __all__ for elson --- src/cosmic/sample/cmc/elson.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/cosmic/sample/cmc/elson.py b/src/cosmic/sample/cmc/elson.py index 812efd5b1..b05112927 100644 --- a/src/cosmic/sample/cmc/elson.py +++ b/src/cosmic/sample/cmc/elson.py @@ -30,6 +30,10 @@ __author__ = "Carl Rodriguez " __credits__ = "Carl Rodriguez " +__all__ = ["M_enclosed", "phi_r", "rho_r", "virial_radius_analytic", "find_rmax_vir", "find_sigma_sqr", + "get_positions", "get_velocities", "get_velocities_plummer", "get_velocities_old", + "scale_pos_and_vel", "draw_r_vr_vt"] + def M_enclosed(r, gamma, rho_0): """ From c8f5f28edc5448bbb6328d154f9498ef7af9021b Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:06:10 -0400 Subject: [PATCH 02/11] use nicer api page --- docs/index.rst | 9 +-------- docs/pages/api.rst | 13 +++++++++++++ 2 files changed, 14 insertions(+), 8 deletions(-) create mode 100644 docs/pages/api.rst diff --git a/docs/index.rst b/docs/index.rst index 48e586b95..7aef0f475 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,11 +28,4 @@ COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid pages/cite pages/developers _generated/whats_new - -***************** -API documentation -***************** - -Please consult these pages for more precise details on the modules in COSMIC: - -* :ref:`modindex` + pages/api diff --git a/docs/pages/api.rst b/docs/pages/api.rst new file mode 100644 index 000000000..ea1b66299 --- /dev/null +++ b/docs/pages/api.rst @@ -0,0 +1,13 @@ +****************** +Full API Reference +****************** + +This page contains detailed information for *every* function/class in ``COSMIC``. Use the links below to explore +each module in detail + +.. toctree:: + :maxdepth: 1 + :caption: Modules + + ../modules/evolve + ../modules/sample From a743bfc8d212810323a6386b0efa674aca9c7059 Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:06:16 -0400 Subject: [PATCH 03/11] add logo to about page --- docs/pages/about.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/pages/about.rst b/docs/pages/about.rst index 8bdf2ae9b..279bcbb47 100644 --- a/docs/pages/about.rst +++ b/docs/pages/about.rst @@ -3,6 +3,11 @@ ##### About ##### + +.. figure:: /_static/cosmic-colour.png + :alt: COSMIC logo + :align: center + COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. COSMIC implements stellar evolution using the fitting formulae described in From f01f4e71080f41f0f0da611c2e605d08446fa9e1 Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:06:30 -0400 Subject: [PATCH 04/11] start building some rst api --- docs/modules/evolve.rst | 9 +++++++++ docs/modules/sample.rst | 44 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 53 insertions(+) create mode 100644 docs/modules/evolve.rst create mode 100644 docs/modules/sample.rst diff --git a/docs/modules/evolve.rst b/docs/modules/evolve.rst new file mode 100644 index 000000000..cb629f03c --- /dev/null +++ b/docs/modules/evolve.rst @@ -0,0 +1,9 @@ +********************** +Evolution (``evolve``) +********************** + +The ``evolve`` module contains the main functions for evolving binary systems. + +.. automodapi:: cosmic.evolve + :no-inheritance-diagram: + :no-heading: diff --git a/docs/modules/sample.rst b/docs/modules/sample.rst new file mode 100644 index 000000000..5c1402d8c --- /dev/null +++ b/docs/modules/sample.rst @@ -0,0 +1,44 @@ +********************* +Sampling (``sample``) +********************* + +The ``sample`` module contains the main functions for sampling binary systems. + +Initial binary tables +--------------------- + +.. automodapi:: cosmic.sample.initialbinarytable + :no-inheritance-diagram: + :no-heading: + +.. automodapi:: cosmic.sample.initialcmctable + :no-inheritance-diagram: + :no-heading: + +Independent sampler +------------------- + +.. automodapi:: cosmic.sample.sampler.independent + :no-inheritance-diagram: + :no-heading: + +Multidimensional sampler +------------------------ + +.. automodapi:: cosmic.sample.sampler.multidim + :no-inheritance-diagram: + :no-heading: + +CMC related functions +--------------------- + +.. automodapi:: cosmic.sample.sampler.cmc + :no-inheritance-diagram: + :no-heading: + +.. automodapi:: cosmic.sample.cmc.elson + :no-inheritance-diagram: + +.. automodapi:: cosmic.sample.cmc.king + :no-inheritance-diagram: + From 051791f88ce9db3d09a109f1c14177aaacbffd2a Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:49:31 -0400 Subject: [PATCH 05/11] add note about explain_setting --- docs/pages/inifile.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/pages/inifile.rst b/docs/pages/inifile.rst index 78e6a5923..5d1c15639 100644 --- a/docs/pages/inifile.rst +++ b/docs/pages/inifile.rst @@ -31,6 +31,17 @@ How to use this page **Interactive config generator** - it can also be used interactively to generate your very own configuration file or BSE settings dictionary for use in running COSMIC. In each of the following sections you can edit the values of the parameter and the files at the end of the page will update in turn for you to copy. Enjoy configuring COSMIC! +.. tip:: + + If you've forgotten what a parameter does and don't want to open the docs, you can always use the ``explain_setting`` function in the ``utils`` module to get a quick refresher on what a parameter does and what values it can take + + .. code-block:: python + + from cosmic.utils import explain_setting + + explain_setting("kickflag") + + All available settings ====================== From 507d718cfa7ff43b6a58373aee18a5d3d89364da Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:50:19 -0400 Subject: [PATCH 06/11] new api setup in config --- docs/conf.py | 99 ++++++++++++++++++++-------------------------------- 1 file changed, 37 insertions(+), 62 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 6fc28622b..d70dca98e 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -27,15 +27,6 @@ sys.path.insert(0, os.path.abspath('.')) # -- General configuration ------------------------------------------------ -# This is the expected signature of the handler for this event, cf doc -def autodoc_skip_member_handler(app, what, name, obj, skip, options): - # Basic approach; you might want a regex instead - return name.startswith("test_") - -# Automatically called by sphinx at startup -def setup(app): - # Connect the autodoc-skip-member event from apidoc to the callback - app.connect('autodoc-skip-member', autodoc_skip_member_handler) # If your documentation needs a minimal Sphinx version, state it here. # needs_sphinx = '1.0' @@ -44,21 +35,20 @@ def setup(app): # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', - 'sphinx.ext.autosummary', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.linkcode', 'sphinx.ext.ifconfig', 'sphinx_automodapi.automodapi', + 'sphinx_automodapi.smart_resolver', 'sphinxcontrib.programoutput', 'matplotlib.sphinxext.plot_directive', - 'IPython.sphinxext.ipython_console_highlighting', - 'IPython.sphinxext.ipython_directive', + #'IPython.sphinxext.ipython_console_highlighting', + #'IPython.sphinxext.ipython_directive', 'numpydoc', 'sphinx_design', 'sphinx_copybutton', @@ -74,8 +64,8 @@ def setup(app): # -- autodoc ------------------------------------ -autoclass_content = 'class' -autodoc_default_flags = ['show-inheritance', 'members', 'inherited-members'] +autoclass_content = 'both' +autodoc_default_flags = ['members', 'inherited-members', 'no-heading', 'no-inheritance-diagram'] # -- sphinx_gallery ----------------------------- @@ -183,11 +173,15 @@ def setup(app): "color-brand-primary": "#3f95e1", "color-brand-content": "#3f95e1", "color-brand-visited": "#3f95e1", + "color-api-name": "#3f95e1", + "color-api-pre-name": "#3f95e1", }, "dark_css_variables": { "color-brand-primary": "#e193ca", "color-brand-content": "#e193ca", - "color-brand-visited": "#e193ca" + "color-brand-visited": "#e193ca", + "color-api-name": "#e193ca", + "color-api-pre-name": "#e193ca", }, "sidebar_hide_name": False, "footer_icons": [ @@ -377,57 +371,38 @@ def setup(app): # -- linkcode ----------------------------------------------------------------- def linkcode_resolve(domain, info): - """Determine the URL corresponding to Python object + """function for linkcode sphinx extension""" + def find_func(): + # find the installed module in sys module + sys_mod = sys.modules[info["module"]] - This code is stolen with thanks from the scipy team. - """ - if domain != 'py': - return None + # use inspect to find the source code and starting line number + names = info["fullname"].split(".") + func = sys_mod + for name in names: + func = getattr(func, name) - modname = info['module'] - fullname = info['fullname'] + print(names, func) + + source_code, line_num = inspect.getsourcelines(func) - submod = sys.modules.get(modname) - if submod is None: - return None + # get the file name from the module + file = info["module"].split(".")[-1] - obj = submod - for part in fullname.split('.'): - try: - obj = getattr(obj, part) - except: - return None - # try and sneak past a decorator - try: - obj = obj.im_func.func_closure[0].cell_contents - except (AttributeError, TypeError): - pass + return file, line_num, line_num + len(source_code) - 1 - try: - fn = inspect.getsourcefile(obj) - except: - fn = None - if not fn: - try: - fn = inspect.getsourcefile(sys.modules[obj.__module__]) - except: - fn = None - if not fn: + # ensure it has the proper domain and has a module + if domain != 'py' or not info['module']: return None + # attempt to cleverly locate the function in the file try: - source, lineno = inspect.findsource(obj) - except: - lineno = None - - if lineno: - linespec = "#L%d" % (lineno + 1) - else: - linespec = "" - - fn = os.path.relpath(fn, start=os.path.dirname(cosmic.__file__)) - if fn.startswith(os.path.pardir): - return None - - return ("http://github.com/COSMIC-PopSynth/COSMIC/tree/%s/COSMIC/%s%s" - % (GWPY_VERSION['full-revisionid'], fn, linespec)) + file, start, end = find_func() + # stitch together a github link with specific lines + filename = "cosmic/{}.py#L{}-L{}".format(file, start, end) + + # if you can't find it in the file then just link to the correct file + except Exception as e: + print(e) + filename = info['module'].replace('.', '/') + '.py' + return f"https://github.com/COSMIC-popsynth/COSMIC/blob/develop/src/{filename}" \ No newline at end of file From 00a6a32911fdc741abc91414974108299b47f44f Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:50:26 -0400 Subject: [PATCH 07/11] add api pages --- docs/modules/output.rst | 9 +++++++++ docs/modules/plotting.rst | 9 +++++++++ docs/modules/sample.rst | 2 ++ docs/modules/utils.rst | 9 +++++++++ docs/pages/api.rst | 3 +++ 5 files changed, 32 insertions(+) create mode 100644 docs/modules/output.rst create mode 100644 docs/modules/plotting.rst create mode 100644 docs/modules/utils.rst diff --git a/docs/modules/output.rst b/docs/modules/output.rst new file mode 100644 index 000000000..5fae1c90b --- /dev/null +++ b/docs/modules/output.rst @@ -0,0 +1,9 @@ +**************************** +Output analysis (``output``) +**************************** + +The ``output`` module contains the main functions for analysing output from COSMIC. + +.. automodapi:: cosmic.output + :no-inheritance-diagram: + :no-heading: \ No newline at end of file diff --git a/docs/modules/plotting.rst b/docs/modules/plotting.rst new file mode 100644 index 000000000..abd080598 --- /dev/null +++ b/docs/modules/plotting.rst @@ -0,0 +1,9 @@ +******************************** +Plotting binaries (``plotting``) +******************************** + +The ``plotting`` module contains the main functions for plotting binaries from COSMIC. + +.. automodapi:: cosmic.plotting + :no-inheritance-diagram: + :no-heading: \ No newline at end of file diff --git a/docs/modules/sample.rst b/docs/modules/sample.rst index 5c1402d8c..2576cde9e 100644 --- a/docs/modules/sample.rst +++ b/docs/modules/sample.rst @@ -38,7 +38,9 @@ CMC related functions .. automodapi:: cosmic.sample.cmc.elson :no-inheritance-diagram: + :no-heading: .. automodapi:: cosmic.sample.cmc.king :no-inheritance-diagram: + :no-heading: diff --git a/docs/modules/utils.rst b/docs/modules/utils.rst new file mode 100644 index 000000000..2f0c9b06f --- /dev/null +++ b/docs/modules/utils.rst @@ -0,0 +1,9 @@ +***************************** +Utility functions (``utils``) +***************************** + +The ``utils`` module contains utility functions for use with COSMIC. + +.. automodapi:: cosmic.utils + :no-inheritance-diagram: + :no-heading: \ No newline at end of file diff --git a/docs/pages/api.rst b/docs/pages/api.rst index ea1b66299..e65aaf354 100644 --- a/docs/pages/api.rst +++ b/docs/pages/api.rst @@ -11,3 +11,6 @@ each module in detail ../modules/evolve ../modules/sample + ../modules/output + ../modules/plotting + ../modules/utils \ No newline at end of file From f8293eda23f74b3a5fdb0c0e65627fa31f55381a Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 11:50:34 -0400 Subject: [PATCH 08/11] fix __all__ statements --- src/cosmic/evolve.py | 2 +- src/cosmic/utils.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/cosmic/evolve.py b/src/cosmic/evolve.py index 2bc015689..b3cc2a3c7 100644 --- a/src/cosmic/evolve.py +++ b/src/cosmic/evolve.py @@ -46,7 +46,7 @@ 'Michael Zevin ', 'digman.12@osu.edu', 'Tom Wagg '] -__all__ = ['Evolve', 'read_tracks_for_METISSE'] +__all__ = ['Evolve', 'read_tracks_for_METISSE', 'populate_tracks'] # Make this match the ordering of all_cols in bpp_array.f diff --git a/src/cosmic/utils.py b/src/cosmic/utils.py index ae4a237a5..f9c1a5b73 100644 --- a/src/cosmic/utils.py +++ b/src/cosmic/utils.py @@ -78,7 +78,7 @@ "read_MIST_track", "read_other_track", "read_eep_directory", - "to_f2py_str_array" + "to_f2py_str_array", "explain_setting", ] From 418eaf5a103dfbec468252abb8b232b6304288ec Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 13:18:16 -0400 Subject: [PATCH 09/11] nicer home page --- docs/index.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 7aef0f475..7b432791f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,10 +3,13 @@ ################## Welcome to COSMIC! ################## -COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. .. raw:: html +

+ COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid binary population synthesis suite with a special focus of generating compact binary populations. +

+
Install COSMIC
Configurations and outputs
@@ -14,6 +17,11 @@ COSMIC (Compact Object Synthesis and Monte Carlo Investigation Code) is a rapid
Evolving binaries
+.. figure:: _static/cosmic-colour.png + :align: center + :width: 50% + :alt: COSMIC logo + .. toctree:: :maxdepth: 2 :hidden: From a453bcfba8f47def469bace39986f343daa41b54 Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 13:19:04 -0400 Subject: [PATCH 10/11] button colours --- docs/pages/inifile.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/inifile.rst b/docs/pages/inifile.rst index 5d1c15639..2bc60c3b4 100644 --- a/docs/pages/inifile.rst +++ b/docs/pages/inifile.rst @@ -17,8 +17,8 @@ The buttons below link to the most recent stable and unstable default inifiles f .. raw:: html
-
Latest stable INIFILE
-
Latest development INIFILE
+
Latest stable INIFILE
+
Latest development INIFILE
From 4cd3c2890e60c953295cea0b75f659e9084d5494 Mon Sep 17 00:00:00 2001 From: Tom Wagg Date: Fri, 29 May 2026 14:17:56 -0400 Subject: [PATCH 11/11] fix errant print statements --- docs/conf.py | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index d70dca98e..90e373e09 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -47,8 +47,8 @@ 'sphinx_automodapi.smart_resolver', 'sphinxcontrib.programoutput', 'matplotlib.sphinxext.plot_directive', - #'IPython.sphinxext.ipython_console_highlighting', - #'IPython.sphinxext.ipython_directive', + 'IPython.sphinxext.ipython_console_highlighting', + 'IPython.sphinxext.ipython_directive', 'numpydoc', 'sphinx_design', 'sphinx_copybutton', @@ -382,8 +382,6 @@ def find_func(): for name in names: func = getattr(func, name) - print(names, func) - source_code, line_num = inspect.getsourcelines(func) # get the file name from the module @@ -403,6 +401,5 @@ def find_func(): # if you can't find it in the file then just link to the correct file except Exception as e: - print(e) filename = info['module'].replace('.', '/') + '.py' return f"https://github.com/COSMIC-popsynth/COSMIC/blob/develop/src/{filename}" \ No newline at end of file