From 2c6df7431326b9638cc78f6cd578a801ff4578f6 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 15:52:28 -0700 Subject: [PATCH 01/12] bump up setup version --- .github/workflows/ci.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6e4fa4a..66d3396 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -31,7 +31,7 @@ jobs: working-directory: ${{github.workspace}} steps: - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v5 with: python-version: ${{matrix.python-version}} - name: Install dependencies @@ -56,7 +56,7 @@ jobs: working-directory: ${{github.workspace}} steps: - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v5 with: python-version: ${{matrix.python-version}} - name: Install dependencies @@ -86,7 +86,7 @@ jobs: working-directory: ${{github.workspace}} steps: - uses: actions/checkout@v4 - - uses: actions/setup-python@v4 + - uses: actions/setup-python@v5 with: python-version: ${{matrix.python-version}} - uses: gerlero/setup-openfoam@v1 From d3137b1af1e2b31833dff47c8e708652ade55347 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 17:04:54 -0700 Subject: [PATCH 02/12] add boilerplate read the docs --- .github/workflows/docs_pages.yml | 45 ++++++++++ docs/Makefile | 29 ++++++ docs/make.bat | 35 ++++++++ docs/source/_templates/layout.html | 31 +++++++ docs/source/_templates/notused_packages.rst_t | 52 +++++++++++ docs/source/acknowledgments.rst | 22 +++++ docs/source/conf.py | 88 +++++++++++++++++++ docs/source/contribute.rst | 22 +++++ docs/source/index.rst | 20 +++++ docs/source/meshing.rst | 22 +++++ docs/source/postprocess.rst | 22 +++++ docs/source/preprocess.rst | 22 +++++ docs/source/quickstart.rst | 22 +++++ docs/source/references.rst | 22 +++++ 14 files changed, 454 insertions(+) create mode 100644 .github/workflows/docs_pages.yml create mode 100644 docs/Makefile create mode 100644 docs/make.bat create mode 100644 docs/source/_templates/layout.html create mode 100644 docs/source/_templates/notused_packages.rst_t create mode 100644 docs/source/acknowledgments.rst create mode 100644 docs/source/conf.py create mode 100644 docs/source/contribute.rst create mode 100644 docs/source/index.rst create mode 100644 docs/source/meshing.rst create mode 100644 docs/source/postprocess.rst create mode 100644 docs/source/preprocess.rst create mode 100644 docs/source/quickstart.rst create mode 100644 docs/source/references.rst diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml new file mode 100644 index 0000000..cbfc15c --- /dev/null +++ b/.github/workflows/docs_pages.yml @@ -0,0 +1,45 @@ +name: BiRD-documentation + +on: + push: + branches: [ sphinx ] + paths: + - 'docs/**' + - '.github/workflows/docs_pages.yml' + +jobs: + + build_docs: + runs-on: ubuntu-latest + env: + GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }} + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: 3.10 + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install sphinx sphinx_rtd_theme sphinx-autoapi + + - name: Build documentation + run: | + cd docs + make html + + - name: deploy + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html + force_orphan: true + full_commit_message: ${{ github.event.head_commit.message }} + + diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f6d7249 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,29 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + rm -rf _build + rm -rf source/_autosummary + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +github: html + -git branch -D gh-pages + -git push origin --delete gh-pages + ghp-import -n -b gh-pages -m "Update documentation" ./_build/html + git checkout gh-pages + git push --set-upstream origin gh-pages + git checkout ${BRANCH} diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..7843185 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=_build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 0000000..68fb29a --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,31 @@ +{% extends "!layout.html" %} + +{% block menu %} + {{ super() }} +

+ Indices +

+ + + {% if menu_links %} +

+ External links +

+ + {% endif %} +{% endblock %} + +{% block htmltitle %} + {% if title == '' or title == 'Home' %} + {{ docstitle|e }} + {% else %} + {{ title|striptags|e }}{{ titlesuffix }} + {% endif %} +{% endblock %} diff --git a/docs/source/_templates/notused_packages.rst_t b/docs/source/_templates/notused_packages.rst_t new file mode 100644 index 0000000..bc8412c --- /dev/null +++ b/docs/source/_templates/notused_packages.rst_t @@ -0,0 +1,52 @@ +{%- macro automodule(modname, options) -%} +.. automodule:: {{ modname }} +{%- for option in options %} + :{{ option }}: +{%- endfor %} +{%- endmacro %} + +{%- macro toctree(docnames) -%} +.. toctree:: + :maxdepth: {{ maxdepth }} +{% for docname in docnames %} + {{ docname }} +{%- endfor %} +{%- endmacro %} + +{%- if is_namespace %} +{{- [pkgname, "namespace"] | join(" ") | e | heading }} +{% else %} +{{- [pkgname, "package"] | join(" ") | e | heading }} +{% endif %} + +{%- if is_namespace %} +.. py:module:: {{ pkgname }} +{% endif %} + +{%- if modulefirst and not is_namespace %} +{{ automodule(pkgname, automodule_options) }} +{% endif %} + +{%- if subpackages %} +Subpackages +----------- + +{{ toctree(subpackages) }} +{% endif %} + +{%- if submodules %} +Submodules +---------- +{% if separatemodules %} +{{ toctree(submodules) }} +{% else %} +{%- for submodule in submodules %} +{% if show_headings %} +{{- [submodule, "module"] | join(" ") | e | heading(2) }} +{% endif %} +{{ automodule(submodule, automodule_options) }} +{% endfor %} +{%- endif %} +{%- endif %} + +# https://github.com/sphinx-doc/sphinx/blob/master/sphinx/templates/apidoc diff --git a/docs/source/acknowledgments.rst b/docs/source/acknowledgments.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/acknowledgments.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000..d6fd22d --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,88 @@ +# Configuration file for the Sphinx documentation builder. +import os +import sys +# Need this so sphinx can find lumache.py. Change is .py files are elsewhere than root. +sys.path.insert(0, os.path.abspath('../..')) +sys.path.insert(0, os.path.abspath('../../bird')) + +here = os.path.abspath(os.path.dirname(__file__)) + +with open(os.path.join(here, '..', '..', "bird", "version.py"), encoding="utf-8") as f: + version = f.read() +version = version.split("=")[-1].strip().strip('"').strip("'") + +# -- Project information + +project = "Bio Reactor Design (BiRD)" +copyright = '2024' +author = 'NREL' + +release = version +version = version + +# -- General configuration + +extensions = [ + 'sphinx.ext.duration', + 'sphinx.ext.doctest', + 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', + 'sphinx.ext.intersphinx', +# 'autoapi.extension', +# 'sphinxcontrib.apidoc', +] + +#autoapi_type = 'python' +#autoapi_dirs = ['../../bird'] + +#apidoc_module_dir = '../../src' +#apidoc_output_dir = '.' +#apidoc_excluded_paths = ['tests'] +#apidoc_separate_modules = True + +intersphinx_mapping = { + 'python': ('https://docs.python.org/3/', None), + 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), +} +intersphinx_disabled_domains = ['std'] + +templates_path = ['_templates'] + +# -- Options for HTML output + +html_theme = 'sphinx_rtd_theme' + +# -- Options for EPUB output +epub_show_urls = 'footnote' + +html_context = { + "display_github": True, # Integrate GitHub + "github_repo": "NREL/BioReactorDesign", # Repo name + "github_version": "main", # Version + "conf_py_path": "docs/source/", # Path in the checkout to the docs root +} + +# -- Options for HTML output ------------------------------------------------- + +html_short_title = "bird-doc" +html_show_sourcelink = False +html_show_sphinx = True +html_show_copyright = True + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] +repository_url = f"https://github.com/NREL/BioReactorDesign" +html_context = { + "menu_links": [ + ( + ' Source Code', + repository_url, + ), + ( + ' License', + f"{repository_url}/blob/main/LICENSE", + ), + ], +} diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/contribute.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000..f0b8145 --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,20 @@ +Bio Reactor Design (BiRD) +=================================== + +`BiRD` is ... + +.. note:: + + This project is under active development. + + +.. toctree:: + :hidden: + + quickstart + meshing + preprocess + postprocess + contribute + references + acknowledgments diff --git a/docs/source/meshing.rst b/docs/source/meshing.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/meshing.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/postprocess.rst b/docs/source/postprocess.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/postprocess.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/preprocess.rst b/docs/source/preprocess.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/preprocess.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + diff --git a/docs/source/references.rst b/docs/source/references.rst new file mode 100644 index 0000000..0c5c3a9 --- /dev/null +++ b/docs/source/references.rst @@ -0,0 +1,22 @@ +Quick start +===== + + +.. _installation: + +Installation +------------ + +To use the functions include this import: + +.. code-block:: console + + import bird + +Examples +---------------- + +For example: + +>>> import bird + From ddc5f1ab960a597808e79bf6af3b39a9e1169c3e Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 17:06:50 -0700 Subject: [PATCH 03/12] fix python version --- .github/workflows/docs_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml index cbfc15c..74dd293 100644 --- a/.github/workflows/docs_pages.yml +++ b/.github/workflows/docs_pages.yml @@ -21,7 +21,7 @@ jobs: - name: Set up Python uses: actions/setup-python@v5 with: - python-version: 3.10 + python-version: '3.10' cache: 'pip' - name: Install dependencies From 3810c139839d127a1604a921c4cfc1cd6672139f Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 18:23:21 -0700 Subject: [PATCH 04/12] add meshing and installation guides --- docs/source/meshing.rst | 235 +++++++++++++++++++++++++++++++++++-- docs/source/quickstart.rst | 55 +++++++-- 2 files changed, 274 insertions(+), 16 deletions(-) diff --git a/docs/source/meshing.rst b/docs/source/meshing.rst index 0c5c3a9..48ecfbc 100644 --- a/docs/source/meshing.rst +++ b/docs/source/meshing.rst @@ -1,22 +1,239 @@ -Quick start +Meshing ===== -.. _installation: +.. _stir_tank: -Installation +Generate stirred tank reactor mesh ------------ -To use the functions include this import: +Generate a ``blockMeshDict`` with .. code-block:: console - import bird + inp=bird/meshing/stirred_tank_mesh_templates/base_tank/tank_par.yaml + out=bird/meshing/stirred_tank_case_templates/base/system/blockMeshDict -Examples ----------------- + python applications/write_stirred_tank_mesh.py -i $inp -o $out -For example: +Then activate openFoam environment and mesh with + +.. code-block:: console + + blockMesh -dict system/blockMeshDict + stitchMesh -perfect -overwrite inside_to_hub inside_to_hub_copy + stitchMesh -perfect -overwrite hub_to_rotor hub_to_rotor_copy + transformPoints "rotate=((0 0 1)(0 1 0))" + +Visualize mesh in Paraview + +.. _fig:stirredtank: + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/stirred_tank.png + :width: 70% + :align: center + :name: fig-str + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/stirred_tank.png + :alt: Stirred-tank reactor + +Related tutorial +^^^^^^^^^^^^^^^ + +- ``tutorial_cases/stirred_tank`` + + + +.. _block_cyl: + +Block cylindrical meshing +------------ + +Generates ``system/blockMeshDict`` + +.. code-block:: console + root=`pwd` + caseFolder=bird/meshing/block_cyl_cases_templates/case + mesh_temp=bird/meshing/block_cyl_mesh_templates/sideSparger + + python applications/write_block_cyl_mesh.py -i $mesh_temp/input.json -t $mesh_temp/topology.json -o $caseFolder/system + +Then activate openFoam environment and mesh with + +.. code-block:: console + + cd $caseFolder + blockMesh + transformPoints "scale=(0.001 0.001 0.001)" + transformPoints "rotate=((0 0 1) (0 1 0))" + cd $root + +Visualize mesh in Paraview + +.. _fig:sidesparger: + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/3dsparger.png + :width: 50% + :align: center + :name: fig-sidesparger + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/3dsparger.png + :alt: Reactor with a side sparger + +How to change the dimensions or mesh refinement? +^^^^^^^^^^^^^^^ + +All dimensions and mesh are controlled by the input file ``input.json``. +The input file can also be in ``.yaml`` format. The parser will decide the file format based on its extension. +See ``bird/meshing/block_cyl_mesh_templates/baseColumn/`` for an example of ``.yaml`` + +How to change the arrangement of concentric cylinders? +^^^^^^^^^^^^^^^ + +The block topology is controlled by the ``topology.json`` +We recomment always working with a schematic. Here is the schematic for this case + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematic.png + :width: 50% + :align: center + :name: fig-schematic + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematic.png + :alt: Side sparger schematic + + +The purple blocks are walls (not meshed) and the white blocks are fluid blocks (meshed). The symmetry axis is indicated as a dashed line + +In the ``topology.json``, the purple blocks are defined as + +.. code-block:: json + + "Walls": { + "Support": [ + {"R": 0, "L": 3}, + {"R": 1, "L": 3} + ], + "Sparger": [ + {"R": 0, "L": 2}, + {"R": 1, "L": 2}, + {"R": 2, "L": 2} + ] + } + + +How to change boundaries? +^^^^^^^^^^^^^^^ + +Boundaries are defined with three types, ``top``, ``bottom`` and ``lateral`` + +In the case of sparger walls shown below with the red lines + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerWalls.png + :width: 50% + :align: center + :name: fig-schematicwalls + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerWalls.png + :alt: Wall side sparger schematic + + +the boundary is defined in the ``topology.json`` as + +.. code-block:: json + + "Boundary": { + "wall_sparger":[ + {"type": "bottom", "Rmin": 2, "Rmax": 2, "Lmin": 2, "Lmax": 3}, + {"type": "top", "Rmin": 0, "Rmax": 0, "Lmin": 1, "Lmax": 2}, + {"type": "top", "Rmin": 1, "Rmax": 1, "Lmin": 1, "Lmax": 2}, + {"type": "top", "Rmin": 2, "Rmax": 2, "Lmin": 1, "Lmax": 2} + ], + +For the side sparger, the inlet is shown below with the red line + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png + :width: 50% + :align: center + :name: fig-schematicinlet + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/schematicSpargerInlet.png + :alt: Inlet side sparger schematic + +the boundary is defined in the ``topology.json`` as + +.. code-block:: json + + "Boundary": { + "inlet": [ + {"type": "lateral", "Rmin": 2, "Rmax": 3, "Lmin": 2, "Lmax": 2} + ], + + + +Related tutorials +^^^^^^^^^^^^^^^ + +- ``tutorial_cases/side_sparger`` +- ``tutorial_cases/bubble_column_20L`` + + +Block rectangular meshing +------------ + +Generates ``system/blockMeshDict`` + +.. code-block:: console + + root=`pwd` + caseFolder=bird/meshing/block_rect_cases_templates/case + mesh_temp=bird/meshing/block_rect_mesh_templates/loopReactor + + python applications/write_block_rect_mesh.py -i $mesh_temp/input.json -o $caseFolder/system + +Then activate openFoam environment and mesh with + +.. code-block:: console + + cd $caseFolder + blockMesh + cd $root + +Visualize mesh in Paraview + +.. _fig:loop_reactor: + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react.png + :width: 80% + :align: center + :name: fig-loopreactor + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react.png + :alt: Loop reactor + + +How to change the block rectangular geometry? +^^^^^^^^^^^^^^^ +The geometry of the block cylindrical mesh is defined within a 3D domain (X,Y,Z). The blocks that represent the fluid domain are a subset of a block rectangular background domain. The fluid blocks are defined using the geometry corners. For the mesh shown above, the geometry corners are the red blocks shown below + +.. _fig:loop_reactor_schematic: + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_schematic.png + :width: 80% + :align: center + :name: fig-loopreactor-schematic + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react_schematic.png + :alt: Loop reactor schematic + + +The corners are defined in the ``input.json`` + +.. code-block:: json + + "Geometry": { + "Fluids": [ + [ [0,0,0], [9,0,0], [9,0,4], [0,0,4] ], + [ [0,1,4], [0,4,4], [0,4,0], [0,1,0] ] + ] + } + + +Related tutorials +^^^^^^^^^^^^^^^ +- ``tutorial_cases/loop_reactor_mixing`` +- ``tutorial_cases/loop_reactor_reacting`` ->>> import bird diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 0c5c3a9..76888b7 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -2,21 +2,62 @@ Quick start ===== -.. _installation: +.. _installation_dev: -Installation +Installation of python package for developers ------------ -To use the functions include this import: .. code-block:: console - import bird + conda create --name bird python=3.10 + conda activate bird + git clone https://github.com/NREL/BioReactorDesign.git + cd BioReactorDesign + pip install -e . -Examples +.. _installation_users: + +Installation of python package for users +------------ + + +.. code-block:: console + + conda create --name bird python=3.10 + conda activate bird + pip install nrel-bird + + +.. _installation_of: + +Installation of BiRD OpenFOAM solver (for developers and users) +------------ + +1. Activate your OpenFOAM-9 environment + +.. code-block:: console + + source /etc/rc + +2. Compile the solver + +.. code-block:: console + + cd OFsolvers/birdmultiphaseEulerFoam/ + ./Allwmake + + + +Run an example ---------------- -For example: +1. Follow the steps to install the python package (see either the :ref:`Installation section for developers` or the :ref:`Installation section for users`) +2. Follow the steps to install the BiRD OpenFOAM solver (see the :ref:`Installation section for the solver`) +3. Check that you can run any of the tutorial cases, for example + +.. code-block:: console ->>> import bird + cd tutorial_cases/bubble_column_20L + bash run.sh From aace4099c7521135cf632c8702b4850d95f77d91 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:05:43 -0700 Subject: [PATCH 05/12] refactor entire doc --- docs/source/_templates/layout.html | 7 ---- docs/source/acknowledgments.rst | 20 ++--------- docs/source/conf.py | 3 +- docs/source/contribute.rst | 23 +++++++------ docs/source/meshing.rst | 5 +-- docs/source/postprocess.rst | 51 +++++++++++++++++++++++----- docs/source/preprocess.rst | 48 ++++++++++++++++++++++----- docs/source/references.rst | 53 ++++++++++++++++++++---------- 8 files changed, 136 insertions(+), 74 deletions(-) diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 68fb29a..2ecba02 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -2,13 +2,6 @@ {% block menu %} {{ super() }} -

