From f235ace8b105e2a0af67018fbb331cb6c35c8776 Mon Sep 17 00:00:00 2001 From: Michael Howard Date: Fri, 26 Jul 2024 15:16:04 -0500 Subject: [PATCH] Complete documentation --- CHANGELOG.rst | 355 ++++++++++++++++++++++++++---------------------- LICENSE | 25 +++- README.md | 26 ++-- doc/credits.rst | 91 +++++++++++++ doc/index.rst | 47 ++++++- doc/license.rst | 9 ++ doc/release.rst | 5 + 7 files changed, 377 insertions(+), 181 deletions(-) create mode 100644 doc/credits.rst create mode 100644 doc/license.rst create mode 100644 doc/release.rst diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 74d90c54..ee24bd37 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -5,296 +5,321 @@ Release notes ============= +v1 +--- + +v1.0.0 +^^^^^^ +Released 26 July 2024 + +This major release is a complete rewrite of azplugins to support HOOMD 4. The +API and build system have been updated to conform to the HOOMD component +template. It was decided to remove some features during the porting process +if they were rarely used or had equivalent implementations in HOOMD. Some other +features will be ported but are not available in this release. Contributions +reimplementing features that have not been ported are certainly welcome! + +v0 +--- + v0.12.0 -------- +^^^^^^^ Released 1 Nov 2022 -This will be the final minor release of azplugins to support HOOMD-blue v2.x. The next planned -release of azplugins will be a major release to support HOOMD v3.x. This will be a breaking -change because of the significant rewrite of HOOMD-blue's API. We plan to support bug fixes -until this major release is ready, and we may support bug fixes targeted toward HOOMD-blue v2.x -during a transition period. +This will be the final minor release of azplugins to support HOOMD-blue v2.x. +The next planned release of azplugins will be a major release to support HOOMD +v3.x. This will be a breaking change because of the significant rewrite of +HOOMD-blue's API. We plan to support bug fixes until this major release is +ready, and we may support bug fixes targeted toward HOOMD-blue v2.x during a +transition period. *New features* - * Add shift parameter and allow sigma & epsilon to be zero in ``bond.fene``. - * Add ``analyze.group_velocity`` to compute the center-of-mass velocity of a group. +* Add shift parameter and allow sigma & epsilon to be zero in ``bond.fene``. +* Add ``analyze.group_velocity`` to compute the center-of-mass velocity of a + group. *Bug fixes* - * Apply CUDA 11.5 thrust / CUB namespace wrap fix. +* Apply CUDA 11.5 thrust / CUB namespace wrap fix. v0.11.0 --------- +^^^^^^^ Released 1 Feb 2022 *New features* - * ``flow.FlowProfiler`` is generalized to support multiple velocity components, - mass averaged velocities, and to compute temperature. - * The documentation has been reorganized, and some tutorials have been added. The - docs are now hosted on `ReadTheDocs `_. - * Support is added for sinusoidal channels and expansion--constriction channels - in ``integrate.sinusoidal_channel`` and ``integration.sinusoidal_expansion_constriction``. - Similar support is also available for the MPCD solvent. +* ``flow.FlowProfiler`` is generalized to support multiple velocity components, + mass averaged velocities, and to compute temperature. +* The documentation has been reorganized, and some tutorials have been added. + The docs are now hosted on `ReadTheDocs `_. +* Support is added for sinusoidal channels and expansion--constriction channels + in ``integrate.sinusoidal_channel`` and + ``integration.sinusoidal_expansion_constriction``. Similar support is also + available for the MPCD solvent. *Other changes* - * Add a code of conduct for contributors. - * Update copyright. azplugins is now maintained as part of our work at - Auburn University. - * The default git branch is renamed ``main``. More - `information `_ is available. - * CI testing has been moved to GitHub Actions. +* Add a code of conduct for contributors. +* Update copyright. azplugins is now maintained as part of our work at Auburn + University. +* The default git branch is renamed ``main``. More `information + `_ is available. +* CI testing has been moved to GitHub Actions. v0.10.1 -------- +^^^^^^^ Released 12 Jan 2021 *Bug fixes* - * Fix normalization of velocity in ``flow.FlowProfiler``. +* Fix normalization of velocity in ``flow.FlowProfiler``. v0.10.0 -------- +^^^^^^^ Released 27 Jul 2020 This is the first release of azplugins to include compilable documentation. The -``docs`` can be built using sphinx. Currently, only the APIs are thoroughly documented, -but we will be expanding the rest of the documentation in future releases with examples -and tutorials. +``docs`` can be built using sphinx. Currently, only the APIs are thoroughly +documented, but we will be expanding the rest of the documentation in future +releases with examples and tutorials. *New features* - * ``restrain.cylinder`` and ``restrain.sphere`` allow particles to be harmonically - restrained by their distance relative to a cylinder or sphere, respectively. - ``restrain.plane`` has been updated to share a condensed API using HOOMD walls. - * ``bond.double_well`` adds a new bond potential having two tunable minima. - * ``flow.FlowProfiler`` adds a python-level analyzer for averaging 1d density - and velocity profiles for both HOOMD and MPCD systems. - * ``pair.hertz`` adds the Hertz pair potential. +* ``restrain.cylinder`` and ``restrain.sphere`` allow particles to be + harmonically restrained by their distance relative to a cylinder or sphere, + respectively. ``restrain.plane`` has been updated to share a condensed API + using HOOMD walls. +* ``bond.double_well`` adds a new bond potential having two tunable minima. +* ``flow.FlowProfiler`` adds a python-level analyzer for averaging 1d density + and velocity profiles for both HOOMD and MPCD systems. +* ``pair.hertz`` adds the Hertz pair potential. *Other changes* - * The python unit tests have been updated to remove ``import *``. +* The python unit tests have been updated to remove ``import *``. v0.9.2 ------- +^^^^^^ Released 3 Mar 2020 *Bug fixes* - * Fix a compilation error on MacOS clang builds. +* Fix a compilation error on MacOS clang builds. *Other changes* - * Update copyright to 2020. +* Update copyright to 2020. v0.9.1 ------- +^^^^^^ Released 18 Dec 2019 *Bug fixes* - * Fix a compilation error in CUDA-enabled builds. +* Fix a compilation error in CUDA-enabled builds. v0.9.0 ------- +^^^^^^ Released 15 Dec 2019 *New features* - * ``flow.constant`` implements a constant flow along a vector. - * ``variant.sphere_area`` adds a new variant that is physically motivated by - a sphere shrinking with a constant rate of change in area. This may be useful - with ``evaporate.implicit`` in the ``droplet`` geometry. +* ``flow.constant`` implements a constant flow along a vector. +* ``variant.sphere_area`` adds a new variant that is physically motivated by a + sphere shrinking with a constant rate of change in area. This may be useful + with ``evaporate.implicit`` in the ``droplet`` geometry. *Other changes* - * Support API changes in HOOMD 2.8.0. Backward compatibility is maintained - through a new API header. - * The pair potential evaluators have been updated to support HOOMD 2.8.0. - New pair potential evaluators should derive from one of the convenience base classes. - * CI testing has been added for HOOMD 2.8.0 in addition to 2.6.0. +* Support API changes in HOOMD 2.8.0. Backward compatibility is maintained + through a new API header. +* The pair potential evaluators have been updated to support HOOMD 2.8.0. New + pair potential evaluators should derive from one of the convenience base + classes. +* CI testing has been added for HOOMD 2.8.0 in addition to 2.6.0. v0.8.0 ------- +^^^^^^ Released 5 Nov 2019 *New features* - * ``evaporate.implicit`` now supports evaporation in both film and droplet - geometries. The default geometry remains the film. - * ``restrain.plane`` allows particles to be harmonically restrained by their - distance relative to a plane. +* ``evaporate.implicit`` now supports evaporation in both film and droplet + geometries. The default geometry remains the film. +* ``restrain.plane`` allows particles to be harmonically restrained by their + distance relative to a plane. v0.7.1 ------- +^^^^^^ Released 20 Aug 2019 *Bug fixes* - * Silence a warning in CMake >= 3.12. - * Fix a link error in compiled unit tests. +* Silence a warning in CMake >= 3.12. +* Fix a link error in compiled unit tests. v0.7.0 ------- +^^^^^^ Released 24 Jun 2019 -This version of the plugin **requires** HOOMD-blue v2.6.0 for compatibility -with the new streaming geometries in its MPCD component. HOOMD-blue **must** -be built with the MPCD component. +This version of the plugin **requires** HOOMD-blue v2.6.0 for compatibility with +the new streaming geometries in its MPCD component. HOOMD-blue **must** be built +with the MPCD component. *Bug fixes* - * Fix compilation errors with HOOMD-blue v2.6.0. +* Fix compilation errors with HOOMD-blue v2.6.0. *Other changes* - * random123 is used as the random number generator throughout azplugins. - This API is more robust and stable than Saru, but sequences of random - numbers drawn for a given seed will change. New features using random - numbers should add a unique 32-bit identifier to ``RNGIdentifiers.h``. +* random123 is used as the random number generator throughout azplugins. This + API is more robust and stable than Saru, but sequences of random numbers drawn + for a given seed will change. New features using random numbers should add a + unique 32-bit identifier to ``RNGIdentifiers.h``. v0.6.2 ------- +^^^^^^ Released 25 Apr 2019 All commits and pull requests are now automatically tested against HOOMD 2.5.1 on CircleCI. Unit tests are run for CPU-only build configurations. CUDA-enabled -builds are tested for compilation, but their unit tests cannot be run on CircleCI. -The CI test environment is available on Docker Hub (https://hub.docker.com/r/mphoward/ci), -and tests for new code should be run locally on a GPU. +builds are tested for compilation, but their unit tests cannot be run on +CircleCI. The CI test environment is available on Docker Hub +(https://hub.docker.com/r/mphoward/ci), and tests for new code should be run +locally on a GPU. *Bug fixes* - * Fix import statements in azplugins modules for python3. - * Fix HOOMD version parsing in CMake for external builds. - * Fix CMake errors in testing for certain build configurations. +* Fix import statements in azplugins modules for python3. +* Fix HOOMD version parsing in CMake for external builds. +* Fix CMake errors in testing for certain build configurations. v0.6.1 ------- +^^^^^^ Released 28 Mar 2019 *Bug fixes* - * Fix thrust template parameters in ``mpcd.reverse_perturbation`` for CUDA 9 & 10. +* Fix thrust template parameters in ``mpcd.reverse_perturbation`` for CUDA 9 & + 10. v0.6.0 ------- +^^^^^^ Released 25 Feb 2019 -This version of the plugin **requires** HOOMD-blue v2.3.0 for compatibility -with the embedded pybind11 library. Be sure to update your git submodules -when recompiling and installing HOOMD-blue. +This version of the plugin **requires** HOOMD-blue v2.3.0 for compatibility with +the embedded pybind11 library. Be sure to update your git submodules when +recompiling and installing HOOMD-blue. -azplugins is now maintained by Michael P. Howard and will be hosted on -GitHub (https://github.com/mphoward/azplugins). +azplugins is now maintained by Michael P. Howard and will be hosted on GitHub +(https://github.com/mphoward/azplugins). *New features* - * ``mpcd.reverse_perturbation`` implements the reverse perturbation method in - the optional MPCD module to simulate shear flow. +* ``mpcd.reverse_perturbation`` implements the reverse perturbation method in + the optional MPCD module to simulate shear flow. *Other changes* - * The azplugins license and packaging has been updated to reflect the - project continuation. - * ``FindHOOMD.cmake`` has been improved to support ``find_package`` and detect - the installed version of HOOOMD. +* The azplugins license and packaging has been updated to reflect the project + continuation. +* ``FindHOOMD.cmake`` has been improved to support ``find_package`` and detect + the installed version of HOOOMD. v0.5.0 ------- +^^^^^^ Released 11 Jun 2018 -This version of the plugin **requires** HOOMD-blue v2.2.2 in order to -ensure all necessary header files are available. +This version of the plugin **requires** HOOMD-blue v2.2.2 in order to ensure all +necessary header files are available. *New features* - * ``flow.reverse_perturbation`` implements the reverse perturbation method - for generating shear flow. This implementation is significantly more stable - than the HOOMD-blue release, but does not currently support MPI. - * ``integrate.slit`` supports NVE integration with bounce-back rules in the slit - geometry. Other bounce back geometries can also be configured. - * ``dpd.general`` implements a generalized DPD potential where the exponent of - the dissipative weight function can be adjusted. A framework is also - implemented for adding other DPD potentials. - * ``flow.langevin`` and ``flow.brownian`` support Langevin and Brownian dynamics in - external flow fields. Currently, the supported fields are ``flow.quiescent`` - and ``flow.parabolic``, but additional fields can be included by templating. +* ``flow.reverse_perturbation`` implements the reverse perturbation method for + generating shear flow. This implementation is significantly more stable than + the HOOMD-blue release, but does not currently support MPI. +* ``integrate.slit`` supports NVE integration with bounce-back rules in the slit + geometry. Other bounce back geometries can also be configured. +* ``dpd.general`` implements a generalized DPD potential where the exponent of + the dissipative weight function can be adjusted. A framework is also + implemented for adding other DPD potentials. +* ``flow.langevin`` and ``flow.brownian`` support Langevin and Brownian dynamics + in external flow fields. Currently, the supported fields are + ``flow.quiescent`` and ``flow.parabolic``, but additional fields can be + included by templating. v0.4.0 ------- +^^^^^^ Released 16 Nov 2017 -This version of the plugin **requires** HOOMD-blue v2.2.1 in order -to ensure all necessary header files are available. +This version of the plugin **requires** HOOMD-blue v2.2.1 in order to ensure all +necessary header files are available. *New features* - * A framework is configured for developing bond potentials. - * ``bond.fene`` implements a standard FENE potential that is cleaned up compared - to the version found in HOOMD. - * ``bond.fene24`` implements the FENE potential with the Ashbaugh-Hatch-style - 48-24 Lennard-Jones potential repulsion. - * ``pair.ashbaugh24`` implements a Ashbaugh-Hatch 48-24 Lennard-Jones potential. - * ``pair.spline`` implements a cubic spline potential. - * ``pair.two_patch_morse`` implements the two-patch Morse anisotropic potential. - * A framework is configured for developing special pair potentials from existing - pair potentials. - * ``special_pair.lj96`` implements the LJ 9-6 potential as a special pair. - * A framework is configured for writing and running compiled unit tests with upp11. - * All source code is now automatically validated for formatting. +* A framework is configured for developing bond potentials. +* ``bond.fene`` implements a standard FENE potential that is cleaned up compared + to the version found in HOOMD. +* ``bond.fene24`` implements the FENE potential with the Ashbaugh-Hatch-style + 48-24 Lennard-Jones potential repulsion. +* ``pair.ashbaugh24`` implements a Ashbaugh-Hatch 48-24 Lennard-Jones potential. +* ``pair.spline`` implements a cubic spline potential. +* ``pair.two_patch_morse`` implements the two-patch Morse anisotropic potential. +* A framework is configured for developing special pair potentials from existing + pair potentials. +* ``special_pair.lj96`` implements the LJ 9-6 potential as a special pair. +* A framework is configured for writing and running compiled unit tests with + upp11. +* All source code is now automatically validated for formatting. *Bug fixes* - * Fix path to cub headers. - * Add missing status line prints. - * Fix possible linker errors for MPI libraries. - * Plugins now build when ``ENABLE_CUDA=OFF``. - * CMake exits gracefully when the MD component is not available from hoomd. - * Plugins now compile with debug flags. +* Fix path to cub headers. +* Add missing status line prints. +* Fix possible linker errors for MPI libraries. +* Plugins now build when ``ENABLE_CUDA=OFF``. +* CMake exits gracefully when the MD component is not available from hoomd. +* Plugins now compile with debug flags. v0.3.0 ------- +^^^^^^ Released 22 Aug 2017 -This version of the plugin is now tested against HOOMD-blue v2.1.9. -Users running older versions of HOOMD-blue are recommended to upgrade -their installations in order to ensure compatibility and the latest -bug fixes on the main code paths. +This version of the plugin is now tested against HOOMD-blue v2.1.9. Users +running older versions of HOOMD-blue are recommended to upgrade their +installations in order to ensure compatibility and the latest bug fixes on the +main code paths. *New features* - * ``pair.lj124`` implements the 12-4 Lennard-Jones potential. - * ``pair.lj96`` implements the 9-6 Lennard-Jones potential. - * A framework is configured for developing anisotropic pair potentials. +* ``pair.lj124`` implements the 12-4 Lennard-Jones potential. +* ``pair.lj96`` implements the 9-6 Lennard-Jones potential. +* A framework is configured for developing anisotropic pair potentials. *Bug fixes* - * Fix import hoomd.md error in ``analyze.rdf``. - * Adds restraint module to ctest list and warns user about running - with orientation restraints in single precision. - * Fix examples in contribution guidelines so that formatting of - pull request checklist is OK. - * Remove unused include from particle evaporator which caused - compilation errors with newer versions of hoomd where the header - was removed. +* Fix import hoomd.md error in ``analyze.rdf``. +* Adds restraint module to ctest list and warns user about running with + orientation restraints in single precision. +* Fix examples in contribution guidelines so that formatting of pull request + checklist is OK. +* Remove unused include from particle evaporator which caused compilation errors + with newer versions of hoomd where the header was removed. v0.2.0 ------- +^^^^^^ Released 28 Feb 2017 *New features* - * ``analyze.rdf`` implements a radial distribution function calculator - between particle groups for small problem sizes. - * ``restrain.position`` implements position restraints for particles. - * ``restrain.orientation`` implements orientation restraints for particles. - * ``pair.slj`` implements a core-shifted Lennard-Jones potential that does - not read from the particle diameters. +* ``analyze.rdf`` implements a radial distribution function calculator between + particle groups for small problem sizes. +* ``restrain.position`` implements position restraints for particles. +* ``restrain.orientation`` implements orientation restraints for particles. +* ``pair.slj`` implements a core-shifted Lennard-Jones potential that does not + read from the particle diameters. *Other updates* @@ -302,23 +327,23 @@ Released 28 Feb 2017 new ``CONTRIBUTING.md``. v0.1.0 ------- +^^^^^^ Released 9 Feb 2017 *New features* - * A framework is configured for developing pair potentials. - * ``pair.ashbaugh`` implements the Ashbaugh-Hatch (Lennard-Jones perturbation) - potential. - * ``pair.colloid`` implements the colloid (integrated Lennard-Jones) potential - for colloidal suspensions. - * A framework is configured for developing wall potentials. - * ``wall.colloid`` implements the integrated Lennard-Jones potential between - a colloid and a half-plane wall. - * ``wall.lj93`` implements the Lennard-Jones 9-3 potential between a point - and a half-plane wall. - * ``update.types`` allows for swapping of particle types based on a slab region - of the simulation box. - * ``evaporate.particles`` supports evaporation of single-particle fluids from - a slab region of the simulation box. - * ``evaporate.implicit`` provides an implicit model for an evaporating solvent. +* A framework is configured for developing pair potentials. +* ``pair.ashbaugh`` implements the Ashbaugh-Hatch (Lennard-Jones perturbation) + potential. +* ``pair.colloid`` implements the colloid (integrated Lennard-Jones) potential + for colloidal suspensions. +* A framework is configured for developing wall potentials. +* ``wall.colloid`` implements the integrated Lennard-Jones potential between a + colloid and a half-plane wall. +* ``wall.lj93`` implements the Lennard-Jones 9-3 potential between a point and a + half-plane wall. +* ``update.types`` allows for swapping of particle types based on a slab region + of the simulation box. +* ``evaporate.particles`` supports evaporation of single-particle fluids from a + slab region of the simulation box. +* ``evaporate.implicit`` provides an implicit model for an evaporating solvent. diff --git a/LICENSE b/LICENSE index db858c18..cfd1749d 100644 --- a/LICENSE +++ b/LICENSE @@ -1,12 +1,27 @@ Copyright (c) 2018-2020, Michael P. Howard Copyright (c) 2021-2024, Auburn University -Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: +Redistribution and use in source and binary forms, with or without modification, +are permitted provided that the following conditions are met: -1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. +1. Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. -2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. +2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. -3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. +3. Neither the name of the copyright holder nor the names of its contributors + may be used to endorse or promote products derived from this software without + specific prior written permission. -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON +ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/README.md b/README.md index f818c829..994ddf59 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,22 @@ list of recent development. ## Compiling azplugins azplugins follows the [standard component template][2]. It has the same -dependencies used to build HOOMD-blue, and you can follow the [directions][3] -listed in the HOOMD-blue documentation to build an external component. +dependencies used to build HOOMD-blue. With HOOMD-blue installed already, adding +azplugins can be as easy as: + +``` +git clone https://github.com/mphowardlab/azplugins +cmake -B build/azplugins -S azplugins +cmake --build build/azplugins +cmake --install build/azplugins +``` + +Please refer to the directions in the HOOMD-blue documentation on building an +external component for more information. ### Testing -After building and installing azplugins, you can run the tests with pytest: +After building and installing azplugins, you can run our tests with pytest: ``` python -m pytest --pyargs hoomd.azplugins @@ -22,9 +32,8 @@ python -m pytest --pyargs hoomd.azplugins ## Contributing Contributions are welcomed and appreciated! Fork and create a pull request on -[GitHub][4]. Be sure to follow the [HOOMD-blue guidelines for developers][5]! We -value the input and experiences all users and contributors bring to -`azplugins`. +[GitHub][3]. Be sure to follow the [HOOMD-blue guidelines for developers][4]! We +value the input and experiences all users and contributors bring to `azplugins`. ## History @@ -34,6 +43,5 @@ Athanassios (Thanos) Z. Panagiotopoulos. [1]: http://glotzerlab.engin.umich.edu/hoomd-blue [2]: https://hoomd-blue.readthedocs.io/en/latest/components.html -[3]: https://hoomd-blue.readthedocs.io/en/latest/components.html -[4]: https://github.com/mphowardlab/azplugins -[5]: https://hoomd-blue.readthedocs.io/en/latest/developers.html +[3]: https://github.com/mphowardlab/azplugins +[4]: https://hoomd-blue.readthedocs.io/en/latest/developers.html diff --git a/doc/credits.rst b/doc/credits.rst new file mode 100644 index 00000000..ef95fd44 --- /dev/null +++ b/doc/credits.rst @@ -0,0 +1,91 @@ +.. Copyright (c) 2018-2020, Michael P. Howard +.. Copyright (c) 2021-2024, Auburn University +.. Part of azplugins, released under the BSD 3-Clause License. + +Credits +======= + +Maintainers +----------- +* Michael P. Howard +* Antonia Statt + +Contributors +------------ +* Mohammadreza Fakhraei +* Arjun Goswami +* Sally Jiao +* Mayukh Kundu +* C. Levi Petix +* Wes Reinhart +* Jude Ann Vishnu + +Source code +----------- +This is a continuation of the ``azplugins`` project begun by members of the +Panagiotopoulos Group at Princeton University. Code from that project is +used under a Modified BSD license: + +.. code-block:: none + + Copyright (c) 2016-2018, Panagiotopoulos Group, Princeton University + + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + * Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + * Neither the name of the copyright holder nor the names of its contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY + DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF + THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +This code is a plugin component for HOOMD-blue. Portions of the code are adapted +under a BSD 3-Clause license: + +.. code-block:: none + + Copyright (c) 2009-2024 The Regents of the University of Michigan. All + rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + + 3. Neither the name of the copyright holder nor the names of its + contributors + may be used to endorse or promote products derived from this software + without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE + LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. diff --git a/doc/index.rst b/doc/index.rst index fdf76f08..493498ea 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,8 +10,42 @@ azplugins is a component for `HOOMD-blue`_ which expands its functionality for tackling a variety of problems in soft matter physics. Currently, azplugins is tested against v4.8.2 of HOOMD-blue. -.. rubric:: - Contents +Compiling +========= + +azplugins follows the `component template`_. It has the same dependencies used +to build HOOMD-blue. With HOOMD-blue installed already, adding azplugins can be +as easy as: + +1. Grab a copy of the code: + + .. code-block:: bash + + git clone https://github.com/mphowardlab/azplugins + +2. Configure azplugins with CMake: + + .. code-block:: bash + + cmake -B build/azplugins -S azplugins + +3. Build azplugins: + + .. code-block:: bash + + cmake --build build/azplugins + +4. Install azplugins alongside HOOMD-blue: + + .. code-block:: bash + + cmake --install build/azplugins + +Please refer to the directions in the HOOMD-blue documentation on building an +external component for more information. + +Contents +======== .. toctree:: :maxdepth: 1 @@ -21,6 +55,14 @@ tested against v4.8.2 of HOOMD-blue. module-azplugins-flow module-azplugins-pair +.. toctree:: + :maxdepth: 1 + :caption: Reference + + credits + license + release + Index ===== @@ -29,3 +71,4 @@ Index * :ref:`search` .. _HOOMD-blue: http://glotzerlab.engin.umich.edu/hoomd-blue +.. _component template: https://hoomd-blue.readthedocs.io/en/latest/components.html diff --git a/doc/license.rst b/doc/license.rst new file mode 100644 index 00000000..a8178b0e --- /dev/null +++ b/doc/license.rst @@ -0,0 +1,9 @@ +.. Copyright (c) 2018-2020, Michael P. Howard +.. Copyright (c) 2021-2024, Auburn University +.. Part of azplugins, released under the BSD 3-Clause License. + +License +======= + +.. literalinclude:: ../LICENSE + :language: none diff --git a/doc/release.rst b/doc/release.rst new file mode 100644 index 00000000..ea8d5bde --- /dev/null +++ b/doc/release.rst @@ -0,0 +1,5 @@ +.. Copyright (c) 2018-2020, Michael P. Howard +.. Copyright (c) 2021-2024, Auburn University +.. Part of azplugins, released under the BSD 3-Clause License. + +.. include:: ../CHANGELOG.rst