Merge branch 'trunk-major' into fix-mpcd-large-snapshots

.github/workflows/build_and_test.yaml

@@ -282,6 +282,21 @@ jobs:
       env:
         _HOOMD_DISALLOW_CUPY_: 1
 
+    ### compute-sanitizer checks: These checks are slow, so run them only when validation is
+    # requested, but no on the actual long validation tests. Every class's basic test should ensure
+    # that the GPU kernel is called for at least a few timesteps for these checks to be effective.
+    - name: Run memcheck
+      if: ${{ contains(inputs.config, 'cuda') && contains(github.event.pull_request.labels.*.name, 'validate') && inputs.validate == 'true' }}
+      run: compute-sanitizer --tool memcheck --error-exitcode 1 python3 -m pytest --pyargs hoomd -x -v -ra --durations=0 --durations-min=0.1
+
+    - name: Run racecheck
+      if: ${{ contains(inputs.config, 'cuda') && contains(github.event.pull_request.labels.*.name, 'validate') && inputs.validate == 'true' }}
+      run: compute-sanitizer --tool racecheck --error-exitcode 1 python3 -m pytest --pyargs hoomd -x -v -ra --durations=0 --durations-min=0.1
+
+    - name: Run synccheck
+      if: ${{ contains(inputs.config, 'cuda') && contains(github.event.pull_request.labels.*.name, 'validate') && inputs.validate == 'true' }}
+      run: compute-sanitizer --tool synccheck --error-exitcode 1 python3 -m pytest --pyargs hoomd -x -v -ra --durations=0 --durations-min=0.1
+
     ### Validation tests
     - name: Run pytest -m validate (serial)
       if: ${{ !contains(inputs.config, 'mpi') && contains(github.event.pull_request.labels.*.name, 'validate') && inputs.validate == 'true' }}

.pre-commit-config.yaml

@@ -3,10 +3,18 @@ ci:
   autoupdate_branch: 'trunk-patch'
   autofix_prs: false
 
-exclude: (?x)(
-        ^hoomd/extern/|
-        ^sphinx-doc/tutorial/
-        )
+# these exclusions must be synced with ruff-format agove and the file ruff.toml.
+exclude: |
+  (?x)(
+    ^hoomd/_hoomd.py|
+    ^hoomd/version_config.py|
+    ^hoomd/md/_md.py|
+    ^hoomd/hpmc/_hpmc.py|
+    ^hoomd/mpcd/_mpcd.py|
+    ^hoomd/extern/|
+    ^sphinx-doc/tutorial/
+    ^hoomd/metal/
+  )
 
 repos:
 - repo: local
@@ -17,6 +25,16 @@ repos:
     entry: '(# Maintainer:|\/\/ Maintainer:)'
     language: pygrep
     types_or: [python, c, c++, cuda, inc]
+- repo: local
+  hooks:
+  - id: generate_toctree
+    name: Generate Sphinx toctree
+    language: python
+    entry: python3 sphinx-doc/generate-toctree.py
+    pass_filenames: false
+    always_run: true
+    additional_dependencies:
+     - numpy==2.1.0
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: 'v5.0.0'
   hooks:
@@ -26,7 +44,6 @@ repos:
     exclude_types: [svg]
   - id: check-json
   - id: check-yaml
-    exclude: (?:^.github/workflows/templates) # templates are not properly formatted yaml
   - id: check-case-conflict
   - id: mixed-line-ending
 - repo: https://github.com/glotzerlab/fix-license-header
@@ -40,7 +57,7 @@ repos:
           ^sphinx-doc/tutorial/|
           ^sphinx-doc/howto/
           )
-    types_or: [python, c, c++, cuda, inc, rst]
+    types_or: [python, c, c++, cuda, inc]
     args:
     - --license-file=LICENSE
     - --add=Part of HOOMD-blue, released under the BSD 3-Clause License.
@@ -54,23 +71,13 @@ repos:
   rev: 'v0.40.2'
   hooks:
   - id: yapf
-- repo: https://github.com/PyCQA/flake8
-  rev: '7.1.1'
+- repo: https://github.com/astral-sh/ruff-pre-commit
+  rev: 'v0.8.0'
   hooks:
-  - id: flake8
-    additional_dependencies:
-    - pep8-naming==0.13.3
-    - pydocstyle==6.3.0
-    - flake8-docstrings==1.7.0
-    - flake8-rst-docstrings==0.3.0
-    # Exclude components not yet ported to hoomd v3
-    # TODO: Remove these exclusions as components are ported
-    # These also need to be removed in setup.cfg
-    exclude: |
-      (?x)(
-        ^hoomd/extern/|
-        ^hoomd/metal/
-      )
+  # - id: ruff-format  # TODO: enable formatting after all other v5 PRs are merged
+  #   types_or: [python]
+  - id: ruff
+    types_or: [python]
 - repo: https://github.com/pre-commit/mirrors-clang-format
   rev: v19.1.1
   hooks:

ARCHITECTURE.md

@@ -18,7 +18,7 @@ Each minor and major release of HOOMD-blue at a minimum supports:
 
 ### Continuous integration
 
-[Github Actions] performs continuous integration testing on HOOMD-blue. GitHub
+[GitHub Actions] performs continuous integration testing on HOOMD-blue. GitHub
 Actions compiles HOOMD-blue, runs the unit tests, and reports the
 status to GitHub pull requests. A number of parallel builds test a variety of
 compiler and build configurations as defined above.
@@ -160,7 +160,7 @@ a shared pointer to the HPMC integrator to access this information.
 There are two MD integrators: `IntegratorTwoStep` implements normal MD simulations and
 `FIREENergyMinimizer` implements energy minimization. In MD, the integrator maintains the list of
 user-supplied forces (`ForceCompute`) to apply to particles. Both integrators also maintain a list
-of user-supplied integration methos (`IntegrationMethodTwoStep`). Each method instance operates
+of user-supplied integration methods (`IntegrationMethodTwoStep`). Each method instance operates
 on a single particle group (`ParticleGroup`) and is solely responsible for integrating the equations
 of motion of all particles in that group.
 
@@ -195,19 +195,19 @@ even when the use of that code is used only in host code. To work around these c
 kernels in HOOMD-blue are called via minimal driver functions. These driver functions are not member
 functions of their respective class, and therefore must take a long C-style argument list consisting
 of bare pointers to data arrays, array sizes, etc... The ABI for these calls is not strictly C, as
-driver functions may be templated on functor classes and/or accept lightwight C++ objects as
+driver functions may be templated on functor classes and/or accept lightweight C++ objects as
 parameters (such as `BoxDim`).
 
 ## Autotuning
 
 HOOMD-blue automatically tunes kernel block sizes, threads per particle, and other kernel launch
-paramters. The `Autotuner` class manages the sparse multi-dimensional of parameters for each kernel.
+parameters. The `Autotuner` class manages the sparse multidimensional of parameters for each kernel.
 It dynamically cycles through the possible parameters and records the performance of each using CUDA
 events. After scanning through all parameters, it selects the best performing one to continue
 executing. GPU code in HOOMD-blue should instantiate and use one `Autotuner` for each kernel.
 Classes that use have `Autotuner` member variables should inherit from `Autotuned` which tracks all
 the autotuners and provides a UI to users. When needed, classes should override the base class
-`isAutotuningComplete` and `startAutotuning` as to pass the calls on to child objects. not otherwise
+`isAutotuningComplete` and `startAutotuning` as to pass the calls on to child objects not otherwise
 managed by the `Simulation`. For example, `PotentialPair::isAutotuningComplete`, calls both
 `ForceCompute::isAutotuningComplete` and `m_nlist->isAutotuningComplete` and combines the results.
 
@@ -300,13 +300,13 @@ specification defining the validation logic for its keys. `ParameterDict`
 contains logic when given a pybind11 produced Python object can sync between C++
 and Python. See `ParameterDict.__setitem__` for this logic. Attribute specific
 logic can be created using the `_getters` and `_setters` attributes. The logic