- Indices -

- {% if menu_links %}

diff --git a/docs/source/acknowledgments.rst b/docs/source/acknowledgments.rst index 0c5c3a9..3471709 100644 --- a/docs/source/acknowledgments.rst +++ b/docs/source/acknowledgments.rst @@ -1,22 +1,6 @@ -Quick start +Acknowledgments ===== +This work was authored by the National Renewable Energy Laboratory (NREL), operated by Alliance for Sustainable Energy, LLC, for the U.S. Department of Energy (DOE) under Contract No. DE-AC36-08GO28308. This work was supported by funding from DOE Bioenergy Technologies Office (BETO) `CO2RUe consortium `_. The research was performed using computational resources sponsored by the Department of Energy's Office of Energy Efficiency and Renewable Energy and located at the National Renewable Energy Laboratory. The views expressed in the article do not necessarily represent the views of the DOE or the U.S. Government. The U.S. Government retains and the publisher, by accepting the article for publication, acknowledges that the U.S. Government retains a nonexclusive, paid-up, irrevocable, worldwide license to publish or reproduce the published form of this work, or allow others to do so, for U.S. Government purposes. -.. _installation: - -Installation ------------- - -To use the functions include this import: - -.. code-block:: console - - import bird - -Examples ----------------- - -For example: - ->>> import bird diff --git a/docs/source/conf.py b/docs/source/conf.py index d6fd22d..f4c760a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -28,10 +28,11 @@ 'sphinx.ext.autodoc', 'sphinx.ext.autosummary', 'sphinx.ext.intersphinx', +# 'sphinxcontrib.bibtex', # 'autoapi.extension', # 'sphinxcontrib.apidoc', ] - +#bibtex_bibfiles = ["references.bib"] #autoapi_type = 'python' #autoapi_dirs = ['../../bird'] diff --git a/docs/source/contribute.rst b/docs/source/contribute.rst index 0c5c3a9..e9b7782 100644 --- a/docs/source/contribute.rst +++ b/docs/source/contribute.rst @@ -1,22 +1,25 @@ -Quick start +Contributing ===== +We welcome pull requests from anybody! -.. _installation: - -Installation +Formatting ------------ -To use the functions include this import: +Code formatting and import sorting are done automatically with ``black`` and ``isort``. + +You can automatically enforce the formatting guidelines with .. code-block:: console - import bird + pip install black isort + bash fixFormat.sh -Examples ----------------- +Spelling is checked but not automatically fixed using ``codespell`` -For example: ->>> import bird +Test +------------ +Please ensure your contribution passes the tests in ``tests`` + diff --git a/docs/source/meshing.rst b/docs/source/meshing.rst index 48ecfbc..4c02113 100644 --- a/docs/source/meshing.rst +++ b/docs/source/meshing.rst @@ -51,6 +51,7 @@ Block cylindrical meshing Generates ``system/blockMeshDict`` .. code-block:: console + root=`pwd` caseFolder=bird/meshing/block_cyl_cases_templates/case mesh_temp=bird/meshing/block_cyl_mesh_templates/sideSparger @@ -211,11 +212,11 @@ The geometry of the block cylindrical mesh is defined within a 3D domain (X,Y,Z) .. _fig:loop_reactor_schematic: -.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_schematic.png +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/bird/meshing/block_rect_mesh_templates/loopReactor/loop_schematic.png :width: 80% :align: center :name: fig-loopreactor-schematic - :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/loop_react_schematic.png + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/bird/meshing/block_rect_mesh_templates/loopReactor/loop_schematic.png :alt: Loop reactor schematic diff --git a/docs/source/postprocess.rst b/docs/source/postprocess.rst index 0c5c3a9..db98598 100644 --- a/docs/source/postprocess.rst +++ b/docs/source/postprocess.rst @@ -1,22 +1,55 @@ -Quick start +Postprocess ===== -.. _installation: +.. _early_pred: -Installation + +Perform early prediction ------------ -To use the functions include this import: .. code-block:: console - import bird + python applications/early_prediction.py -df bird/postprocess/data_early + +Generates + +.. container:: figures-early-pred + + .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/early_det.png + :width: 70% + :align: center + :alt: Determinisitc early prediction + + .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/early_uq.png + :width: 70% + :align: center + :alt: Uncertainty-aware early prediction + + +Plot conditional means +------------ + +.. code-block:: console + + python applications/compute_conditional_mean.py -f bird/postprocess/data_conditional_mean -avg 2 + +Generates (among others) + +.. container:: figures-cond-mean + + .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/gh_cond_mean.png + :width: 70% + :align: center + :alt: Height-conditional gas holdup + + .. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/co2g_cond_mean.png + :width: 70% + :align: center + :alt: Height-conditional CO2 gas fraction -Examples ----------------- + -For example: ->>> import bird diff --git a/docs/source/preprocess.rst b/docs/source/preprocess.rst index 0c5c3a9..2ad629b 100644 --- a/docs/source/preprocess.rst +++ b/docs/source/preprocess.rst @@ -1,22 +1,52 @@ -Quick start +Preprocess ===== -.. _installation: +.. _stl_patch: -Installation +Generate STL patch mesh ------------ -To use the functions include this import: +Boundaries may be specified with ``surfaceToPatch`` utility in OpenFOAM, based on STL files that can be generated with .. code-block:: console - import bird + python applications/write_stl_patch.py -v -Examples ----------------- -For example: +The verbose flag (``-v``) generates a plot of the stl mesh + +.. _fig:stl_patch: + +.. figure:: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/simpleOutput.png + :width: 70% + :align: center + :name: fig-stl-patch + :target: https://raw.githubusercontent.com/NREL/BioReactorDesign/main/assets/simpleOutput.png + :alt: STL patch + +How to change the set of shapes in the boundary patch? +^^^^^^^^^^^^^^^ + +Edit the json files read when generating the mesh. In the case ``tutorial_cases/loop_reactor_mixing`` the boundary condition ``inlets`` consists of 3 discs + +.. code-block:: json + + { + "inlets": [ + {"type": "circle", "centx": 5.0, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50}, + {"type": "circle", "centx": 2.5, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50}, + {"type": "circle", "centx": 7.5, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50} + ], + } + + +Related tutorials +^^^^^^^^^^^^^^^ + +- ``tutorial_cases/loop_reactor_mixing`` +- ``tutorial_cases/loop_reactor_reacting`` +- ``tutorial_cases/bubble_column_20L`` + ->>> import bird diff --git a/docs/source/references.rst b/docs/source/references.rst index 0c5c3a9..88ce3b5 100644 --- a/docs/source/references.rst +++ b/docs/source/references.rst @@ -1,22 +1,39 @@ -Quick start +References ===== +Software record `SWR 24-35 `_ + +To cite BiRD, please use these articles on `CO2 interphase mass transfer (open access) `_ on `aerobic bioreactors `_ and on `butanediol synthesis `_ + + +.. code-block:: console + + @article{hassanaly2024inverse, + title={Bayesian calibration of bubble size dynamics applied to \ce{CO2} gas fermenters}, + author={Hassanaly, Malik and Parra-Alvarez, John M. and Rahimi, Mohammad J. and Sitaraman, Hariswaran}, + journal={Under Review}, + year={2024}, + } + + + @article{rahimi2018computational, + title={Computational fluid dynamics study of full-scale aerobic bioreactors: Evaluation of gas--liquid mass transfer, oxygen uptake, and dynamic oxygen distribution}, + author={Rahimi, Mohammad J and Sitaraman, Hariswaran and Humbird, David and Stickel, Jonathan J}, + journal={Chemical Engineering Research and Design}, + volume={139}, + pages={283--295}, + year={2018}, + publisher={Elsevier} + } + + @article{sitaraman2023reacting, + title={A reacting multiphase computational flow model for 2, 3-butanediol synthesis in industrial-scale bioreactors}, + author={Sitaraman, Hariswaran and Lischeske, James and Lu, Yimin and Stickel, Jonathan}, + journal={Chemical Engineering Research and Design}, + volume={197}, + pages={38--52}, + year={2023}, + publisher={Elsevier} + } -.. _installation: - -Installation ------------- - -To use the functions include this import: - -.. code-block:: console - - import bird - -Examples ----------------- - -For example: - ->>> import bird From 91e4083e09ab4995900ead741cd3432d85a0a60c Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:10:31 -0700 Subject: [PATCH 06/12] simplify readme --- README.md | 331 +------------------------------------ docs/source/quickstart.rst | 5 +- 2 files changed, 6 insertions(+), 330 deletions(-) diff --git a/README.md b/README.md index 5b082b6..b7d346c 100644 --- a/README.md +++ b/README.md @@ -34,336 +34,9 @@ pip install nrel-bird 2. cd `OFsolvers/birdmultiphaseEulerFoam/` 3. `./Allwmake` -The same steps are done in the `ci.yml` (under `Test-OF - Compile solver`) which can be used as a reference. -However, note that `ci.yml` compiles the solver in debug mode which is not suitable for production. +## Documentation -We provide a new drag model `Grace`, a new interfacial composition model `Higbie` and various other models which magnitude can be controlled via an efficiency factor (see [this paper](https://arxiv.org/pdf/2404.19636) for why efficiency factors are useful). - - -## Meshing - -### Generate Stir tank mesh - -```bash -inp=bird/meshing/stirred_tank_mesh_templates/base_tank/tank_par.yaml -out=bird/meshing/stirred_tank_case_templates/base/system/blockMeshDict - -python applications/write_stirred_tank_mesh.py -i $inp -o $out -``` - -Generates a blockMeshDict - -Then activate openFoam environment (tested with OpenFoam9) and mesh with - -```bash -blockMesh -dict system/blockMeshDict -stitchMesh -perfect -overwrite inside_to_hub inside_to_hub_copy -stitchMesh -perfect -overwrite hub_to_rotor hub_to_rotor_copy -transformPoints "rotate=((0 0 1)(0 1 0))": -``` -Mesh visualized in Paraview - -

