Merge branch 'main' into jc/stability-analysis

dynamicslab · Mar 20, 2024 · 892d844 · 892d844
2 parents 840d9a6 + e61a732
commit 892d844
Show file tree

Hide file tree

Showing 39 changed files with 816 additions and 576 deletions.
diff --git a/.github/workflows/black.yml b/.github/workflows/black.yml
diff --git a/.github/workflows/ruff.yml b/.github/workflows/ruff.yml
@@ -5,6 +5,22 @@ on: [push, pull_request]
 jobs:
   ruff:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
     steps:
       - uses: actions/checkout@v3
-      - uses: chartboost/ruff-action@v1
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ruff codespell tomli
+      - name: Run Ruff
+        run: |
+          ruff check .
+      - name: Spelling check with codespell
+        run: |
+          codespell --toml pyproject.toml
diff --git a/.github/workflows/yapf.yml b/.github/workflows/yapf.yml
@@ -0,0 +1,23 @@
+name: Yapf Format
+
+on: [push, pull_request]
+
+jobs:
+  yapf:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10"]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install yapf toml
+      - name: Run Yapf
+        run: |
+          yapf --diff --recursive .
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@
 <a href="https://python.org/"><img alt="Language: Python" src="https://img.shields.io/badge/language-Python-orange.svg"></a>
 <a href="https://spdx.org/licenses/MIT.html"><img alt="License WarpX" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
 <a href="https://join.slack.com/t/hydrogym/shared_invite/zt-27u914dfn-UFq3CkaxiLs8dwZ_fDkBuA"><img alt="Slack" src="https://img.shields.io/badge/slack-hydrogym-brightgreen.svg?logo=slack"></a>
-<a href="https://github.com/psf/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
+<a href="https://github.com/google/yapf"><img alt="Code style: yapf" src="https://img.shields.io/badge/code%20style-yapf-000000.svg"></a>
 </p>
 
 
@@ -26,7 +26,7 @@ Currently these "environments" are all implemented using the [Firedrake](https:/
     - High-level: `hydrogym.env.FlowEnv` classes implement the OpenAI `gym.Env` interface
     - Intermediate: Typical CFD interface with `hydrogym.FlowConfig` and `hydrogym.TransientSolver` classes
     - Low-level: Access to linearized operators and sparse scipy or PETSc CSR matrices
-* __Modeling and anlysis tools:__ Global stability analysis (via SLEPc) and modal decompositions (via modred)
+* __Modeling and analysis tools:__ Global stability analysis (via SLEPc) and modal decompositions (via modred)
 * __Scalable:__ Individual environments parallelized with MPI with a **highly scalable [Ray](https://github.com/ray-project/ray) backend reinforcement learning training**.
 
 # Installation
@@ -39,6 +39,9 @@ This means that the latest release of Hydrogym can be simply installed via [PyPI
 pip install hydrogym
 ```
 
+> BEWARE: The pip-package is currently behind the main repository, and we strongly urge users to build HydroGym
+>         directly from the source code. Once we've stabilized the package, we will update the pip package in turn.
+
 However, the package assumes that the solver backend is available, so in order to run simulations locally you will
 need to _separately_ ensure the solver backend is installed (again, currently all the environments are implemented with Firedrake).
 Alternatively (and this is important for large-scale RL training), the core Hydrogym package can (or will soon be able to) launch reinforcement learning training on a Ray-cluster without an underlying Firedrake install.
@@ -79,7 +82,7 @@ For more detail, check out:
 
 There are currently a number of main flow configurations, the most prominent of which are:
 
-- Periodic cyclinder wake at Re=100
+- Periodic cylinder wake at Re=100
 - Chaotic pinball at Re=130
 - Open cavity at Re=7500
 - Backwards-facing step at Re=600

diff --git a/docs/_templates/custom-class-template.rst b/docs/_templates/custom-class-template.rst
@@ -0,0 +1,34 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :nosignatures:
+   {% for item in methods %}
+      {%- if not item.startswith('_') %}
+      ~{{ name }}.{{ item }}
+      {%- endif -%}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/_templates/custom-module-template.rst b/docs/_templates/custom-module-template.rst
@@ -0,0 +1,66 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :nosignatures:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+      :nosignatures:
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/api.rst b/docs/api.rst
@@ -0,0 +1,6 @@
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   hydrogym
diff --git a/docs/api_reference/api.rst b/docs/api_reference/api.rst
diff --git a/docs/api_reference/index.rst b/docs/api_reference/index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,4 +1,8 @@
 # Configuration file for the Sphinx documentation builder.
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
 
 # -- Project information
 
@@ -18,10 +22,15 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
+    "sphinx.ext.autodoc.typehints",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.mathjax",
 ]
+autosummary_generate = True
+autoclass_content = "both"
+html_show_sourcelink = False
+autodoc_inherit_docstrings = True
 
 intersphinx_mapping = {
     "rtd": ("https://docs.readthedocs.io/en/stable/", None),
@@ -31,6 +40,12 @@
 intersphinx_disabled_domains = ["std"]
 
 templates_path = ["_templates"]
+autodoc_mock_imports = [
+    "firedrake",
+    "pyadjoint",
+    "ufl",
+    "mpi4py",
+]
 
 # -- Options for HTML output
 

diff --git a/docs/dev_notes/index.rst b/docs/dev_notes/index.rst
@@ -1,10 +1,10 @@
-Developer Notes
-===============
+Developer Documentation
+=======================
 
 .. toctree::
     :maxdepth: 1
 
     docker_development
     testing
     distributed_backend
-    further_backend
+    further_backend
diff --git a/docs/html/.buildinfo b/docs/html/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 399fab98a0ccd21ea9e49f55b2e83d33
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/docs/index.rst b/docs/index.rst
@@ -12,9 +12,9 @@ Core Features
 
 * **Hierarchical:** Designed for analysis and controller design from a high-level black-box interface
   to low-level operator access.
-   * High-level: `hydrogym.env.FlowEnv` classes implement the OpenAI `gym.env` interface.
-   * Intermediate-level: Provides a typical CFD interface with `hydrogym.FlowConfig`, and `hydrogym.TransientSolver`.
-   * Low-level: Enables access to linearized operators, and sparse scipy or PETSc CSR matrices.
+  * High-level: `hydrogym.env.FlowEnv` classes implement the OpenAI `gym.env` interface.
+  * Intermediate-level: Provides a typical CFD interface with `hydrogym.FlowConfig`, and `hydrogym.TransientSolver`.
+  * Low-level: Enables access to linearized operators, and sparse scipy or PETSc CSR matrices.
 * **Modeling and Analysis Tools:** Provides global stability analysis (via SLEPc) and modal decomposition (via modred).
 * **Scalable:** Individual environments parallelized with MPI with a **highly scalable** `Ray <https://github.com/ray-project/ray>`_ **backend reinforcement learning training.**
 
@@ -26,7 +26,7 @@ Core Features
 
 .. toctree::
    :hidden:
-   :maxdepth: 2
+   :maxdepth: 3
 
    installation
    quickstart
@@ -35,4 +35,4 @@ Core Features
    integrations/index
    glossary
    dev_notes/index
-   api_reference/index
+   API Reference <_autosummary/hydrogym>