-requires (outside custom getters and setters that all `ParameterDict` keys be
+requires (outside custom getters and setters) that all `ParameterDict` keys be
 available as properties of the C++ object using the pybind11 property
 implementation
 (https://pybind11.readthedocs.io/en/stable/classes.html#instance-and-static-fields).
 Properties can be read-only which means they will never be set through
 `ParameterDict`, but can be through the C++ class constructor. Attempting to set
-such a property after attaching will result in an `MutabilityError` being thrown.
+such a property after attaching will result in a `MutabilityError` being thrown.
 
 This class should be used to define all attributes shared with C++ member
 variables that are on a per-object basis (i.e. not per type). Examples of
@@ -399,18 +399,18 @@ written in Python. See the examples in `hoomd/write/table.py` and
 
 ### Pickling
 
-By default all Python subclasses of `hoomd.operation._HOOMDBaseObject` support
+By default, all Python subclasses of `hoomd.operation._HOOMDBaseObject` support
 pickling. This is to facilitate restartability and reproducibility of
 simulations. For understanding what *pickling* and Python's supported magic
-methods regarding it are see https://docs.python.org/3/library/pickle.html. In
-general we prefer using `__getstate__` and `__setstate__` if possible to make
+methods regarding it see https://docs.python.org/3/library/pickle.html. In
+general, we prefer using `__getstate__` and `__setstate__` if possible to make
 class's picklable.  For the implementation of the default pickling support for
 `hoomd.operation._HOOMDBaseObject` see the class's `__getstate__` method.
 *Notice* that we do not implement a generic `__setstate__`. We rely on Python's
 default generally which is somewhat equivalent to `self.__dict__ =
 self.__getstate__()`. Adding a custom `__setstate__` method is fine if necessary
 (see [hoomd/write/table.py](hoomd/write/table.py)).  However, using `__reduce__`
-is an appropriate alternative if is significantly reduces code complexity or has
+is an appropriate alternative if significantly reduces code complexity or has
 demonstrable advantages; see [hoomd/filter/set\_.py](hoomd/filter/set_.py) for
 an example of this approach.  _Note_ that `__reduce__` requires that a function
 be able to fully recreate the current state of the object (this means that often
@@ -436,7 +436,7 @@ wrappers, supporting pickling using pybind11 (see
 https://pybind11.readthedocs.io/en/stable/advanced/classes.html#pickling-support)
 is acceptable as well. Care just needs to be made that users are not exposed to
 C++ classes that "slip" out of their Python subclasses which can happen if no
-reference in Python remains to a unpickled object. See
+reference in Python remains to an unpickled object. See
 [hoomd/Trigger.cc](hoomd/Trigger.cc) for examples of using pybind11.
 
 **Supporting Class Changes**
@@ -457,7 +457,7 @@ internal attributes should not cause problems as well.
 
 HOOMD allows for C++ classes to expose their GPU and CPU data buffers directly
 in Python using the `__cuda_array_interface__` and `__array_interface__`. This
-behavior is controlled using the `hoomd.data.local_access._LocalAcces` class in
+behavior is controlled using the `hoomd.data.local_access._LocalAccess` class in
 Python and the classes found in `hoomd/PythonLocalDataAccess.h`. See these files
 for more details. For example implementations look at `hoomd/ParticleData.h`.
 
@@ -475,12 +475,48 @@ The top level directories are:
 
 ## User
 
-The user facing documentation is compiled into a human readable document by Sphinx. The
+The user facing documentation is compiled into a human-readable document by Sphinx. The
 documentation consists of `.rst` files in the `sphinx-doc` directory and the docstrings of
 user-facing Python classes in the implementation (imported by the Sphinx autodoc extension).
 HOOMD-blue's Sphinx configuration defines mocked imports so that the documentation may be built from
-the source directory without needing to compile the C++ source code. This is greatly beneficial when
-building the documentation on readthedocs.
+the source directory without needing to compile the C++ source code.
+
+`autodoc` defaults to one HTML page per module. Users find it more convenient to read
+documentation with one page per class. The file `sphinx-doc/generate-toctree.py`
+imports `hoomd`, reads the `__all__` member and then recursively generates `.rst` files
+for each module and class. `generate-toctree.py` is run as a `pre-commit` hook to ensure
+that the documentation is always updated.
+
+Users also strongly prefer not to navigate up the super class chain in the documentation
+in order to discover the members of a given class. Unfortunately, we are not able to
+use Sphinx'x automatic inherit-documentation because HOOMD extensively uses
+`__getattr__/__setattr__`. To meet this need, HOOMD based classes define a class-level
+`_doc_inherited` string that summarizes the inherited members. Classes should append
+this string to `__doc__` and _then_ add their inherited members (if any) to
+`_doc_inherited`.
+
+Sybil parses only docstrings, so there can be no Sybil codeblock examples in
+`_doc_inherited`. At the same time, Sphinx always adds autodoc members **after** the
+docstring contents. To work around this and provide documentation in a consistent and
+meaningful order: class docstrints should include the text `{inherited}` and update the
+docstring with `__doc__ = __doc__.replace("{inherited}", Parent._doc_inherited)`.
+
+After `{inherited}`, the docstring should include the lines
+```
+----------
+
+**Members defined in** `ThisClassName`:
+```
+Similarly, any additions to `_doc_inherited` should start with
+```
+----------
+
+**Members inherited from** `ThisClassName <hoomd.module.ThisClassName>:`
+```
+Together, these visually break up the sections and allow the user to see which
+methods come from where. Each entry in `_doc_inherited` should repeat only the brief
+description and provide a link to the full description (follow
+the examples in the codebase when writing your own).
 
 The tutorial portion of the documentation is written in Jupyter notebooks housed in the
 [hoomd-examples][hoomd_examples] repository. HOOMD-blue includes these in the generated Sphinx

CHANGELOG.rst

@@ -1,6 +1,3 @@
-.. Copyright (c) 2009-2024 The Regents of the University of Michigan.
-.. Part of HOOMD-blue, released under the BSD 3-Clause License.
-
 Change Log
 ==========
 
@@ -21,6 +18,17 @@ Change Log
   (`#1934 <https://github.com/glotzerlab/hoomd-blue/pull/1934>`__).
 * Correctly apply ``HPMCIntegrator.external_potentials`` in ``hoomd.hpmc.update.MuVT``
   (`#1941 <https://github.com/glotzerlab/hoomd-blue/pull/1941>`__).
+* Ensure GPU autotuners for MPCD methods are included in ``hoomd.Operations.is_tuning_complete`` and
+  ``hoomd.Operations.tune_kernel_parameters`` through ``hoomd.mpcd.Integrator``
+  (`#1951 <https://github.com/glotzerlab/hoomd-blue/pull/1951>`__).
+* Read after write hazard in the GPU implementation of ``Dipole``, ``ALJ``, and all ``Patchy``
+  potentials in ``hoomd.md.pair.ansiso``
+  (`#1944 <https://github.com/glotzerlab/hoomd-blue/pull/1944>`__).
+* Read after write hazard in the GPU implementation of ``hoomd.md.mesh.conservation.Volume``
+  (`#1953 <https://github.com/glotzerlab/hoomd-blue/pull/1953>`__).
+* ``hoomd.hpmc.pair.Pair.energy`` now computes the correct energy when there are multiple pair
+  potentials with different ``r_cut`` values
+  (`#1955 <https://github.com/glotzerlab/hoomd-blue/pull/1955>`__).
 
 *Added*
 
@@ -43,6 +51,8 @@ Change Log
 * ``hoomd.hpmc.external.field.Harmonic`` is now ``hoomd.hpmc.external.Harmonic`` and works
   with ``IntegratorHPMC.external_potentials``
   (`#1941 <https://github.com/glotzerlab/hoomd-blue/pull/1941>`__).
+* Document one class per html page and show inherited members in class documentation
+  (`#1952 <https://github.com/glotzerlab/hoomd-blue/pull/1952>`__).
 
 *Removed*
 
@@ -266,7 +276,7 @@ Change Log
 * ``hoomd.variant.box.InverseVolumeRamp`` - Linearly ramp the inverse volume of the system
   (`#1685 <https://github.com/glotzerlab/hoomd-blue/pull/1685>`__).
 * ``hoomd.hpmc.update.QuickCompress`` now accepts a ``hoomd.variant.box.BoxVariant`` object for
-  `target_box` (`#1736 <https://github.com/glotzerlab/hoomd-blue/pull/1736>`__).
+  ``target_box`` (`#1736 <https://github.com/glotzerlab/hoomd-blue/pull/1736>`__).
 * ``box`` argument to ``hoomd.update.BoxResize`` that accepts a ``hoomd.variant.box.BoxVariant``
   (`#1740 <https://github.com/glotzerlab/hoomd-blue/pull/1740>`__).
 * ``hoomd.hpmc.pair.Union`` computes pair potentials between unions of points. Replaces

CONTRIBUTING.rst

@@ -88,15 +88,9 @@ User documentation
 Write user documentation
 ________________________
 
-Document public-facing API with Python docstrings in Google style.
-
-Document version status
-_______________________
-
-Add `versionadded, versionchanged, and deprecated Sphinx directives
-<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-versionadded>`__
-to each user-facing Python class, method, etc., so that users will be aware of how functionality
-changes from version to version. Remove this when breaking APIs in major releases.
+Document public-facing API with Python docstrings in Google style, use the ``_doc_inherited``
+member as documented in ``ARCHITECTURE.md`` and list new public classes and functions in
+``__all__``.
 
 Add developer to the credits
 ____________________________

example_plugins/pair_plugin/__init__.py

@@ -4,3 +4,5 @@
 """Example python module."""
 
 from hoomd.pair_plugin import pair
+
+__all__ = ['pair']

example_plugins/shape_plugin/__init__.py

@@ -4,3 +4,5 @@
 """Example MC shape plugin."""
 
 from . import integrate
+
+__all__ = ['integrate']

example_plugins/updater_plugin/__init__.py

@@ -4,3 +4,5 @@
 """Example python module."""
 
 from hoomd.updater_plugin import update
+
+__all__ = ['update']