- -

- -#### Related tutorial - -`tutorial_cases/stirred_tank` - - -### Block cylindrical meshing - -Generates `blockMeshDict` in `system` - -```bash -root=`pwd` -caseFolder=bird/meshing/block_cyl_cases_templates/case -mesh_temp=bird/meshing/block_cyl_mesh_templates/sideSparger - -python applications/write_block_cyl_mesh.py -i $mesh_temp/input.json -t $mesh_temp/topology.json -o $caseFolder/system -``` - -Then activate openFoam environment (tested with OpenFoam9) and mesh with - -```bash -cd $caseFolder -blockMesh -transformPoints "scale=(0.001 0.001 0.001)" -transformPoints "rotate=((0 0 1) (0 1 0))" -cd $root -``` - -Will generate this - -

- -

- - -#### How to change the dimensions or mesh refinement - -All dimensions and mesh are controlled by the input file `input.json`. -The input file can also be in `.yaml` format. The parser will decide the file format based on its extension. -See `bird/meshing/block_cyl_mesh_templates/baseColumn/` for an example of `.yaml` - -#### How to change the arrangement of concentric cylinders - -The block topology is controlled by the `topology.json` -Always work with a schematic. Here is the schematic for this case - -

- -

- -The purple blocks are walls (not meshed) and the white blocks are fluid blocks (meshed). The symmetry axis is indicated as a dashed line - -In the `topology.json`, the purple blocks are defined as - -``` -"Walls": { - "Support": [ - {"R": 0, "L": 3}, - {"R": 1, "L": 3} - ], - "Sparger": [ - {"R": 0, "L": 2}, - {"R": 1, "L": 2}, - {"R": 2, "L": 2} - ] - } -``` - -#### How to change boundaries - -Boundaries are defined with three types, `top`, `bottom` and `lateral` - -In the case of sparger walls shown below with the red lines -

