fix conflicts

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 *.py[cod]
 *$py.class
+*.swp
 
 # C extensions
 *.so

.pre-commit-config.yaml

@@ -18,7 +18,7 @@ repos:
       - id: trailing-whitespace
         exclude: 'flowermd/tests/assets/.* | flowermd/assets/.*'
   - repo: https://github.com/psf/black
-    rev: 23.12.0
+    rev: 24.2.0
     hooks:
       - id: black
         args: [ --line-length=80 ]
@@ -32,7 +32,7 @@ repos:
         exclude: 'flowermd/tests/assets/.* '
 
   - repo: https://github.com/pycqa/flake8
-    rev: 6.1.0
+    rev: 7.0.0
     hooks:
       - id: flake8
         args:
@@ -44,5 +44,5 @@ repos:
     rev: '6.3.0'
     hooks:
       - id: pydocstyle
-        exclude: ^(flowermd/tests/|flowermd/utils/|setup.py|flowermd/__version__.py|docs/)
+        exclude: ^(flowermd/tests/|flowermd/internal/|flowermd/utils|setup.py|flowermd/__version__.py|docs/)
         args: [ --convention=numpy ]

README.md

@@ -56,14 +56,29 @@ conda activate flowermd-dev
 python -m pip install -e .
 ```
 
+**A note on GPU compatibility:**
+
+To install a GPU compatible version of HOOMD-blue in your flowerMD
+environment, you need to manually set the CUDA version **before installing flowermd**.
+This is to ensure that the HOOMD build pulled from conda-forge is compatible with your CUDA version.
+To set the CUDA version, run the following command before installing flowermd:
+```
+export CONDA_OVERRIDE_CUDA="[YOUR_CUDA_VERSION]"
+```
+
 ## Basic Usage
 Please check out the [tutorials](tutorials) for a detailed description of
 how to use flowerMD and what functionalities it provides.
 
 ## Documentation
 Documentation is available at [https://flowermd.readthedocs.io](https://flowermd.readthedocs.io)
 
-## Contributing
+## Citing flowerMD
+If you use flowerMD in your research, please cite the following paper:
+
+Albooyeh, M., Jones, C., Barrett, R., & Jankowski, E. (2023). FlowerMD: Flexible Library of Organic Workflows and Extensible Recipes for Molecular Dynamics. Journal of Open Source Software, 8(92), 5989, https://doi.org/10.21105/joss.05989
+
+## Contributing to flowerMD
 We welcome all contributions to flowerMD. Please see
 [contributing guidelines](CONTRIBUTING.md) for more information.
 

docs/source/index.rst

@@ -40,9 +40,17 @@ Quick start
 Resources
 =========
 
-`GitHub Repository <https://github.com/cmelab/flowerMD>`_: Source code and issue tracker.
+- `GitHub Repository <https://github.com/cmelab/flowerMD>`_: Source code and issue tracker.
 
-`Tutorials <https://github.com/cmelab/flowerMD/tree/main/tutorials>`_: Examples of how to use flowerMD.
+- `Tutorials <https://github.com/cmelab/flowerMD/tree/main/tutorials>`_: Examples of how to use flowerMD.
+
+- `FlowerMD JOSS paper <https://joss.theoj.org/papers/10.21105/joss.05989>`_
+
+Citation
+========
+If you use flowerMD in your research, please cite the following paper:
+
+Albooyeh, M., Jones, C., Barrett, R., & Jankowski, E. (2023). FlowerMD: Flexible Library of Organic Workflows and Extensible Recipes for Molecular Dynamics. Journal of Open Source Software, 8(92), 5989, https://doi.org/10.21105/joss.05989
 
 
 .. toctree::
@@ -52,6 +60,7 @@ Resources
    base
    modules
    library
+   utils
 
 
 

docs/source/installation.rst

@@ -25,3 +25,13 @@ Install from source
     $ conda env create -f environment.yml
     $ conda activate flowermd
     $ python -m pip install .
+
+.. note::
+
+    To install a GPU compatible version of HOOMD-blue in your flowerMD environment, you need to manually set the CUDA version **before installing flowermd**.
+    This is to ensure that the HOOMD build pulled from conda-forge is compatible with your CUDA version.
+    To set the CUDA version, run the following command before installing flowermd::
+
+        $ export CONDA_OVERRIDE_CUDA="[YOUR_CUDA_VERSION]"
+
+    Please see the `HOOMD-blue installation instructions <https://hoomd-blue.readthedocs.io/en/stable/installation.html>`_ for more information.

