Document gotchas from Slack discussion (#1564)

* Document gotchas from Slack discussion

* Update changelog

* further clarify wording

* try downpinning ipywidgets

* ipywidgets bug should be fixed upstream

* ipywidgets=7 for everyone

---------

Co-authored-by: Jeffrey Wagner <jwagnerjpl@gmail.com>

devtools/conda-envs/openeye.yaml

@@ -36,3 +36,4 @@ dependencies:
   - qcengine
   - mdtraj
   - parmed
+  - ipywidgets =7

devtools/conda-envs/rdkit.yaml

@@ -34,3 +34,5 @@ dependencies:
   - qcelemental
   - qcportal >=0.15
   - qcengine
+  - ipywidgets =7
+

docs/releasehistory.md

@@ -8,6 +8,10 @@ Releases follow the `major.minor.micro` scheme recommended by [PEP440](https://w
 
 ## Current development
 
+### Improved documentation and warnings
+
+- [PR #1564] Improve documentation of conformer selection in `Molecule.assign_partial_charges()`
+
 ## 0.12.1
 
 ### New features

openff/toolkit/topology/molecule.py

@@ -37,6 +37,7 @@
     DefaultDict,
     Dict,
     Generator,
+    Iterable,
     List,
     Optional,
     Sequence,
@@ -2404,7 +2405,7 @@ def assign_partial_charges(
         self,
         partial_charge_method: str,
         strict_n_conformers: bool = False,
-        use_conformers: Optional[List[Quantity]] = None,
+        use_conformers: Optional[Iterable[Quantity]] = None,
         toolkit_registry: TKR = GLOBAL_TOOLKIT_REGISTRY,
         normalize_partial_charges: bool = True,
     ):
@@ -2422,8 +2423,23 @@ def assign_partial_charges(
         - ``"mmff94"``
         - ``"gasteiger"``
 
-        For more supported charge methods and details, see the corresponding
-        methods in each toolkit wrapper:
+        By default, the conformers on the input molecule are not used
+        in the charge calculation. Instead, any conformers needed for
+        the charge calculation are generated by this method. If this
+        behavior is undesired, specific conformers can be provided via the
+        ``use_conformers`` argument.
+
+        ELF10 methods will neither fail nor warn when fewer than the
+        expected number of conformers could be generated, as many small
+        molecules are too rigid to provide a large number of conformers. Note
+        that only the ``"am1bccelf10"`` partial charge method uses ELF
+        conformer selection; the ``"am1bcc"`` method only uses a single
+        conformer. This may confuse users as the `ToolkitAM1BCC`_ SMIRNOFF
+        tag in a force field file defines that AM1BCC-ELF10 should be used
+        if the OpenEye Toolkits are available.
+
+        For more supported charge methods and their details, see the
+        corresponding methods in each toolkit wrapper:
 
         - :meth:`OpenEyeToolkitWrapper.assign_partial_charges \
           <openff.toolkit.utils.toolkits.OpenEyeToolkitWrapper.assign_partial_charges>`
@@ -2434,6 +2450,9 @@ def assign_partial_charges(
         - :meth:`BuiltInToolkitWrapper.assign_partial_charges \
           <openff.toolkit.utils.toolkits.BuiltInToolkitWrapper.assign_partial_charges>`
 
+        .. _ToolkitAM1BCC: https://openforcefield.github.io/standards/standards/smirnoff/\
+            #toolkitam1bcc-temporary-support-for-toolkit-based-am1-bcc-partial-charges
+
         Parameters
         ----------
         partial_charge_method : string
@@ -2443,13 +2462,10 @@ def assign_partial_charges(
             Whether to raise an exception if an invalid number of conformers is
             provided for the given charge method. If this is False and an
             invalid number of conformers is found, a warning will be raised.
-        use_conformers : iterable of openff.unit.Quantity-wrapped numpy arrays, each with shape (n_atoms, 3) and
-            dimension of distance. Optional, default=None
-            Coordinates to use for partial charge calculation. If None, an
+        use_conformers : Arrays with shape (n_atoms, 3) and dimensions of distance
+            Coordinates to use for partial charge calculation. If ``None``, an
             appropriate number of conformers will be generated.
-        toolkit_registry : openff.toolkit.utils.toolkits.ToolkitRegistry or
-            openff.toolkit.utils.toolkits.ToolkitWrapper,
-            optional, default=None
+        toolkit_registry
             :class:`ToolkitRegistry` or :class:`ToolkitWrapper` to use for the
             calculation.
         normalize_partial_charges : bool, default=True
@@ -2461,9 +2477,21 @@ def assign_partial_charges(
         Examples
         --------
 
+        Generate AM1 Mulliken partial charges. Conformers for the AM1
+        calculation are generated automatically:
+
         >>> molecule = Molecule.from_smiles('CCCCCC')
         >>> molecule.assign_partial_charges('am1-mulliken')
 
+        To use pre-generated conformations, use the ``use_conformers`` argument:
+
+        >>> molecule = Molecule.from_smiles('CCCCCC')
+        >>> molecule.generate_conformers(n_conformers=1)
+        >>> molecule.assign_partial_charges(
+        ...     'am1-mulliken',
+        ...     use_conformers=molecule.conformers
+        ... )
+
         Raises
         ------
         InvalidToolkitRegistryError

openff/toolkit/typing/engines/smirnoff/forcefield.py

@@ -1130,6 +1130,11 @@ def create_openmm_system(
     ) -> Union["openmm.System", Tuple["openmm.System", "Topology"]]:
         """Create an OpenMM System from this ForceField and a Topology.
 
+        Note that most force fields specify their own partial charges, and any
+        partial charges defined on the ``Molecule`` objects in the topology are
+        ignored. To use custom partial charges, see the
+        ``charge_from_molecules`` argument.
+
         Parameters
         ----------
         topology