- -

- -the boundary is defined in the `topology.json` as -``` -"Boundary": { - "wall_sparger":[ - {"type": "bottom", "Rmin": 2, "Rmax": 2, "Lmin": 2, "Lmax": 3}, - {"type": "top", "Rmin": 0, "Rmax": 0, "Lmin": 1, "Lmax": 2}, - {"type": "top", "Rmin": 1, "Rmax": 1, "Lmin": 1, "Lmax": 2}, - {"type": "top", "Rmin": 2, "Rmax": 2, "Lmin": 1, "Lmax": 2} - ], -... -``` - -In the case of sparger inlet shown below with the red line -

- -

- -the boundary is defined in the `topology.json` as -``` -"Boundary": { - "inlet": [ - {"type": "lateral", "Rmin": 2, "Rmax": 3, "Lmin": 2, "Lmax": 2} - ], -... -``` - -#### Manual - -``` -usage: write_block_cyl_mesh.py [-h] -i -t -o - -Block cylindrical meshing - -options: - -h, --help show this help message and exit - -i , --input_file Input file for meshing and geometry parameters - -t , --topo_file Block description of the configuration - -o , --output_folder - Output folder for blockMeshDict -``` - -#### Related tutorials - -- `tutorial_cases/side_sparger` -- `tutorial_cases/bubble_column_20L` - - -### Block rectangular meshing - -Generates `blockMeshDict` in `system` - -```bash -root=`pwd` -caseFolder=bird/meshing/block_rect_cases_templates/case -mesh_temp=bird/meshing/block_rect_mesh_templates/loopReactor - -python applications/write_block_rect_mesh.py -i $mesh_temp/input.json -o $caseFolder/system -``` - -Then activate openFoam environment (tested with OpenFoam9) and mesh with - -```bash -cd $caseFolder -blockMesh -cd $root -``` - -Will generate this - -

- -

- - -#### How to change the block rectangular geometry - -The geometry of the block cylindrical mesh is defined within a 3D domain (X,Y,Z). The blocks that represent the fluid domain are a subset of a block rectangular background domain. The fluid blocks are defined using the geometry corners. For the mesh shown above, the geometry corners are the red blocks shown below - -

- -

- -The corners are defined in the `input.json` -``` -"Geometry": { - "Fluids": [ - [ [0,0,0], [9,0,0], [9,0,4], [0,0,4] ], - [ [0,1,4], [0,4,4], [0,4,0], [0,1,0] ] - ] -} -... -``` - -#### Related tutorials - -- `tutorial_cases/loop_reactor_mixing` -- `tutorial_cases/loop_reactor_reacting` - -## Preprocess -### Generate STL mesh - -Boundaries may be specified with `surfaceToPatch` utility in OpenFOAM, based on STL files that can be generated with - -`python applications/write_stl_patch.py -v` - -Generates - -

- -

- - -To see how to use this on an actual case see `tutorial_cases/loop_reactor_mixing` and `tutorial_cases/loop_reactor_reacting` - -### Manual - -``` -usage: write_stl_patch.py [-h] [-i] [-v] - -Generate boundary patch - -options: - -h, --help show this help message and exit - -i , --input Boundary patch Json input - -v, --verbose plot on screen -``` -### How to change the set of shapes in the boundary patch - -Edit the json files read when generating the mesh. In the case below, the boundary condition `inlets` consists of 3 discs - -``` -{ - "inlets": [ - {"type": "circle", "centx": 5.0, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50}, - {"type": "circle", "centx": 2.5, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50}, - {"type": "circle", "centx": 7.5, "centy": 0.0, "centz": 0.5, "radius": 0.4, "normal_dir": 1,"nelements": 50} - ], -} -... -``` -### Related tutorials - -- `tutorial_cases/bubble_column_20L` -- `tutorial_cases/loop_reactor_mixing` -- `tutorial_cases/loop_reactor_reacting` - - -## Postprocess - -### Perform early prediction - -`python applications/early_prediction.py -df bird/postprocess/data_early` - -Generates - -