docs/source/utils.rst

@@ -0,0 +1,18 @@
+Utils
+=======
+
+
+.. py:currentmodule:: flowermd.utils
+
+Utils
+-----
+
+.. automodule:: flowermd.utils.utils
+   :members:
+
+
+Base Types
+----------
+
+.. automodule:: flowermd.utils.base_types
+   :members:

flowermd/__init__.py

@@ -1,4 +1,5 @@
 """flowerMD package."""
+
 from .base import (
     CoPolymer,
     Lattice,

flowermd/__version__.py

@@ -1,3 +1,3 @@
-VERSION = (1, 1, 1)
+VERSION = (1, 2, 0)
 
 __version__ = ".".join(map(str, VERSION))

flowermd/assets/__init__.py

@@ -1,3 +1,4 @@
 """Paths to the assets used by flowerMD."""
+
 from .forcefields import FF_DIR
 from .molecule_files import MON_DIR

flowermd/assets/forcefields/__init__.py

@@ -1,4 +1,5 @@
 """Forcefield files for flowerMD."""
+
 import os
 
 FF_DIR = os.path.abspath(os.path.dirname(__file__))

flowermd/assets/molecule_files/__init__.py

@@ -1,4 +1,5 @@
 """Molecule files for flowerMD."""
+
 import os
 
 MON_DIR = os.path.abspath(os.path.dirname(__file__))

flowermd/base/__init__.py

@@ -1,4 +1,5 @@
 """Base classes for flowerMD."""
+
 from .forcefield import BaseHOOMDForcefield, BaseXMLForcefield
 from .molecule import CoPolymer, Molecule, Polymer
 from .simulation import Simulation

flowermd/base/forcefield.py

@@ -1,4 +1,5 @@
 """Base forcefield classes."""
+
 import forcefield_utilities as ffutils
 import foyer
 

flowermd/base/molecule.py

@@ -1,4 +1,5 @@
 """Base class for all flowerMD molecules, Polymers, and CoPolymers."""
+
 import itertools
 import os.path
 import random
@@ -14,9 +15,9 @@
 from mbuild.lib.recipes import Polymer as mbPolymer
 
 from flowermd.base import BaseHOOMDForcefield, BaseXMLForcefield
-from flowermd.utils import check_return_iterable
-from flowermd.utils.exceptions import ForceFieldError, MoleculeLoadError
-from flowermd.utils.ff_utils import _validate_hoomd_ff
+from flowermd.internal import check_return_iterable
+from flowermd.internal.exceptions import ForceFieldError, MoleculeLoadError
+from flowermd.internal.ff_utils import _validate_hoomd_ff
 
 
 class Molecule:

flowermd/base/simulation.py

@@ -1,4 +1,5 @@
 """Base simulation class for flowerMD."""
+
 import inspect
 import pickle
 import warnings
@@ -9,14 +10,9 @@
 import numpy as np
 import unyt as u
 
-from flowermd.utils import (
-    HOOMDThermostats,
-    StdOutLogger,
-    UpdateWalls,
-    calculate_box_length,
-    validate_ref_value,
-)
-from flowermd.utils.exceptions import ReferenceUnitError
+from flowermd.internal import validate_ref_value
+from flowermd.utils.actions import StdOutLogger, UpdateWalls
+from flowermd.utils.base_types import HOOMDThermostats
 
 
 class Simulation(hoomd.simulation.Simulation):
@@ -542,9 +538,9 @@ def set_integrator_method(self, integrator_method, method_kwargs):
         if not self.integrator:  # Integrator and method not yet created
             self.integrator = hoomd.md.Integrator(
                 dt=self.dt,
-                integrate_rotational_dof=True
-                if self._rigid_constraint
-                else False,
+                integrate_rotational_dof=(
+                    True if self._rigid_constraint else False
+                ),
             )
             if self._rigid_constraint:
                 self.integrator.rigid = self._rigid_constraint
@@ -613,24 +609,27 @@ def remove_walls(self, wall_axis):
 
     def run_update_volume(
         self,
+        final_box_lengths,
         n_steps,
         period,
         kT,
         tau_kt,
-        final_box_lengths=None,
-        final_density=None,
         thermalize_particles=True,
         write_at_start=True,
     ):
         """Run an NVT simulation while shrinking or expanding simulation box.
 
         The simulation box is updated using `hoomd.update.BoxResize` and the
-        final box lengths are set to `final_box_lengths` or inferred from
-        `final_density` if `final_box_lengths` is not provided.
+        final box lengths are set to `final_box_lengths`.
 
+        See `flowermd.utils.get_target_volume_mass_density` and
+        `flowermd.utils.get_target_volume_number_density` which are
+        helper functions that can be used to get `final_box_lengths`.
 
         Parameters
         ----------
+        final_box_lengths : np.ndarray or unyt.array.unyt_array, shape=(3,), required # noqa: E501
+            The final box edge lengths in (x, y, z) order.
         n_steps : int, required
             Number of steps to run during volume update.
         period : int, required
@@ -639,52 +638,54 @@ def run_update_volume(
             The temperature to use during volume update.
         tau_kt : float, required
             Thermostat coupling period (in simulation time units).
-        final_box_lengths : np.ndarray, shape=(3,), dtype=float, default None
-            The final box edge lengths in (x, y, z) order.
-        final_density : float, default None
-            The final density of the simulation in g/cm^3.
         write_at_start : bool, default True
             When set to True, triggers writers that evaluate to True
             for the initial step to execute before the next simulation
             time step.
 
-        """
-        if final_box_lengths is None and final_density is None:
-            raise ValueError(
-                "Must provide either `final_box_lengths` or `final_density`"
+        Examples
+        --------
+        In this example, a low density system is initialized with `Pack`
+        and a box matching a density of 1.1 g/cm^3 is passed into
+        `final_box_lengths`.
+
+        ::
+
+            import unyt
+            from flowermd.base import Pack, Simulation
+            from flowermd.library import PPS, OPLS_AA_PPS
+
+            pps_mols = PPS(num_mols=20, lengths=15)
+            pps_system = Pack(
+                molecules=[pps_mols],
+                force_field=OPLS_AA_PPS(),
+                r_cut=2.5,
+                density=0.5,
+                auto_scale=True,
+                scale_charges=True
             )
-        if final_box_lengths is not None and final_density is not None:
-            raise ValueError(
-                "Cannot provide both `final_box_lengths` and `final_density`."
+            sim = Simulation(
+                initial_state=pps_system.hoomd_snapshot,
+                forcefield=pps_system.hoomd_forcefield
             )
-        if final_box_lengths is not None:
-            final_box = hoomd.Box(
-                Lx=final_box_lengths[0],
-                Ly=final_box_lengths[1],
-                Lz=final_box_lengths[2],
+            target_box = flowermd.utils.get_target_box_mass_density(
+                density=1.1 * unyt.g/unyt.cm**3, mass=sim.mass.to("g")
+            )
+            sim.run_update_volume(
+                n_steps=1e4, kT=1.0, tau_kt=1.0, final_box_lengths=target_box
             )
-        else:
-            if not self.reference_values:
-                raise ReferenceUnitError(
-                    "Missing simulation units. Please "
-                    "provide units for mass, length, and"
-                    " energy."
-                )
-
-            if isinstance(final_density, u.unyt_quantity):
-                density_quantity = final_density.to(u.g / u.cm**3)
-            else:
-                density_quantity = u.unyt_quantity(
-                    final_density, u.g / u.cm**3
-                )
-            mass_g = self.mass.to("g")
-            L = calculate_box_length(mass_g, density_quantity)
-            # convert L from cm to reference units
-            L = (
-                L.to(self.reference_length.units) / self.reference_length.value
-            ).value
-            final_box = hoomd.Box(Lx=L, Ly=L, Lz=L)
 
+        """
+        if self.reference_length and hasattr(final_box_lengths, "to"):
+            ref_unit = self.reference_length.units
+            final_box_lengths = final_box_lengths.to(ref_unit)
+            final_box_lengths /= self.reference_length
+
+        final_box = hoomd.Box(
+            Lx=final_box_lengths[0],
+            Ly=final_box_lengths[1],
+            Lz=final_box_lengths[2],
+        )
         resize_trigger = hoomd.trigger.Periodic(period)
         box_ramp = hoomd.variant.Ramp(
             A=0, B=1, t_start=self.timestep, t_ramp=int(n_steps)