Merge from Main (#87)

* Automatic generation of API documentation (#70) - Create API reference automatically for all public members of quemb Before this change one had to manually create rst files and manage them. Now they are recursively created automatically. The layout of the documentation matches the layout of the namespace - This change automatically ensures that all (public) docstrings are actually parsed by Sphinx and it is ensured that they are properly written. Had to fix some docstrings - Type-hinting is now picked up by sphinx. * H5py use contextmanager (#73) * put if __main__ guard to test * use h5py contextmanager nearly everywhere * fixed a bug from wrong close statement * Fix parallelization and add parallel tests (#75) * fix _opt to work with be_parallel * modify oneshot to work with be_func_parallel * modify two tests to use nproc > 1 * fix ruff errors * modify octane test * Remove CCSD reference from octane test * Final scratch dir attempt (#74) # Mayor changes This PR unifies the use of the ScratchDir. It is now guaranteed, that files are cleaned up if the calculation exits with no error. (If the user passes `WorkDir(cleanup_at_end=False)` the files are retained). A `WorkDir` is passed from the top of the call stack to the bottom. This allows the user to change the WorkDir if necessary. (Fixes #19) Got rid of some special cased keyword arguments for DMRG and moved them into an explicit `DMRG_solver_kwargs`. This way we can catch arguments that are supplied and do nothing. It is probably a good idea to do the same for SHCI specific keywords @lweisburn . It is probably a good idea to get rid of the dictionary altogether and to replace it with a dataclass. # Minor changes If the `__init__` of a class was just populating the attributes, then I replaced the class definition with `attrs.define`. On the way I did a lot of type hinting. It is probably a good idea to double check my assumptions in review. Additionally, I did some refactoring, where explicit open-close pairs where replaced with context managers. The same was true for multiprocessing Pools. Here and there I encountered constructs that could be simplified a lot ```python3 veffs = [] [veffs.append(result.get()) for result in results] # becomes veffs = [result.get() for result in results] ``` or ```python3 self.frozen_core = False if not fobj.frozen_core else True # becomes self.frozen_core = fobj.frozen_core ``` or ```python3 rdm_return = False if relax_density: rdm_return = True # becomes rdm_return = relax_density ``` * Update fragment energies (#79) * Untangling eeval and frag_energy energy evaluation options * small changes for frag_energy consistency * start changing eeval and ereturn in parallel functions, making serial and parallel consistent * put if __main__ guard to test * use h5py contextmanager nearly everywhere * changed mbe.StoreBE into attrs defined class * ignore broken link to numpy.float64 in documentation * fixed a bug from wrong close statement * testsuite don't wait for analysis * added types for molbe BE object * fixed wrong close statements * fixed scratch-dir for molbe-be * added typing for molbe.BE.optimize - this fixed a likely bug in optimize. previously we had J0 = [[J0[-1, -1]]] now it is J0 = [[J0[-1][-1]]] since it is a list[list[float]] * renamed _opt.py to opt.py finished BEOPT attrs refactoring * pass on solver_kwargs to be_func * added types to be_func * added delete multiple_files function * use the new scratch dir in be_func * added types to molbe.BE.optimize + call self.scratch_dir.cleanup call self.scratch_dir.cleanup in both `optimize` and `oneshot` * moved schmidt_decomposition to prevent circular import makes much more sense like this * added type hints to be_func_parallel * fixed typo * fixed several small errors in the code * fixed be_func_parallel calls * simplified be_func_parallel * added types to run_solver * use frag_scratch in be_func_parallel * use frag_scratch in run_solver * added typehints to kbe BE class * simplified a few boolean expressions * the tests should be working now * ensure scratch cleanup for kbe * removed call to self.compute_energy_full (related to #35) * write nicer Pool statements - used proper list comprehensions - use contextmanager for Pool * fixed naming error * use more explicit way of freeing memory (it is still ugly... ) * refactored expression * use Tuple[int, ...] for numpy shapes :-( * refactored WorkDir to use atexit.register for cleanup * added better docstring for config * require static analysis to be ok for running test suite * renamed DMRG specific solver kwargs to its proper name * better naming for DMRG stuff * added types to block2 DMRG function * refactor some DMRG arguments * change behaviour of scratch contextmanager now it is ensured, that files are deleted even after an exception when using it as context manager and cleanup_at_end=True * fixed the deadlock in the test requirements * added new scratch dir also to ube * avoid list[list[float]]; use consistently array instead * Update energy keywords and logic in restricted BE, serial and parallel, oneshot and parallel. Update and rearrange some documentation for the keywords TODO: add non-cumulant energy, update unrestricted BE * Update kbe/pbe and kbe/misc for consistency * Fix kbe/pbe and kbe/misc to raise error for non-cumulant * Add non-cumulant energy option for molecular code * remove mypy attempt from get_energy_frag for now * fix be2puffin call of oneshot and update ube oneshot default * Update get_frag_energy function to work for periodic calculations * Remove double del line * remove redundant frag_energy keyword * Update src/quemb/molbe/helper.py, eri_file to be optional Co-authored-by: Minsik <[email protected]> * Update src/quemb/molbe/mbe.py: ebe_tot readability Co-authored-by: Minsik <[email protected]> * move use_cumulant to optimize and oneshot, not BE --------- Co-authored-by: Leah Weisburn <[email protected]> Co-authored-by: Oskar Weser <[email protected]> Co-authored-by: Minsik <[email protected]> * Adding back veff0 for molecular code, removing the now-unnecessary hf_veff from be_func (#81) * More type annotations + simpler boolean expressions (#76) Simplifications in the code - A couple more type annotations - simpler boolean expressions - removed keyword arguments if they are always true in the code * Dataclass for solver kwargs (#77) - Introduced a dataclass for solver kwargs. This is makes it much more explicit what arguments are supported by DMRG and SHCI - Could simplify the interface of BE by removing a couple of arguments * Simplify init (#82) - moved the saving operation out of the __init__ method. - don't redundantly store information from `fobj`, but use `fobj` itself directly. * Make numpy shorter (#83) - replacing `np.dot` with `@` - replacing the `numpy.something` calls with `from numpy import something` if functions appear several times - replacing the `numpy.something` call with `np.something` if a function appears rarely --------- Co-authored-by: Oskar Weser <[email protected]> Co-authored-by: Leah Weisburn <[email protected]> Co-authored-by: Leah Weisburn <[email protected]> Co-authored-by: Minsik <[email protected]>
troyvvgroup · Jan 14, 2025 · cf7d9e4 · cf7d9e4
1 parent e7d5570
commit cf7d9e4
Show file tree

Hide file tree

Showing 55 changed files with 2,348 additions and 2,444 deletions.
diff --git a/.github/workflows/build_docs.yml b/.github/workflows/build_docs.yml
@@ -18,10 +18,10 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - name: Set up Python 3.10
+    - name: Set up Python 3.12
       uses: actions/setup-python@v5
       with:
-        python-version: "3.10"
+        python-version: "3.12"
         cache: 'pip'
     - name: Install dependencies
       run: |

diff --git a/.github/workflows/quemb_unittest.yml b/.github/workflows/quemb_unittest.yml
@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10"]
+        python-version: ["3.12"]
 
 
     steps:

diff --git a/.gitignore b/.gitignore
@@ -71,6 +71,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/source/_autosummary
 
 # PyBuilder
 .pybuilder/

diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst
@@ -0,0 +1,28 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   {% for item in attributes %}
+   .. autoattribute:: {{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block methods %}
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_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:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: custom-class-template.rst
+   {% 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 %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: custom-module-template.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst
@@ -0,0 +1,13 @@
+API reference
+=============
+
+.. currentmodule:: quemb
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   molbe
+   kbe
+   shared
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -14,30 +14,52 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
+rst_prolog = """
+.. role:: python(code)
+    :language: python
+    :class: highlight
+
+.. role:: bash(code)
+   :language: bash
+   :class: highlight
+"""
+
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.napoleon",
-    "sphinx_rtd_theme",
     "sphinx.ext.intersphinx",
     "sphinx_autodoc_typehints",
     # https://github.com/tox-dev/sphinx-autodoc-typehints
+    "sphinx.ext.autosummary",
+    "sphinx_rtd_theme",
 ]
 
+autodoc_typehints_format = "short"
+autodoc_default_flags = [
+    "members",
+    "special-members",
+    "private-members",
+    "undoc-members",
+]
+always_use_bars_union = True
+python_use_unqualified_type_names = True
+
+
 napoleon_google_docstring = False
 napoleon_include_init_with_doc = True
 napoleon_numpy_docstring = True
-exclude_patterns = []
+napoleon_use_param = True
+
+templates_path = ["_templates"]
 
 intersphinx_mapping = {
     "numpy": ("https://docs.scipy.org/doc/numpy/", None),
     "pandas": ("http://pandas.pydata.org/pandas-docs/stable/", None),
     "python": ("https://docs.python.org/3", None),
     "pyscf": ("https://pyscf.org/", None),
+    "h5py": ("https://docs.h5py.org/en/stable/", None),
 }
 
-autodoc_typehints_format = "short"
-python_use_unqualified_type_names = True
-
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

diff --git a/docs/source/fragment.rst b/docs/source/fragment.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -29,15 +29,4 @@ References
    :maxdepth: 1
 
    install
-   usage
-   fragment
-   pfrag
-   kernel
-   optimize
-   solvers
-   misc
-
-
-
-.. role:: bash(code)
-   :language: bash
+   api_reference
diff --git a/docs/source/kernel.rst b/docs/source/kernel.rst
diff --git a/docs/source/misc.rst b/docs/source/misc.rst
diff --git a/docs/source/nitpick-exceptions b/docs/source/nitpick-exceptions
@@ -1 +1,2 @@
 py:class optional
+py:class numpy.float64
diff --git a/docs/source/optimize.rst b/docs/source/optimize.rst
diff --git a/docs/source/pfrag.rst b/docs/source/pfrag.rst
diff --git a/docs/source/solvers.rst b/docs/source/solvers.rst