- - -

- -#### Manual - -``` -usage: early_prediction.py [-h] -df [-func] - -Early prediction - -options: - -h, --help show this help message and exit - -df , --dataFolder Data folder containing multiple QOI time histories - -func , --functionalForm - functional form used to perform extrapolation -``` - - -### Plot conditional means - -`python applications/compute_conditional_mean.py -f bird/postprocess/data_conditional_mean -avg 2` - -Generates (among others) - -

- - -

- - -```bash -usage: compute_conditional_mean.py [-h] -f [-vert] [-avg] [--fl FL [FL ...]] [-n [...]] - -Compute conditional means of OpenFOAM fields - -options: - -h, --help show this help message and exit - -f , --caseFolder caseFolder to analyze - -vert , --verticalDirection - Index of vertical direction - -avg , --windowAve Window Average - --fl FL [FL ...], --field_list FL [FL ...] - List of fields to plot - -n [ ...], --names [ ...] - names of cases -``` - - - -## Formatting [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1?style=flat&labelColor=ef8336)](https://pycqa.github.io/isort/) - -Code formatting and import sorting are done automatically with `black` and `isort`. - -Fix imports and format : `pip install black isort; bash fixFormat.sh` - -Spelling is checked but not automatically fixed using `codespell` +See the [github-pages website](https://nrel.github.io/BioReactorDesign). ## References diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst index 76888b7..d6adf71 100644 --- a/docs/source/quickstart.rst +++ b/docs/source/quickstart.rst @@ -47,7 +47,10 @@ Installation of BiRD OpenFOAM solver (for developers and users) cd OFsolvers/birdmultiphaseEulerFoam/ ./Allwmake - +The same steps are done in the ``ci.yml`` (under ``Test-OF - Compile solver``) which can be used as a reference. +However, note that ``ci.yml`` compiles the solver in debug mode which is not suitable for production. + +We provide a new drag model ``Grace``, a new interfacial composition model ``Higbie`` and various other models which magnitude can be controlled via an efficiency factor (see `this paper `_ for why efficiency factors are useful). Run an example ---------------- From 33735c4acd2d186f9592e78c7171e39727aaef66 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:10:52 -0700 Subject: [PATCH 07/12] remove auto api for now --- .github/workflows/docs_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml index 74dd293..a4129a8 100644 --- a/.github/workflows/docs_pages.yml +++ b/.github/workflows/docs_pages.yml @@ -27,7 +27,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip - pip install sphinx sphinx_rtd_theme sphinx-autoapi + pip install sphinx sphinx_rtd_theme - name: Build documentation run: | From 047646a861f0bcc5f63a622b1b555d4ebe0122e2 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:23:41 -0700 Subject: [PATCH 08/12] populate the landing page --- docs/source/index.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index f0b8145..ab35ffc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,11 +1,22 @@ Bio Reactor Design (BiRD) =================================== -`BiRD` is ... +`BiRD` is a toolbox aimed a facilitating the numerical simulation of bioreactors with OpenFOAM. +The purpose of `BiRD` is + +1. to ensure reproducibility of numerical simulations of bioreactors. +2. to create a suite of test cases that can be used to test different reactor configurations. +3. to facilitate validation of multiphase flow models against several experimental campaigns. +4. to facilitate optimization (geometry and operating conditions) of bioreactors. + +It contains a python module ``bird`` that can be used to generate input files that may be read by OpenFOAM to generate meshes and cases. It can also be used to post process the output of OpenFOAM simulations. + +We also provide a solver ``birdmultiphaseEulerFoam`` that contains custom models added to the base OpenFOAM-v9. + .. note:: - This project is under active development. + This project is under active development. We welcome community contributions and testing! .. toctree:: From 314d89ea30f0eca604b81ac2ae9d0af26c0ee6bc Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:24:53 -0700 Subject: [PATCH 09/12] format --- .github/linters/.codespellrc | 2 +- docs/source/conf.py | 65 +++++++++++++++++++----------------- 2 files changed, 35 insertions(+), 32 deletions(-) diff --git a/.github/linters/.codespellrc b/.github/linters/.codespellrc index c4036fa..a8ac105 100644 --- a/.github/linters/.codespellrc +++ b/.github/linters/.codespellrc @@ -1,3 +1,3 @@ [codespell] -skip = None, .git,OFsolvers,tutorial_cases,experimental_cases,build,__pycache__,data_conditional_mean,Figures,assets +skip = None, .git,OFsolvers,tutorial_cases,experimental_cases,build,_build,__pycache__,data_conditional_mean,Figures,assets ignore-words = .github/linters/.codespell-ignore-words diff --git a/docs/source/conf.py b/docs/source/conf.py index f4c760a..be385be 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,21 +1,24 @@ # Configuration file for the Sphinx documentation builder. import os import sys + # Need this so sphinx can find lumache.py. Change is .py files are elsewhere than root. -sys.path.insert(0, os.path.abspath('../..')) -sys.path.insert(0, os.path.abspath('../../bird')) +sys.path.insert(0, os.path.abspath("../..")) +sys.path.insert(0, os.path.abspath("../../bird")) here = os.path.abspath(os.path.dirname(__file__)) -with open(os.path.join(here, '..', '..', "bird", "version.py"), encoding="utf-8") as f: +with open( + os.path.join(here, "..", "..", "bird", "version.py"), encoding="utf-8" +) as f: version = f.read() version = version.split("=")[-1].strip().strip('"').strip("'") # -- Project information project = "Bio Reactor Design (BiRD)" -copyright = '2024' -author = 'NREL' +copyright = "2024" +author = "NREL" release = version version = version @@ -23,44 +26,44 @@ # -- General configuration extensions = [ - 'sphinx.ext.duration', - 'sphinx.ext.doctest', - 'sphinx.ext.autodoc', - 'sphinx.ext.autosummary', - 'sphinx.ext.intersphinx', -# 'sphinxcontrib.bibtex', -# 'autoapi.extension', -# 'sphinxcontrib.apidoc', + "sphinx.ext.duration", + "sphinx.ext.doctest", + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.intersphinx", + # 'sphinxcontrib.bibtex', + # 'autoapi.extension', + # 'sphinxcontrib.apidoc', ] -#bibtex_bibfiles = ["references.bib"] -#autoapi_type = 'python' -#autoapi_dirs = ['../../bird'] +# bibtex_bibfiles = ["references.bib"] +# autoapi_type = 'python' +# autoapi_dirs = ['../../bird'] -#apidoc_module_dir = '../../src' -#apidoc_output_dir = '.' -#apidoc_excluded_paths = ['tests'] -#apidoc_separate_modules = True +# apidoc_module_dir = '../../src' +# apidoc_output_dir = '.' +# apidoc_excluded_paths = ['tests'] +# apidoc_separate_modules = True intersphinx_mapping = { - 'python': ('https://docs.python.org/3/', None), - 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), + "python": ("https://docs.python.org/3/", None), + "sphinx": ("https://www.sphinx-doc.org/en/master/", None), } -intersphinx_disabled_domains = ['std'] +intersphinx_disabled_domains = ["std"] -templates_path = ['_templates'] +templates_path = ["_templates"] # -- Options for HTML output -html_theme = 'sphinx_rtd_theme' +html_theme = "sphinx_rtd_theme" # -- Options for EPUB output -epub_show_urls = 'footnote' +epub_show_urls = "footnote" html_context = { - "display_github": True, # Integrate GitHub - "github_repo": "NREL/BioReactorDesign", # Repo name - "github_version": "main", # Version - "conf_py_path": "docs/source/", # Path in the checkout to the docs root + "display_github": True, # Integrate GitHub + "github_repo": "NREL/BioReactorDesign", # Repo name + "github_version": "main", # Version + "conf_py_path": "docs/source/", # Path in the checkout to the docs root } # -- Options for HTML output ------------------------------------------------- @@ -73,7 +76,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] repository_url = f"https://github.com/NREL/BioReactorDesign" html_context = { "menu_links": [ From 24c670aff74e0dc0bfd9673bc8070e5d9a8c62d0 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:27:52 -0700 Subject: [PATCH 10/12] prepare for PR --- .github/workflows/docs_pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docs_pages.yml b/.github/workflows/docs_pages.yml index a4129a8..5e86d24 100644 --- a/.github/workflows/docs_pages.yml +++ b/.github/workflows/docs_pages.yml @@ -2,7 +2,7 @@ name: BiRD-documentation on: push: - branches: [ sphinx ] + branches: [ main ] paths: - 'docs/**' - '.github/workflows/docs_pages.yml' From f4f275ef569a15e75d6d38d2c6d115d01127fd42 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:29:14 -0700 Subject: [PATCH 11/12] fix doc link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b7d346c..f931da9 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ pip install nrel-bird ## Documentation -See the [github-pages website](https://nrel.github.io/BioReactorDesign). +See the [nrel.github.io/BioReactorDesign](https://nrel.github.io/BioReactorDesign). ## References From c5b9acd32b2ba23d68a290d10b50580b9d47f211 Mon Sep 17 00:00:00 2001 From: Malik Date: Sun, 15 Dec 2024 19:58:03 -0700 Subject: [PATCH 12/12] add pypi urls --- setup.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setup.py b/setup.py index d1655cb..54b1b67 100644 --- a/setup.py +++ b/setup.py @@ -42,6 +42,10 @@ "data_conditional_mean", ] }, + project_urls={ + "Documentation": "https://nrel.github.io/BioReactorDesign/", + "Repository": "https://github.com/NREL/BioReactorDesign", + }, include_package_data=True, python_requires=">=3.9", install_requires=install_requires,