From 48c2ebaf5c21ef1e54f4a2a6847f5cd8840c3ad2 Mon Sep 17 00:00:00 2001 From: marjanalbouye Date: Tue, 14 Nov 2023 13:06:26 -0700 Subject: [PATCH 1/5] add reference to flowermd docs --- tutorials/1-flowerMD-basics.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tutorials/1-flowerMD-basics.ipynb b/tutorials/1-flowerMD-basics.ipynb index ee952b44..79dbfcb5 100644 --- a/tutorials/1-flowerMD-basics.ipynb +++ b/tutorials/1-flowerMD-basics.ipynb @@ -153,7 +153,7 @@ "Now that the molecules are packed in the box, we can apply the forcefield and parameterize particle interactions.\n", "We use the pre-defined `OPLS` forcefield class, which was created from the [OPLS](https://en.wikipedia.org/wiki/OPLS) XML forcefield, to parameterize particle interactions.\n", "\n", - "The flowerMD library offers some commonly used forcefields that can be employed to parameterize the interactions within specific systems. Please refer to `flowermd.library.forcefields` for more examples.\n" + "The flowerMD library offers some commonly used forcefields that can be employed to parameterize the interactions within specific systems. Please refer to [flowerMD's documentation](https://flowermd.readthedocs.io/en/latest/forcefields.html) for more examples.\n" ] }, { @@ -530,7 +530,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "The simulation class also allows users to run the simulation under different conditions/ensembles such as NPT ensemble, NVE ensemble and Langevin dynamics. Check out `flowermd/base/simulation.py` for more functionalities." + "The simulation class also allows users to run the simulation under different conditions/ensembles such as NPT ensemble, NVE ensemble and Langevin dynamics. Check out [flowerMD's documentation](https://flowermd.readthedocs.io/en/latest/simulation.html) for more functionalities." ] }, { From 913a2c40e7351dbc4ef775d2141963f619a8e030 Mon Sep 17 00:00:00 2001 From: marjanalbouye Date: Tue, 14 Nov 2023 13:36:43 -0700 Subject: [PATCH 2/5] add description for molecule subclasses --- tutorials/2-flowerMD-advanced.ipynb | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tutorials/2-flowerMD-advanced.ipynb b/tutorials/2-flowerMD-advanced.ipynb index 86dd57d9..ec8ef0a1 100644 --- a/tutorials/2-flowerMD-advanced.ipynb +++ b/tutorials/2-flowerMD-advanced.ipynb @@ -227,7 +227,9 @@ } }, "source": [ - "Checkout some polymer examples defined in `flowermd/library/polymers.py`." + "Users can extend the molecule class functionalities by creating subclasses of the `Molecule` base class. This can be achieved by overriding the `_generate` method, which is responsible for generating all the molecules in form of [mbuild compounds](https://mbuild.mosdef.org/en/stable/topic_guides/data_structures.html#compound) and appending them to the `self._molecules` list.\n", + "\n", + "flowerMD implements two subclasses of the `Molecule` class: `Polymer` and `CoPolymer`. Please see [flowerMD's Molecule documentation](https://flowermd.readthedocs.io/en/latest/molecule.html) for more details." ] }, { From 0e7e3860b649f6fca8abfd238320a9643ca10705 Mon Sep 17 00:00:00 2001 From: marjanalbouye Date: Tue, 14 Nov 2023 15:02:22 -0700 Subject: [PATCH 3/5] update custom forcefield description --- tutorials/2-flowerMD-advanced.ipynb | 72 ++++++++++++++++++----------- 1 file changed, 44 insertions(+), 28 deletions(-) diff --git a/tutorials/2-flowerMD-advanced.ipynb b/tutorials/2-flowerMD-advanced.ipynb index ec8ef0a1..59b39b8e 100644 --- a/tutorials/2-flowerMD-advanced.ipynb +++ b/tutorials/2-flowerMD-advanced.ipynb @@ -243,9 +243,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "flowerMD offers a range of predefined forcefield classes that can be used to parameterize a system. Checkout [`flowermd/library/forcefields.py`](https://github.com/cmelab/flowerMD/blob/main/flowermd/library/forcefields.py) to see the list of available forcefields.\n", + "flowerMD offers a range of predefined forcefield classes that can be used to parameterize a system. Checkout [flowerMD's library documentation](https://flowermd.readthedocs.io/en/latest/forcefields.html) to see the list of available forcefields.\n", "\n", - "To create a custom forcefield object, you can follow these two approaches:" + "Users can also define their own custom forcefields with the following two options:" ] }, { @@ -256,7 +256,7 @@ } }, "source": [ - "### Custom ForceFields (XML-based)" + "### Option 1: XML-based custom forcefields" ] }, { @@ -267,7 +267,9 @@ } }, "source": [ - "Given the path to the XML file of a desired forcefield, users can employ the `FF_from_file` class available in `flowermd.library` to instantiate a forcefield object." + "Given the path to the XML file of a desired forcefield, users can employ the `FF_from_file` class available in `flowermd.library` to instantiate a forcefield object.\n", + "\n", + "*Note*: The XML file should be in the format of [foyer](https://foyer.mosdef.org/en/stable/getting_started/quickstart.html) forcefield files." ] }, { @@ -285,6 +287,15 @@ "benzene_ff = FF_from_file(forcefield_files=\"../flowermd/assets/forcefields/benzene_opls.xml\")" ] }, + { + "cell_type": "markdown", + "source": [ + "### Option 2: HOOMD Forces custom forcefields\n" + ], + "metadata": { + "collapsed": false + } + }, { "cell_type": "markdown", "metadata": { @@ -293,27 +304,40 @@ } }, "source": [ - "Check out [`flowermd/library/forcefields.py`](https://github.com/cmelab/flowerMD/blob/main/flowermd/library/forcefields.py) for more some examples of defining a forcefield using a subclass of `foyer.Forcefield` for specific molecules." + "Users have the flexibility to directly define their own list of HOOMD force objects tailored to specific simulation requirements rather than initiating it from an XML based forcefield. In such cases, users can specify the forces by creating a subclass of the `flowermd.base.BaseHOOMDForcefield` class. This can be achieved by developing `_create_forcefield` method, which is responsible for generating a list of `hoomd.md.force` objects. Below is an example of defining `BreadSpring` custom class that creates HOOMD force objects for a system of coarse-grained beads given the parameters for bonded and non-bonded interactions.\n" ] }, { - "cell_type": "markdown", - "metadata": {}, + "cell_type": "code", + "execution_count": null, + "outputs": [], "source": [ - "### HOOMD Forces" - ] + "from flowermd.base import BaseHOOMDForcefield\n", + "class BeadSpring(BaseHOOMDForcefield):\n", + " def __init__(self, r_cut, beads, bonds=None, angles=None, dihedrals=None,exclusions=[\"bond\", \"1-3\"]):\n", + " # ...\n", + " hoomd_forces = self._create_forcefield()\n", + " super(BeadSpring, self).__init__(hoomd_forces)\n", + "\n", + " def _create_forcefield(self):\n", + " hoomd_forces = []\n", + " # generate hoomd forces for pair interactions, bonds, angles, dihedrals, etc.\n", + " # ...\n", + " return hoomd_forces\n", + "\n" + ], + "metadata": { + "collapsed": false + } }, { "cell_type": "markdown", - "metadata": { - "jupyter": { - "outputs_hidden": false - } - }, "source": [ - "Alternatively, users have the flexibility to define their own custom class that handles forces. This can be achieved by implementing a class or method that generates a list of `hoomd.md.force` objects, tailored to specific simulation requirements.\n", - "Check out the `BeadSpring` class in [`flowermd/library/forcefields.py`](https://github.com/cmelab/flowerMD/blob/main/flowermd/library/forcefields.py) for an example of defining HOOMD force objects for a system of coarse-grained beads." - ] + "Please also see [flowerMD's Forcefield documentation](https://flowermd.readthedocs.io/en/latest/forcefields.html) for more examples.\n" + ], + "metadata": { + "collapsed": false + } }, { "cell_type": "markdown", @@ -388,11 +412,10 @@ } }, "source": [ - "Note: Both `Pack` and `Lattice` classes are subclasses of the `System` class. The base `System` class is designed as an abstract class, meaning it's not intended to be directly instantiated.\n", - "\n", - "If you desire to customize a molecule assembly algorithm that suits your specific requirements, you should create a subclass of the `System` class and override the abstract method `_build_system`. This method is responsible for organizing molecules from the `Molecule` class into a simulation box and returning the resulting mbuild compound. \n", + "Note: Both `Pack` and `Lattice` classes are subclasses of the `System` class. The base `System` class is designed as an abstract class, meaning it's not intended to be directly instantiated. Check out `Pack` and `Lattice` [documentation](https://flowermd.readthedocs.io/en/latest/system.html) for more details .\n", "\n", - "Check out `Pack` and `Lattice` in `flowermd/base/systems.py` for examples of how to define custom assembly algorithms." + "If you desire to customize a molecule assembly algorithm that suits your specific requirements, you should create a subclass of the `System` class and override the abstract method `_build_system`. This method is responsible for organizing molecules from the `Molecule` class into a simulation box and returning the resulting mbuild compound.\n", + "\n" ] }, { @@ -462,13 +485,6 @@ "As mentioned in the previous tutorial, when the `auto_scale` parameter is set to `True` during system building, the parameters of the forcefields will be scaled automatically to range between 0 to 1. The scaling factor for these conversions can be retrieved from `system.reference_values`, which includes scaling factors for energy, length and mass values." ] }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ - "TODO: (need to talk about units and how to set units)" - ] - }, { "cell_type": "markdown", "metadata": {}, From 57bcfdf659a3486984be508644e4f81f6683dbf4 Mon Sep 17 00:00:00 2001 From: marjanalbouye Date: Tue, 14 Nov 2023 15:35:15 -0700 Subject: [PATCH 4/5] added questions guideline to contribution guideline --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bb699e1b..0b6a7359 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,3 +34,8 @@ interested in contributing code, please follow the steps below: New functionalities should be covered by unit tests. If you are adding a new function/feature/class please follow the existing style for docstrings. + +## Questions and comments + +Please feel free to create an issue if you have any questions or comments about +flowerMD. \ No newline at end of file From de463235f400e1b647e5565f379aa95d012ba7e6 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 14 Nov 2023 22:35:28 +0000 Subject: [PATCH 5/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b6a7359..58d62ca8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,4 +38,4 @@ function/feature/class please follow the existing style for docstrings. ## Questions and comments Please feel free to create an issue if you have any questions or comments about -flowerMD. \ No newline at end of file +flowerMD.