Log charge provenance once per unique molecule

docs/using/advanced.md

@@ -2,44 +2,34 @@
 
 ## Charge assignment logging
 
-SMIRNOFF force fields support several different partial charge assignment methods. These are applied, in the following order
-
-1. Look for preset charges from the `charge_from_molecules` argument
-1. Look for chemical environment matches within the `<LibraryCharges>` section
-1. Look for chemical environment matches within the `<ChargeIncrementModel>` section
-1. Try to run AM1-BCC according to the `<ToolkitAM1BCC>` section or some variant
-
-If a molecule gets charges from one method, attempts to match charges for later methods are skipped. Note that preset charges override the force field and are not checked for consistency; any charges provided to the `charge_from_molecules` argument technically modify the force field. For more on how SMIRNOFF defines this behavior, see [this issue](https://github.com/openforcefield/standards/issues/68) and linked discussions.
-
-After all (mass-bearing) atoms have partial charges assigned, virtual sites are given charges by transferring charge from the atoms they are associated with ("orientation" atoms) according to the parameters of the force field. (The value of these parameters can be 0.0.)
-
-Given this complexity, it may be useful to track how each atom actually got charges assigned. Interchange has opt-in logging to track this behavior. This uses the [standard library `logging` module](https://docs.python.org/3/library/logging.html) at the `logging.DEBUG` level. The easiest way to get started is by adding something like `logging.getLogger("openff.interchange").setLevel(logging.DEBUG)` to the beginning of a script or program. For example, this script:
+SMIRNOFF force fields support several different partial charge assignment methods and [employ a hierarchical scheme](smirnoff-charge-assignment-hierarchy) to determine which is used on each molecule. Given this complexity, it may be useful to track how each molecule's atoms actually had their charges assigned. (Note that, except for some complexity with `<ChargeIncrementModel>`, all atoms in a given molecule are assigned charges via the same method when using SMIRNOFF force fields.) Interchange has opt-in logging to track this behavior. This uses the [standard library `logging` module](https://docs.python.org/3/library/logging.html) at the `DEBUG` level. The easiest way to get started is by adding something like `logging.getLogger("openff.interchange").setLevel(logging.DEBUG)` to the beginning of a script or program. For example, this script:
 
 ```python
 import logging
 
-from openff.toolkit import ForceField, Molecule
+from openff.toolkit import ForceField, Molecule, Topology
 
 logging.basicConfig()
 logging.getLogger("openff.interchange").setLevel(logging.DEBUG)
 
-ForceField("openff-2.2.0.offxml").create_interchange(
-    Molecule.from_smiles("CCO").to_topology()
+ForceField("openff-2.3.0.offxml").create_interchange(
+    Topology.from_molecules(
+        [
+            Molecule.from_smiles("CCO"),
+            Molecule.from_smiles("O"),
+            Molecule.from_smiles("O"),
+            Molecule.from_smiles(341 * "C"),
+        ],
+    )
 )
 ```
 
 will produce output including something like
 
 ```shell
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 0
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 1
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 2
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 3
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 4
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 5
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 6
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 7
-DEBUG:openff.interchange.smirnoff._nonbonded:Charge section ToolkitAM1BCC, using charge method am1bccelf10, applied to topology atom index 8
+DEBUG:openff.interchange.smirnoff._nonbonded:Charge section NAGLCharges, using NAGL model openff-gnn-am1bcc-1.0.0.pt, applied to molecule with Hill formula C2H6O and InChIKey LFQSCWFLJHTTHZ-UHFFFAOYSA-N
+DEBUG:openff.interchange.smirnoff._nonbonded:Charge section LibraryCharges, applied to molecule with Hill formula H2O and InChIKey XLYOFNOQVPJJNP-UHFFFAOYSA-N
+DEBUG:openff.interchange.smirnoff._nonbonded:Charge section NAGLCharges, using NAGL model openff-gnn-am1bcc-1.0.0.pt, applied to molecule with Hill formula C341H684 and InChIKey CLLUCSPVKWTWLW-UHFFFAOYSA-N
 ```
 
 This functionality is only available with SMIRNOFF force fields.

docs/using/edges.md

@@ -36,6 +36,8 @@ You may also wish to make the vdW cut-off distance longer. This is typically acc
 
 ## Quirks of charge assignment
 
+(smirnoff-charge-assignment-hierarchy)=
+
 ### Charge assignment hierarchy
 
 Interchange, following the [SMIRNOFF specification](https://openforcefield.github.io/standards/standards/smirnoff/#partial-charge-and-electrostatics-models), assigns charges to (heavy) atoms with the following priority: